Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/tcoppex/mbed-ble-hid
:raising_hand: Implement Human Interface Device over Bluetooth Low Energy on a Mbed stack (Arduino nano 33 BLE).
https://github.com/tcoppex/mbed-ble-hid
arduino arduino-library ble bluetooth-low-energy hid mbed nano33ble
Last synced: about 1 month ago
JSON representation
:raising_hand: Implement Human Interface Device over Bluetooth Low Energy on a Mbed stack (Arduino nano 33 BLE).
- Host: GitHub
- URL: https://github.com/tcoppex/mbed-ble-hid
- Owner: tcoppex
- License: mit
- Created: 2020-06-02T16:30:42.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2022-11-01T08:21:56.000Z (about 2 years ago)
- Last Synced: 2024-04-19T16:13:31.166Z (8 months ago)
- Topics: arduino, arduino-library, ble, bluetooth-low-energy, hid, mbed, nano33ble
- Language: C++
- Homepage:
- Size: 104 KB
- Stars: 49
- Watchers: 3
- Forks: 14
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
```diff
⚠️ Important
- This version is currently deprecated.
```
# Mbed BLE HID
This project provides a simple library to implement *Human Interface Device* (**HID**) for *Bluetooth Low Energy* (**BLE**) on a Mbed stack using the *HID Over GATT Profile* (**HOGP**).
It was designed for the **Arduino nano 33 BLE** and tested with _GNU/Linux, Android 8.0, iOS, and Windows 10_.
## Environment
On the Arduino IDE you will need the **Arduino Mbed X Boards** package, where *X* is the name of your board (eg. *OS Nano*), with version **2.0.0** ot higher (In the menu bar click on "_Tools > Boards > Boards manager.._").
Alternatively you can use [platformio](https://github.com/platformio) [Deviot](https://github.com/platformio/Deviot) [_Recommended_].
## Getting started
The header `Nano33BleHID.h` defines three basic HID ready to use : Mouse, Keyboard, and Gamepad.
```cpp
#include "Nano33BleHID.h"
// Alias to Nano33BleHID
Nano33BleGamepad pad("SuperAwesome Pad");
void setup() {
// initialize the ble HID.
pad.initialize();
// Launch the eventqueue thread.
MbedBleHID_RunEventThread();
}
void loop() {
// Retrieve the HID service handle.
auto *hid = pad.hid();
// Update internal values.
float theta = PI * (random(255) / 255.0);
hid->motion(cos(theta), sin(theta));
// Send them !
hid->SendReport();
}
```
## Creating a custom HID
A bluetooth HID is defined by *at least* three services :
* a *Device Information* service,
* a *Battery* service,
* a *HID* service.
This library defines the *device information* and *battery* services for you, as well as basic HID services for mouse, keyboard, and gamepad (**HIDMouseService**, **HIDKeyboardService**, and **HIDGamepadService** respectively).
To develop your own HID you will need to derive the **HIDService** class and define a `report descriptors` as described in referenced documentations. A _report descriptor_ is defined by a markup-like language that maps input values to standard interface, like a pointer motion or a key pressed.
Once you have written your HID service you have two options :
1) If your service has a single parameter constructor you can directly use the *Nano33BleHID* wrapper template to create your bluetooth HID :
```cpp
#include "Nano33BleHID.h"
class HIDSampleService : HIDService {
public:
HIDSampleService(BLE &_ble);
// Implement this method to describe how your HID
// is perceived by other BLE managers.
ble::adv_data_appearance_t appearance() override;
};
Nano33BleHID sampleHID;
```
2) Alternatively you can derive your HID from the base class `MbedBleHID` for more complex cases :
```cpp
#include "MbedBleHID.h"
class SampleHID : MbedBleHID {
public:
SampleHID() : MbedBleHID("A Sample HID in the wild") {/**/}
// This should return the polymorphic shared_ptr of your service.
std::shared_ptr CreateHIDService(BLE &ble) override;
// [ Add some fancy stuff here & there ]
};
SampleHID sampleHID;
```
## Example
### ble_mouse
This sample emulate a simple two-buttons mouse (motion and button states), using an `Arduino nano 33 BLE` and an `analog 2-axis joystick` with its X axis (respectively Y) set to analog input *6* (respectively *7*) and its push button set to digital input *2*.
By default the sample is set to demo mode and will output random motions for a few seconds after pairing.
To disable demo mode you can set the macro definition **DEMO_ENABLE_RANDOM_INPUT** to 0.
### ble_shining_kb
Simulate a ghost writer repeating a sentence over and over again.
By default the keyboard layout is set to **LAYOUT_US_INTERNATIONAL**, you can change it by uncommenting the desired layout in [*src/services/keylayouts.h*](https://github.com/tcoppex/mbed-ble-hid/blob/master/src/services/keylayouts.h).
## Known limitations
*Boot protocol*, which allows mouses and keyboards to be used on a boot level, is laid out but not implemented.
## Acknowledgment
This project has benefited from the following resources :
* mbed Microcontroller Library samples,
* [Nordic semiconductor SDK 16](http://developer.nordicsemi.com/nRF5_SDK/nRF5_SDK_v16.x.x/),
* [BLEKeyboard](https://github.com/bitbank2/BLE_Keyboard) by bitbank2,
* [BLE_HID](https://github.com/jpbrucker/BLE_HID) by jpbrucker.
You might want to look at jpbrucker's implementation for a well documented but deprecated alternative.
The file `keylayouts.h` is a slightly modified version from @PaulStoffregen [teensyduino](https://github.com/PaulStoffregen/cores/blob/master/teensy/keylayouts.h) project.
## References
* *Bluetooth HUMAN INTERFACE DEVICE PROFILE 1.1*
* *Bluetooth HID OVER GATT PROFILE SPECIFICATION v10*
* *USB Device Class Definition for Human Interface Devices (HID) v1.11*
* *USB HID Usage Table v1.12*
## License
_**Mbed BLE HID**_ is released under the MIT License.