| nRF5 SDK v12.0.0 |

Choose documentation: | nRF5 SDK | S130 SoftDevice API | S132 SoftDevice API | S212 SoftDevice API | S332 SoftDevice API

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
HID Keyboard Application
This example requires one of the following SoftDevices: S130, S132

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

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:

- Human Interface Device Service
- Device Information Service
- Battery Service

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 the 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:

- During Connection:
  - Button 1: Send sample text to the computer
  - Button 2: Simulates the Shift key

# 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:
   - BSP_INDICATE_ALERT_OFF is indicated.
   - The text 'capsof' will be seen on the editor window.
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.
11. The device should be discoverable again after it switches to advertising mode.

You can also test the application with the Master Control Panel 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 Master Control Panel (the device will be advertising as 'Nordic_Keyboard'), then bond and perform service discovery. Observe that BSP_INDICATE_CONNECTED state is indicated.
3. Click the 'Enable services' button on Master Control Panel, and observe that 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'. This corresponds 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:
   - Keeping Button 2 pressed, push the 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:
   - On the Master Control Panel, select the HID Report, which has the properties Read, WriteWithoutResponse, and Write (the Output Report) and UUID: 0x2A4D.
   - Click the 'hex' radio button.
   - 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. 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:
   - On the Master Control Panel, select the same HID Report as in the previous step (the Output Report).
   - Click the 'hex' radio button.
   - 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. 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. Click on the Disconnect button in Master Control Panel. Observe that no new notifications are received and the device is advertising with Whitelist.
9. As bond info is preserved by Master Control Panel, it should be possible to immediately reconnect to the device by clicking on the Connect button again. Observe that Battery Level notifications are being received every two seconds.