https://github.com/nanoframework/nanoframework.bluetooth.hid
📦 .NET nanoFramework library for Bluethoot.Hid
https://github.com/nanoframework/nanoframework.bluetooth.hid
bluetooth csharp dotnet embedded-systems hacktoberfest nanoframework
Last synced: 9 months ago
JSON representation
📦 .NET nanoFramework library for Bluethoot.Hid
- Host: GitHub
- URL: https://github.com/nanoframework/nanoframework.bluetooth.hid
- Owner: nanoframework
- License: mit
- Created: 2023-03-15T08:17:33.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2025-04-02T17:38:36.000Z (9 months ago)
- Last Synced: 2025-04-19T16:41:12.130Z (9 months ago)
- Topics: bluetooth, csharp, dotnet, embedded-systems, hacktoberfest, nanoframework
- Language: C#
- Homepage: https://www.nanoframework.net
- Size: 242 KB
- Stars: 9
- Watchers: 3
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project
README
[](https://sonarcloud.io/summary/new_code?id=nanoframework_nanoFramework.Bluetooth.Hid) [](https://sonarcloud.io/summary/new_code?id=nanoframework_nanoFramework.Bluetooth.Hid) [](https://www.nuget.org/packages/nanoFramework.Bluetooth.Hid/) [](https://github.com/nanoframework/Home/blob/main/CONTRIBUTING.md) [](https://discord.gg/gCyBu8T)
# nanoFramework Bluetooth HID
This library contains an implementation of Bluetooth Low Energy HID Keyboard and Mouse (more in the future).
## Build status
| Component | Build Status | NuGet Package |
|:-|---|---|
| nanoFramework.Bluetooth.Hid | [](https://dev.azure.com/nanoframework/nanoFramework.Bluetooth.Hid/_build/latest?definitionId=105&repoName=nanoframework%2FnanoFramework.Bluetooth.Hid&branchName=main) | [](https://www.nuget.org/packages/nanoFramework.Bluetooth.Hid/) |
## Hardware requirements
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.
## Usage
### Keyboard
Start by initializing a `Keyboard` class:
```csharp
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](https://the-sz.com/products/usbid/index.php?v=&p=&n=Keyboard).
Next, the `Keyboard` must be initialized and advertised on Bluetooth. This is done with these two lines:
```csharp
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:
#### Simulating key presses
`Keyboard` contains methods to simulate key presses and releases. Example usage:
```csharp
// 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.
#### Simulating typing on a keyboard
This is done using the `KeyboardUtilities` class:
```csharp
KeyboardUtilities.TypeText(kbd, "Hello, World. I want to play a game.");
```
### Mouse
Initializing a `Mouse` is done in the same way as `Keyboard`:
```csharp
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.
#### Simulating Mouse Movement
```cshrap
// 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.
#### Simulating Scrolling
```csharp
// scroll down
mouse.Scroll(-5);
```
#### Simulating Button Clicks
```csharp
// left click something
mouse.Click(MouseButton.Left);
```
## Samples
Sample projects using this library can be found in the `Samples` folder. They can be deployed directly to a device and used.
## Feedback and documentation
For documentation, providing feedback, issues and finding out how to contribute please refer to the [Home repo](https://github.com/nanoframework/Home).
Join our Discord community [here](https://discord.gg/gCyBu8T).
## Credits
The list of contributors to this project can be found at [CONTRIBUTORS](https://github.com/nanoframework/Home/blob/main/CONTRIBUTORS.md).
## License
The **nanoFramework** Class Libraries are licensed under the [MIT license](LICENSE.md).
## Code of Conduct
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](https://dotnetfoundation.org/code-of-conduct).
## .NET Foundation
This project is supported by the [.NET Foundation](https://dotnetfoundation.org).