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
| Function | HID++ fn | Signature | Returns |
|---|---|---|---|
get_capabilities | 0 | () | SmartShiftEnhancedInfo |
get_ratchet_control_mode | 1 | () | SmartShiftEnhancedStatus |
set_ratchet_control_mode | 2 | (change: SmartShiftEnhancedStatusChange) | SmartShiftEnhancedStatus |
All methods are async. All methods return Result<…, Hidpp20Error>.
Types
SmartShiftEnhancedInfo
| Field | Type | Description |
|---|---|---|
capabilities | SmartShiftEnhancedCapabilities | Capability bits. Unknown bits are retained. |
auto_disengage_default | u8 | Default automatic-release threshold. |
default_tunable_torque | u8 | Default torque as a percentage of maximum force. |
max_force | u8 | Maximum force in gram-force units. |
SmartShiftEnhancedStatus
| Field | Type | Description |
|---|---|---|
wheel_mode | WheelMode | Current requested wheel mode. |
auto_disengage | u8 | Current automatic-release threshold. |
current_tunable_torque | u8 | Current torque as a percentage of maximum force. |
SmartShiftEnhancedStatusChange
None encodes as the wire value 0, which means do not change.
| Field | Type | Description |
|---|---|---|
wheel_mode | Option<WheelMode> | Wheel mode to apply, or None to preserve it. |
auto_disengage | Option<NonZeroU8> | Threshold to apply, or None to preserve it. |
tunable_torque | Option<NonZeroU8> | Torque byte to apply, or None to preserve it. |
SmartShiftEnhancedCapabilities
| Flag | Bit | Description |
|---|---|---|
TUNABLE_TORQUE | 0 | The device advertises tunable ratchet torque. |
WheelMode
WheelMode is re-exported from 0x2110 smartShift.
| Variant | Value | Description |
|---|---|---|
Freespin | 1 | Free-spin mode. |
Ratchet | 2 | Ratchet 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 byte | Field | Notes |
|---|---|---|
| 0 | capabilities | Bit 0 is TUNABLE_TORQUE. OpenLogi retains unknown bits. |
| 1 | auto_disengage_default | Default automatic-release threshold. |
| 2 | default_tunable_torque | Default torque, expressed as a percentage of maximum force. |
| 3 | max_force | Maximum 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 byte | Field | Notes |
|---|---|---|
| 0 | wheel_mode | 1 = Freespin; 2 = Ratchet. Other values return UnsupportedResponse. |
| 1 | auto_disengage | 0x01–0xFE is a threshold in quarter-turns/s. 0xFF means permanent ratchet. |
| 2 | current_tunable_torque | 0 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 byte | Source | Notes |
|---|---|---|
| 0 | change.wheel_mode | None encodes 0 to preserve the mode. 1 selects free-spin. 2 selects ratchet. |
| 1 | change.auto_disengage | None encodes 0 to preserve the threshold. 0x01–0xFE is a threshold. 0xFF selects permanent ratchet. |
| 2 | change.tunable_torque | None 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);
}