BLEHidAdafruit

The Bluefruit nRF52 BSP codebase is undergoing active development based on customer feedback and testing. As such, the class documentation here is incomplete, and you should consult the Github repo for the latest code and API developments: https://goo.gl/LdEx62

BLEHidAdafruit allows you to simulate a mouse or keyboard using the HID (Human Interface Device) profile that is part of the Bluetooth Low Energy standard.

Most modern mobile devices with Bluetooth Low Energy support, and the latest operating systems generally support Bluetooth Low Energy mice and keyboards out of the box, once you pair your Bluefruit nRF52/nRF52840 Feather and run an appropriate sketch.

API

The BLEHidAdafruit helper class has the following public API:

Download: file
// Constructor
BLEHidAdafruit(void);

// Call this once to start the HID service
virtual err_t begin(void);

// Keyboard
err_t keyboardReport(hid_keyboard_report_t* report);
err_t keyboardReport(uint8_t modifier, uint8_t keycode[6]);
err_t keyboardReport(uint8_t modifier, uint8_t keycode0, uint8_t keycode1=0, uint8_t keycode2=0, uint8_t keycode3=0, uint8_t keycode4=0, uint8_t keycode5=0);

err_t keyPress(char ch);
err_t keyRelease(void);
err_t keySequence(const char* str, int interal=5);

// Consumer Media Keys
err_t consumerReport(uint16_t usage_code);
err_t consumerKeyPress(uint16_t usage_code);
err_t consumerKeyRelease(void);

// Mouse
err_t mouseReport(hid_mouse_report_t* report);
err_t mouseReport(uint8_t buttons, int8_t x, int8_t y, int8_t wheel=0, int8_t pan=0);

err_t mouseButtonPress(uint8_t buttons);
err_t mouseButtonRelease(void);

err_t mouseMove(int8_t x, int8_t y);
err_t mouseScroll(int8_t scroll);
err_t mousePan(int8_t pan);

Example Sketches

There are a variety of example sketches showing how to use the BLEHidAdafruit class. You can browse the latest source code on Github with the following links:

  • hid_keyboard: This example will simulate an HID keyboard, waiting for data to arrive via the nRF52's serial port (via USB serial), and send that data over the air to the bonded Central device.
  • hid_mouse: This example will simulate an HID mouse. To use it run the sketch and open the Serial Monitor, then enter the appropriate characters to move the mouse or trigger/release the mouse buttons.

Bonding HID Devices

In order to use your HID mouse or keyboard, you will first need to bond the two devices. The bonding process involves the following steps:

  • The two devices will connect to each other normally
  • A set of security keys are exchanged between the two devices, and stores in non-volatile memory on each side. This is to ensure that each side is reasonably confident it is talking to the device it thinks it is for future connections, and to encrypt over the air communication between the devices (so that people can 'sniff' your keyboard data, etc.).
  • On the nRF52 side this key data will be stored in a section of flash memory reserved for this purpose using an internal file system.
  • The process of storing these security keys is referred to as bonding, and allows bonded devices to securely communicate without user interaction in the future.
  • To cancel the bonding agreement, you can simply delete the keys on the nRF52 via the clearbonds sketch, or delete the bonding data on your mobile device of computer.
If you run into any bonding problems, try running the clearbonds sketch to remove and old bonding data from local non-volatile memory!

Setting up your Bluefruit device for bonding

To bond an device, run an appropriate HID sketch on the nRF52 to emulate either an HID mouse or an HID keyboard. In the event that you use the HID mouse example you may need to open the Serial Monitor to use it.

In this example we'll run the hid_keyboard example sketch, flashing it to the nRF52, which should give you the following results:

Opening the Serial Monitor will give you the following output (though it may differ depending on the debug level you have selected):

Bonding on iOS

To bond to an iOS device, make sure the sketch is running (as described above) and go into your Settings app and Select Bluetooth.

You should see a device at the bottom of this page called Bluefruit52 (this may vary depending on the version of the sketch you are using!):

Click the device, and you will get a pairing request like this:

Click the Pair button, and the devices will be paired and bonded, and will automatically connect to each other in the future.

If everything went will, you will see the device in your MY DEVICES list, as follows:

Testing the HID Keyboard and Bonding

To test the HID keyboard sketch and bonding process, open the Serial Monitor (or your favorite terminal emulator), enter some text, and if you are using the Serial Monitor click the Send button. This will send some text over the air to whatever textbox or text control has focus in your app.

The text will then appear in your mobile app or bonded device.

If the characters don't match exactly what you send, be sure to check your keyboard language settings, since you may be sending data to a device with a different keyboard setup!

This guide was first published on Mar 22, 2017. It was last updated on Mar 22, 2017. This page (BLEHidAdafruit) was last updated on Feb 11, 2019.