.. _nrf_desktop_hids: HID Service module ################## .. contents:: :local: :depth: 2 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 ************* .. include:: ../../../../../../applications/nrf_desktop/doc/event_propagation.rst :start-after: table_hids_start :end-before: table_hids_end .. note:: |nrf_desktop_module_event_note| Configuration ************* Complete the basic Bluetooth configuration, as described in :ref:`nrf_desktop_bluetooth_guide`. Make sure that both :option:`CONFIG_DESKTOP_ROLE_HID_PERIPHERAL` and :option:`CONFIG_DESKTOP_BT_PERIPHERAL` Kconfig options are enabled. The HID Service application module is enabled by the :option:`CONFIG_DESKTOP_HIDS_ENABLE` option, which is implied by :option:`CONFIG_DESKTOP_BT_PERIPHERAL` together with other GATT Services that are required for a HID device. GATT Service configuration ========================== The :option:`CONFIG_DESKTOP_HIDS_ENABLE` option selects the following Kconfig options: * The :kconfig:option:`CONFIG_BT_HIDS` option that automatically enables the :ref:`nrf:hids_readme`. * The :kconfig:option:`CONFIG_BT_CONN_CTX` option that automatically enables the :ref:`nrf:bt_conn_ctx_readme`, which is required by the |GATT_HID|. The nRF Desktop application modifies the default Kconfig option values, defined by the :ref:`nrf:hids_readme`, to tailor the default configuration to application needs. The configuration is tailored for either nRF Desktop mouse (:option:`CONFIG_DESKTOP_PERIPHERAL_TYPE_MOUSE`) or nRF Desktop keyboard (:option:`CONFIG_DESKTOP_PERIPHERAL_TYPE_KEYBOARD`). For more details, see the :file:`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| configuration. Otherwise, see :ref:`nrf:hids_readme` documentation for configuration details. HID SCI support --------------- The :option:`CONFIG_DESKTOP_HIDS_SCI_ENABLE` option selects :kconfig:option:`CONFIG_BT_HIDS_SCI` and the required Bluetooth LE Host and Controller features for support of shorter connection intervals. The option cannot be used together with :kconfig:option:`CONFIG_CAF_BLE_USE_LLPM`. It depends on Bluetooth Controller support for shorter connection intervals (:kconfig:option:`CONFIG_BT_CTLR_SHORTER_CONNECTION_INTERVALS_SUPPORT`). The SoftDevice Link Layer (:kconfig:option:`CONFIG_BT_LL_SOFTDEVICE`) is an example of a Bluetooth LE Link Layer with SCI support. By default, the GATT pool sizes defined in the :file:`Kconfig.ble` file and the maximum number of HIDS attributes defined in the :file:`src/modules/Kconfig.hids` file are automatically aligned to the needs of the nRF Desktop application, including HID SCI support. If you need adjustments, for example due to changing the set of supported HID reports, make sure that these values remain sufficient. The default HID SCI mode transport parameters for nRF Desktop peripherals are defined in the :file:`src/modules/Kconfig.sci.defaults.periph` file. .. note:: The default maximum peripheral latency for the FAST mode is ``99``. If a lower first-packet latency is required, set :kconfig:option:`CONFIG_BT_HIDS_SCI_FAST_MAX_LATENCY` to ``0``. On the nRF54L15 DK in the release configuration, this results in the first-packet latency being decreased by about 2 ms. At the same time, the current consumption in Bluetooth LE connected idle state increases - for nRF54L15DK in the release configuration from around 250 µA to around 1 mA. You can choose other maximum peripheral latency values to balance the first-packet latency and power consumption for your application. Mode change requests received through the HID control point characteristic are handled by the :ref:`nrf_desktop_ble_latency`. See the documentation page for implementation 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 :ref:`nrf_desktop_hid_state` 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 :c:struct:`hid_report_subscriber_event` and :c:struct:`hid_report_subscription_event`. After subscriptions are enabled in |hid_state|, the |hid_state| sends the HID input reports as :c:struct:`hid_report_event`. The HID Service application module sends the report over Bluetooth LE and submits the :c:struct:`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 :c:struct:`hid_report_subscriber_event`: * :option:`CONFIG_DESKTOP_HIDS_SUBSCRIBER_PRIORITY` (:c:member:`hid_report_subscriber_event.priority`). * :option:`CONFIG_DESKTOP_HIDS_SUBSCRIBER_REPORT_MAX` (:c:member:`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 (:c:member:`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 (:option:`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 :option:`CONFIG_DESKTOP_HIDS_FIRST_REPORT_DELAY` option is set to 1000 ms for nRF Desktop keyboards (:option:`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|. 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 :ref:`nrf_desktop_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 :c:struct:`hid_report_event` that is handled by |hid_state|. Right now, only development kits in ``keyboard`` build type configuration display information received in the HID output report using hardware LEDs. The nRF54L15 DK keyboard configuration uses hardware LEDs 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 :ref:`nrf_desktop_led_state` documentation. Detailed information about displaying state of the HID keyboard LEDs using hardware LEDs is available in :ref:`nrf_desktop_hid_state` documentation. Bluetooth LE connections and disconnections =========================================== The module informs the |GATT_HID| about the Bluetooth LE connections and disconnections using :c:func:`bt_hids_connected` and :c:func:`bt_hids_disconnected`, respectively. Registered handlers =================== The |GATT_HID| 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. * Writes to the HID control point characteristic. HID notifications ================= The :c:struct:`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| calls a callback related to enabling or disabling the notifications and the event is received only by the HID Service application module. HID control point ================= The connected Bluetooth host can write to the HID control point characteristic to inform about host suspend or exit suspend, or to request a HID SCI (Shorter Connection Intervals) mode change. The HID Service application module translates these writes into dedicated application events: * :c:struct:`hid_host_suspend_event` - Submitted when the host enters or exits suspend. The :c:member:`hid_host_suspend_event.suspended` field indicates whether the host entered or exited suspend. * :c:struct:`hid_sci_mode_request_event` - Submitted when the host requests an SCI mode update. The :c:member:`hid_sci_mode_request_event.mode` field contains the requested :c:enum:`bt_hids_sci_mode_value`. This event is submitted only if the :option:`CONFIG_DESKTOP_HIDS_SCI_ENABLE` Kconfig option is enabled. Transport for configuration channel =================================== The HID Service application module works as a transport for the :ref:`nrf_desktop_config_channel` and exchanges the |conf_channel| HID reports over Bluetooth LE. The module communicates with the |conf_channel| listeners using :c:struct:`config_event`.