Bluetooth: Peripheral HIDS keyboard

The Peripheral HIDS keyboard sample demonstrates how to use the GATT Human Interface Device (HID) Service to implement a keyboard input device that you can connect to your computer.

The sample also shows how to perform LE Secure Connections Out-of-Band pairing using NFC.

Note

Apart from HID samples, the nRF Connect SDK provides a complete reference application design of Human Interface Device (HID). Depending on the configuration, the application can work as a desktop mouse, gaming mouse, keyboard, or connection dongle. It supports connection over Bluetooth® LE, USB, or both. For details, see the nRF Desktop documentation.

Requirements

The sample supports the following development kits:

Hardware platforms

PCA

Board name

Board target

nRF54LV10 DK

PCA10188

nrf54lv10dk

nrf54lv10dk/nrf54lv10a/cpuapp/ns nrf54lv10dk/nrf54lv10a/cpuapp

nRF54LS05 DK

PCA10214

nrf54ls05dk

nrf54ls05dk/nrf54ls05b/cpuapp

nRF54LM20 DK

PCA10184

nrf54lm20dk

nrf54lm20dk/nrf54lm20b/cpuapp nrf54lm20dk/nrf54lm20a/cpuapp

nRF54LC10 DK

PCA10226

nrf54lc10dk

nrf54lc10dk/nrf54lc10a/cpuapp/ns nrf54lc10dk/nrf54lc10a/cpuapp

nRF54L15 DK

PCA10156

nrf54l15dk

nrf54l15dk/nrf54l15/cpuapp

nRF54L15 DK (emulating nRF54L10)

PCA10156

nrf54l15dk

nrf54l15dk/nrf54l10/cpuapp

nRF54L15 DK (emulating nRF54L05)

PCA10156

nrf54l15dk

nrf54l15dk/nrf54l05/cpuapp

nRF54H20 DK

PCA10175

nrf54h20dk

nrf54h20dk/nrf54h20/cpuapp

nRF5340 DK

PCA10095

nrf5340dk

nrf5340dk/nrf5340/cpuapp/ns nrf5340dk/nrf5340/cpuapp

nRF52 DK

PCA10040

nrf52dk

nrf52dk/nrf52832

nRF52840 DK

PCA10056

nrf52840dk

nrf52840dk/nrf52840

For more security, it is recommended to use the */ns variant of the board target. When built for this variant, the sample is configured to compile and run as a non-secure application using security by separation. Therefore, it automatically includes Trusted Firmware-M that prepares the required peripherals and secure services to be available for the application.

If the NFC OOB pairing feature (CONFIG_SAMPLE_NFC_OOB_PAIRING) is enabled, the sample requires a smartphone or a tablet with Android v8.0.0 or newer.

Overview

The sample uses the buttons on a development kit to simulate keys on a keyboard. One button simulates the letter keys by generating letter keystrokes for a predefined string. A second button simulates the Shift button and shows how to modify the letter keystrokes. An LED displays the Caps Lock state, which can be modified by another connected keyboard.

This sample exposes the HID GATT Service. It uses a report map for a generic keyboard.

LE Secure Out-of-Band pairing with NFC is enabled by default in this sample. You can disable this feature by clearing the CONFIG_SAMPLE_NFC_OOB_PAIRING flag in the application configuration. The following paragraphs describe the application behavior when NFC pairing is enabled.

When the application starts, it initializes and starts the NFCT peripheral that is used for pairing. The application does not start advertising immediately, but only when the NFC tag is read by an NFC polling device, for example a smartphone or a tablet with NFC support.

To trigger advertising without NFC, press Button 4. The NDEF message that the tag sends to the NFC device contains data required to initiate pairing. To start the NFC data transfer, the NFC device must touch the NFC antenna that is connected to the nRF52 device.

After reading the tag, the device can pair with the nRF52 device which is advertising. After connecting, the sample application behaves in the same way as the original HID Keyboard sample. Reading the NFC tag again when the application is in a connected state causes disconnection. When the connection is lost, advertising does not restart automatically.

User interface

Button 1:

Sends one character of the predefined input (“hello\n”) to the computer.

When pairing, press this button to confirm the passkey value that is printed on the COM listener to pair with the other device.

Button 2:

Simulates the Shift key.

When pairing, press this button to reject the passkey value which is printed on the COM listener to prevent pairing with the other device.

LED 1:

Blinks with a period of two seconds with the duty cycle set to 50% when the main loop is running and the device is advertising.

LED 2:

Lit when at least one device is connected.

LED 3:

Indicates if Caps Lock is enabled.

If the NFC OOB pairing feature (CONFIG_SAMPLE_NFC_OOB_PAIRING) is enabled:

Button 4:

Starts advertising.

LED 4:

Indicates if an NFC field is present.

Configuration

See Configuring and building for information about how to permanently or temporarily change the configuration.

Configuration options

The following sample-specific Kconfig options are used in this sample (defined in samples/bluetooth/peripheral_hids_keyboard/Kconfig):

CONFIG_SAMPLE_NFC_OOB_PAIRING

(bool) Enable NFC OOB pairing

CONFIG_SETTINGS

(unknown)

CONFIG_ZMS

(unknown)

CONFIG_NVS

(unknown)

HID Shorter Connection Intervals (SCI)

If you build the sample with -DFILE_SUFFIX=hid_sci, support for HID Shorter Connection Intervals (SCI) is enabled. This feature allows the device to enter a specific HID SCI mode when requested by the central. The HID SCI modes are sets of connection parameters that you can use to optimize the connection for a specific use case. For example, the FAST mode is used to achieve the shortest connection intervals, allowing for minimum latency and maximum throughput.

Setup

The HID service specification does not require encryption (CONFIG_BT_HIDS_DEFAULT_PERM_RW_ENCRYPT), but some systems disconnect from the HID devices that do not support security.

Building and running

This sample can be found under samples/bluetooth/peripheral_hids_keyboard in the nRF Connect SDK folder structure.

For more security, it is recommended to use the */ns variant of the board target (see the Requirements section above.) When built for this variant, the sample is configured to compile and run as a non-secure application using security by separation. Therefore, it automatically includes Trusted Firmware-M that prepares the required peripherals and secure services to be available for the application.

To build the sample, follow the instructions in Building an application for your preferred building environment. See also Programming an application for programming steps and Testing and optimization for general information about testing and debugging in the nRF Connect SDK.

Note

When building repository applications in the SDK repositories, building with sysbuild is enabled by default. If you work with out-of-tree freestanding applications, you need to manually pass the --sysbuild parameter to every build command or configure west to always use it.

When building this sample with Sysbuild for an SoC that has a network core, the IPC radio firmware is automatically applied to the build. The IPC radio is one of the companion components in the nRF Connect SDK and allows to use the radio peripheral from another core in a multicore device. If needed, you can modify the IPC radio configuration in the prj.conf source file in the sample’s sysbuild/ipc_radio directory.

To build the sample with HID SCI support, use -DFILE_SUFFIX=hid_sci.

Testing

After programming the sample to your development kit, you can test it either by connecting the kit as keyboard device to a Microsoft Windows computer or by connecting to it with nRF Connect for Desktop.

Testing with a Microsoft Windows computer

To test with a Microsoft Windows computer that has a Bluetooth radio, complete the following steps:

  1. Power on your development kit.

  2. Press Button 4 on the kit if the device is not advertising. A blinking LED 1 indicates that the device is advertising.

  3. Connect to the kit with a terminal emulator (for example, the Serial Terminal app). See Testing and optimization for the required settings and steps.

  4. On your Windows computer, search for Bluetooth devices and connect to the device named “NCS HIDS keyboard”.

  5. Observe that the connection state is indicated by LED 2.

  6. Open a text editor (for example, Notepad).

  7. Repeatedly press Button 1 on the kit. Every button press sends 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.

  8. Press Button 2 and hold it while pressing Button 1. Observe that the next letter of the “hello” message appears as capital letter. This is because Button 2 simulates the Shift key.

  9. Turn on Caps Lock on the computer. Observe that LED 3 turns on. This confirms that the output report characteristic has been written successfully on the HID device.

  10. Turn Caps Lock off on the computer. Observe that LED 3 turns off.

  11. Disconnect the computer from the device by removing the device from the computer’s devices list.

Testing with Bluetooth Low Energy app

To test with the Bluetooth Low Energy app, complete the following steps:

  1. Power on your development kit.

  2. Press Button 4 on the kit if the device is not advertising. A blinking LED 1 indicates that the device is advertising.

  3. Connect to the kit with a terminal emulator (for example, the Serial Terminal app). See Testing and optimization for the required settings and steps.

  4. Start nRF Connect for Desktop.

  5. Open the Bluetooth Low Energy app.

  6. Connect to the device from the app. The device is advertising as “NCS HIDS keyboard”.

  7. Pair the devices:

    1. Click the Settings button for the device in the app.

    2. Select Pair.

    3. Optionally, select Perform Bonding.

    Optionally, check Enable MITM protection to pair with MITM protection and use a button on the device to confirm or reject the passkey value.

    Wait until the bond is established before you continue.

  8. Observe that the connection state is indicated by LED 2.

  9. Observe that the services of the connected device are shown.

  10. Enable notifications for all HID characteristics.

  11. Press Button 1 on the kit. Observe that two notifications are received on one of the HID Report characteristics, denoting press and release for one character of the test message.

    The first notification has the value 00000B0000000000, the second has the value 0000000000000000. The received values correspond to press and release of character “h”. The format used for keyboard reports is the following byte array: [modifier, reserved, Key1, Key2, Key3, Key4, Key5, Key6].

    Similarly, further press and release events will result in press and release notifications of subsequent characters of the test string. Therefore, pressing Button 1 again will result in notification of press and release reports for character “e”.

  12. Press Button 2 and hold it while pressing Button 1. Pressing Button 2 changes the modifier bit to 02, which simulates pressing the Shift key on a keyboard.

    Observe that two notifications are received on one of the HID Report characteristics, denoting press and release for one character of the test message. The first one has the value 02000F0000000000, the second has the value 0200000000000000. These values correspond to press and release of character “l” with the Shift key pressed.

  13. In the app, select the HID Report (which has UUID 0x2A4D and the properties Read, WriteWithoutResponse, and Write). Enter any number that has bit 1 set to 1 (for example 02) in the text box and click the tick mark button. This sets the Output Report to the written value, in which setting bit 1 to 1 simulates turning Caps Lock ON. Other bits are responsible for controlling other Output Report fields that are not reflected in the sample’s UI, for example Num Lock.

    Observe that LED 3 is lit.

  14. Select the same HID Report again. Enter any number that has bit 1 set to 0 (for example 00) in the text box and click Write. Setting this bit of the Output Report to 0 simulates turning Caps Lock OFF.

    Observe that LED 3 turns off.

  15. Disconnect the device in the app. Observe that no new notifications are received.

  16. If the advertising did not start automatically, press Button 4 to continue advertising.

  17. As bond information is preserved by the app, you can immediately reconnect to the device by clicking the Connect button again.

Testing with Android using NFC for pairing

To test with an Android smartphone/tablet, complete the following steps:

  1. Touch the NFC antenna with the smartphone or tablet and observe that LED 4 is lit.

  2. Observe that the device is advertising, as indicated by blinking LED 1.

  3. Confirm pairing with ‘Nordic_HIDS_keyboard’ in a pop-up window on the smartphone/tablet.

  4. Observe that the connection state is indicated by LED 2.

  5. Repeatedly press Button 1 on the kit. Every button press sends one character of the test message “hello” to the smartphone (the test message includes a carriage return).

  6. Press Button 2 and hold it while pressing Button 1. Observe that the next letter of the “hello” message appears as a capital letter. This is because Button 2 simulates the Shift key.

  7. Touch the NFC antenna with the same central device again.

  8. Observe that devices disconnect.

Dependencies

This sample uses the following nRF Connect SDK libraries:

When the NFC OOB pairing feature (CONFIG_SAMPLE_NFC_OOB_PAIRING) is enabled, it also uses the Type 2 Tag library from sdk-nrfxlib:

The sample uses the following Zephyr libraries:

  • include/zephyr/types.h

  • include/sys/printk.h

  • include/sys/byteorder.h

  • GPIO Interface

  • Settings

  • API:

    • include/bluetooth/bluetooth.h

    • include/bluetooth/hci.h

    • include/bluetooth/conn.h

    • include/bluetooth/uuid.h

    • include/bluetooth/gatt.h

    • samples/bluetooth/gatt/bas.h

References

The sample also uses the following secure firmware component: