HID Service module

Use the HID Service module to handle the GATT Human Interface Device Service. The GATT Service is used to exchange HID data with the peer connected over Bluetooth®. For this reason, it is mandatory for every nRF Desktop peripheral.

Module events

Source Module

Input Event

This Module

Output Event

Sink Module

Bluetooth LE advertising module

ble_peer_event

hids

Bluetooth LE state module

Source modules for config_event

config_event

HID Service module

hid_notification_event

HID forward module

hid_report_event

HID state module

HID Service module

USB state module

Source modules for module_state_event

module_state_event

config_event

Sink modules for config_event

hid_notification_event

HID Service module

hid_report_sent_event

HID forward module

HID state module

Motion module

hid_report_subscription_event

HID forward module

HID state module

Motion module

module_state_event

Sink modules for module_state_event

hid_report_event

Bluetooth LE Quality of Service module

Bluetooth LE scanning module

Device Firmware Upgrade module

HID forward module

HID state module

HID Service module

USB state module

Note

See the Overview: Firmware architecture for more information about the event-based communication in the nRF Desktop application and about how to read this table.

Configuration

Complete the following steps to configure the module:

  1. Complete the basic Bluetooth configuration, as described in Bluetooth in nRF Desktop. During this configuration, you must enable the CONFIG_BT_PERIPHERAL Kconfig option for every nRF Desktop peripheral. When this option is enabled, the CONFIG_DESKTOP_HID_PERIPHERAL is set to y, which enables the following two additional options, among others:

    This step also enables the GATT HID Service.

  2. Enable the Bluetooth connection context (CONFIG_BT_CONN_CTX). This is required by the GATT HID Service.

  3. Configure the GATT Human Interface Device (HID) Service. See its documentation for configuration details.

    Tip

    If the HID report configuration is identical to the configuration used for one of the existing devices, you can use the same GATT HID Service configuration.

The HID Service application module forwards the information about the enabled HID notifications to other application modules using hid_report_subscription_event. These notifications are enabled by the connected Bluetooth® Central. By default, the hids application module starts forwarding the subscriptions right after the Bluetooth connection is secured.

You can define additional delay for forwarding the notifications on connection (CONFIG_DESKTOP_HIDS_FIRST_REPORT_DELAY). Sending the first HID report to the connected Bluetooth peer is delayed by this period of time.

Note

The nRF Desktop centrals perform the GATT service discovery and reenable the HID notifications on every reconnection. A HID report that is received before the subscription is reenabled will be dropped before it reaches the application. The CONFIG_DESKTOP_HIDS_FIRST_REPORT_DELAY is used for keyboard reference design (nRF52832 Desktop Keyboard) to make sure that the input will not be lost on reconnection with the nRF Desktop dongle.

Implementation details

The HID Service application module initializes and configures the GATT HID Service. The application module registers the HID report map and every HID report that was enabled in the application configuration. Detailed information about HID-related configuration in nRF Desktop is available in the HID state module documentation.

Sending HID input reports

After subscriptions are enabled in HID state module, the HID state module sends the HID input reports as hid_report_event. The HID Service application module sends the report over Bluetooth LE and submits the hid_report_sent_event to inform that the given HID input report was sent.

HID keyboard LED output report

The module can receive an HID output report setting state of the keyboard LEDs, e.g. state of the Caps Lock. The report is received from the Bluetooth connected host. The module forwards the report using hid_report_event, that is handled either by HID state module (for peripheral) or HID forward module (for central).

Right now, the only board that displays information received in the HID output report using hardware LEDs is nrf52840dk_nrf52840 in ZDebug_keyboard configuration. The keyboard reference design (nrf52kbd_nrf52832) has only one LED that is used to display the Bluetooth LE peer state. Detailed information about the usage of LEDs to display information about Bluetooth LE peer state and system state to the user is available in the LED state module documentation. Detailed information about displaying state of the HID keyboard LEDs using hardware LEDs is available in HID state module documentation.

Bluetooth LE connections and disconnections

The module informs the GATT HID Service about the Bluetooth LE connections and disconnections using bt_hids_connected() and bt_hids_disconnected(), respectively.

Registered handlers

The GATT HID Service uses registered handlers to send the following information to the HID Service application module:

  • Enabling or disabling a HID input report notification.

  • Incoming HID output or feature reports.

  • Switching between the boot mode and the report mode.

HID notifications

The hid_notification_event is used to synchronize the information about enabling or disabling the HID notifications for the HID input report. The event is submitted when the GATT HID Service calls a callback related to enabling or disabling the notifications and the event is received only by the hids application module.

Transport for configuration channel

The HID Service application module works as a transport for the Configuration channel and exchanges the Configuration channel HID reports over Bluetooth LE. The module communicates with the Configuration channel listeners using config_event.