ESP32 BLE Keyboard & Mouse Combo library

This library allows you to make the ESP32 act as a Bluetooth Keyboard & Mouse Combo and control what it does.
You might also be interested in:

• ESP32-BLE-Keyboard
• ESP32-BLE-Mouse
• ESP32-BLE-Gamepad

Features

• Send key strokes
• Send text
• Press/release individual keys
• Media keys are supported
• Read Numlock/Capslock/Scrolllock state
• Set battery level (basically works, but doesn't show up in Android's status bar)
• Compatible with Android
• Compatible with Windows
• Compatible with Linux
• Compatible with MacOS X (not stable, some people have issues, doesn't work with old devices)
• Compatible with iOS (not stable, some people have issues, doesn't work with old devices)

Installation

• (Make sure you can use the ESP32 with the Arduino IDE. Instructions can be found here.)
• Download the latest release of this library from the release page.
• In the Arduino IDE go to "Sketch" -> "Include Library" -> "Add .ZIP Library..." and select the file you just downloaded.
• You can now go to "File" -> "Examples" -> "ESP32 BLE Keyboard" and select any of the examples to get started.

Example

/**
 * 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 <BleCombo.h>

BleCombo bleCombo;

void setup() {
  Serial.begin(115200);
  Serial.println("Starting BLE work!");
  bleCombo.begin();
}

void loop() {
  if(BleCombo.isConnected()) {
    Serial.println("Sending 'Hello world'...");
    bleCombo.print("Hello world");

    delay(1000);

    Serial.println("Sending Enter key...");
    bleCombo.write(KEY_RETURN);

    delay(1000);

    Serial.println("Sending Play/Pause media key...");
    bleCombo.write(KEY_MEDIA_PLAY_PAUSE);

    delay(1000);

    Serial.println("Sending Ctrl+Alt+Delete...");
    bleCombo.press(KEY_LEFT_CTRL);
    bleCombo.press(KEY_LEFT_ALT);
    bleCombo.press(KEY_DELETE);
    delay(100);
    bleCombo.releaseAll();

    delay(1000);

    Serial.println("Left click");
    bleCombo.click(MOUSE_LEFT);
    delay(500);

    Serial.println("Right click");
    bleCombo.click(MOUSE_RIGHT);
    delay(500);

    Serial.println("Scroll wheel click");
    bleCombo.click(MOUSE_MIDDLE);
    delay(500);

    Serial.println("Back button click");
    bleCombo.click(MOUSE_BACK);
    delay(500);

    Serial.println("Forward button click");
    bleCombo.click(MOUSE_FORWARD);
    delay(500);

    Serial.println("Click left+right mouse button at the same time");
    bleCombo.click(MOUSE_LEFT | MOUSE_RIGHT);
    delay(500);

    Serial.println("Click left+right mouse button and scroll wheel at the same time");
    bleCombo.click(MOUSE_LEFT | MOUSE_RIGHT | MOUSE_MIDDLE);
    delay(500);

  }
  Serial.println("Waiting 5 seconds...");
  delay(5000);
}

API docs

The BleCombo interface is almost identical to the Arduino Keyboard and Mouse Interface, so you can use documentation right here: https://www.arduino.cc/reference/en/language/functions/usb/keyboard/ https://www.arduino.cc/reference/en/language/functions/usb/mouse/

Just remember that you have to use bleCombo instead of just Keyboard or Mouse and you need these two lines at the top of your script:

#include <BleCombo.h>
BleCombo bleCombo;

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 BleCombo bleCombo; you can do BleCombo bleCombo("Bluetooth Device Name", "Bluetooth Device Manufacturer", 100);. (Max lenght is 15 characters, anything beyond that will be truncated.)
The third parameter is the initial battery level of your device. To adjust the battery level later on you can simply call e.g. bleCombo.setBatteryLevel(50) (set battery level to 50%).
By default the battery level will be set to 100%, the device name will be ESP32 Combo HID and the manufacturer will be Espressif.
There is also a setDelay method to set a delay between each key event. E.g. bleCombo.setDelay(10) (10 milliseconds). The default is 8.
This feature is meant to compensate for some applications and devices that can't handle fast input and will skip letters if too many keys are sent in a small time frame.

NimBLE-Mode

The NimBLE mode enables a significant saving of RAM and FLASH memory.

Comparison (SendKeyStrokes.ino at compile-time)

Standard

RAM:   [=         ]   9.3% (used 30548 bytes from 327680 bytes)
Flash: [========  ]  75.8% (used 994120 bytes from 1310720 bytes)

NimBLE mode

RAM:   [=         ]   8.3% (used 27180 bytes from 327680 bytes)
Flash: [====      ]  44.2% (used 579158 bytes from 1310720 bytes)

Comparison (SendKeyStrokes.ino at run-time)

	Standard	NimBLE mode	difference
ESP.getHeapSize()	296.804	321.252	+ 24.448
ESP.getFreeHeap()	143.572	260.764	+ 117.192
ESP.getSketchSize()	994.224	579.264	- 414.960

How to activate NimBLE mode?

ArduinoIDE: Before including the library, insert the line #define USE_NIMBLE

#define USE_NIMBLE
#include <BleCombo.h>

PlatformIO: Change your platformio.ini to the following settings

lib_deps = 
  NimBLE-Arduino

build_flags = 
  -D USE_NIMBLE

Credits

Credits to chegewara and the authors of the USB keyboard library as this project is heavily based on their work!
Also, credits to duke2421 who helped a lot with testing, debugging and fixing the device descriptor! And credits to sivar2311 for adding NimBLE support, greatly reducing the memory footprint, fixing advertising issues and for adding the setDelay method.