OpenLogi SmartShift Wheel Configuration: A Complete Guide to Tuning Your Logitech Mouse

OpenLogi exposes three configurable parameters—mode, auto_disengage, and tunable_torque—that control the Logitech SmartShift wheel behavior through TOML configuration files and programmatic APIs.

The AprilNEA/OpenLogi open-source project provides a Rust-based driver stack for Logitech HID++ devices, exposing the SmartShift wheel as a fully tunable feature. Unlike proprietary Logitech software, OpenLogi allows granular control over wheel physics through declarative configuration and runtime APIs. This guide covers the complete configuration schema, valid parameter ranges, and implementation details derived directly from the source code.

SmartShift Configuration Parameters

OpenLogi defines three distinct settings under the per-device .smartshift TOML table. Each parameter maps to specific firmware registers and HID++ feature payloads.

Mode Selection

The mode setting determines the wheel’s fundamental operating behavior:

• "free": Enables free-spin mode where the wheel rotates endlessly with minimal friction
• "ratchet": Enables clicky, detented rotation with optional automatic disengagement

In the source code, these map to the SmartShiftMode enum defined in crates/openlogi-core/src/hid/smartshift.rs (lines 35-38), where Free = 1 and Ratchet = 2.

Auto-Disengage Threshold

The auto_disengage parameter controls the rotational velocity threshold at which a ratchet-mode wheel automatically releases into free-spin:

• Values 1–254: Represent speed thresholds in firmware units of 0.25 turns/second (e.g., value 16 equals ~4 turns/second)
• Value 255 (0xFF): Forces permanent ratchet mode, disabling auto-release entirely

This is implemented in crates/openlogi-core/src/hid/smartshift.rs (lines 24-28) as the SmartShiftAutoDisengage enum, distinguishing between Threshold and Permanent variants.

Tunable Torque

The tunable_torque parameter adjusts the physical resistance of the ratchet mechanism:

• Valid range: Integers 1–254
• Value 0: Reserved as a "preserve" sentinel that leaves the current hardware setting unchanged

According to crates/openlogi-hidpp/src/feature/smartshift_enhanced.rs (lines 63-66), this value adjusts the electromagnetic braking force applied to the wheel mechanism.

TOML Configuration Examples

Configure SmartShift settings per device in your OpenLogI configuration file. Device sections use the format devices."receiver:{id}:slot:{number}".

Basic Ratchet Configuration

[devices."receiver:abcd1234:slot:1".smartshift]
mode = "ratchet"          # Clicky, detented feel

auto_disengage = 16       # Release to free-spin at ~4 turns/s (16 × 0.25)

tunable_torque = 50     # Medium resistance

Permanent Ratchet Mode

To disable automatic mode switching completely:

[devices."receiver:abcd1234:slot:1".smartshift]
mode = "ratchet"
auto_disengage = 255      # 0xFF forces permanent ratchet

tunable_torque = 70     # Firmer detent strength

The auto_disengage = 255 value translates to SmartShiftAutoDisengage::Permanent in the firmware protocol, as defined in the TryFrom<u8> implementation in smartshift.rs.

Programmatic Configuration

For runtime control, OpenLogi provides a type-safe Rust API through the openlogi_core::config module.

Constructing Configuration Objects

use openlogi_core::config::{WheelMode, SmartShift, SmartShiftAutoDisengage, SmartShiftThreshold, TunableTorque};

let smartshift = SmartShift {
    mode: WheelMode::Ratchet,                     // Matches TOML "ratchet"
    auto_disengage: SmartShiftAutoDisengage::Threshold(
        SmartShiftThreshold::try_new(16).unwrap(), // Validated 1-254
    ),
    tunable_torque: Some(TunableTorque::try_new(50).unwrap()),
};

Runtime Mode Toggling

Toggle between free-spin and ratchet modes using the device trait interface:

// Assumes `device` implements `openlogi_core::hid::SmartShiftWrite`
let current = device.read_smartshift().await?;
let new_mode = current.mode.flipped(); // Switches Free ↔ Ratchet

device.write_smartshift(&SmartShift {
    mode: new_mode.into(),
    ..current
}).await?;

The write_smartshift method serializes the configuration into HID++ packets via the translation logic in openlogi-device/src/write/smartshift.rs.

Implementation Architecture

The configuration flow follows a strict pipeline from user input to hardware registers:

1. Configuration Layer: TOML parsed into crate::config::SmartShift struct
2. Translation Layer: openlogi-core/src/hid/smartshift.rs converts high-level enums to wire format
3. Transport Layer: openlogi-device/src/write/smartshift.rs assembles HID++ packets
4. Protocol Layer: openlogi-hidpp/src/feature/smartshift_enhanced.rs defines raw byte layouts

Key Source Files

File Path	Purpose
crates/openlogi-core/src/hid/smartshift.rs	Defines SmartShiftMode, SmartShiftAutoDisengage, and conversion traits
crates/openlogi-device/src/write/smartshift.rs	Implements low-level write path to HID++ layer
crates/openlogi-hidpp/src/feature/smartshift_enhanced.rs	Raw HID++ feature payload with tunable_torque fields
crates/openlogi-cli/src/cmd/diag/smartshift.rs	CLI diagnostics for reading current device state
docs/config.example.toml	Reference documentation for TOML schema (lines 69-73)

Summary

• OpenLogi configures SmartShift through three TOML settings: mode, auto_disengage, and tunable_torque.
• auto_disengage uses firmware units of 0.25 turns/second (1-254) or 255 for permanent ratchet mode.
• The tunable_torque range (1-254) directly controls electromagnetic braking force; 0 preserves existing hardware values.
• Configuration flows through openlogi-core into HID++ packets defined in openlogi-hidpp, ensuring type safety from UI to firmware.
• Runtime toggling is supported through the SmartShiftWrite trait implemented by device handles.

Frequently Asked Questions

What is the difference between free and ratchet mode in OpenLogi?

Free mode allows the wheel to spin freely without detents, ideal for rapid scrolling through long documents, while ratchet mode provides tactile clicks for precise line-by-line control. The mode can be toggled manually or configured to auto-disengage based on rotation speed.

How do I prevent my Logitech mouse wheel from automatically switching to free-spin?

Set auto_disengage = 255 (or 0xFF in hex) in your TOML configuration. This value maps to SmartShiftAutoDisengage::Permanent in crates/openlogi-core/src/hid/smartshift.rs, disabling the automatic release mechanism and keeping the wheel in ratchet mode permanently.

What units does the auto_disengage threshold use?

The threshold uses 0.25 turns per second per unit. Multiply the TOML value by 0.25 to calculate the actual rotation speed trigger. For example, a value of 20 triggers mode switch at approximately 5 turns/second (20 × 0.25).

Where can I verify my current SmartShift settings are applied correctly?

Use the diagnostic CLI command implemented in crates/openlogi-cli/src/cmd/diag/smartshift.rs. This tool queries the device firmware directly and displays the active mode, auto_disengage threshold, and tunable_torque values, confirming your configuration reached the hardware.

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