OpenLogi

0x2111 · smartShiftEnhanced

Read or update a SmartShift Enhanced wheel’s mode, automatic-release threshold, and tunable ratchet torque.

smartShiftEnhanced controls newer SmartShift wheels, including MX Master 3, 3S, and 4. OpenLogi uses this feature before it considers the legacy 0x2110 smartShift fallback.

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

Function reference

SmartShiftEnhancedFeature is the version-0 wrapper for feature 0x2111.

Methods

FunctionHID++ fnSignatureReturns
get_capabilities0()SmartShiftEnhancedInfo
get_ratchet_control_mode1()SmartShiftEnhancedStatus
set_ratchet_control_mode2(change: SmartShiftEnhancedStatusChange)SmartShiftEnhancedStatus

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

Types

SmartShiftEnhancedInfo

FieldTypeDescription
capabilitiesSmartShiftEnhancedCapabilitiesCapability bits. Unknown bits are retained.
auto_disengage_defaultu8Default automatic-release threshold.
default_tunable_torqueu8Default torque as a percentage of maximum force.
max_forceu8Maximum force in gram-force units.

SmartShiftEnhancedStatus

FieldTypeDescription
wheel_modeWheelModeCurrent requested wheel mode.
auto_disengageu8Current automatic-release threshold.
current_tunable_torqueu8Current torque as a percentage of maximum force.

SmartShiftEnhancedStatusChange

None encodes as the wire value 0, which means do not change.

FieldTypeDescription
wheel_modeOption<WheelMode>Wheel mode to apply, or None to preserve it.
auto_disengageOption<NonZeroU8>Threshold to apply, or None to preserve it.
tunable_torqueOption<NonZeroU8>Torque byte to apply, or None to preserve it.

SmartShiftEnhancedCapabilities

FlagBitDescription
TUNABLE_TORQUE0The device advertises tunable ratchet torque.

WheelMode

WheelMode is re-exported from 0x2110 smartShift.

VariantValueDescription
Freespin1Free-spin mode.
Ratchet2Ratchet mode.

Events

This wrapper declares no events.

Wire format

All three wrapper methods send a 3-byte HID++ short-report payload. Each wrapper calls extend_payload() before it parses the reply. A short reply is therefore zero-padded to 16 bytes. The protocol wrapper does not validate response length.

get_capabilities (fn 0)

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

Response byteFieldNotes
0capabilitiesBit 0 is TUNABLE_TORQUE. OpenLogi retains unknown bits.
1auto_disengage_defaultDefault automatic-release threshold.
2default_tunable_torqueDefault torque, expressed as a percentage of maximum force.
3max_forceMaximum force in gram-force units.
4–15/OpenLogi has no fields for these bytes. See Open questions for byte 4.

get_ratchet_control_mode (fn 1)

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.
2current_tunable_torque0 means no torque level. The device layer accepts 1–100 percent and rejects higher values.

set_ratchet_control_mode (fn 2)

The request is [wheel_mode, auto_disengage, tunable_torque].

Request byteSourceNotes
0change.wheel_modeNone encodes 0 to preserve the mode. 1 selects free-spin. 2 selects ratchet.
1change.auto_disengageNone encodes 0 to preserve the threshold. 0x01–0xFE is a threshold. 0xFF selects permanent ratchet.
2change.tunable_torqueNone encodes 0 to preserve torque. The raw wrapper accepts any NonZeroU8. OpenLogi’s device layer supplies only 1–100 percent.

The reply has the getter layout. The raw wrapper returns the parsed status. The device layer compares every field it wrote with the echoed value.

How OpenLogi uses it

OpenLogi probes 0x2111 first. It retries a missing-feature probe once before it falls back to 0x2110. Other feature, transport, and protocol errors propagate. Both wrappers are registered at feature version 0.

A mode toggle reads the current status, then writes the opposite mode. A sensitivity change reads the status, then writes the current mode with the new threshold. Both operations send torque byte 2 as 0, so they preserve torque. An explicit torque change sends bytes 0–1 as 0.

OpenLogi reads capabilities before it writes an explicit torque value. It sends a non-zero torque only when bit 0 is TUNABLE_TORQUE. Without that bit, a mode or threshold write still succeeds with byte 2 set to 0. An explicit torque request returns FeatureUnsupported.

TunableTorque limits OpenLogi’s device, configuration, and IPC values to 1–100 percent. A status reply of 0 becomes no torque value. A status reply above 100 returns UnsupportedResponse. A full saved configuration writes torque only when it differs from the current value.

The device layer accepts a write only when its reply matches each written field. It retries the same target once after a transient error. The desktop then reads the status again and compares the whole value. OpenLogi saves the chosen 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

  • Options+ 2.8 exposes a low-level capability getter with a possible fifth output byte. Its higher-level caller uses only bytes 0–3. OpenLogi also uses bytes 0–3. No public specification or hardware trace establishes a meaning for byte 4.
  • 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::WheelMode,
        smartshift_enhanced::{
            SmartShiftEnhancedFeature,
            SmartShiftEnhancedStatusChange,
        },
    },
};
use std::num::NonZeroU8;

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

    let applied = feature
        .set_ratchet_control_mode(SmartShiftEnhancedStatusChange {
            wheel_mode: Some(WheelMode::Ratchet),
            auto_disengage: NonZeroU8::new(16),
            tunable_torque: None,
        })
        .await?;
    println!("applied mode: {:?}", applied.wheel_mode);
}

On this page