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

> Remap middle, mode-shift, and thumbwheel buttons in OpenLogi. Map HID++ events to logical actions using TOML or the openlogi-cli bind command for custom control.

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

---

**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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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:

```toml
[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:

```toml
[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`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-cli/src/cmd/bind.rs) provides runtime binding modifications without editing configuration files directly. Use the following syntax to remap inputs immediately:

```bash

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

```bash
openlogi-cli dump bindings

```

## Key Source Files Reference

- **Gesture Session**: [`crates/openlogi-device/src/session/gesture.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-device/src/reprog_controls.rs) (lines 58-60) — Control IDs for Mode-Shift family
- **Thumbwheel Decoder**: [`crates/openlogi-device/src/thumbwheel.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-device/src/thumbwheel.rs) (lines 42-50) — Parses `thumbwheelEvent` packets
- **Binding Enum**: [`crates/openlogi-core/src/binding/button.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/binding/button.rs) (lines 24-26) — Logical Mode-Shift button variant
- **CLI Implementation**: [`crates/openlogi-cli/src/cmd/bind.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-cli/src/cmd/bind.rs) persist changes immediately to this TOML file, ensuring that remappings survive agent restarts.