diff --git a/BleKeyboard.cpp b/BleKeyboard.cpp index 70dbefc..f7c16c3 100644 --- a/BleKeyboard.cpp +++ b/BleKeyboard.cpp @@ -63,12 +63,12 @@ static const uint8_t _hidReportDescriptor[] = { USAGE_PAGE(1), 0x0C, // USAGE_PAGE (Consumer) USAGE(1), 0x01, // USAGE (Consumer Control) COLLECTION(1), 0x01, // COLLECTION (Application) - REPORT_ID(1), MEDIA_KEYS_ID, // REPORT_ID (3) + REPORT_ID(1), MEDIA_KEYS_ID, // REPORT_ID (3) USAGE_PAGE(1), 0x0C, // USAGE_PAGE (Consumer) LOGICAL_MINIMUM(1), 0x00, // LOGICAL_MINIMUM (0) LOGICAL_MAXIMUM(1), 0x01, // LOGICAL_MAXIMUM (1) REPORT_SIZE(1), 0x01, // REPORT_SIZE (1) - REPORT_COUNT(1), 0x0A, // REPORT_COUNT (16) + REPORT_COUNT(1), 0x10, // REPORT_COUNT (16) USAGE(1), 0xB5, // USAGE (Scan Next Track) ; bit 0: 1 USAGE(1), 0xB6, // USAGE (Scan Previous Track) ; bit 1: 2 USAGE(1), 0xB7, // USAGE (Stop) ; bit 2: 4 @@ -454,4 +454,4 @@ size_t BleKeyboard::write(const uint8_t *buffer, size_t size) { buffer++; } return n; -} \ No newline at end of file +} diff --git a/BleKeyboard.h b/BleKeyboard.h index 4e4c494..1db82c4 100644 --- a/BleKeyboard.h +++ b/BleKeyboard.h @@ -67,7 +67,7 @@ const MediaKeyReport KEY_MEDIA_PLAY_PAUSE = {8, 0}; const MediaKeyReport KEY_MEDIA_MUTE = {16, 0}; const MediaKeyReport KEY_MEDIA_VOLUME_UP = {32, 0}; const MediaKeyReport KEY_MEDIA_VOLUME_DOWN = {64, 0}; -const MediaKeyReport KEY_MEDIA_WWW_HOME = {128, 0}; // Opens "My Computer" on Windows +const MediaKeyReport KEY_MEDIA_WWW_HOME = {128, 0}; const MediaKeyReport KEY_MEDIA_LOCAL_MACHINE_BROWSER = {0, 1}; // Opens "My Computer" on Windows const MediaKeyReport KEY_MEDIA_CALCULATOR = {0, 2}; const MediaKeyReport KEY_MEDIA_WWW_BOOKMARKS = {0, 4}; diff --git a/README.md b/README.md index a276630..6abeb93 100644 --- a/README.md +++ b/README.md @@ -2,8 +2,18 @@ This library allows you to make the ESP32 act as a Bluetooth Keyboard and control what it does. -Warning: This library is not ready yet. Atm keys can only be sent using the `sendReport` method. -The code hasn't been tested at all. It should compile wihtout errors though. +## Features + + - [x] Send key strokes + - [x] Send text + - [x] Press/release individual keys + - [x] Media keys are supported + - [ ] Read Numlock/Capslock/Scrolllock state + - [x] Compatible with Android + - [x] Compatible with Windows + - [x] Compatible with Linux + - [ ] Compatible with MacOS X (Untested) + - [ ] Compatible with iOS (Untested) ## Installation - (Make sure you can use the ESP32 with the Arduino IDE. [Instructions can be found here.](https://github.com/espressif/arduino-esp32#installation-instructions)) @@ -15,7 +25,7 @@ The code hasn't been tested at all. It should compile wihtout errors though. ``` C++ /** - * This example turns the ESP32 into a Bluetooth LE keyboard that types the letter `a` once every 5 seconds. + * This example turns the ESP32 into a Bluetooth LE keyboard that writes the words, presses Enter, presses a media key and then Ctrl+Alt+Delete */ #include @@ -28,36 +38,31 @@ void setup() { } void loop() { - if(bleKeyboard.isConnected()) { - Serial.println("Pressing the a-key via the Bluetooth keyboard"); - - KeyReport keyReport; - keyReport.modifiers = 0x00; - keyReport.reserved = 0x00; - keyReport.keys[0] = 0x61; // a-key - keyReport.keys[0] = 0x00; - keyReport.keys[0] = 0x00; - keyReport.keys[0] = 0x00; - keyReport.keys[0] = 0x00; - keyReport.keys[0] = 0x00; - - bleKeyboard.sendReport(&keyReport); // a-key down - - delay(50); - - KeyReport keyReport2; - keyReport.modifiers = 0x00; - keyReport.reserved = 0x00; - keyReport.keys[0] = 0x00; - keyReport.keys[0] = 0x00; - keyReport.keys[0] = 0x00; - keyReport.keys[0] = 0x00; - keyReport.keys[0] = 0x00; - keyReport.keys[0] = 0x00; - - bleKeyboard.sendReport(&keyReport2); // a-key up +if(bleKeyboard.isConnected()) { + Serial.println("Sending 'Hello world'..."); + bleKeyboard.print("Hello world"); + + delay(1000); + + Serial.println("Sending Enter key..."); + bleKeyboard.write(KEY_RETURN); + + delay(1000); + + Serial.println("Sending Play/Pause media key..."); + bleKeyboard.write(KEY_MEDIA_PLAY_PAUSE); + + delay(1000); + + Serial.println("Sending Ctrl+Alt+Delete..."); + bleKeyboard.press(KEY_LEFT_CTRL); + bleKeyboard.press(KEY_LEFT_ALT); + bleKeyboard.press(KEY_DELETE); + delay(100); + bleKeyboard.releaseAll(); } + Serial.println("Waiting 5 seconds..."); delay(5000); } ``` @@ -72,6 +77,24 @@ Just remember that you have to use `bleKeyboard` instead of just `Keyboard` and BleKeyboard bleKeyboard; ``` +In addition to that you can send media keys (which is not possible with the USB keyboard library). Supported are the following: +- KEY_MEDIA_NEXT_TRACK +- KEY_MEDIA_PREVIOUS_TRACK +- KEY_MEDIA_STOP +- KEY_MEDIA_PLAY_PAUSE +- KEY_MEDIA_MUTE +- KEY_MEDIA_VOLUME_UP +- KEY_MEDIA_VOLUME_DOWN +- KEY_MEDIA_WWW_HOME +- KEY_MEDIA_LOCAL_MACHINE_BROWSER // Opens "My Computer" on Windows +- KEY_MEDIA_CALCULATOR +- KEY_MEDIA_WWW_BOOKMARKS +- KEY_MEDIA_WWW_SEARCH +- KEY_MEDIA_WWW_STOP +- KEY_MEDIA_WWW_BACK +- KEY_MEDIA_CONSUMER_CONTROL_CONFIGURATION // Media Selection +- KEY_MEDIA_EMAIL_READER + There is also Bluetooth specific information that you can set (optional): Instead of `BleKeyboard bleKeyboard;` you can do `BleKeyboard bleKeyboard("Bluetooth Device Name", "Bluetooth Device Manufacturer", 100);`. The third parameter is the initial battery level of your device. To adjust the battery level later on you can simply call e.g. `bleKeyboard.setBatteryLevel(50)` (set battery level to 50%). @@ -79,4 +102,4 @@ By default the battery level will be set to 100%, the device name will be `ESP32 ## Credits -Credits to [chegewara](https://github.com/chegewara) as this library is based on [this piece of code](https://github.com/nkolban/esp32-snippets/issues/230#issuecomment-473135679) that he provided. \ No newline at end of file +Credits to [chegewara](https://github.com/chegewara) and [the authors of the USB keyboard library](https://github.com/arduino-libraries/Keyboard/) as this project is heavily based on their work! diff --git a/examples/SendKeyStrokes/SendKeyStrokes.ino b/examples/SendKeyStrokes/SendKeyStrokes.ino index ab36e03..4173433 100644 --- a/examples/SendKeyStrokes/SendKeyStrokes.ino +++ b/examples/SendKeyStrokes/SendKeyStrokes.ino @@ -1,5 +1,5 @@ /** - * This example turns the ESP32 into a Bluetooth LE keyboard that sends the `a`-key and the `Play/Pause`-key once every 5 seconds. + * This example turns the ESP32 into a Bluetooth LE keyboard that writes the words, presses Enter, presses a media key and then Ctrl+Alt+Delete */ #include @@ -13,54 +13,29 @@ void setup() { void loop() { if(bleKeyboard.isConnected()) { -/* - Serial.println("Pressing the a-key via the Bluetooth keyboard..."); - KeyReport keyReport; - keyReport.modifiers = 0x00; - keyReport.reserved = 0x00; - keyReport.keys[0] = 0x04; // "a" - keyReport.keys[1] = 0x00; - keyReport.keys[2] = 0x00; - keyReport.keys[3] = 0x00; - keyReport.keys[4] = 0x00; - keyReport.keys[5] = 0x00; + Serial.println("Sending 'Hello world'..."); + bleKeyboard.print("Hello world"); - bleKeyboard.sendReport(&keyReport); // a-key down + delay(1000); - delay(50); + Serial.println("Sending Enter key..."); + bleKeyboard.write(KEY_RETURN); - KeyReport keyReport2; - keyReport.modifiers = 0x00; - keyReport.reserved = 0x00; - keyReport.keys[0] = 0x00; - keyReport.keys[1] = 0x00; - keyReport.keys[2] = 0x00; - keyReport.keys[3] = 0x00; - keyReport.keys[4] = 0x00; - keyReport.keys[5] = 0x00; + delay(1000); - bleKeyboard.sendReport(&keyReport2); // a-key up - - delay(1000) -*/ -/* - Serial.println("Pressing the Play/Pause-key via the Bluetooth keyboard..."); - - MediaKeyReport mediaKeyReport; - mediaKeyReport[0] = 8; // Play/Pause - mediaKeyReport[1] = 0; - bleKeyboard.sendReport(&mediaKeyReport); // play/pause-key down (2=MEDIA_KEYS_ID) + Serial.println("Sending Play/Pause media key..."); + bleKeyboard.write(KEY_MEDIA_PLAY_PAUSE); - delay(50); + delay(1000); - MediaKeyReport mediaKeyReport2; - mediaKeyReport2[0] = 0; - mediaKeyReport2[1] = 0; - bleKeyboard.sendReport(&mediaKeyReport2); // play/pause-key up (2=MEDIA_KEYS_ID) -*/ + Serial.println("Sending Ctrl+Alt+Delete..."); + bleKeyboard.press(KEY_LEFT_CTRL); + bleKeyboard.press(KEY_LEFT_ALT); + bleKeyboard.press(KEY_DELETE); + delay(100); + bleKeyboard.releaseAll(); - bleKeyboard.write(KEY_MEDIA_PLAY_PAUSE); - Serial.println("Key sent!"); } + Serial.println("Waiting 5 seconds..."); delay(5000); -} \ No newline at end of file +}