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

> Master OpenLogi SmartShift wheel configuration. Tune Logitech mouse behavior with mode, auto_disengage, and tunable_torque settings via TOML or API.

- Repository: [Xuan Zhang/OpenLogi](https://github.com/AprilNEA/OpenLogi)
- Tags: deep-dive
- Published: 2026-09-12

---

**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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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

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

```toml
[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`](https://github.com/AprilNEA/OpenLogi/blob/main/smartshift.rs).

## Programmatic Configuration

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

### Constructing Configuration Objects

```rust
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:

```rust
// 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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/openlogi-core/src/hid/smartshift.rs) converts high-level enums to wire format
3. **Transport Layer**: [`openlogi-device/src/write/smartshift.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/openlogi-device/src/write/smartshift.rs) assembles HID++ packets
4. **Protocol Layer**: [`openlogi-hidpp/src/feature/smartshift_enhanced.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/openlogi-hidpp/src/feature/smartshift_enhanced.rs) defines raw byte layouts

### Key Source Files

| File Path | Purpose |
|-----------|---------|
| [`crates/openlogi-core/src/hid/smartshift.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/hid/smartshift.rs) | Defines `SmartShiftMode`, `SmartShiftAutoDisengage`, and conversion traits |
| [`crates/openlogi-device/src/write/smartshift.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-device/src/write/smartshift.rs) | Implements low-level write path to HID++ layer |
| [`crates/openlogi-hidpp/src/feature/smartshift_enhanced.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-hidpp/src/feature/smartshift_enhanced.rs) | Raw HID++ feature payload with `tunable_torque` fields |
| [`crates/openlogi-cli/src/cmd/diag/smartshift.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-cli/src/cmd/diag/smartshift.rs) | CLI diagnostics for reading current device state |
| [`docs/config.example.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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.