0x2121 · hiResWheel
Read and preserve high-resolution wheel state, receive diverted movement and ratchet events, and support OpenLogi's opt-in smooth wheel.
hiResWheel configures high-resolution wheel reports and their native or diverted route. It also reports wheel movement and ratchet-switch changes. OpenLogi v0.8.15 preserves the complete three-byte mode when it changes the documented settings.
Spec: Logitech HID++ 2.0 — x2121 hiResWheel (v1). Cross-checked: Logi Options+ 2.8 (static analysis), Solaar. Used by: Scrolling.
Function reference
HiResWheelFeature (0x2121) supports feature version 0 and exposes the following methods.
Methods
| Function | HID++ fn | Signature | Returns |
|---|---|---|---|
get_wheel_capabilities | 0 | () | Result<WheelCapabilities, Hidpp20Error> |
get_wheel_mode | 1 | () | Result<WheelMode, Hidpp20Error> |
set_wheel_mode | 2 | (mode: WheelMode) | Result<WheelMode, Hidpp20Error> |
get_ratchet_switch_state | 3 | () | Result<WheelRatchetState, Hidpp20Error> |
listen | event | () | async_channel::Receiver<HiResWheelEvent> |
The first four methods are async. listen is the EmittingFeature trait method. OpenLogi has no get_analytics_data method for function 4.
Types
WheelCapabilities
| Field | Type | Description |
|---|---|---|
multiplier | u8 | Hi-res movement units per ratchet distance. |
has_priority | bool | The mode has byte 1, named priority by Options+ 2.8. |
has_rate | bool | The mode has byte 2, named rate by Options+ 2.8. |
has_switch | bool | The wheel has a physical ratchet-mode switch. |
has_invert | bool | The device supports native-HID direction inversion. It does not apply to diverted reports. |
has_analytics_data | bool | The feature reports analytics data. OpenLogi does not read it. |
ratches_per_rotation | u8 | Ratchets in one full rotation. |
wheel_diameter | u8 | Nominal wheel diameter in millimeters. |
WheelMode
| Field | Type | Description |
|---|---|---|
target | WheelEventTarget | Native HID or diverted HID++ movement route. |
resolution | WheelResolution | Current reporting resolution. |
inverted | bool | Native-HID direction inversion. |
| private extension | private | Byte 0 bits outside 0–2, plus bytes 1–2. OpenLogi preserves these firmware-owned bytes verbatim. |
WheelMode has no public constructor. Read it with get_wheel_mode, edit only its public fields, then pass it to set_wheel_mode.
WheelResolution
| Variant | Value | Description |
|---|---|---|
Low | 0 | Low-resolution reporting. |
High | 1 | High-resolution reporting. |
WheelEventTarget
| Variant | Value | Description |
|---|---|---|
Native | 0 | Movement goes to the native HID path. |
Diverted | 1 | Movement arrives as HID++ events. |
WheelRatchetState
| Variant | Value | Description |
|---|---|---|
Freespin | 0 | The wheel is in free-spin mode. |
Ratchet | 1 | The wheel is in ratchet mode. |
Events
HiResWheelEvent
| Variant | Payload | Description |
|---|---|---|
WheelMovement | WheelMovementData | Diverted wheel movement. |
RatchetSwitch | WheelRatchetState | Ratchet-mode change. |
WheelMovementData
| Field | Type | Description |
|---|---|---|
resolution | WheelResolution | Resolution reported by this movement event. |
periods | U4 | Sampling-period count, from 0 to 15. |
delta_vertical | i16 | BE signed vertical delta. Moving away from the user is positive. |
delta_horizontal | i16 | BE signed horizontal delta. A vertically-only wheel reports zero. Options+ 2.8. |
Wire format
Every OpenLogi function request uses a three-byte payload. OpenLogi expands replies and events to a 16-byte buffer before decoding. Multi-byte movement deltas are BE signed i16 values.
get_wheel_capabilities (fn 0)
Request: [0x00, 0x00, 0x00].
Response:
| Byte | Field | Notes |
|---|---|---|
| 0 | multiplier | Raw u8. |
| 1 bit 0 | has_priority | Options+ 2.8. |
| 1 bit 1 | has_rate | Options+ 2.8. |
| 1 bit 2 | has_switch | Ratchet-switch capability. |
| 1 bit 3 | has_invert | Native-inversion capability. |
| 1 bit 4 | has_analytics_data | Options+ 2.8. |
| 1 bits 5–7 | Reserved or unknown | OpenLogi ignores these bits. |
| 2 | ratches_per_rotation | Raw u8. |
| 3 | wheel_diameter | Raw u8 millimeters. |
get_wheel_mode (fn 1)
Request: [0x00, 0x00, 0x00].
Response:
| Byte | Field | Notes |
|---|---|---|
| 0 bit 0 | target | 0 is Native; 1 is Diverted. |
| 0 bit 1 | resolution | 0 is Low; 1 is High. |
| 0 bit 2 | inverted | Applies to native HID reporting. |
| 0 bit 3 | analytics | Options+ 2.8. OpenLogi preserves it but does not expose it. |
| 0 bits 4–7 | Reserved or unknown | OpenLogi preserves them verbatim in the private mode extension. |
| 1 | priority | Options+ 2.8. OpenLogi preserves it but does not expose or validate it. |
| 2 | rate | Options+ 2.8. OpenLogi preserves it but does not expose or validate it. |
set_wheel_mode (fn 2)
Request: the three bytes of a previously read WheelMode.
| Byte | Fields written | Notes |
|---|---|---|
| 0 | target, resolution, inverted, and extension flags | OpenLogi replaces bits 0–2 from public fields. It preserves bit 3 and bits 4–7. |
| 1 | priority | Preserved verbatim from the mode read. Options+ 2.8. |
| 2 | rate | Preserved verbatim from the mode read. Options+ 2.8. |
Response: the same three-byte mode layout as get_wheel_mode.
get_ratchet_switch_state (fn 3)
Request: [0x00, 0x00, 0x00].
Response:
| Byte | Field | Notes |
|---|---|---|
| 0 bit 0 | WheelRatchetState | 0 is Freespin; 1 is Ratchet. |
| 0 bits 1–7 | Reserved | OpenLogi ignores these bits. |
get_analytics_data (fn 4)
OpenLogi does not implement this function. Options+ 2.8 reads function 4 only when analytics data is available and accepts a response of at least 16 raw bytes. The request layout and the 16-byte data semantics remain unverified.
Events
WheelMovement (event fn 0)
| Byte | Field | Notes |
|---|---|---|
| 0 bit 4 | resolution | 0 is Low; 1 is High. |
| 0 bits 3–0 | periods | U4, from 0 to 15. |
| 1–2 | delta_vertical | BE signed i16. |
| 3–4 | delta_horizontal | BE signed i16. Options+ 2.8 requires a five-byte movement payload. |
RatchetSwitch (event fn 1)
| Byte | Field | Notes |
|---|---|---|
| 0 bit 0 | WheelRatchetState | 0 is Freespin; 1 is Ratchet. |
How OpenLogi uses it
OpenLogi inventories 0x2121 as the hires_wheel capability. It separately reads has_invert before it exposes native wheel inversion. Normal resolution and inversion writes first read the full mode. They modify only target, resolution, or inverted, send the original extension bytes, check the setter echo, then read back and check the documented fields. Native inversion writes require has_invert.
The per-device smooth_wheel option defaults to false. It arms only when the device has 0x2121, the device is enabled, mouse capture is enabled, and the OS mouse hook can post input. On macOS, the last condition requires Accessibility access. The capture session reads capabilities and mode, then read-modify-writes target = Diverted with configured resolution or inversion when available. The normal native-mode reapply path stands down while this session owns the wheel.
The session routes vertical WheelMovement reports to the agent. High-resolution movement is divided by multiplier; low-resolution movement uses one unit per notch. The agent applies the configured inversion and macOS natural-scrolling direction, then posts eased scrolling even when the global smooth-scroll option is off. If its scroll runtime cannot accept input, it posts the already scaled vertical delta directly. OpenLogi currently drops delta_horizontal and only logs RatchetSwitch; neither becomes a user-facing event.
On a normal stop, disconnect, capture-plan change, or arming failure, OpenLogi read-modify-writes only target = Native. This preserves resolution, inversion, analytics, priority, rate, and unknown mode bits. A failed restoration remains pending and is retried on the current channel. If the agent exits abnormally, the wheel can remain diverted until OpenLogi reconnects or runs again.
Open questions
Options+ 2.8 names byte 0 bit 3 analytics and bytes 1–2 priority and rate. Its static analysis does not establish their valid ranges or device behavior. OpenLogi preserves all three fields without exposing them as settings.
Options+ 2.8 requires a five-byte WheelMovement payload. OpenLogi decodes an expanded 16-byte buffer and does not reject a shorter original payload. Hardware behavior for a truncated event remains unverified.
Options+ 2.8 accepts at least 16 bytes from function 4. The request payload and the meaning of those bytes remain unverified. OpenLogi exposes the analytics capability flag but has no raw function-4 API.
Usage (Rust)
use std::sync::Arc;
use hidpp::{
channel::HidppChannel,
device::Device,
feature::{
EmittingFeature,
hires_wheel::{HiResWheelFeature, WheelEventTarget, WheelResolution},
},
};
async fn read_one_diverted_event(
channel: Arc<HidppChannel>,
device_index: u8,
) -> Result<(), Box<dyn std::error::Error>> {
let mut device = Device::new(channel, device_index).await?;
device.enumerate_features().await?;
let Some(feature) = device.get_feature::<HiResWheelFeature>() else {
return Ok(());
};
let mut mode = feature.get_wheel_mode().await?;
let original_target = mode.target;
mode.target = WheelEventTarget::Diverted;
mode.resolution = WheelResolution::High;
feature.set_wheel_mode(mode).await?;
let events = feature.listen();
if let Ok(event) = events.recv().await {
println!("{event:?}");
}
let mut restore = feature.get_wheel_mode().await?;
restore.target = original_target;
feature.set_wheel_mode(restore).await?;
Ok(())
}