https://github.com/T-vK/ESP32-BLE-Keyboard
Bluetooth LE Keyboard library for the ESP32 (Arduino IDE compatible)
https://github.com/T-vK/ESP32-BLE-Keyboard
arduino arduino-library ble bluetooth bluetooth-le esp32 keyboard
Last synced: 3 months ago
JSON representation
Bluetooth LE Keyboard library for the ESP32 (Arduino IDE compatible)
- Host: GitHub
- URL: https://github.com/T-vK/ESP32-BLE-Keyboard
- Owner: T-vK
- Created: 2019-08-07T16:11:19.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2024-08-07T17:01:45.000Z (11 months ago)
- Last Synced: 2025-04-03T09:07:04.642Z (3 months ago)
- Topics: arduino, arduino-library, ble, bluetooth, bluetooth-le, esp32, keyboard
- Language: C++
- Homepage:
- Size: 33.2 KB
- Stars: 2,641
- Watchers: 52
- Forks: 451
- Open Issues: 240
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- StarryDivineSky - T-vK/ESP32-BLE-Keyboard - BLE-Keyboard是一个用于ESP32的蓝牙低功耗键盘库，兼容Arduino IDE。它允许ESP32模拟HID键盘，通过BLE与电脑、手机等设备无线连接。该项目基于NimBLE-Arduino库实现BLE通信，无需额外的硬件，只需ESP32开发板即可。你可以使用Arduino IDE编写代码，控制ESP32发送键盘按键、组合键、媒体控制键等。项目特色包括支持多平台，易于使用，以及提供了丰富的示例代码，方便开发者快速上手。其工作原理是ESP32作为BLE外设广播键盘服务，设备连接后，通过BLE发送HID报告模拟键盘输入。这个库简化了在ESP32上创建无线键盘或控制器的过程，适用于各种DIY项目和物联网应用。 (硬件_其他 / 资源传输下载)
README
# ESP32 BLE Keyboard library
This library allows you to make the ESP32 act as a Bluetooth Keyboard and control what it does.
You might also be interested in:
- [ESP32-BLE-Mouse](https://github.com/T-vK/ESP32-BLE-Mouse)
- [ESP32-BLE-Gamepad](https://github.com/lemmingDev/ESP32-BLE-Gamepad)
## Features
- [x] Send key strokes
- [x] Send text
- [x] Press/release individual keys
- [x] Media keys are supported
- [ ] Read Numlock/Capslock/Scrolllock state
- [x] Set battery level (basically works, but doesn't show up in Android's status bar)
- [x] Compatible with Android
- [x] Compatible with Windows
- [x] Compatible with Linux
- [x] Compatible with MacOS X (not stable, some people have issues, doesn't work with old devices)
- [x] 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.](https://github.com/espressif/arduino-esp32#installation-instructions))
- [Download the latest release of this library from the release page.](https://github.com/T-vK/ESP32-BLE-Keyboard/releases)
- 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
``` C++
/**
* 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 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);
//
// Below is an example of pressing multiple keyboard modifiers
// which by default is commented out.
//
/* 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 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);`. (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. `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 Keyboard` and the manufacturer will be `Espressif`.
There is also a `setDelay` method to set a delay between each key event. E.g. `bleKeyboard.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:
Uncomment the first line in BleKeyboard.h
```C++
#define USE_NIMBLE
```
### PlatformIO:
Change your `platformio.ini` to the following settings
```ini
lib_deps =
NimBLE-Arduino
build_flags =
-D USE_NIMBLE
```
## Credits
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!
Also, credits to [duke2421](https://github.com/T-vK/ESP32-BLE-Keyboard/issues/1) who helped a lot with testing, debugging and fixing the device descriptor!
And credits to [sivar2311](https://github.com/sivar2311) for adding NimBLE support, greatly reducing the memory footprint, fixing advertising issues and for adding the `setDelay` method.