OpenLogi

0x2110 · smartShift

Read or update a legacy SmartShift wheel’s mode and automatic-release threshold.

The legacy smartShift feature controls a wheel’s free-spin or ratchet mode. It is used, for example, by MX Master 2S. Newer SmartShift wheels use 0x2111 smartShiftEnhanced.

Spec: Logitech HID++ 2.0 — smartShift. Cross-checked: Logi Options+ 2.8 (static analysis), Solaar. Used by: SmartShift.

Function reference

SmartShiftFeature is the version-0 wrapper for feature 0x2110.

Methods

FunctionHID++ fnSignatureReturns
get_ratchet_control_mode0()RatchetControlMode
set_ratchet_control_mode1(wheel_mode: Option<WheelMode>, auto_disengage: Option<NonZeroU8>, auto_disengage_default: Option<NonZeroU8>)RatchetControlMode

Both methods are async. Both return Result<…, Hidpp20Error>.

Types

RatchetControlMode

FieldTypeDescription
wheel_modeWheelModeSoftware- or button-selected wheel mode. It does not show a transient automatic release.
auto_disengageu8Automatic-release threshold. 0xFF means permanent ratchet.
auto_disengage_defaultu8Default threshold as modelled by OpenLogi. See Open questions.

WheelMode

VariantValueDescription
Freespin1Free-spin mode.
Ratchet2Ratchet mode.

Events

This wrapper declares no events.

Wire format

Every wrapper call sends a 3-byte HID++ short-report payload. FeatureEndpoint::call() always uses that payload size. The wrapper calls extend_payload() before parsing a reply. Therefore, a short reply is zero-padded to 16 bytes rather than length-validated.

get_ratchet_control_mode (fn 0)

The request has no parameters. OpenLogi writes [0x00, 0x00, 0x00].

Response byteFieldNotes
0wheel_mode1 = Freespin; 2 = Ratchet. Other values return UnsupportedResponse.
1auto_disengage0x01–0xFE is a threshold in quarter-turns/s. 0xFF means permanent ratchet.
2auto_disengage_defaultOpenLogi parses this as the default threshold. Options+ 2.8 and Solaar use only bytes 0–1.

set_ratchet_control_mode (fn 1)

The request is [wheel_mode, auto_disengage, auto_disengage_default].

Request byteSourceNotes
0wheel_modeNone encodes 0 to preserve the current mode. 1 selects free-spin. 2 selects ratchet.
1auto_disengageNone encodes 0 to preserve the threshold. 0x01–0xFE is a threshold. 0xFF selects permanent ratchet.
2auto_disengage_defaultNone encodes 0. The device layer always supplies None, so it writes 0. Direct wrapper callers can send a non-zero value.

OpenLogi parses the reply with the getter layout and returns RatchetControlMode. The device layer compares bytes 0–1 with the fields it wrote. The raw wrapper returns the reply without making that comparison.

How OpenLogi uses it

OpenLogi first probes 0x2111. It repeats a missing-feature probe once before it falls back to 0x2110. Transport and protocol errors do not trigger that fallback. The two feature wrappers have no version gate beyond version 0.

The device layer reads the current status before a sensitivity update or a toggle. It writes the selected mode and threshold together. It always writes byte 2 as 0, so the device retains that field under OpenLogi’s model. It accepts a write only when the echoed mode and threshold match. A transient failure retries the same target once.

The desktop performs a second read after every panel write. It marks the write confirmed only when the full returned status matches. OpenLogi stores the selected state and reapplies it after reconnect because SmartShift state is volatile. It does not restore a previous SmartShift state when the application exits.

Open questions

  • OpenLogi and its cited HID++ source model byte 2 as auto_disengage_default. Options+ 2.8 and Solaar send and consume only two semantic bytes. No hardware capture or public source resolves whether byte 2 is a valid field, a reserved byte, or an implementation-specific extension. OpenLogi therefore exposes it in the raw wrapper, while its device layer writes 0.
  • The reviewed sources did not establish a SmartShift-specific HID++ notification layout. OpenLogi defines no event type for this feature.

Usage (Rust)

use hidpp::{
    device::Device,
    feature::smartshift::{SmartShiftFeature, WheelMode},
};
use std::num::NonZeroU8;

// `device` is an initialized `&mut Device`.
device.enumerate_features().await?;
if let Some(feature) = device.get_feature::<SmartShiftFeature>() {
    let current = feature.get_ratchet_control_mode().await?;
    println!("current mode: {:?}", current.wheel_mode);

    let applied = feature
        .set_ratchet_control_mode(
            Some(WheelMode::Freespin),
            NonZeroU8::new(16),
            None,
        )
        .await?;
    println!("applied threshold: {}", applied.auto_disengage);
}

On this page