How to Configure SmartShift Mode and Sensitivity in OpenLogi

OpenLogi provides three interfaces—static TOML configuration, dynamic CLI commands, and a Rust API—to control Logitech SmartShift wheel-ratchet behavior, including mode selection, auto-disengage sensitivity thresholds, and optional torque settings.

SmartShift is Logitech's proprietary wheel-ratchet technology that enables mice to switch between a tactile clicky mode and a smooth free-spin mode based on rotational speed. The AprilNEA/OpenLogi open-source project exposes complete firmware-level control over this feature, allowing you to define persistent device profiles or adjust behavior dynamically at runtime.

Understanding SmartShift Controls

OpenLogi exposes three distinct parameters that govern SmartShift behavior. These map directly to HID++ feature registers in the device firmware.

• Mode: Determines the wheel's immediate state. Free (firmware value 1) enables smooth spinning, while Ratchet (firmware value 2) engages the mechanical click mechanism. Defined in SmartShiftMode in crates/openlogi-core/src/hid/smartshift.rs.

• Auto-disengage (sensitivity): The rotational speed threshold (measured in 0.25 turns per second steps) at which a ratchet wheel automatically releases into free-spin. Valid values range from 1 to 254, where lower numbers increase sensitivity. A value of 255 disables auto-disengage entirely, creating a permanent ratchet. Defined in SmartShiftAutoDisengage.

• Tunable torque (enhanced devices only): Specifies the percentage of maximum electromagnetic force applied to the ratchet mechanism, ranging from 0 to 100 percent. This parameter is defined in SmartShiftEnhancedStatus and implemented in crates/openlogi-hidpp/src/feature/smartshift_enhanced.rs.

Static Configuration via TOML

Define SmartShift settings permanently by adding a [devices.<id>.smartshift] table to your config.toml. The device ID follows the format receiver:<hex>:slot:<n>.

[devices."receiver:aabbccdd:slot:1".smartshift]
mode = "ratchet"          # "free" or "ratchet"

auto_disengage = 16       # 1-254 (lower = more sensitive)

tunable_torque = 50       # 0-100% (enhanced devices only)

The configuration schema maps these keys to their respective firmware structs: mode instantiates SmartShiftMode, auto_disengage maps to SmartShiftAutoDisengage, and tunable_torque corresponds to the enhanced feature's torque value. See the complete example in [docs/config.example.toml](https://github.com/AprilNEA/OpenLogi/blob/master/docs/config.example.toml#L69-L73).

Dynamic Configuration via CLI

The OpenLogi CLI provides diagnostic commands for runtime adjustments without restarting the application. The implementation resides in [crates/openlogi-cli/src/cmd/diag/smartshift.rs](https://github.com/AprilNEA/OpenLogi/blob/master/crates/openlogi-cli/src/cmd/diag/smartshift.rs).

Toggle between free-spin and ratchet modes:

openlogi diag smartshift                   # toggles and immediately reverts (test mode)

openlogi diag smartshift --leave-flipped   # toggles and retains the new mode

Adjust auto-disengage sensitivity:

openlogi diag smartshift --sensitivity 20

The --sensitivity flag accepts a non-zero u8 value (1-255). The command preserves the current wheel mode, writes the new threshold to the device, and prints the read-back status for verification.

Programmatic Configuration via Rust API

For integration into custom tools or daemons, use the openlogi_hid crate. High-level helpers are exported from crates/openlogi-device/src/write/smartshift.rs, while low-level HID++ protocol handling remains in crates/openlogi-hidpp/src/feature/smartshift_enhanced.rs.

use openlogi_hid::{SmartShiftAutoDisengage, SmartShiftMode};

// 1️⃣ Read current status
let status = openlogi_hid::get_smartshift_status(&route).await?;
println!("mode={:?}, sensitivity={}", status.mode, status.auto_disengage);

// 2️⃣ Change sensitivity (preserve current mode)
let new_sensitivity = SmartShiftAutoDisengage::from(non_zero_u8);
let updated = openlogi_hid::set_smartshift_sensitivity(&route, new_sensitivity).await?;
assert_eq!(updated.auto_disengage, new_sensitivity);

// 3️⃣ Toggle mode
let new_mode = openlogi_hid::toggle_smartshift(&route).await?;
println!("new mode = {:?}", new_mode);

Key functions include:

• get_smartshift_status: Returns the current SmartShiftMode and SmartShiftAutoDisengage values.
• set_smartshift_sensitivity: Updates only the auto-disengage threshold while preserving the operational mode.
• toggle_smartshift: Flips between Free and Ratchet modes while retaining the existing sensitivity setting.

Summary

• SmartShift controls Logitech wheel-ratchet behavior through three parameters: operational mode, auto-disengage sensitivity (1-255), and optional tunable torque (0-100%).
• Static configuration uses the [devices.<id>.smartshift] table in config.toml with keys mode, auto_disengage, and tunable_torque.
• CLI adjustments are performed via openlogi diag smartshift, supporting both mode toggles (--leave-flipped) and sensitivity changes (--sensitivity <value>).
• Rust integration leverages the openlogi_hid crate helpers defined in crates/openlogi-device/src/write/smartshift.rs for status queries, sensitivity adjustments, and mode toggling.

Frequently Asked Questions

What is the difference between SmartShift mode and sensitivity?

Mode determines the wheel's immediate mechanical state—either Free (smooth spinning) or Ratchet (tactile clicks)—while sensitivity (auto-disengage) defines the rotational speed threshold that automatically triggers a transition from ratchet to free-spin mode when spinning the wheel rapidly. Setting sensitivity to 255 creates a permanent ratchet that never auto-disengages.

Which source file defines the SmartShift data structures in OpenLogi?

The core data types are defined in crates/openlogi-core/src/hid/smartshift.rs, which contains the SmartShiftMode enum (mapping firmware values 1 and 2) and the SmartShiftAutoDisengage newtype wrapper that validates threshold ranges from 1 to 255.

How do I permanently disable automatic SmartShift switching?

Set auto_disengage = 255 in your TOML configuration file or pass --sensitivity 255 via the CLI. This value corresponds to the firmware's permanent ratchet setting that prevents the wheel from automatically releasing into free-spin mode regardless of rotation speed.

Which crate provides the toggle_smartshift function?

The high-level toggle_smartshift function is exported from crates/openlogi-device/src/write/smartshift.rs within the openlogi-device crate. This function wraps the low-level HID++ protocol implementation found in crates/openlogi-hidpp/src/feature/smartshift_enhanced.rs to safely flip between Free and Ratchet modes while preserving the current sensitivity threshold.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}