OpenLogi0x2150 · thumbwheel
横向拇指轮控制——查询能力、将滚轮转动事件从 HID 转向 HID++，并读取触摸与轻点状态。
MX 系列鼠标上的横向拇指轮。getThumbwheelInfo 报告其能力（分辨率、原生还是可转向、默认方向）；getThumbwheelStatus 读取当前的上报模式；setThumbwheelReporting 将滚轮转向，使其转动以事件形式交给 OpenLogi，而非原生滚动。转向期间，该功能会发出携带转动增量以及触摸 / 轻点标志的状态更新。
OpenLogi 将拇指轮转向，用于驱动横向滚动以及 ThumbwheelScrollUp / ThumbwheelScrollDown 绑定，并按拇指轮灵敏度设置进行缩放。
规格： Logitech HID++ 2.0 —— x2150 thumbwheel。用于： 拇指轮绑定。
Function reference
The ThumbwheelFeature wrapper (0x2150) exposes:
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> |
get_thumbwheel_info, get_thumbwheel_status, and set_thumbwheel_reporting are async and return Result<…, Hidpp20Error>. listen is synchronous and returns a receiver directly.
Types
ThumbwheelInfo
Information about the thumbwheel as reported by get_thumbwheel_info.
| Field | Type | Description |
|---|---|---|
native_resolution | u16 | Number of ratchets generated per revolution in native (HID) mode. |
diverted_resolution | u16 | Number of rotation increments generated per revolution in diverted (HID++) mode. |
time_unit | u16 | Timestamp unit in microseconds for ThumbwheelStatusUpdate::time_elapsed. 0 if ThumbwheelCapabilities::time_stamp is not supported. |
default_direction | ThumbwheelDirection | The default rotation direction. |
capabilities | ThumbwheelCapabilities | The capabilities of the thumbwheel. |
ThumbwheelCapabilities
The capabilities the thumbwheel may support.
| Field | Type | Description |
|---|---|---|
time_stamp | bool | Whether the thumbwheel supports emitting the elapsed time between two events via ThumbwheelStatusUpdate::time_elapsed. |
touch | bool | Whether the thumbwheel is equipped with a touch sensor. |
proxy | bool | Whether the thumbwheel is equipped with a proximity sensor. |
single_tap | bool | Whether the thumbwheel supports detecting single taps. |
ThumbwheelDirection
Determines which rotation direction produces a positive value in ThumbwheelStatusUpdate::rotation. Direction descriptors (LeftOrBack, RightOrFront) are specific to device orientation.
| Variant | Value | Description |
|---|---|---|
PositiveWhenLeftOrBack | 0 | Positive rotation means left/back for this device orientation. |
PositiveWhenRightOrFront | 1 | Positive rotation means right/front for this device orientation. |
ThumbwheelStatus
Current thumbwheel status as reported by get_thumbwheel_status.
| Field | Type | Description |
|---|---|---|
reporting_mode | ThumbwheelReportingMode | The mode how thumbwheel events are reported (native/HID or diverted/HID++). |
direction_inverted | bool | Whether the default direction is inverted. |
touch | bool | Whether the user is currently touching the thumbwheel. Only meaningful if ThumbwheelCapabilities::touch is supported. |
proxy | bool | Whether the user is currently close to the thumbwheel. Only meaningful if ThumbwheelCapabilities::proxy is supported. |
ThumbwheelReportingMode
The mode how the thumbwheel reports its events.
| Variant | Value | Description |
|---|---|---|
Native | 0 | Thumbwheel events are reported only to the native HID channel. |
Diverted | 1 | Thumbwheel events are reported only to the diverted HID++ channel. Required for listen to receive events. |
Events
ThumbwheelFeature implements EmittingFeature<ThumbwheelEvent>. Call listen() to obtain an async_channel::Receiver<ThumbwheelEvent>. Events are only delivered when the thumbwheel is in ThumbwheelReportingMode::Diverted.
ThumbwheelEvent
| Variant | Description |
|---|---|
StatusUpdate(ThumbwheelStatusUpdate) | Emitted whenever the thumbwheel status updates. Requires diverted reporting mode. |
ThumbwheelStatusUpdate
| Field | Type | Description |
|---|---|---|
rotation | i16 | Rotation delta, relative to ThumbwheelInfo::native_resolution or ThumbwheelInfo::diverted_resolution. |
time_elapsed | u16 | Time elapsed since the last event, in units of ThumbwheelInfo::time_unit. 0 if timestamp capability is not supported. |
rotation_status | ThumbwheelRotationStatus | Status of the current rotation gesture. |
touch | bool | Whether the user is touching the thumbwheel. Only set if ThumbwheelCapabilities::touch is supported. |
proxy | bool | Whether the user is close to the thumbwheel. Only set if ThumbwheelCapabilities::proxy is supported. |
single_tap | bool | Whether the user single-tapped the thumbwheel. Only set if ThumbwheelCapabilities::single_tap is supported. |
ThumbwheelRotationStatus
| Variant | Value | Description |
|---|---|---|
Inactive | 0 | The thumbwheel was not rotated. |
Start | 1 | The thumbwheel rotation was started. |
Active | 2 | The thumbwheel rotation is ongoing. |
Stop | 3 | The thumbwheel was released. |
Wire format
All three methods use a 3-byte request payload. Getter responses are read from the 16-byte extended payload returned by extend_payload(). The event payload is delivered by the message listener on function sub-id 0.
get_thumbwheel_info (fn 0)
Request: [0x00, 0x00, 0x00] (no parameters)
Response (byte → field):
| Bytes | Field | Notes |
|---|---|---|
| 0–1 | native_resolution | Big-endian u16 |
| 2–3 | diverted_resolution | Big-endian u16 |
| 4 | default_direction | Bit 0 only (& 1); 0 = PositiveWhenLeftOrBack, 1 = PositiveWhenRightOrFront |
| 5 | capabilities | Bit 0 = time_stamp, bit 1 = touch, bit 2 = proxy, bit 3 = single_tap |
| 6–7 | time_unit | Big-endian u16; 0 when time_stamp capability is absent |
get_thumbwheel_status (fn 1)
Request: [0x00, 0x00, 0x00] (no parameters)
Response (byte → field):
| Byte | Field | Notes |
|---|---|---|
| 0 | reporting_mode | 0 = Native, 1 = Diverted |
| 1 | flags | Bit 0 = direction_inverted, bit 1 = touch, bit 2 = proxy |
set_thumbwheel_reporting (fn 2)
Request: [mode, invert, 0x00]
| Byte | Parameter | Notes |
|---|---|---|
| 0 | mode | ThumbwheelReportingMode as u8; 0 = Native, 1 = Diverted |
| 1 | invert_direction | 1 if inverted, 0 otherwise |
| 2 | — | Reserved, always 0x00 |
Response: ignored (no fields decoded).
StatusUpdate event (fn 0, sub-id 0)
Emitted by the device while in Diverted mode. The listener filters on function sub-id 0 via func.to_lo() != 0.
| Bytes | Field | Notes |
|---|---|---|
| 0–1 | rotation | Big-endian i16 rotation delta |
| 2–3 | time_elapsed | Big-endian u16; 0 when timestamp capability is absent |
| 4 | rotation_status | 0 = Inactive, 1 = Start, 2 = Active, 3 = Stop |
| 5 | flags | Bit 1 = touch, bit 2 = proxy, bit 3 = single_tap |
Usage (Rust)
use hidpp::feature::thumbwheel::{ThumbwheelFeature, ThumbwheelReportingMode};
// mut device: Device, already created via Device::new(channel, index)
device.enumerate_features().await?;
if let Some(feat) = device.get_feature::<ThumbwheelFeature>() {
let info = feat.get_thumbwheel_info().await?;
println!("native res: {}, diverted res: {}", info.native_resolution, info.diverted_resolution);
// Divert the thumbwheel so HID++ events are delivered instead of native scrolling.
feat.set_thumbwheel_reporting(ThumbwheelReportingMode::Diverted, false).await?;
// Subscribe to rotation events.
let rx = feat.listen();
while let Ok(event) = rx.recv().await {
println!("{event:?}");
}
}