How to Capture and Remap Middle, Mode-Shift, and Thumbwheel Buttons in OpenLogi

You can capture and remap the middle Mode-Shift button and thumbwheel gestures in OpenLogi by mapping HID++ feature events to logical actions via TOML configuration or the openlogi-cli bind command.

OpenLogi is an open-source driver for Logitech mice that exposes low-level HID++ features through a Rust-based architecture. The project enables deep customization of mouse inputs—including the middle Mode-Shift button and thumbwheel—by translating hardware events into configurable actions like ToggleSmartShift or CycleDPI.

Understanding the Input Capture Architecture

OpenLogi uses a multi-process architecture where an agent maintains a direct HID++ session with the mouse hardware. This agent registers specific features—such as the Mode-Shift button (located beneath the scroll wheel) and the thumbwheel (feature ID 0x2150)—through the device's feature registry.

Incoming reports are parsed in crates/openlogi-device/src/session/gesture.rs, where the comment block at lines 3-10 explicitly documents the purpose: handling "DPI/ModeShift button, and the thumb wheel over HID++". The agent then packages these as CapturedInput objects and transmits them via a local-socket tarpc IPC channel to the GUI or overlay process.

Capturing Hardware Events

Mode-Shift Button Detection

The middle Mode-Shift button—typically used to toggle SmartShift ratchet modes—is identified by specific control IDs defined in crates/openlogi-device/src/reprog_controls.rs. The comment at lines 58-60 marks the "Control IDs of the 'DPI / ModeShift' button family", which the agent monitors through the HID++ reprogrammable controls feature.

Thumbwheel Gesture Parsing

Thumbwheel events are decoded in crates/openlogi-device/src/thumbwheel.rs, where lines 42-50 handle the raw thumbwheelEvent packet structure. The implementation parses byte 4 of the HID++ report to determine direction and velocity, converting physical wheel movements into logical gesture events.

Core Button Abstractions

Logical button representations reside in crates/openlogi-core/src/binding/button.rs. Lines 24-26 define the Mode-Shift variant with documentation noting it as "The 'ModeShift' button under the wheel – typically used for SmartShift". This abstraction layer allows the configuration system to reference hardware inputs by semantic names rather than raw HID codes.

Remapping Configuration Methods

Method 1: TOML Configuration File

The persistent binding store is located at ~/.config/openlogi/config.toml. You can map the Mode-Shift button and thumbwheel to built-in actions or custom scripts using the following structure:

[bindings.button]

# Toggle ratchet/free-spin mode when pressing the middle button

mode_shift = "ToggleSmartShift"

# Cycle through DPI presets on thumbwheel tap

thumbwheel = "CycleDPI"

For custom shell scripts, use the expanded table syntax:

[bindings.button]
mode_shift = { script = "/home/user/scripts/smartshift-toggle.sh" }
thumbwheel = { script = "/home/user/scripts/dpi-cycle.sh" }

Method 2: CLI Binding Commands

The openlogi-cli utility in crates/openlogi-cli/src/cmd/bind.rs provides runtime binding modifications without editing configuration files directly. Use the following syntax to remap inputs immediately:

# Map Mode-Shift to SmartShift toggle

openlogi-cli bind button mode_shift ToggleSmartShift

# Map thumbwheel to DPI cycling

openlogi-cli bind button thumbwheel CycleDPI

To verify active mappings during debugging, dump the current binding state:

openlogi-cli dump bindings

Key Source Files Reference

• Gesture Session: crates/openlogi-device/src/session/gesture.rs (lines 3-10, 224-476) — Captures raw DPI/Mode-Shift and thumbwheel HID++ reports
• Control Definitions: crates/openlogi-device/src/reprog_controls.rs (lines 58-60) — Control IDs for Mode-Shift family
• Thumbwheel Decoder: crates/openlogi-device/src/thumbwheel.rs (lines 42-50) — Parses thumbwheelEvent packets
• Binding Enum: crates/openlogi-core/src/binding/button.rs (lines 24-26) — Logical Mode-Shift button variant
• CLI Implementation: crates/openlogi-cli/src/cmd/bind.rs — Runtime binding commands

Summary

• OpenLogi captures the middle Mode-Shift button and thumbwheel through dedicated HID++ feature parsers in the agent process.
• Hardware events are abstracted into logical button variants in openlogi-core, allowing semantic remapping.
• You can configure bindings persistently in ~/.config/openlogi/config.toml or temporarily via openlogi-cli bind.
• The Mode-Shift button is typically mapped to ToggleSmartShift, while the thumbwheel commonly handles CycleDPI or custom script execution.

Frequently Asked Questions

How do I identify if my mouse supports Mode-Shift remapping?

Check the HID++ feature registry response in the agent logs. If crates/openlogi-device/src/reprog_controls.rs lists control IDs for the DPI/Mode-Shift family (lines 58-60), your device exposes the necessary reprogrammable controls. The MX Master series and similar Logitech mice typically include this functionality.

Can I bind the thumbwheel to keyboard shortcuts instead of mouse actions?

Yes. While the raw analysis shows CycleDPI and ToggleSmartShift as built-in actions, OpenLogi's binding system supports action chaining. You can map the thumbwheel to a custom script (as shown in the TOML examples) that executes xdotool or ydotool commands to inject arbitrary keystrokes, effectively translating wheel gestures into keyboard shortcuts.

What is the difference between Mode-Shift and SmartShift?

Mode-Shift refers to the physical button located beneath the scroll wheel (the middle button), while SmartShift is the software feature that toggles the wheel between ratcheted and freespin modes. According to openlogi-core/src/binding/button.rs (lines 24-26), the Mode-Shift button is the input mechanism, and ToggleSmartShift is the action typically assigned to it in the default configuration.

Where does OpenLogi store runtime binding changes?

Runtime modifications made via openlogi-cli bind are serialized to ~/.config/openlogi/config.toml (or the platform-specific configuration directory). The CLI commands in crates/openlogi-cli/src/cmd/bind.rs persist changes immediately to this TOML file, ensuring that remappings survive agent restarts.

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