OpenLogi

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

FunctionHID++ fnSignatureReturns
get_thumbwheel_info0()ThumbwheelInfo
get_thumbwheel_status1()ThumbwheelStatus
set_thumbwheel_reporting2(mode: ThumbwheelReportingMode, invert_direction: bool)()
listenevent()async_channel::Receiver<ThumbwheelEvent>

The first three methods are async and return Result<…, Hidpp20Error>. listen is synchronous.

Types

ThumbwheelInfo

FieldTypeDescription
native_resolutionu16Ratchets per revolution in native HID mode.
diverted_resolutionu16Rotation increments per revolution in diverted HID++ mode.
time_unitu16time_elapsed unit in microseconds. It is 0 without TIME_STAMP.
default_directionThumbwheelDirectionDevice-specific positive rotation direction.
capabilitiesThumbwheelCapabilitiesAdvertised capability bits. Unknown bits are retained.

ThumbwheelCapabilities

FieldValueDescription
TIME_STAMP1 << 0The event reports elapsed time.
TOUCH1 << 1The wheel reports touch state.
PROXY1 << 2The wheel reports proximity state.
SINGLE_TAP1 << 3The wheel reports single taps.

ThumbwheelDirection

VariantValueDescription
PositiveWhenLeftOrBack0Positive rotation is left or back for this orientation.
PositiveWhenRightOrFront1Positive rotation is right or front for this orientation.

ThumbwheelStatus

FieldTypeDescription
reporting_modeThumbwheelReportingModeNative HID or diverted HID++ reporting.
direction_invertedboolThe default direction is inverted.
touchboolCurrent touch state when supported.
proxyboolCurrent proximity state when supported.

ThumbwheelReportingMode

VariantValueDescription
Native0Reports go only to native HID.
Diverted1Reports go only to HID++. This is required for listen.

Events

ThumbwheelFeature implements EmittingFeature<ThumbwheelEvent>. It accepts only event sub-ID 0.

ThumbwheelEvent

VariantDescription
StatusUpdate(ThumbwheelStatusUpdate)A diverted wheel status update.

ThumbwheelStatusUpdate

FieldTypeDescription
rotationi16Signed rotation delta in the active reporting resolution.
time_elapsedu16Elapsed time in ThumbwheelInfo::time_unit units.
rotation_statusThumbwheelRotationStatusRotation lifecycle state.
touchboolCurrent touch state.
proxyboolCurrent proximity state.
single_tapboolA single-tap indication.

ThumbwheelRotationStatus

VariantValueDescription
Inactive0The wheel is not rotating.
Start1A rotation starts.
Active2A rotation continues.
Stop3A rotation stops.
Other(u8)otherThe 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)

BytesFieldNotes
0–1native_resolutionu16, BE.
2–3diverted_resolutionu16, BE.
4 bit[0]default_direction0 = PositiveWhenLeftOrBack; 1 = PositiveWhenRightOrFront. Bits 7:1 are ignored.
5 bits[3:0]capabilitiesTIME_STAMP, TOUCH, PROXY, and SINGLE_TAP. Bits 7:4 are retained in the bitflags value without named semantics.
6–7time_unitu16, BE.
8–15—OpenLogi ignores these bytes.

get_thumbwheel_status (fn 1)

BytesFieldNotes
0reporting_mode0 = Native; 1 = Diverted. Other values return Hidpp20Error::UnsupportedResponse.
1 bit[0]direction_invertedSet when the default direction is inverted.
1 bit[1]touchCurrent touch state.
1 bit[2]proxyCurrent proximity state.
1 bits[7:3], 2–15—OpenLogi ignores these bits and bytes.

set_thumbwheel_reporting (fn 2)

ByteFieldNotes
0mode0 = Native; 1 = Diverted.
1invert_direction0 = 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)

BytesFieldNotes
0–1rotationi16, BE.
2–3time_elapsedu16, BE.
4rotation_statusValues 0–3 map to named variants. Other values become Other(u8).
5 bit[1]touchTouch state.
5 bit[2]proxyProximity state.
5 bit[3]single_tapSingle-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:?}");
    }
}

On this page