This library contains an implementation of Bluetooth Low Energy HID Keyboard and Mouse (more in the future).
| Component | Build Status | NuGet Package |
|---|---|---|
| nanoFramework.Bluetooth.Hid |  |
Currently only support on ESP32 devices running on of the following firmware images:
- ESP32_BLE_REV0
- ESP32_BLE_REV3
- ESP32_PSRAM_BLE_GenericGraphic_REV3
- ESP32_S3_BLE
- M5Core2
- LilygoTWatch2021
- ESP32_ETHERNET_KIT_1.2
The Bluetooth is not in every firmware due to a restriction in the IRAM memory space in the firmware image. For earlier revision 1 ESP32 devices, the PSRAM implementation required a large number of PSRAM library fixes which greatly reduces the available space in the IRAM area, so PSRAM is currently disabled for ESP32_BLE_REV0. With the revision 3 devices the Bluetooth and PSRAM are both available.
Start by initializing a Keyboard class:
var kbd = new Keyboard(deviceName: "nF BLE Keyboard",
deviceInfo: new DeviceInformation("nF", "BLEKBD1", "1", "01", "01", "01"),
protocolMode: ProtocolMode.Report,
plugAndPlayElements: new PnpElements(sig: 0x02, vid: 0xE502, pid: 0xA111, version: 0x210));The deviceName parameter is the name shown to any device scanning for Bluetooth.
deviceInfo parameter takes a DeviceInformation object instance which contains information about the manufacturer and device (serial number, hardware/software revision, etc...).
protocolMode specifies which HID Protocol to use: ReportMode (Default, Supported) or BootMode (Currently unsupported/untested).
plugAndPlayElements field sets various plug and play attributes that the HID Host Operating System uses to recognize and interact with the device. These are product-unique values and you can find a database of PnP devices on this site.
Next, the Keyboard must be initialized and advertised on Bluetooth. This is done with these two lines:
kbd.Initialize();
kbd.Advertise();The keyboard should now be discoverable to nearby devices. To stop advertising, call kbd.StopAdvertising().
Once the keyboard is paired with a host, key presses can be simulated:
Keyboard contains methods to simulate key presses and releases. Example usage:
// open task manager
kbd.Press(Keys.Modifiers.LeftCtrl);
kbd.Press(Keys.Modifiers.LeftShift);
kbd.Press(Keys.Control.Escape);
kbd.ReleaseAll();Alternatively, Send is a shortcut method that makes the code above shorter:
kbd.Send(Keys.Modifiers.LeftCtrl, Keys.Modifiers.LeftShift, Keys.Control.Escape);
When a key is pressed using Press, you can release only that key from the set of pressed keys using Release(key) and passing the key to release.
This is done using the KeyboardUtilities class:
KeyboardUtilities.TypeText(kbd, "Hello, World. I want to play a game.");Initializing a Mouse is done in the same way as Keyboard:
var mouse = new Mouse("nF BLE Mouse",
deviceInfo: new DeviceInformation("nF", "BLEMOUSE1", "1", "01", "01", "01"),
protocolMode: ProtocolMode.Report,
plugAndPlayElements: new PnpElements(sig: 0x02, vid: 0xE502, pid: 0xA111, version: 0x210));
mouse.Initialize();
mouse.Advertise();Once connected to a Host, basic mouse functions can be simulated.
// move to the right and bottom (diagonal)
mouse.Move(x: 5, y: 5);
The X & Y values are cumulative as the OS will increment the X & Y from previous Move calls.
// scroll down
mouse.Scroll(-5);// left click something
mouse.Click(MouseButton.Left);Sample projects using this library can be found in the Samples folder. They can be deployed directly to a device and used.
For documentation, providing feedback, issues and finding out how to contribute please refer to the Home repo.
Join our Discord community here.
The list of contributors to this project can be found at CONTRIBUTORS.
The nanoFramework Class Libraries are licensed under the MIT license.
This project has adopted the code of conduct defined by the Contributor Covenant to clarify expected behavior in our community. For more information see the .NET Foundation Code of Conduct.
This project is supported by the .NET Foundation.
