# How to Bind OpenLogi Thumbwheel Actions: HID++ Configuration Guide

> Learn how to bind OpenLogi thumbwheel actions by mapping TOML profiles to HID++ events. Customize your hardware signals with this configuration guide.

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

---

**OpenLogi binds thumbwheel actions by mapping TOML profile presets to HID++ diverted events, using `ThumbwheelFeature::set_thumbwheel_reporting` to intercept hardware signals and route them to user-defined `Action` variants like `VolumeUp` or `MouseBack`.**

OpenLogi is an open-source driver for Logitech mice that exposes the thumbwheel as a configurable HID++ feature. Binding thumbwheel actions requires understanding how the driver translates physical scroll events into software commands through diverted reporting modes and preset mappings defined in the AprilNEA/OpenLogi repository.

## Understanding the HID++ Thumbwheel Architecture

### Feature Discovery and Capability Detection

The thumbwheel is exposed as HID++ feature ID `0x2150`. When OpenLogi initializes a device, it calls `ThumbwheelFeature::get_thumbwheel_info` to retrieve the hardware capabilities. This determines whether the thumbwheel supports native bidirectional reporting or requires event diversion to override default behavior.

### Event Diversion Mechanism

To bind custom actions, OpenLogi switches the thumbwheel from native mode to diverted mode using `ThumbwheelFeature::set_thumbwheel_reporting`. This method accepts two parameters: a `ThumbwheelReportingMode` enum (typically `ThumbwheelReportingMode::Diverted`) and an `invert_direction` boolean flag that reverses the forward/backward orientation.

## Mapping Presets to Core Actions

### Built-in Thumbwheel Presets

The desktop interface presents presets defined in [`crates/openlogi-desktop/src/features/mouse/thumbwheel.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-desktop/src/features/mouse/thumbwheel.rs). Each `ThumbwheelPreset` variant maps to a pair of `Action` variants from [`crates/openlogi-core/src/binding/action.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/binding/action.rs):

- `ThumbwheelPreset::BackForward` → `Action::MouseBack` / `Action::MouseForward`
- `ThumbwheelPreset::UndoRedo` → `Action::Undo` / `Action::Redo`
- `ThumbwheelPreset::Volume` → `Action::VolumeDown` / `Action::VolumeUp`

### Custom Action Pairs

If the preset list does not match your use case, you can define a custom `ThumbwheelPair` by specifying individual actions for the backward and forward directions. The system stores these as raw action strings in the profile TOML.

## Configuring Bindings in TOML Profiles

OpenLogi persists thumbwheel configurations in user profiles located at `~/.config/openlogi/profiles/`. The `[mouse.thumbwheel]` section accepts either a preset name or explicit action pairs.

### Using Presets

To select a built-in preset, reference the enum variant name:

```toml
[mouse.thumbwheel]
preset = "Volume"

```

For reversed direction (e.g., scrolling up for volume down), append "Reversed" to the preset name, which sets the `invert_direction` flag internally:

```toml
[mouse.thumbwheel]
preset = "VolumeReversed"

```

### Defining Custom Actions

When no preset matches your requirements, specify the actions directly using valid enum variants from the `Action` type:

```toml
[mouse.thumbwheel]
backward = "ScrollDown"
forward = "ScrollUp"

```

The desktop agent reads this configuration, constructs a `ThumbwheelPair`, and checks `ThumbwheelPreset::recognize`. If the pair does not match a known preset, the UI displays "Custom" while applying the specified bindings.

## Programmatic Thumbwheel Control

For automation scripts or alternative frontends, you can manipulate the thumbwheel reporting mode directly via the HID++ crate.

### Enabling Diverted Mode

The following Rust example demonstrates how to programmatically enable diverted reporting mode on a thumbwheel feature handle:

```rust
use openlogi_hidpp::feature::ThumbwheelFeature;
use openlogi_hidpp::feature::ThumbwheelReportingMode;

async fn enable_diverted_mode(thumbwheel: &ThumbwheelFeature) -> Result<(), Hidpp20Error> {
    // Divert events to HID++ and preserve native direction
    thumbwheel
        .set_thumbwheel_reporting(ThumbwheelReportingMode::Diverted, false)
        .await
}

```

This call intercepts thumbwheel events at the hardware level, allowing OpenLogi to remap them to arbitrary actions rather than passing through default mouse button events.

## Key Source Files

The thumbwheel binding system spans multiple crates in the OpenLogi repository:

- [`crates/openlogi-hidpp/src/feature/thumbwheel.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-hidpp/src/feature/thumbwheel.rs) – Implements low-level HID++ communication, including `get_thumbwheel_info` and `set_thumbwheel_reporting`
- [`crates/openlogi-device/src/thumbwheel.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-device/src/thumbwheel.rs) – Provides the higher-level `Thumbwheel` wrapper used by the agent process
- [`crates/openlogi-desktop/src/features/mouse/thumbwheel.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-desktop/src/features/mouse/thumbwheel.rs) – Defines `ThumbwheelPreset`, handles UI logic, and maps presets to `Action` pairs
- [`crates/openlogi-core/src/binding/action.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/binding/action.rs) – Enumerates all bindable actions available for thumbwheel mapping

## Summary

- OpenLogi represents the thumbwheel as HID++ feature `0x2150`, discovered via `ThumbwheelFeature::get_thumbwheel_info`
- Binding requires diverting events using `ThumbwheelFeature::set_thumbwheel_reporting` with `ThumbwheelReportingMode::Diverted`
- Presets like `Volume` and `BackForward` map to `Action` pairs defined in `openlogi-core`
- Custom bindings use explicit `backward` and `forward` keys in the TOML profile
- The `invert_direction` parameter handles reversed scroll orientation without swapping action definitions

## Frequently Asked Questions

### Can I bind any keyboard shortcut to the OpenLogi thumbwheel?

The thumbwheel binds to `Action` enum variants defined in [`crates/openlogi-core/src/binding/action.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/binding/action.rs), which includes media controls, scrolling, and mouse buttons. For arbitrary keyboard shortcuts, you would need to map the thumbwheel to a specific action that your operating system or window manager interprets as that shortcut, as the HID++ protocol does not transmit raw keyboard scan codes through the thumbwheel feature.

### Where are thumbwheel configurations stored?

User-specific thumbwheel bindings reside in TOML files under `~/.config/openlogi/profiles/`, typically in [`default.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/default.toml) under the `[mouse.thumbwheel]` section. The desktop agent reads these files at startup and programs the device accordingly.

### How do I reverse the thumbwheel direction without changing actions?

Use the "Reversed" suffix on any preset name (e.g., `preset = "VolumeReversed"`) or set the `invert_direction` parameter to `true` when calling `set_thumbwheel_reporting` programmatically. This flips the hardware orientation flag without modifying the underlying `Action` mappings.

### What happens if I specify an invalid action name in the TOML?

OpenLogi validates action names against the `Action` enum during profile loading. If an invalid variant is specified, the configuration parser will reject the profile section, and the thumbwheel will likely fall back to default behavior or the previously valid configuration, depending on the error handling implementation in `crates/openlogi-desktop`.