0x2150 · thumbwheel
Query and divert a horizontal thumb wheel, then receive its rotation, touch, proximity, and tap status.
0x2150 controls the horizontal thumb wheel on supported MX mice. It reports wheel capabilities and current reporting state. Diverted reporting sends rotation and touch updates through HID++ instead of native HID.
Spec: Logitech HID++ 2.0 — x2150 thumbwheel (v0). Cross-checked: Logi Options+ 2.8 (static analysis), Solaar. Used by: Scrolling and Remap buttons.
Function reference
ThumbwheelFeature implements feature version 0.
Methods
| Function | HID++ fn | Signature | Returns |
|---|---|---|---|
get_thumbwheel_info | 0 | () | ThumbwheelInfo |
get_thumbwheel_status | 1 | () | ThumbwheelStatus |
set_thumbwheel_reporting | 2 | (mode: ThumbwheelReportingMode, invert_direction: bool) | () |
listen | event | () | async_channel::Receiver<ThumbwheelEvent> |
The first three methods are async and return Result<…, Hidpp20Error>. listen is synchronous.
Types
ThumbwheelInfo
| Field | Type | Description |
|---|---|---|
native_resolution | u16 | Ratchets per revolution in native HID mode. |
diverted_resolution | u16 | Rotation increments per revolution in diverted HID++ mode. |
time_unit | u16 | time_elapsed unit in microseconds. It is 0 without TIME_STAMP. |
default_direction | ThumbwheelDirection | Device-specific positive rotation direction. |
capabilities | ThumbwheelCapabilities | Advertised capability bits. Unknown bits are retained. |
ThumbwheelCapabilities
| Field | Value | Description |
|---|---|---|
TIME_STAMP | 1 << 0 | The event reports elapsed time. |
TOUCH | 1 << 1 | The wheel reports touch state. |
PROXY | 1 << 2 | The wheel reports proximity state. |
SINGLE_TAP | 1 << 3 | The wheel reports single taps. |
ThumbwheelDirection
| Variant | Value | Description |
|---|---|---|
PositiveWhenLeftOrBack | 0 | Positive rotation is left or back for this orientation. |
PositiveWhenRightOrFront | 1 | Positive rotation is right or front for this orientation. |
ThumbwheelStatus
| Field | Type | Description |
|---|---|---|
reporting_mode | ThumbwheelReportingMode | Native HID or diverted HID++ reporting. |
direction_inverted | bool | The default direction is inverted. |
touch | bool | Current touch state when supported. |
proxy | bool | Current proximity state when supported. |
ThumbwheelReportingMode
| Variant | Value | Description |
|---|---|---|
Native | 0 | Reports go only to native HID. |
Diverted | 1 | Reports go only to HID++. This is required for listen. |
Events
ThumbwheelFeature implements EmittingFeature<ThumbwheelEvent>. It accepts only event sub-ID 0.
ThumbwheelEvent
| Variant | Description |
|---|---|
StatusUpdate(ThumbwheelStatusUpdate) | A diverted wheel status update. |
ThumbwheelStatusUpdate
| Field | Type | Description |
|---|---|---|
rotation | i16 | Signed rotation delta in the active reporting resolution. |
time_elapsed | u16 | Elapsed time in ThumbwheelInfo::time_unit units. |
rotation_status | ThumbwheelRotationStatus | Rotation lifecycle state. |
touch | bool | Current touch state. |
proxy | bool | Current proximity state. |
single_tap | bool | A single-tap indication. |
ThumbwheelRotationStatus
| Variant | Value | Description |
|---|---|---|
Inactive | 0 | The wheel is not rotating. |
Start | 1 | A rotation starts. |
Active | 2 | A rotation continues. |
Stop | 3 | A rotation stops. |
Other(u8) | other | The wrapper preserves an unmodelled status byte. |
Wire format
Getters send a three-byte zero request. OpenLogi reads their extended response payload. It ignores response bytes not listed below.
get_thumbwheel_info (fn 0)
| Bytes | Field | Notes |
|---|---|---|
| 0–1 | native_resolution | u16, BE. |
| 2–3 | diverted_resolution | u16, BE. |
4 bit[0] | default_direction | 0 = PositiveWhenLeftOrBack; 1 = PositiveWhenRightOrFront. Bits 7:1 are ignored. |
5 bits[3:0] | capabilities | TIME_STAMP, TOUCH, PROXY, and SINGLE_TAP. Bits 7:4 are retained in the bitflags value without named semantics. |
| 6–7 | time_unit | u16, BE. |
| 8–15 | — | OpenLogi ignores these bytes. |
get_thumbwheel_status (fn 1)
| Bytes | Field | Notes |
|---|---|---|
| 0 | reporting_mode | 0 = Native; 1 = Diverted. Other values return Hidpp20Error::UnsupportedResponse. |
1 bit[0] | direction_inverted | Set when the default direction is inverted. |
1 bit[1] | touch | Current touch state. |
1 bit[2] | proxy | Current proximity state. |
1 bits[7:3], 2–15 | — | OpenLogi ignores these bits and bytes. |
set_thumbwheel_reporting (fn 2)
| Byte | Field | Notes |
|---|---|---|
| 0 | mode | 0 = Native; 1 = Diverted. |
| 1 | invert_direction | 0 = default direction; 1 = inverted direction. |
| 2 | — | OpenLogi always writes 0x00. |
OpenLogi accepts a successful transport reply and does not decode its payload.
StatusUpdate event (fn 0)
| Bytes | Field | Notes |
|---|---|---|
| 0–1 | rotation | i16, BE. |
| 2–3 | time_elapsed | u16, BE. |
| 4 | rotation_status | Values 0–3 map to named variants. Other values become Other(u8). |
5 bit[1] | touch | Touch state. |
5 bit[2] | proxy | Proximity state. |
5 bit[3] | single_tap | Single-tap indication. |
5 bit[0], bits[7:4], 6–15 | — | OpenLogi ignores these bits and bytes. |
How OpenLogi uses it
The device layer uses its own 0x2150 accessor for capture. It reads getThumbwheelInfo and getThumbwheelStatus before it diverts the wheel. It then normalizes rotation polarity from default_direction and scales diverted increments to native resolution.
Since v0.8.14, PR #1753 reads the previous status before diversion. On exit, it restores native reporting and preserves the previous inversion only when the previous mode was native. A failed restore remains pending and retries on the current device route.
The capture path emits nonzero rotation as scroll. It suppresses a zero-rotation tap when the current status is rolling, or the previous status was Start or Active. It sends a settled single_tap as a Thumbwheel button pulse.
Open questions
The typed wrapper preserves an unknown event status as Other(u8). The device capture accessor instead classifies an unknown status as Inactive. Therefore, a zero-rotation unknown-status update with single_tap can still become a button pulse. No hardware capture has verified that combination.
If getThumbwheelInfo fails, the capture path still diverts the wheel. It then uses the default polarity and an unscaled 1.0 resolution ratio. This fallback is not hardware-verified as safe.
Usage (Rust)
use hidpp::{
device::Device,
feature::{
EmittingFeature,
thumbwheel::{ThumbwheelFeature, ThumbwheelReportingMode},
},
};
// device: &mut Device, already created via Device::new(channel, index)
device.enumerate_features().await?;
if let Some(feature) = device.get_feature::<ThumbwheelFeature>() {
let info = feature.get_thumbwheel_info().await?;
println!("{} / {}", info.native_resolution, info.diverted_resolution);
feature
.set_thumbwheel_reporting(ThumbwheelReportingMode::Diverted, false)
.await?;
let receiver = feature.listen();
while let Ok(event) = receiver.recv().await {
println!("{event:?}");
}
}