HID provider mouse module

The HID provider mouse module is a HID report provider integrated with the HID state module. The module is responsible for providing the HID mouse input report and the HID boot mouse input report.

The module listens to the user input (button_event, wheel_event, and motion_event) and communicates with the HID state module. It provides HID mouse reports when requested by the HID state module. It also notifies the HID state module when new data is available.

For details related to the HID report providers integration in the HID state module, see the Providing HID input reports documentation section.

Module events

Source Module

Input Event

This Module

Output Event

Sink Module

Buttons module

button_event

hid_provider_mouse

Button simulator module

Function key module

HID provider consumer control module

hid_report_provider_event

HID provider keyboard module

HID provider mouse module

HID provider system control module

Source modules for module_state_event

module_state_event

Motion module

motion_event

Wheel module

wheel_event

hid_report_event

Sink modules for hid_report_event

hid_report_provider_event

HID state module

HID provider consumer control module

HID provider keyboard module

HID provider mouse module

HID provider system control 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

You can enable the default implementation of the HID provider using the CONFIG_DESKTOP_HID_REPORT_PROVIDER_MOUSE Kconfig option. This option is enabled by default if the device uses HID provider events (CONFIG_DESKTOP_HID_REPORT_PROVIDER_EVENT) and supports HID mouse reports (CONFIG_DESKTOP_HID_REPORT_MOUSE_SUPPORT). The default implementation of the HID provider uses a predefined format of HID reports, which is aligned with the default HID report map in the common configuration (CONFIG_DESKTOP_HID_REPORT_DESC). The module also provides HID boot mouse input report if it is supported (CONFIG_DESKTOP_HID_BOOT_INTERFACE_MOUSE).

Alternatively, you can substitute the module with a custom HID mouse report provider implementation. Using the custom provider allows you to modify the sources of user input and the HID report format. Enable the CONFIG_DESKTOP_HID_REPORT_PROVIDER_MOUSE_ALT Kconfig option to use a custom HID mouse report provider. The option disables the default HID mouse report provider. Make sure to introduce the custom HID mouse report provider if you enable this option.

Default implementation

If you use the default implementation, you only need to configure the HID keymap for the module.

HID keymap

The module uses the HID keymap utility to map an application-specific key ID to a HID report ID and HID usage ID pair. The module selects the CONFIG_DESKTOP_HID_KEYMAP Kconfig option to enable the utility. Make sure to configure the HID keymap utility. See the utility’s documentation for details.

Implementation details

The module is used by HID state module as a HID input report provider for the HID mouse input report and HID boot mouse input report. The module registers two separate HID report providers to handle both input reports. On initialization, the module submits the events of type hid_report_provider_event to establish two-way callbacks between the HID state module and the HID report providers.

Handling user input

The module handles the following types of user input:

Both input types are stored internally in the report_data structure.

Relative value data

The relative value data is stored within the report_data structure’s axes member. There are separate fields for wheel, mouse motion over the X axis, and mouse motion over the Y axis.

The values of axes are stored whenever the input data is received, but these values are cleared when HID report subscription is enabled. Consequently, values outside of the HID subscription period are never retained.

HID mouse pipeline

The nRF Desktop application synchronizes motion sensor sampling with sending HID mouse input reports to the HID host. The HID provider mouse module tracks the number of HID reports in flight and maintains a HID report pipeline to ensure proper HID report flow:

  • If the number of HID reports in flight is lower than the pipeline size, the module provides additional HID reports to generate the HID report pipeline on user input.

  • If the number of HID reports in flight is greater than or equal to the pipeline size, the module buffers user input internally and delays providing subsequent HID input reports until previously submitted reports are sent to the HID host. If the motion source is active, then after a HID input report handled by the module is sent, the module waits for a subsequent motion_event before submitting a subsequent HID input report. This is done to ensure that the recent value of motion will be included in the subsequent HID input report.

See the HID mouse report handling section for an overview of handling HID mouse input reports in the nRF Desktop. The section focuses on interactions between application modules.

Absolute value data

After an application-specific key ID (button_event.key_id) is mapped to the HID mouse input report ID and related HID usage ID, the HID usage ID is handled by the provider. The module remembers HID usage IDs of all the currently pressed keys as a bitmask. The bitmask is then included as part of the HID mouse input report or HID boot mouse input report. Because of the fact that HID usage IDs are stored as a bitmask, the module does not support handling multiple hardware buttons mapped to the same HID usage ID.

The module ignores keypresses that happen before HID report subscription is enabled and clears the HID usage ID bitmask when HID report subscription is disabled. As a result, keypresses outside of the HID subscription period are never retained.