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 module_state_event	module_state_event
Source modules for config_event	config_event
HID Service module	hid_notification_event
Source modules for hid_report_event	hid_report_event
			config_event	Sink modules for config_event
			hid_notification_event	HID Service module
			hid_report_event	Sink modules for hid_report_event
			hid_report_sent_event	HID forward module
				HID state module
				Motion module
			hid_report_subscriber_event	HID forward module
				HID state module
			hid_report_subscription_event	HID forward module
				HID state module
				Motion module
			module_state_event	Sink modules for module_state_event

Note

See the Application overview for more information about the event-based communication in the nRF Desktop application and about how to read this table.

Configuration

Complete the basic Bluetooth configuration, as described in nRF Desktop: Bluetooth.

Make sure that both CONFIG_DESKTOP_ROLE_HID_PERIPHERAL and CONFIG_DESKTOP_BT_PERIPHERAL Kconfig options are enabled. The HID Service application module is enabled by the CONFIG_DESKTOP_HIDS_ENABLE option, which is implied by CONFIG_DESKTOP_BT_PERIPHERAL together with other GATT Services that are required for a HID device.

GATT Service configuration

The CONFIG_DESKTOP_HIDS_ENABLE option selects the following Kconfig options:

• The CONFIG_BT_HIDS option that automatically enables the GATT Human Interface Device (HID) Service.

• The CONFIG_BT_CONN_CTX option that automatically enables the Bluetooth connection context, which is required by the GATT HID Service.

The nRF Desktop application modifies the default Kconfig option values, defined by the GATT Human Interface Device (HID) Service, to tailor the default configuration to application needs. The configuration is tailored for either nRF Desktop mouse (CONFIG_DESKTOP_PERIPHERAL_TYPE_MOUSE) or nRF Desktop keyboard (CONFIG_DESKTOP_PERIPHERAL_TYPE_KEYBOARD). For more details, see the src/modules/Kconfig.hids file.

Tip

If the HID report configuration is identical to the default configuration of either nRF Desktop mouse or keyboard, you do not need to modify the GATT HID Service configuration. Otherwise, see GATT Human Interface Device (HID) Service documentation for configuration details.

HID subscriber configuration

The HID reports are forwarded to the connected GATT Client after it enables the HID notifications.

On an nRF Desktop peripheral, the HID state module handles generating HID reports as per your input and providing the reports to the HID subscriber. The HID Service application module subscribes for HID reports using hid_report_subscriber_event and hid_report_subscription_event. 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 event once the given HID input report has been sent.

You can use the following Kconfig options to modify HID subscription parameters used in the hid_report_subscriber_event:

• CONFIG_DESKTOP_HIDS_SUBSCRIBER_PRIORITY (hid_report_subscriber_event.priority).

• CONFIG_DESKTOP_HIDS_SUBSCRIBER_REPORT_MAX (hid_report_subscriber_event.report_max).

For more details, see the Kconfig help.

Note

For the Bluetooth connections, the information that GATT notification with a HID report was sent is delayed by one Bluetooth LE connection interval. Because of this delay, the module always uses pipeline (hid_report_subscriber_event.pipeline_size) of two sequential HID reports to make sure that data can be sent on every Bluetooth LE connection event.

HID subscription delay

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 option is set to 1000 ms for nRF Desktop keyboards (CONFIG_DESKTOP_PERIPHERAL_TYPE_KEYBOARD) to make sure that the input is not 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. For detailed information about the HID-related configuration in the nRF Desktop, see the HID configuration documentation.

HID keyboard LED output report

The module can receive a HID output report setting state of the keyboard LEDs, for example, 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 by HID state module.

Right now, only development kits in keyboard build type configuration display information received in the HID output report using hardware LEDs. The keyboard reference design (nrf52kbd) 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 HID Service 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.