What Is SmartShift in OpenLogi and How to Configure It

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, 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:

• 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:

[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. 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:

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 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 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.
• 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 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, 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, 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 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.

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