USB state module

The USB state module is responsible for tracking the USB connection. It is also responsible for transmitting HID data through USB on the application’s device.

Module events

Source Module

Input Event

This Module

Output Event

Sink Module

Source modules for config_event

config_event

usb_state

HID forward module

hid_report_event

HID state module

HID Service module

USB state module

Source modules for module_state_event

module_state_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

hid_report_sent_event

HID forward module

HID state module

Motion module

hid_report_subscriber_event

HID state module

hid_report_subscription_event

HID forward module

HID state module

Motion module

module_state_event

Sink modules for module_state_event

usb_state_event

Battery charger module

Bluetooth LE connection parameters module

Motion module

USB state power manager module

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

The module is enabled by selecting the CONFIG_DESKTOP_USB_ENABLE option.

The CONFIG_DESKTOP_USB_ENABLE option is implied by the CONFIG_DESKTOP_ROLE_HID_DONGLE option. The module is enabled by default for the nRF Desktop dongles because the dongles forward the HID data to the host connected over USB. See the HID configuration documentation for details.

The module can be used with either the USB legacy stack or the USB next stack. The USB stack is selected by enabling one of the following Kconfig choice options:

Note

The USB next stack integration is experimental. The HID boot protocol integration is not yet fully tested and may not work properly. The secondary image slot background erase in Device Firmware Upgrade module may cause missing USB HID subscriptions after a USB cable is attached.

Some of the properties are configured in the same way for both stacks, but part of the configuration is specific to the selected USB stack. See the following sections for details.

USB device identifiers

USB device identifiers are defined in the same way for both USB stacks. The module relies on common HID device identifiers defined for the nRF Desktop application.

For the USB legacy stack, this results in updating defaults for the following Kconfig options:

For the USB next stack, the module uses dedicated APIs to set the USB device identifiers during initialization.

USB HID class instance configuration

The nRF Desktop device can provide multiple instances of HID-class USB. By default, the number of the HID-class USB instances should be set to:

See the subsections below for details.

nRF Desktop peripheral

The nRF Desktop peripheral devices by default use only a single HID-class USB instance. In that case, this instance is used for all the HID reports.

Enable CONFIG_DESKTOP_USB_SELECTIVE_REPORT_SUBSCRIPTION to use more than one USB HID-class instance on the nRF Desktop peripheral. Make sure to configure additional HID-class USB instances and create an additional usb_state_def.h header in the configuration. The header assigns HID input reports to the HID-class USB instances. A given HID report can be handled only by a single HID-class USB instance. For example, the file contents can look as follows:

#include "hid_report_desc.h"

/* This configuration file is included only once from usb_state module and holds
 * information about HID report subscriptions of USB HID instances.
 */

/* This structure enforces the header file is included only once in the build.
 * Violating this requirement triggers a multiple definition error at link time.
 */
const struct {} usb_state_def_include_once;

static const uint32_t usb_hid_report_bm[] = {
       BIT(REPORT_ID_MOUSE),
       BIT(REPORT_ID_KEYBOARD_KEYS),
};

The usb_hid_report_bm defines HID reports handled by a HID-class USB instance, in a bitmask format. In this example, the HID mouse input report is handled by the first HID-class USB instance and the HID keyboard input report is handled by the second HID-class USB instance.

nRF Desktop dongle

The nRF Desktop dongle device can use either a single HID-class USB instance or a number of instances equal to that specified in the CONFIG_DESKTOP_HID_DONGLE_BOND_COUNT option. If only one instance is used, reports from all peripherals connected to the dongle are forwarded to the same instance. In other cases, reports from each of the bonded peripherals are forwarded to a dedicated HID-class USB instance. The same instance is used after reconnection.

USB HID configuration in USB legacy stack

For the USB legacy stack, the CONFIG_DESKTOP_USB_STACK_LEGACY selects the required dependencies: CONFIG_USB_DEVICE_STACK and CONFIG_USB_DEVICE_HID Kconfig options. The number of HID-class USB instances in the USB legacy stack is specified by CONFIG_USB_HID_DEVICE_COUNT. The default value of this option is updated to match requirements for either an nRF Desktop peripheral or a dongle.

Low latency device configuration

The module sets the default value of CONFIG_USB_HID_POLL_INTERVAL_MS to 1. For low latency of HID reports, the device requests a polling rate of 1 ms.

Boot protocol configuration

The CONFIG_DESKTOP_HID_BOOT_INTERFACE_MOUSE and CONFIG_DESKTOP_HID_BOOT_INTERFACE_KEYBOARD Kconfig options are used to control support of HID boot reports in the nRF Desktop application. The module aligns the USB HID boot protocol configuration with the application configuration. The module sets the default value of the CONFIG_USB_HID_BOOT_PROTOCOL Kconfig option and calls the usb_hid_set_proto_code() function during initialization to set the USB HID boot interface protocol code. Common HID boot protocol code is used for all of the HID-class USB instances.

USB HID configuration in USB next stack

For the USB next stack, the CONFIG_DESKTOP_USB_STACK_NEXT selects the CONFIG_USB_DEVICE_STACK_NEXT Kconfig option. Every USB HID-class instance is configured through a separate DTS node compatible with zephyr,hid-device. The DTS node configures, among others, the used HID boot protocol, the size of the longest HID input report, and the HID polling rate. You can configure your preferred USB HID polling rate using the in-polling-rate property of the DTS node. The lowest polling rate that is supported by the USB High-Speed is 125 µs, which corresponds to 8 kHz report rate. The lowest polling rate supported by devices that do not support USB High-Speed is 1000 µs, which corresponds to 1 kHz report rate. Make sure to update the DTS configuration to match requirements of your application. nRF Desktop application defines the USB HID-class instances used by the USB next stack for all of the supported boards and file suffixes. See the existing configurations for reference.

Defining USB HID-class instances in the DTS, by default, enables the CONFIG_USBD_HID_SUPPORT Kconfig option.

USB wakeup configuration

The nRF Desktop device can work as a source of wakeup events for the host device if connected through the USB. To use the feature, enable the CONFIG_DESKTOP_USB_REMOTE_WAKEUP option. This option selects the CONFIG_USB_DEVICE_REMOTE_WAKEUP Kconfig option to enable required dependencies if USB legacy stack is used. The USB next stack supports remote wakeup by default, and you do not need to select any additional Kconfig dependencies.

When host enters the suspended state, the USB will be suspended as well. This state change is used to suspend the nRF Desktop device (see Power manager module). When the nRF Desktop device wakes up from standby, the USB state module will issue a wakeup request on the USB.

Note

The USB wakeup request is transmitted to the host only if the host enables this request before suspending the USB.

Implementation details

The USB state module registers all of the configured instances of HID-class USB and initializes the USB subsystem.

USB state tracking

The necessary callbacks are connected to the module to ensure that the state of the USB connection is tracked. From the application’s viewpoint, USB can be in the following states:

These states are broadcasted by the USB state module with a usb_state_event. When the device is connected to the host and configured for the communication, the module will broadcast the USB_STATE_ACTIVE state.

HID data handling

The module handles USB HID input report subscriptions. For the USB legacy stack, all of the USB HID-class instances subscribe to all supported HID reports for the selected protocol. This occurs when the USB stack reports USB_DC_CONFIGURED, and the USB_STATE_ACTIVE state is broadcasted. When leaving the active state, the module will unsubscribe from receiving the HID reports. For the USB next stack, a separate callback provided by USB HID-class API is used to track HID subscription state.

When the HID report data is transmitted through hid_report_event, the module will pass it to the associated USB HID-class instance. Upon data delivery, hid_report_sent_event is submitted by the module.

Note

Only one HID input report is transmitted by the module to a single instance of HID-class USB device at any given time. Different instances can transmit reports in parallel.

The USB state module is a transport for Configuration channel when the channel is enabled.

The module also handles a HID keyboard LED output report received through USB from the connected host. The module sends the report using hid_report_event, that is handled either by HID state module (for peripheral) or by the HID forward module (for dongle).

nRF54H20 support

Due to the characteristics of the nRF54H20 USB Device Controller (UDC), several changes have been made in the USB state module to support the nRF54H20 platform:

  • The USB state module creates a separate thread to initialize, enable, and disable the USB stack.

  • The module disables the USB stack when the USB cable is disconnected and enables the stack when the cable is connected.

These changes are applicable to the nRF54H20 platform only. They are necessary to ensure proper USB stack operation on the nRF54H20 platform.

The USB stack cannot be initialized from the system workqueue thread, because it causes a deadlock. Because of that, a separate thread is used to initialize the USB stack. For more details, see the CONFIG_DESKTOP_USB_INIT_THREAD Kconfig option. The UDC is powered down whenever the USB cable is disconnected, failing to trigger the necessary callbacks to the USB stack. It may cause the USB stack to become non-functional. The USB stack is disabled upon disconnecting the cable to work around this issue. For more details, see the CONFIG_DESKTOP_USB_STACK_NEXT_DISABLE_ON_VBUS_REMOVAL Kconfig option.