# What Is SmartShift in OpenLogi and How to Configure It

> Learn what SmartShift is in OpenLogi and how to configure it to switch Logitech mouse wheel modes. Control Free-spin and Ratchet modes via GUI, CLI, or config file.

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

---

**SmartShift is a HID++ feature in OpenLogi that toggles Logitech mice between Free-spin and Ratchet wheel modes, configurable via the GUI, CLI, or TOML config file.**

OpenLogi implements SmartShift to control Logitech mouse wheel behavior through a unified API that abstracts legacy and enhanced HID++ protocols. The feature allows users to switch between a smooth free-spinning wheel and a clicking ratchet mode, with optional automatic release thresholds. This guide covers the architecture, configuration options, and source code implementation of SmartShift in the AprilNEA/OpenLogi repository.

## How SmartShift Works in OpenLogi

SmartShift operates at the firmware level using HID++ feature IDs **0x2110** (legacy) or **0x2111** (enhanced). OpenLogi detects which version your device supports and exposes both through a consistent interface defined in the HID layer.

### Feature Detection and Abstraction

In [`crates/openlogi-hid/src/write/smartshift.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-hid/src/write/smartshift.rs), the `SmartShift::open` method attempts to initialize the enhanced feature (`0x2111`) first. If the device returns *FeatureUnsupported*, it automatically falls back to the legacy feature (`0x2110`) according to lines 10-31 of that file. This ensures compatibility across both old and new Logitech hardware.

### State Representation and Data Types

The core types defining SmartShift behavior live in [`crates/openlogi-core/src/hid/smartshift.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/hid/smartshift.rs):

- **`SmartShiftMode`** defines the two operational states: **Free** (value `1`) for smooth scrolling and **Ratchet** (value `2`) for tactile clicks (lines 30-39).
- **`SmartShiftAutoDisengage`** stores the auto-release threshold as a value from 1-254, or `255` to indicate permanent ratchet mode that never releases (lines 18-28).
- **`SmartShiftStatus`** bundles the mode, auto-disengage setting, and tunable torque values for enhanced devices.

## Configuring SmartShift in OpenLogi

You can configure SmartShift through three interfaces: the TOML configuration file, the desktop GUI, or the command-line diagnostic tool.

**Config file editing** modifies `~/.config/openlogi/config.toml` (or the directory shown by `openlogi --config-dir`). Add a `[smartshift]` section with the following keys:

```toml
[smartshift]
mode = "ratchet"            # Options: "free" or "ratchet"

auto_disengage = 20         # Threshold 1-254, or 255 for permanent ratchet

```

The `mode` field maps directly to `SmartShiftMode`, while `auto_disengage` represents the raw HID++ byte value. A value of `255` disables automatic release, forcing the wheel to remain in ratchet mode permanently.

**GUI configuration** uses the `SmartShiftPanel` implemented in [`crates/openlogi-desktop/src/features/pointer/smartshift.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-desktop/src/features/pointer/smartshift.rs). The interface provides three controls:

- A segmented control to toggle between **Free** and **Ratchet** modes
- A slider to adjust the auto-disengage threshold (1-254), handled by `threshold_from_slider`
- A "Permanent" checkbox that sets the threshold to `255`

When you adjust these controls, the GUI invokes `client.set_smartshift` via the IPC layer and persists changes through `AppState::commit_smartshift` (lines 99-107).

**CLI diagnostics** provides quick testing without launching the GUI. Run the diagnostic 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):

```bash
openlogi diag smartshift

```

This command toggles the current SmartShift mode and prints the resulting status to verify the change took effect.

## IPC Architecture and Persistence

The IPC module in [`crates/openlogi-ipc/src/ipc.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-ipc/src/ipc.rs) declares the async methods that bridge the UI and hardware (lines 389-396):

- **`set_smartshift`**: Writes new SmartShift parameters to the device
- **`read_smartshift`**: Retrieves current mode and threshold settings

These methods allow the GUI and CLI to communicate with the background agent without direct hardware access. Changes made through any interface are persisted to [`config.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/config.toml) and reapplied when the agent restarts or the mouse reconnects.

## Summary

- SmartShift controls Logitech mouse wheel behavior through HID++ features **0x2110** (legacy) or **0x2111** (enhanced) as implemented in [`crates/openlogi-hid/src/write/smartshift.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-hid/src/write/smartshift.rs).
- **Two modes** are available: **Free** (smooth scrolling, value `1`) and **Ratchet** (tactile clicks, value `2`).
- The **auto-disengage** threshold accepts values **1-254** for automatic release or **255** for permanent ratchet mode.
- Configure via [`config.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/config.toml) using the `[smartshift]` section, through the GUI panel in Pointer settings, or using the `openlogi diag smartshift` CLI command.

## Frequently Asked Questions

### What is the difference between Free and Ratchet modes in SmartShift?

**Free mode** allows the mouse wheel to spin freely without tactile feedback, ideal for rapid scrolling through long documents. **Ratchet mode** engages mechanical clicks for precise line-by-line control. According to the OpenLogi source in [`crates/openlogi-core/src/hid/smartshift.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/hid/smartshift.rs), these map to HID++ values `1` and `2` respectively.

### How do I make the ratchet mode permanent?

Set the `auto_disengage` value to `255` (or check the "Permanent" option in the GUI). In [`crates/openlogi-core/src/hid/smartshift.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/hid/smartshift.rs), the `SmartShiftAutoDisengage` type treats `255` as a special value that disables automatic release, keeping the wheel in ratchet mode indefinitely.

### Why does OpenLogi have two HID++ feature IDs for SmartShift?

The codebase supports both legacy devices using feature ID **0x2110** and newer devices using **0x2111** (enhanced). The abstraction layer in [`crates/openlogi-hid/src/write/smartshift.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-hid/src/write/smartshift.rs) automatically attempts the enhanced feature first and falls back to the legacy ID if the device reports *FeatureUnsupported*, ensuring broad hardware compatibility.

### Where are SmartShift settings stored?

Settings persist in the user configuration file at `~/.config/openlogi/config.toml` under the `[smartshift]` section. The GUI writes to this file via `AppState::commit_smartshift` after each change, and the agent reapplies these values on startup or device reconnection.