Skip to content
Bluetooth LE Keyboard library for the ESP32 (Arduino IDE compatible)
C++
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples/SendKeyStrokes
BleConnectionStatus.cpp
BleConnectionStatus.h
BleKeyboard.cpp
BleKeyboard.h
KeyboardOutputCallbacks.cpp
KeyboardOutputCallbacks.h
README.md
keywords.txt
library.properties

README.md

ESP32 BLE Keyboard library

This library allows you to make the ESP32 act as a Bluetooth Keyboard and control what it does.

Features

  • Send key strokes
  • Send text
  • Press/release individual keys
  • Media keys are supported
  • Read Numlock/Capslock/Scrolllock state
  • Compatible with Android
  • Compatible with Windows
  • Compatible with Linux
  • Compatible with MacOS X (Untested)
  • Compatible with iOS (Untested)

Installation

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 <BleKeyboard.h>

BleKeyboard bleKeyboard;

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

void loop() {
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);
}

API docs

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

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

#include <BleKeyboard.h>
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%). By default the battery level will be set to 100%, the device name will be ESP32 Bluetooth Mouse and the manufacturer will be Espressif.

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!

You can’t perform that action at this time.