OpenLogi

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

FunctionHID++ fnSignatureReturns
get_wheel_capabilities0()Result<WheelCapabilities, Hidpp20Error>
get_wheel_mode1()Result<WheelMode, Hidpp20Error>
set_wheel_mode2(mode: WheelMode)Result<WheelMode, Hidpp20Error>
get_ratchet_switch_state3()Result<WheelRatchetState, Hidpp20Error>
listenevent()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

FieldTypeDescription
multiplieru8Hi-res movement units per ratchet distance.
has_priorityboolThe mode has byte 1, named priority by Options+ 2.8.
has_rateboolThe mode has byte 2, named rate by Options+ 2.8.
has_switchboolThe wheel has a physical ratchet-mode switch.
has_invertboolThe device supports native-HID direction inversion. It does not apply to diverted reports.
has_analytics_databoolThe feature reports analytics data. OpenLogi does not read it.
ratches_per_rotationu8Ratchets in one full rotation.
wheel_diameteru8Nominal wheel diameter in millimeters.

WheelMode

FieldTypeDescription
targetWheelEventTargetNative HID or diverted HID++ movement route.
resolutionWheelResolutionCurrent reporting resolution.
invertedboolNative-HID direction inversion.
private extensionprivateByte 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

VariantValueDescription
Low0Low-resolution reporting.
High1High-resolution reporting.

WheelEventTarget

VariantValueDescription
Native0Movement goes to the native HID path.
Diverted1Movement arrives as HID++ events.

WheelRatchetState

VariantValueDescription
Freespin0The wheel is in free-spin mode.
Ratchet1The wheel is in ratchet mode.

Events

HiResWheelEvent

VariantPayloadDescription
WheelMovementWheelMovementDataDiverted wheel movement.
RatchetSwitchWheelRatchetStateRatchet-mode change.

WheelMovementData

FieldTypeDescription
resolutionWheelResolutionResolution reported by this movement event.
periodsU4Sampling-period count, from 0 to 15.
delta_verticali16BE signed vertical delta. Moving away from the user is positive.
delta_horizontali16BE 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:

ByteFieldNotes
0multiplierRaw u8.
1 bit 0has_priorityOptions+ 2.8.
1 bit 1has_rateOptions+ 2.8.
1 bit 2has_switchRatchet-switch capability.
1 bit 3has_invertNative-inversion capability.
1 bit 4has_analytics_dataOptions+ 2.8.
1 bits 5–7Reserved or unknownOpenLogi ignores these bits.
2ratches_per_rotationRaw u8.
3wheel_diameterRaw u8 millimeters.

get_wheel_mode (fn 1)

Request: [0x00, 0x00, 0x00].

Response:

ByteFieldNotes
0 bit 0target0 is Native; 1 is Diverted.
0 bit 1resolution0 is Low; 1 is High.
0 bit 2invertedApplies to native HID reporting.
0 bit 3analyticsOptions+ 2.8. OpenLogi preserves it but does not expose it.
0 bits 4–7Reserved or unknownOpenLogi preserves them verbatim in the private mode extension.
1priorityOptions+ 2.8. OpenLogi preserves it but does not expose or validate it.
2rateOptions+ 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.

ByteFields writtenNotes
0target, resolution, inverted, and extension flagsOpenLogi replaces bits 0–2 from public fields. It preserves bit 3 and bits 4–7.
1priorityPreserved verbatim from the mode read. Options+ 2.8.
2ratePreserved 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:

ByteFieldNotes
0 bit 0WheelRatchetState0 is Freespin; 1 is Ratchet.
0 bits 1–7ReservedOpenLogi 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)

ByteFieldNotes
0 bit 4resolution0 is Low; 1 is High.
0 bits 3–0periodsU4, from 0 to 15.
1–2delta_verticalBE signed i16.
3–4delta_horizontalBE signed i16. Options+ 2.8 requires a five-byte movement payload.

RatchetSwitch (event fn 1)

ByteFieldNotes
0 bit 0WheelRatchetState0 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(())
}

On this page