HID forward module

Module events
Configuration
Implementation details

Use the HID forward module for the following purposes:

Receive the HID input reports from the peripherals connected over Bluetooth®.
Forward the HID input reports in report or boot protocol.
Forward the Configuration channel data between the peripherals connected over Bluetooth and the host.

Module events 

Source Module	Input Event	This Module	Output Event	Sink Module
Bluetooth LE discovery module	`ble_discovery_complete_event`	`hid_forward`
Source modules for config_event	`config_event`
Bluetooth LE advertising module	`ble_peer_event`
Bluetooth LE state module	`ble_peer_event`
Bluetooth LE bond module	`ble_peer_operation_event`
HID forward module	`hid_report_event`
HID state module
HID Service module
USB state module
HID Service module	`hid_report_sent_event`
USB state module	`hid_report_sent_event`
HID Service module	`hid_report_subscription_event`
USB state module	`hid_report_subscription_event`
Source modules for module_state_event	`module_state_event`
Power manager module	`power_down_event`
Bluetooth LE advertising module	`wake_up_event`
Buttons module
HID forward module
Motion module
Power manager module
Wheel module
			`config_event`	Sink modules for config_event
			`hid_report_event`	Sink modules for hid_report_event
			`module_state_event`	Sink modules for module_state_event
			`wake_up_event`	Sink modules for wake_up_event

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:

Complete the basic Bluetooth configuration, as described in Bluetooth in nRF Desktop. Make sure that both CONFIG_DESKTOP_ROLE_HID_DONGLE and CONFIG_DESKTOP_BT_CENTRAL are enabled.
The GATT Human Interface Device Service (HIDS) Client (CONFIG_BT_HOGP) is enabled by default. An nRF Desktop dongle does not generate its own HID input reports. The dongle uses HID forward module to forward the HID reports. The reports are received by the HID service client from the peripherals connected over Bluetooth.

Note

The maximum number of supported HID reports (CONFIG_BT_HOGP_REPORTS_MAX) is set by default for the nRF Desktop dongle, which supports two peripherals with an average of six HID reports each. Make sure to align this configuration value for other use cases, for example, if the dongle supports more peripherals.
The CONFIG_DESKTOP_HID_FORWARD_ENABLE option enables the HID forward module and is automatically selected by the CONFIG_DESKTOP_ROLE_HID_DONGLE option.
nRF Desktop dongle can forward either mouse or keyboard boot reports. The forwarded boot report type is specified using the following Kconfig options:
- CONFIG_DESKTOP_HID_BOOT_INTERFACE_KEYBOARD - This option enables forwarding keyboard boot reports.
- CONFIG_DESKTOP_HID_BOOT_INTERFACE_MOUSE - This option enables forwarding mouse boot reports.
Those options affect USB state module that subscribes for HID boot reports. The Dongle forwards HID reports from both mouse and keyboard, and so either option works if you want to have the Dongle work as boot mouse or boot keyboard. For more information about the configuration of the HID boot protocol, see the boot protocol configuration section in the USB state module documentation.

You can set the queued HID input reports limit using the CONFIG_DESKTOP_HID_FORWARD_MAX_ENQUEUED_REPORTS Kconfig option.

Implementation details 

This section describes the functioning of the HID forward module.

The USB state module can be configured to have one or more instances of the HID-class USB device. If there is more than one instance of the HID-class USB device, this number must match the maximum number of bonded Bluetooth peripheral devices. Each instance of HID-class USB device subscribes to HID reports forwarded by the HID forward module.

The HID forward module has an array of subscribers, one for each HID-class USB device. The possible cases that impact how the host to which the nRF desktop dongle is connected interprets the reports are as follows:

Number of HID-class USB devices is equal to number of bonded peripheral devices. In this case:
- Reports from every bonded peripheral will be forwarded to a dedicated HID-class USB device.
- The host can distinguish the source of the report.
Only one HID-class USB device is used. In this case:
- Reports from all peripherals will be forwarded to a single HID-class USB device.
- The host cannot distinguish the source of the report.

When reports are forwarded to the USB state module, each HID-class USB device is treated independently. This means that the HID forward module can concurrently send reports to every available HID-class USB device, if a report from the linked peripheral is available.

When received by the module, the HID boot protocol reports come with the report ID assigned to REPORT_ID_RESERVED. This ID is later changed by the HID forward module to either REPORT_ID_BOOT_KEYBOARD or REPORT_ID_BOOT_MOUSE. The choice depends on fact, if the Bluetooth device is boot mouse or keyboard. While receiving a subscription event, the HID forward module updates the HID protocol of peripherals connected through Bluetooth that are associated with the given subscriber.

Forwarding HID input reports 

After Bluetooth LE discovery module successfully discovers a connected peripheral, the HID forward module automatically subscribes for every HID input report provided by the peripheral. The subscriber can use either the HID boot protocol or the HID report protocol, but both protocols cannot be used at the same time. In the current implementation, the USB state module supports either the HID boot keyboard or the HID boot mouse reports, because the HID boot protocol code is set using a single Kconfig option that is common for all of the instances of the USB HID.

The hidc_read() callback is called when HID input report is received from the connected peripheral. The received HID input report data is converted to hid_report_event.

hid_report_event is submitted and then the HID-class USB device configured by USB state module forwards it to the host. When a HID report is sent to the host by the HID-class USB device, the HID forward module receives a hid_report_sent_event with the identifier of this device.

Enqueuing incoming HID input reports

The HID forward module forwards only one HID input report to the HID-class USB device at a time. Another HID input report may be received from a peripheral connected over Bluetooth before the previous one was sent. In that case, hid_report_event is enqueued and submitted later. Up to the number of reports specified in CONFIG_DESKTOP_HID_FORWARD_MAX_ENQUEUED_REPORTS reports can be enqueued at a time for each report type and for each connected peripheral. If there is not enough space to enqueue a new event, the module drops the oldest enqueued event that was received from this peripheral (of the same type).

Upon receiving the hid_report_sent_event, the HID forward module submits the hid_report_event enqueued for the peripheral that is associated with the HID-class USB device. The enqueued report to be sent is chosen by the HID forward module in the round-robin fashion. The report of the next type will be sent if available. If not available, the next report type will be checked until a report is found or there is no report in any of the queues. If there is no hid_report_event in the queue, the module waits for receiving data from peripherals.

Forwarding HID output reports 

When the HID forward module receives a hid_report_event that contains an output report from a USB state module, it tries to forward the output report. The HID output report is forwarded to all of the Bluetooth connected peripherals that forward the HID data to the HID subscriber that is source of the HID output report. The HID output report is never forwarded to peripheral that does not support it.

If the GATT write without response operation is in progress for the given HID output report ID and connected peripheral, the report is placed in a queue and sent later. The HID forward module sends information only about the last received HID output report with given ID. If changes of state related to the HID output report with the given ID are frequent, some intermediate states can be omitted by the HID forward module.

Bluetooth Peripheral disconnection 

On a peripheral disconnection, nRF Desktop central informs the host that all the pressed keys reported by the peripheral are released. This is done to make sure that the user will not observe a problem with a key stuck on peripheral disconnection.

Configuration channel data forwarding 

The HID forward module forwards the Configuration channel data between the host and the peripherals connected over Bluetooth. The data is exchanged with the peripheral connected over Bluetooth using HID feature report or HID output report.

In contrast to HID configurator for nRF Desktop, the HID forward module does not use configuration channel request to get hardware ID (HW ID) of the peripheral. The peripheral identification on nRF Desktop central is based on the HW ID that is received from Bluetooth LE discovery module when peripheral discovery is completed. The peripheral uses Device description module to provide the HW ID to the nRF Desktop central.

The HID forward module only forwards the configuration channel requests that come from the USB connected host, it does not generate its own requests.

For more details, see Configuration channel documentation.