# How to Configure SmartShift Mode and Sensitivity in OpenLogi

> Configure SmartShift mode and sensitivity in OpenLogi using TOML, CLI, or Rust API. Optimize your Logitech wheel-ratchet behavior today.

- Repository: [Xuan Zhang/OpenLogi](https://github.com/AprilNEA/OpenLogi)
- Tags: how-to-guide
- Published: 2026-09-11

---

**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`](https://github.com/AprilNEA/OpenLogi/blob/master/crates/openlogi-core/src/hid/smartshift.rs#L34-L39) in [`crates/openlogi-core/src/hid/smartshift.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/master/crates/openlogi-core/src/hid/smartshift.rs#L121-L128).

- **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`](https://github.com/AprilNEA/OpenLogi/blob/master/crates/openlogi-hidpp/src/feature/smartshift_enhanced.rs#L42-L48) and implemented in [`crates/openlogi-hidpp/src/feature/smartshift_enhanced.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/config.toml). The device ID follows the format `receiver:<hex>:slot:<n>`.

```toml
[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/main/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/main/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:**

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

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

```

**Adjust auto-disengage sensitivity:**

```bash
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`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-device/src/write/smartshift.rs), while low-level HID++ protocol handling remains in [`crates/openlogi-hidpp/src/feature/smartshift_enhanced.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-hidpp/src/feature/smartshift_enhanced.rs).

```rust
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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-hidpp/src/feature/smartshift_enhanced.rs) to safely flip between `Free` and `Ratchet` modes while preserving the current sensitivity threshold.