nRF5 SDK v15.0.0
HID Keyboard Application
This example requires one of the following SoftDevices: S112, S132, S140

Important: Before you run this example, make sure to program the SoftDevice.

All provided HID examples conform with USB HID usage tables, http://www.usb.org/developers/hidpage.

The HID Keyboard Application is an example that implements the HID over GATT profile for keyboard using the hardware delivered in the nRF5 Development Kit.

The application includes the three mandatory services needed for the HID over GATT profile:

Note
This application is not power optimized!
The application will stop advertising and go to system-off mode after 3 minutes and 30 seconds (if no advertising with whitelist was done) or after 4 minutes (if advertising with whitelist was done). Push Button 1 to restart advertising.

Setup

You can find the source code and the project file of the example in the following folder: <InstallFolder>\examples\ble_peripheral\ble_app_hids_keyboard

Button assignments - in addition to those defined in BSP BLE Button Assignments:

Testing

Test the HID Keyboard Application with a Microsoft Windows 8 computer with a Bluetooth radio:

  1. Compile and program the application. Observe that the BSP_INDICATE_ADVERTISING state is indicated.
  2. On the Windows 8 computer, search for Bluetooth devices, and connect to the device named 'Nordic_Keyboard'. Observe that the BSP_INDICATE_CONNECTED state is indicated.
  3. Open a text editing application (for example Notepad).
  4. Press Button 1 on the board. This will send one character of the test message 'hello' (the test message includes a carriage return) to the computer, and this will be displayed in the text editor.
  5. Press Button 1 while keeping the Button 2 pressed. Observe that the same 'hello' text will appear in capital letters. This is because Button 2 simulates the Shift key.
  6. Turn Caps Lock on on the computer. Observe that:
    • BSP_INDICATE_ALERT_3 is indicated.
    • The text 'CAPSON' will be seen on the text editor window on the computer. This verifies that output report characteristic has been written successfully on the HID device.
  7. Turn Caps Lock off on the computer. This should result in two events:
  8. Disconnect the computer from the device by removing the device from the computer's devices list. Observe that for the first period, the BSP_INDICATE_ADVERTISING_DIRECTED state is indicated. Then it switches to BSP_INDICATE_ADVERTISING_WHITELIST. Press and hold Button 2 to turn off the whitelist. Observe that BSP_INDICATE_ADVERTISING is indicated at first, then it switches to BSP_INDICATE_ADVERTISING_SLOW, and finally it switches to BSP_INDICATE_IDLE.
  9. Reset the device while pressing Button 2 to erase bond info. Repeat step 2, and check if the device can send messages to the computer.
  10. Disconnect the device from Windows 8, thereby removing the bond info from the computer. Start a search for Bluetooth devices and observe that while the device is advertising with Whitelist, Windows 8 is not able to discover the device.

You can also test the application with nRF Connect by performing the following steps:

  1. Compile and program the application. Observe that BSP_INDICATE_ADVERTISING state is indicated.
  2. Connect to the device from nRF Connect (the device is advertising as 'Nordic_Keyboard'), then bond to the device. To bond, click the settings button for the device in nRF Connect, select "Pair", check "Perform Bonding", and click "Pair". Wait until the bond is established before you continue. Observe that BSP_INDICATE_CONNECTED state is indicated.
  3. Observe that the services are shown in the connected device and that you can start receiving values for the Battery Level Service by clicking the 'Play' button. Battery Level notifications are being received every two seconds.
  4. Push Button 1 on the board. Observe that 2 notifications on one of the HID Report characteristics are received; two notifications (press and release) each for one character of the test message. The first one has the value '00000B0000000000', the second has the value '0000000000000000'. The format used for keyboard reports is the following byte array: [modifier, reserved, Key1, Key2, Key3, Key4, Key6, Key7]. The received values correspond to press and release of character 'h'. Similarly, further press and release events will result in press and release notifications of subsequent characters of the test string. Therefore, pushing Button 1 again will result in notification of press and release reports for character 'e'.
  5. Simulate Shift key:
    • Pushing Button 2 will change the modifier bit to 02, which simulates pushing the shift key on a keyboard.
    • Keep Button 2 pressed, while pushing Button 1 on the board.
    • Observe that 2 notifications on one of the HID Report characteristics are received; two notifications (press and release) each for one character of the test message. The first one has the value '02000F0000000000', the second has the value '0200000000000000'. This corresponds to press and release of character 'l' with the Shift key pressed.
  6. Simulate Caps Lock ON:
    • Setting the modifier bit to 02 will simulate Caps Lock ON.
    • In nRF Connect, select the HID Report, which has the properties Read, WriteWithoutResponse, and Write (the Output Report) and UUID: 0x2A4D.
    • Enter '02' in the text box.
    • Click the 'Write' button.
    • Observe that BSP_INDICATE_ALERT_3 is indicated and that 7 notifications on the other HID Report characteristic (the Input Report) are received in the log. The first one has the value '0000060413161211', the second has the value '0000000413161211', third has the value '0000000013161211', and so on until release event for all characters is sent as the 7th one as '0000000000000000'.
  7. Simulate Caps Lock OFF:
    • Setting the modifier bit back to 00 will simulate Caps Lock OFF.
    • In nRF Connect, select the same HID Report as in the previous step (the Output Report).
    • Enter '00' in the text box.
    • Click the 'Write' button.
    • Observe that BSP_INDICATE_ALERT_OFF is indicated and that 7 notifications on the other HID Report characteristic are received in the log. The first one has the value '0000060413161209', the second has the value '0000000413161209', third has the value '0000000013161209', and so on until release event for all characters is sent as the 7th one as '0000000000000000'.
  8. Disconnect the device in nRF Connect. Observe that no new notifications are received and the device is advertising with whitelist.
  9. As bond information is preserved by nRF Connect, it should be possible to immediately reconnect to the device by clicking the Connect button again. Observe that Battery Level notifications are being received every two seconds.

Documentation feedback | Developer Zone | Subscribe | Updated