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

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

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:

// 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):

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

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