⚠️ 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 Deviot [Recommended].

Getting started

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();
}

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 :

#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;

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.

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,
• BLEKeyboard by bitbank2,
• 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 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.