⚠️ Important
- This version is currently deprecated.
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.
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 Deviot [Recommended].
The header Nano33BleHID.h
defines three basic HID ready to use : Mouse, Keyboard, and Gamepad.
#include "Nano33BleHID.h"
// Alias to Nano33BleHID<HIDGamepadService>
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();
}
A bluetooth HID is defined by at least three services :
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
#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<HIDSampleService> sampleHID;
2) Alternatively you can derive your HID from the base class MbedBleHID
for more complex cases :
#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<HIDService> CreateHIDService(BLE &ble) override;
// [ Add some fancy stuff here & there ]
};
SampleHID sampleHID;
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.
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.
Boot protocol, which allows mouses and keyboards to be used on a boot level, is laid out but not implemented.
This project has benefited from the following resources :
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 project.
Mbed BLE HID is released under the MIT License.