Wheel module

The wheel module is responsible for generating events related to the rotation of the mouse wheel.

Module events

Source Module	Input Event	This Module	Output Event	Sink Module
Power manager module	power_down_event	wheel
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
			module_state_event	Sink modules for module_state_event
			wake_up_event	Sink modules for wake_up_event
			wheel_event	HID provider mouse 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

To enable the module, use the CONFIG_DESKTOP_WHEEL_ENABLE Kconfig option.

For detecting rotation, the wheel module uses Zephyr’s QDEC driver. You can enable the module only when QDEC is configured in DTS and the Zephyr’s QDEC driver is enabled with the CONFIG_QDEC_NRFX Kconfig option. If your board supports multiple QDEC instances (for example nrf54l15dk/nrf54l15/cpuapp), you also need to specify the used QDEC instance with the nrfdesktop-wheel-qdec DT alias. If your board supports only one QDEC instance, the module relies on the qdec DT label and you need not define the DT alias.

The QDEC DTS configuration specifies how many steps are done during one full angle. The sensor reports the rotation data in angle degrees. The CONFIG_DESKTOP_WHEEL_SENSOR_VALUE_DIVIDER (a wheel configuration option) converts the angle value into a value that is passed with a wheel_event to the destination module.

For example, configuring QDEC with 24 steps means that for each step the sensor will report a rotation of 15 degrees. For HID to see this rotation as increment of one, set the CONFIG_DESKTOP_WHEEL_SENSOR_VALUE_DIVIDER Kconfig option to 15.

Implementation details

The wheel module can be in the following states:

• STATE_DISABLED

• STATE_ACTIVE_IDLE

• STATE_ACTIVE

• STATE_SUSPENDED

When in STATE_ACTIVE, the module enables the QDEC driver and waits for callback that indicates rotation. The QDEC driver may consume power during its operation.

If no rotation is detected after the time specified in the CONFIG_DESKTOP_WHEEL_SENSOR_IDLE_TIMEOUT Kconfig option, the wheel module switches to STATE_ACTIVE_IDLE, in which QDEC is disabled. In this state, rotation is detected using GPIO interrupts. When rotation is detected, the module switches back to STATE_ACTIVE.

When the system enters the low power state, the wheel module switches to STATE_SUSPENDED. In this state, rotation is detected using the GPIO interrupts. The module issues a system wake-up event on wheel movement.