# How to Configure OpenLogi Button Mappings: A Complete TOML Guide

> Learn how to configure OpenLogi button mappings using a TOML guide. Customize application or global behaviors with specific actions and parameters in your config file.

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

---

**OpenLogi stores button mappings in a plain-text TOML configuration file where each profile defines application-specific or global behaviors using the `[profiles.<name>.buttons.<id>]` syntax with `action` and optional `params` fields.**

OpenLogi is an open-source Logitech device management tool that replaces proprietary software with a flat-file configuration approach. Learning how to configure OpenLogi button mappings allows you to remap side buttons, DPI toggles, and scroll wheels to custom actions or macros without vendor lock-in. All settings reside in a single TOML file that the agent monitors for changes.

## Understanding the Configuration Structure

OpenLogi uses a profile-based architecture defined in [`docs/CONFIGURATION.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/CONFIGURATION.md). Each profile corresponds to either a specific executable or a global catch-all, allowing contextual button behavior that switches automatically based on the active window.

### The profiles Table

Configuration files are organized into **profiles** under the top-level `[profiles]` namespace. The special `"default"` profile acts as a fallback when no application-specific mapping exists. According to the implementation in [[`crates/openlogi-core/src/config.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/config.rs)](https://github.com/AprilNEA/OpenLogi/blob/master/crates/openlogi-core/src/config.rs), the parser expects the following hierarchy:

```toml
[profiles.<profile_name>]

# Per-profile settings like DPI

[profiles.<profile_name>.buttons.<button_id>]
action = "<action_name>"
params = { key = "value" }

```

- **`<profile_name>`** — String identifier. Use `"default"` for global settings, or `"app.exe"` for per-application mappings.
- **`<button_id>`** — Numeric identifier as reported by the HID device (e.g., `1` for the first side button).

### Button Identifiers

Physical buttons are referenced by integer IDs. While these vary by Logitech model, standard MX Master series devices typically map side buttons to low integers. The configuration parser validates these IDs against available hardware inputs defined in the core library.

## Defining Button Actions

Every button mapping requires an `action` field and optionally accepts a `params` table for customization. Supported actions include `scroll`, `dpi_up`, `dpi_down`, `smartshift_toggle`, and `macro`.

### Basic Syntax

The minimal configuration binds a button to a built-in action:

```toml
[profiles.default.buttons.1]
action = "scroll"

```

This assigns the scroll action to button 1 in the default profile.

### Action Parameters

Complex actions accept structured parameters. For example, scroll speed adjustments use the `speed` key, while macros require a `keys` array. The full schema is documented in [[`docs/CONFIGURATION.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/CONFIGURATION.md)](https://github.com/AprilNEA/OpenLogi/blob/master/docs/CONFIGURATION.md) and enforced by the deserialization logic in [[`crates/openlogi-core/src/config.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/config.rs)](https://github.com/AprilNEA/OpenLogi/blob/master/crates/openlogi-core/src/config.rs).

```toml
[profiles.default.buttons.1]
action = "scroll"
params = { speed = 3 }

```

## Practical Configuration Examples

Real-world setups often require mixing global defaults with application-specific overrides. The agent loads these definitions at startup and monitors the file for changes.

### Example 1: Global Scroll Mapping

Map the first side button to a fast scroll action across all applications:

```toml
[profiles.default.buttons.1]
action = "scroll"
params = { speed = 3 }

```

### Example 2: Per-Application DPI Control

Assign DPI-up functionality to button 2 only when Photoshop is active:

```toml
[profiles."photoshop.exe".buttons.2]
action = "dpi_up"

```

### Example 3: Complex Macro Binding

Bind a keystroke sequence to button 3 using the macro action with inline array syntax:

```toml
[profiles.default.buttons.3]
action = "macro"
params = { keys = ["Ctrl", "Alt", "M"] }

```

## Configuration Reload and File Location

Place your configuration file at `~/.config/openlogi/config.toml` (Linux) or the platform-appropriate equivalent. As implemented in [[`crates/openlogi-agent/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent/src/main.rs)](https://github.com/AprilNEA/OpenLogi/blob/master/crates/openlogi-agent/src/main.rs), the agent automatically reloads the configuration when the file changes on disk. Alternatively, force an immediate reload by running:

```bash
openlogi reload

```

For a complete reference implementation, see [[`docs/config.example.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/config.example.toml)](https://github.com/AprilNEA/OpenLogi/blob/master/docs/config.example.toml) in the repository.

## Summary

- **Configuration format**: Plain-text TOML file located at `~/.config/openlogi/config.toml`
- **Profile syntax**: Use `[profiles.<name>.buttons.<id>]` to define mappings
- **Required fields**: Each button requires an `action` string
- **Optional fields**: Use `params` tables to pass action-specific arguments like `speed` or `keys`
- **Reload behavior**: Changes apply automatically or via `openlogi reload` as handled by the agent entry point
- **Source references**: Parsing logic lives in [`crates/openlogi-core/src/config.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/config.rs) with runtime loading in [`crates/openlogi-agent/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent/src/main.rs)

## Frequently Asked Questions

### Where does OpenLogi look for the configuration file?

By default, OpenLogi searches for [`config.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/config.toml) in the platform-specific user configuration directory, typically `~/.config/openlogi/` on Linux systems. You can verify the exact path and loading behavior by examining the initialization sequence in [[`crates/openlogi-agent/src/main.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent/src/main.rs)](https://github.com/AprilNEA/OpenLogi/blob/master/crates/openlogi-agent/src/main.rs).

### How do I find the numeric button ID for my mouse?

Button IDs correspond to the HID usage indices reported by your specific Logitech device. While the core configuration parser in [[`crates/openlogi-core/src/config.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/config.rs)](https://github.com/AprilNEA/OpenLogi/blob/master/crates/openlogi-core/src/config.rs) accepts any integer, you should consult your device's technical specifications or use a HID debugging tool to identify the correct index for physical buttons.

### Can I share button mappings across all applications?

Yes. Define bindings under the `[profiles.default]` section to create global mappings. These apply whenever the active window does not match a specific application profile. The default profile serves as the fallback layer in the hierarchy described in [[`docs/CONFIGURATION.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/CONFIGURATION.md)](https://github.com/AprilNEA/OpenLogi/blob/master/docs/CONFIGURATION.md).

### What actions are supported besides scroll and DPI controls?

OpenLogi supports `smartshift_toggle`, `macro`, and any custom actions defined in the `actions` table of your configuration. The full list of built-in identifiers and their parameter schemas is documented in the project's configuration specification.