# How to Configure Gesture Bindings in OpenLogi: A Complete Guide

> Learn to configure gesture bindings in OpenLogi with our complete guide. Discover how to map swipe directions to actions in TOML files for seamless device control.

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

---

**OpenLogi stores gesture bindings in a plain-text TOML file where you map swipe directions to named actions inside device-specific `[devices."<physical-key>".bindings]` tables.**

To configure gesture bindings in OpenLogi, you edit the application's TOML configuration—typically located at `~/.config/openlogi/config.toml`—to define direction-based actions for gesture-enabled buttons on your Logitech devices. Unlike simple button mappings, gesture bindings use a nested structure that assigns distinct actions to up, down, left, and right swipes, which the application parses at runtime through the `DeviceConfig` struct in [`crates/openlogi-core/src/config.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/config.rs).

## Where Gesture Bindings Are Stored

OpenLogi uses a hierarchical TOML format for all peripheral settings. The configuration schema is documented in [`docs/CONFIGURATION.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/CONFIGURATION.md) (lines 66-83), with gesture-specific metadata appearing at line 82 and device-key handling described in the "Shape" section (lines 39-45).

Before editing, locate your platform-specific config path:

- **Linux**: `~/.config/openlogi/config.toml`
- **macOS**: `~/Library/Application Support/openlogi/config.toml`
- **Windows**: `%APPDATA%\openlogi\config.toml`

Gesture bindings reside inside the `[devices."<physical-key>".bindings]` table, where `<physical-key>` is your device's unique identifier (e.g., `receiver:1234:slot:2`).

## Configuring Gesture Bindings

Follow these steps to map swipe directions to actions for any gesture-enabled button.

### Step 1: Locate Your Device Configuration

Identify or create the device entry using the physical device key reported by OpenLogi. This key follows the format `receiver:<id>:slot:<number>`:

```toml
[devices."receiver:1234:slot:2"]
enabled = true
custom_name = "MX Master 3"
dpi = 1200

```

### Step 2: Define the Gesture Map

Create a `bindings` subtable for your device. Use the button's logical name (e.g., `Button3` for the gesture button on MX Master mice) as the key, and supply a `gesture` table containing the four direction keys:

```toml
[devices."receiver:1234:slot:2".bindings]
Button3 = {
    gesture = {
        up    = "VolumeUp",
        down  = "VolumeDown",
        left  = "Back",
        right = "Forward"
    }
}

```

Each direction must contain a valid action name string. These names correspond to action definitions elsewhere in your configuration file.

### Step 3: Save and Reload

Save the file. OpenLogi watches the configuration file for changes and reloads automatically without requiring a restart, as implemented in the configuration parsing logic within [`crates/openlogi-core/src/config.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/config.rs).

## Disabling Specific Gesture Directions

You can selectively disable swipe directions for an entire device using the `disabled_gestures` array. Add this field directly inside the device table (not the bindings subtable):

```toml
[devices."receiver:1234:slot:2"]
disabled_gestures = ["left", "right"]

```

This prevents left and right swipes from generating any actions across all gesture buttons on that device, effectively freeing those directions for system-level shortcuts.

## Complete Configuration Example

Here is a full working example based on [`config.example.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/config.example.toml) that demonstrates proper structure alongside other device settings:

```toml
[devices."receiver:1234:slot:2"]
custom_name = "My MX Master 3"
enabled = true
dpi = 1200
thumbwheel_sensitivity = 14
disabled_gestures = ["left", "right"]

[devices."receiver:1234:slot:2".bindings]
Button3 = {
    gesture = {
        up    = "Copy",
        down  = "Paste",
        left  = "Back",
        right = "Forward"
    }
}

```

In this configuration, swiping up on Button3 triggers the `Copy` action, while swiping down triggers `Paste`. The `disabled_gestures` entry ensures left and right swipes are ignored entirely for this device.

## Summary

- OpenLogi configures gesture bindings through TOML files located in your system's config directory.
- Bindings live inside `[devices."<physical-key>".bindings]` tables using button logical names like `Button3`.
- The `gesture` subtable maps `up`, `down`, `left`, and `right` directions to named action strings.
- Use the `disabled_gestures` array in the device table to suppress specific directions device-wide.
- Configuration parsing and validation occur in [`crates/openlogi-core/src/config.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/config.rs) via the `DeviceConfig` struct.

## Frequently Asked Questions

### How do I find the correct physical device key for my Logitech device?

The physical device key follows the format `receiver:<receiver-id>:slot:<slot-number>` and appears in OpenLogi's logs when you connect a peripheral. You can retrieve it by running OpenLogi with verbose logging enabled, then use that exact string—including quotes—inside your TOML device tables, as documented in [`docs/CONFIGURATION.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/CONFIGURATION.md) (lines 66-83).

### Can I use different gesture bindings for different devices?

Yes. Each device has its own `[devices."<physical-key>"]` table with an isolated `bindings` subtable. Configure `Button3` with different gesture maps in each device block, and OpenLogi will apply the correct mappings based on which device is currently active, according to the implementation in [`crates/openlogi-core/src/config.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/config.rs).

### What action names are valid for gesture directions?

Valid action names are the same strings used for standard button bindings throughout OpenLogi. These typically include actions like `Copy`, `Paste`, `VolumeUp`, `VolumeDown`, `Back`, and `Forward`. Refer to the Actions section in [`docs/CONFIGURATION.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/CONFIGURATION.md) for the complete list of supported action strings recognized by the `DeviceConfig` parser.

### How do I disable gestures only on specific buttons rather than the entire device?

Currently, OpenLogi supports disabling gestures at the device level using the `disabled_gestures` array in the device table (documented at line 82 of [`docs/CONFIGURATION.md`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/CONFIGURATION.md)). To disable a specific direction on a single button, simply omit that direction from the button's `gesture` map—only defined directions will trigger actions, while undefined directions effectively perform no operation on that specific button.