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

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. Each ThumbwheelPreset variant maps to a pair of Action variants from 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:

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

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

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

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 – Implements low-level HID++ communication, including get_thumbwheel_info and set_thumbwheel_reporting
• 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 – Defines ThumbwheelPreset, handles UI logic, and maps presets to Action pairs
• 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, 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 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.

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