# How to Remap Buttons on Your Logitech Mouse with OpenLogi: A Complete Guide

> Easily remap Logitech mouse buttons using OpenLogi. This guide shows how to leverage HID++ commands for custom button mapping without Logitech Options+.

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

---

**Yes, OpenLogi allows you to remap buttons on any Logitech HID++-compatible mouse without using Logitech Options+, implementing low-level HID++ protocol commands to rewrite the device's internal button mapping tables.**

OpenLogi is an open-source alternative to proprietary Logitech configuration software that provides local-first button remapping for Logitech mice. If you want to remap buttons on a Logitech mouse with OpenLogi, the tool implements a three-layer architecture that directly manipulates the HID++ protocol to reprogram physical button actions. This approach works entirely offline across macOS and Linux (with early Windows support), requiring no cloud services or proprietary drivers.

## How Button Remapping Works in OpenLogi

OpenLogi implements button remapping through three tightly-integrated layers that bridge low-level hardware communication with user-friendly configuration. Unlike software-level key remappers, OpenLogi writes new mappings directly to the mouse firmware using the HID++ reprogrammable-control feature.

### Device Layer: HID++ Protocol Implementation

At the core of the remapping system sits the HID++ driver in `crates/openlogi-hidpp`. This crate implements the *reprogrammable-control* feature that exposes a device's button remapping capabilities. When you change a button mapping, OpenLogi dispatches a `SetCidReporting` command that updates the device's internal reporting state table.

The high-level driver code in [`crates/openlogi-device/src/write/reprog_controls.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-device/src/write/reprog_controls.rs) wraps these protocol operations, providing a clean interface to `set_cid_reporting` that translates logical user actions into binary HID++ packets. This file maintains the authoritative implementation for persisting remap configurations to hardware.

### Agent Runtime: Capture and Translation

The background agent (`openlogi-agent`) maintains a live capture plan for each connected device. When the system detects a button press, the hook logic in [`crates/openlogi-hook/src/lib.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-hook/src/lib.rs) evaluates whether the source device is remappable via the `source_is_remappable` function.

If the device qualifies as a Logitech HID++ mouse, the agent intercepts the original button event and consults the stored profile to determine the mapped action. It then translates the event before it reaches the operating system, ensuring that remapped clicks appear as the new action to all applications while remaining invisible to the original button logic.

### User Interface: Profile Management

The desktop GUI (`crates/openlogi-desktop`) presents a per-profile editor where you assign logical actions (such as "Middle Click" or "Back") to physical buttons. The UI logic in [`crates/openlogi-desktop/src/features/mouse/geometry.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-desktop/src/features/mouse/geometry.rs) exposes remappable button markers only for supported Logitech devices, filtering out buttons that cannot be reprogrammed on incompatible hardware.

When you save a profile, OpenLogi writes the configuration to a local TOML file (typically `~/.config/openlogi/profile.toml`) and instructs the agent to push the new mappings to the device via the HID++ write path.

## Methods to Remap Buttons

You can configure button mappings through three interfaces: manual TOML editing, the command-line interface, or programmatic Rust API calls.

### Manual TOML Configuration

For power users, OpenLogi stores profiles as human-readable TOML files. Create or edit `~/.config/openlogi/profile.toml` to define device-specific remaps using HID++ control IDs:

```toml

# ~/.config/openlogi/profile.toml

[[profiles]]
name = "My Mouse"
device = "Logitech MX Master 3"

# Button IDs follow the HID++ spec (see openlogi-hidpp::feature::reprog_controls)

# Map Button 4 → Middle Click, Button 5 → Back

[profiles.remap]
0x07 = { action = "MiddleClick" }   # Button 4

0x08 = { action = "Back" }          # Button 5

```

When OpenLogi starts, it loads this configuration and calls `reprog_controls::set_cid_reporting` for each entry, updating the device’s internal mapping table according to the HID++ specification.

### Command-Line Interface

The CLI tool provides scriptable access to the same remapping engine used by the GUI. Located in [`crates/openlogi-cli/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-cli/src/main.rs), this interface wraps the HID++ write path for automation and headless environments.

```bash

# List all detected Logitech HID++ devices

openlogi-cli list

# Remap button 4 (control ID 0x07) to "MiddleClick" on a specific device

openlogi-cli set-remap --device "Logitech MX Master 3" --control 0x07 --action MiddleClick

```

The CLI invokes the same `set_cid_reporting` routine found in the device driver, ensuring consistency across all configuration methods.

### Rust API Integration

Developers can integrate OpenLogi remapping into custom applications using the agent runtime API. This approach allows dynamic remapping without restarting the service:

```rust
use openlogi_device::write::reprog_controls::{ControlId, Reporting};
use openlogi_agent_core::runtime::Runtime;

// Assume `runtime` is a running OpenLogi agent instance
let device_id = /* obtain device identifier */;
let control = ControlId(0x07);               // Button 4
let new_reporting = Reporting {
    diverted: false,
    raw_xy: false,
    remap: Some(control),                     // Map to MiddleClick (control 0x07)
};
runtime.set_cid_reporting(device_id, control, new_reporting);

```

This snippet demonstrates direct interaction with the agent's runtime, which ultimately writes the new HID++ configuration to the mouse firmware.

## Key Source Files and Architecture

Understanding the codebase helps when debugging remapping issues or contributing new features:

- **[`crates/openlogi-hidpp/src/feature/reprog_controls.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-hidpp/src/feature/reprog_controls.rs)**: Implements the HID++ *reprogrammable-control* feature that defines how to read and write button remap states to the device.
- **[`crates/openlogi-device/src/write/reprog_controls.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-device/src/write/reprog_controls.rs)**: High-level driver that issues write commands to apply button mappings; contains the authoritative `set_cid_reporting` implementation.
- **[`crates/openlogi-hook/src/lib.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-hook/src/lib.rs)**: Contains `source_is_remappable` logic that filters capture events to identify Logitech devices eligible for hardware-level remapping.
- **[`crates/openlogi-desktop/src/features/mouse/geometry.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-desktop/src/features/mouse/geometry.rs)**: UI component that renders remappable button indicators only for supported Logitech mice.
- **[`crates/openlogi-cli/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-cli/src/main.rs)**: Entry point for command-line remapping operations, bridging user commands to the device driver.

## Summary

- OpenLogi remaps Logitech mouse buttons at the hardware level using the HID++ protocol, not software-level key interception.
- The architecture separates concerns into a protocol driver (`openlogi-hidpp`), a runtime agent (`openlogi-agent`), and a configuration interface.
- You can configure mappings via TOML files, CLI commands, or the Rust API, all utilizing the same `set_cid_reporting` implementation.
- Remapping requires HID++-compatible Logitech hardware and works locally without cloud services or proprietary drivers.
- Key implementation files reside in [`crates/openlogi-device/src/write/reprog_controls.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-device/src/write/reprog_controls.rs) and [`crates/openlogi-hidpp/src/feature/reprog_controls.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-hidpp/src/feature/reprog_controls.rs).

## Frequently Asked Questions

### Does OpenLogi support all Logitech mouse models?

OpenLogi supports any Logitech mouse that implements the HID++ protocol specification. The `source_is_remappable` function in [`crates/openlogi-hook/src/lib.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-hook/src/lib.rs) specifically checks for HID++ compatibility before allowing remapping operations. Most modern Logitech mice (MX series, gaming series) use HID++, but older devices using standard HID descriptors may have limited or no remapping support.

### Can I remap mouse buttons without using the GUI?

Yes. OpenLogi provides headless configuration through both TOML files and the CLI. You can edit `~/.config/openlogi/profile.toml` directly or use `openlogi-cli set-remap` commands to update mappings programmatically. Both methods invoke the same underlying driver code in [`crates/openlogi-device/src/write/reprog_controls.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-device/src/write/reprog_controls.rs) that the GUI uses.

### Will remapped buttons work in all applications?

Yes. Because OpenLogi writes remappings directly to the device firmware via HID++ `SetCidReporting` commands, the translated button events reach the operating system as if they were physically different buttons. This hardware-level approach ensures that all applications, including games and system utilities, see the remapped actions rather than the original button presses.

### Is internet connectivity required for button remapping?

No. OpenLogi operates as a local-first tool that communicates directly with your mouse through USB or Bluetooth HID++ protocols. All configuration storage (TOML profiles), runtime logic (`openlogi-agent`), and protocol implementation (`openlogi-hidpp`) reside locally on your machine, eliminating the need for Logitech Options+ cloud services or internet access.