# How SmartShift Wheel Mode Toggle and Permanent-Ratchet Panel Differ from Standard DPI in OpenLogi

> Discover how SmartShift wheel mode toggle and permanent-ratchet panel differ from standard DPI in OpenLogi. Understand distinct HID++ features and their unique implementations.

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

---

**SmartShift wheel mode toggle and the permanent-ratchet panel operate on the HID++ SmartShift Enhanced feature (`0x2111`) to control mouse wheel mechanics, while standard DPI controls use the ReprogControls feature (`0x1b04`) to adjust sensor resolution, representing architecturally separate subsystems with distinct data structures, write paths, and UI implementations.**

OpenLogi is an open-source Rust-based management tool for Logitech devices that exposes hardware capabilities through the HID++ protocol. While both SmartShift configuration and DPI adjustment appear in pointer settings, they target fundamentally different hardware subsystems—wheel ratchet behavior versus optical sensor resolution—using separate feature IDs, packet structures, and device interfaces.

## Architectural Differences in HID++ Feature Implementation

### SmartShift Enhanced Feature (0x2111)

SmartShift functionality is exposed through the **SmartShift Enhanced** HID++ feature with ID `0x2111`. This feature controls the mechanical behavior of the mouse wheel, specifically switching between free-spin and ratchet (clicky) modes.

In [`crates/openlogi-core/src/hid/smartshift.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/hid/smartshift.rs), the `SmartShiftMode` enum defines the available states:

- **FreeSpin**: The wheel spins freely without tactile feedback
- **Ratchet**: The wheel provides tactile clicks during rotation  
- **PermanentRatchet**: Forces ratchet mode regardless of scroll speed

The permanent-ratchet variant uses a magic value of `0xFF` sent to the `ratchet_control_mode` field, effectively disabling automatic mode switching based on scroll velocity.

### Standard DPI Controls (0x1b04)

DPI configuration operates through the **ReprogControls** feature (`0x1b04`), which exposes control IDs for sensor resolution adjustments. According to [`crates/openlogi-device/src/reprog_controls.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-device/src/reprog_controls.rs), DPI changes are handled by:

- **DPI Change** (`0xED`): Adjusts sensor resolution incrementally
- **DPI Switch** (`0xFD`): Toggles between predefined DPI levels

These controls map to logical `ButtonId::DpiToggle` in the OpenLogi core binding system, completely separate from the wheel mechanics controlled by SmartShift.

## Data Structures and Core Types

The internal representations for these features differ significantly in both structure and storage location.

**SmartShift** uses the `SmartShiftMode` enum that serializes to a single byte (`u8`) for the `ratchet_control_mode` field. When the permanent-ratchet panel is enabled, the system explicitly writes `0xFF` to force ratchet mode independent of speed thresholds.

**DPI controls** utilize the `Dpi` struct and `ExtendedDpi` feature (`0x2201`/`0x2202`), storing resolution values as 16-bit integers in sensor DPI tables. The write implementation in [`crates/openlogi-device/src/write/dpi.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-device/src/write/dpi.rs) handles these sensor-specific data packets, contrasting with the wheel-focused SmartShift implementation.

## UI Implementation Differences

### SmartShift Panel in Desktop Interface

The SmartShift UI resides in [`crates/openlogi-desktop/src/features/pointer/smartshift.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-desktop/src/features/pointer/smartshift.rs), rendering controls under **Desktop → Pointer**. The interface provides:

- A primary toggle switching between free-spin and ratchet modes
- A pill-style **permanent-ratchet** toggle that forces constant ratchet behavior

The UI implements safety interlocks at lines 266-268 of the same file, disabling the permanent-ratchet toggle while the auto-disengage sensitivity slider is active to prevent configuration conflicts.

### DPI Panel Implementation

Conversely, the DPI panel displays as a separate configuration section featuring:

- A numerical slider for continuous DPI adjustment
- A button list for preset DPI steps

The panel only enables when the device advertises support for `DPI_MODE_SHIFT_CIDS`, an array defined in [`crates/openlogi-device/src/reprog_controls.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-device/src/reprog_controls.rs) that validates the presence of reprogrammable DPI controls.

## Interaction Flows and Write Paths

The write implementations demonstrate the architectural separation between these systems.

**SmartShift Toggle Implementation** ([`crates/openlogi-device/src/write/smartshift.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-device/src/write/smartshift.rs)):

```rust
pub async fn toggle_smartshift(&self, route: &DeviceRoute) -> Result<(), Hidpp20Error> {
    let feature = SmartShiftFeature::new(route.clone());
    let current = feature.get_ratchet_control_mode().await?;
    let new_mode = match current {
        SmartShiftMode::FreeSpin => SmartShiftMode::Ratchet,
        SmartShiftMode::Ratchet => SmartShiftMode::FreeSpin,
        SmartShiftMode::PermanentRatchet => SmartShiftMode::Ratchet,
    };
    feature.set_ratchet_control_mode(new_mode).await
}

```

**Permanent-Ratchet Activation**:

```rust
// Called when the permanent-ratchet pill is toggled on
feature.set_ratchet_control_mode(SmartShiftMode::PermanentRatchet).await?;

```

**Standard DPI Change** ([`crates/openlogi-device/src/write/dpi.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-device/src/write/dpi.rs)):

```rust
pub async fn set_dpi(&self, sensor: u8, dpi: u16) -> Result<(), Hidpp20Error> {
    let feature = DpiFeature::new(self.route.clone(), sensor);
    feature.set_sensor_dpi(dpi).await
}

```

These distinct write paths—`set_ratchet_control_mode` for wheel behavior versus `set_dpi` for sensor resolution—confirm that SmartShift and DPI controls operate on different hardware features with separate packet structures and device endpoints.

## Summary

- **SmartShift wheel mode toggle** controls mouse wheel mechanics through HID++ feature `0x2111`, using the `SmartShiftMode` enum and `ratchet_control_mode` field.
- **Permanent-ratchet panel** forces constant ratchet mode by writing `0xFF` via `set_ratchet_control_mode`, independent of scroll speed detection.
- **Standard DPI controls** manage sensor resolution through HID++ feature `0x1b04`, utilizing `Dpi` structs and write operations in [`crates/openlogi-device/src/write/dpi.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-device/src/write/dpi.rs).
- **UI separation** places SmartShift controls in the Pointer panel with interlocked toggles, while DPI configuration appears in a dedicated panel with sliders and presets.
- **Data model differences** include single-byte mode values for SmartShift versus 16-bit integer DPI tables for sensor resolution.

## Frequently Asked Questions

### What is the difference between SmartShift toggle and permanent ratchet in OpenLogi?

The SmartShift toggle switches between free-spin and standard ratchet modes based on scroll velocity thresholds, while the permanent-ratchet panel forces the wheel to stay in ratchet mode continuously by writing the magic value `0xFF` to the `ratchet_control_mode` field. The UI disables the permanent toggle when adjusting auto-disengage sensitivity to prevent conflicting configurations.

### Can SmartShift wheel mode and DPI controls be used simultaneously?

Yes, SmartShift and DPI controls are independent subsystems that can operate concurrently. SmartShift manages wheel mechanics via feature `0x2111`, while DPI adjustments modify sensor resolution through feature `0x1b04`. Changes to one do not affect the other, as evidenced by their separate write paths in [`crates/openlogi-device/src/write/smartshift.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-device/src/write/smartshift.rs) and [`crates/openlogi-device/src/write/dpi.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-device/src/write/dpi.rs).

### What HID++ feature ID controls the SmartShift wheel mode?

SmartShift functionality is controlled by the **SmartShift Enhanced** feature with HID++ ID `0x2111`. This feature exposes the `ratchet_control_mode` field that accepts values for free-spin, ratchet, or permanent-ratchet (`0xFF`) modes, distinct from the `0x1b04` feature used for DPI controls.

### How does the permanent-ratchet setting work at the protocol level?

At the protocol level, enabling permanent ratchet calls `set_ratchet_control_mode` with `SmartShiftMode::PermanentRatchet`, which serializes to `0xFF` in the HID++ packet payload. This value tells the device firmware to ignore automatic mode-switching logic and maintain constant ratchet resistance regardless of scroll speed, implemented in [`crates/openlogi-core/src/hid/smartshift.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/hid/smartshift.rs).