# OpenLogi TOML Configuration File Structure: Complete Schema Guide

> Explore the OpenLogi TOML configuration file structure. Understand the schema, global settings, device configs, and keyboard bindings in this comprehensive guide.

- Repository: [Xuan Zhang/OpenLogi](https://github.com/AprilNEA/OpenLogi)
- Tags: api-reference
- Published: 2026-08-27

---

**The OpenLogi TOML configuration file is a versioned document structured around a top-level `Config` struct that defines global application settings, a map of per-device configurations keyed by physical device identifiers, and a global keyboard bindings section, all implemented in [`crates/openlogi-core/src/config.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/config.rs).**

OpenLogi stores all user preferences—from DPI settings to button remappings—in a single TOML document that is deserialized directly into Rust data structures. Understanding the OpenLogi TOML configuration file structure enables advanced customization of Logitech peripherals through direct file editing, bypassing GUI limitations while maintaining type safety through schema versioning.

## Top-Level Configuration Schema

The root of the configuration file contains five primary keys that organize all settings. The `schema_version` field is mandatory and currently set to `4`, ensuring the application can parse legacy formats and migrate data forward.

The `app_settings` table holds non-device preferences such as `launch_at_login`, `check_for_updates`, `language`, and `appearance`. The optional `selected_device` string specifies which device should appear selected on application startup, using the same physical identifier format found in the `devices` map.

## Device-Specific Configuration

The `devices` table is a map where each key represents a stable physical device identifier, such as `"receiver:abc1234:slot:2"`. According to the source code in [`crates/openlogi-core/src/config.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/config.rs), each device entry contains optional sub-tables that control hardware behavior.

### Input and Sensitivity Settings

Device entries support direct configuration of pointer behavior through fields like `dpi` (integer), `dpi_presets` (array of integers), `thumbwheel_sensitivity`, and `invert_scroll` (boolean). The `scroll_resolution` field accepts string values of `"high"` or `"low"` to adjust wheel granularity.

### Button and Gesture Bindings

The `bindings` table maps button identifiers—such as `Back`, `Forward`, or `GestureButton`—to action strings like `BrowserBack` or `MissionControl`. For gesture-capable buttons, a nested `GestureButton` table accepts directional keys (`Click`, `Up`, `Down`, `Left`, `Right`) to define motion-based triggers.

### Per-Application Overrides

Advanced configurations use the `per_app_bindings` table to define context-sensitive mappings. Entries are keyed by application bundle identifiers (e.g., `per_app_bindings."com.apple.Safari"`), allowing device buttons to perform different actions depending on the active foreground application.

### Advanced Hardware Features

Several optional sub-tables control proprietary Logitech features:

- **Action Ring**: Configure `action_ring.enabled`, `action_ring.haptics`, and `action_ring.default.slots` (an array of tables with `action` and `icon` fields) to customize the cylindrical input mechanism.
- **Lighting**: Set `lighting.enabled`, `lighting.color`, and `lighting.brightness` for RGB control on supported devices.
- **SmartShift**: Adjust `smartshift.mode`, `smartshift.auto_disengage`, and `smartshift.tunable_torque` to modify the adaptive scroll wheel behavior.
- **Host Switching**: The `host_switch_targets` array lists other device identifiers that can be targeted when pressing host-switch keys.

## Global Keyboard Bindings

Independent of any specific device, the `keyboard` table contains a `bindings` sub-table for system-wide function key remapping. These bindings apply to any connected keyboard and use the same action strings as device-specific configurations.

```toml
[keyboard.bindings]
f1 = "MissionControl"
"shift+command+f5" = "ShowDesktop"

```

## Configuration File Locations and Examples

While the exact filesystem path varies by operating system, the canonical reference implementation resides in [`docs/config.example.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/config.example.toml). This file demonstrates valid syntax for all supported features, including complex nested tables and array structures.

```toml

# Minimal viable configuration

schema_version = 4

[app_settings]
launch_at_login = true
language = "en"

[devices."receiver:abcd1234:slot:1"]
dpi = 1600
dpi_presets = [800, 1600, 3200]

[devices."receiver:abcd1234:slot:1".bindings]
Back = "BrowserBack"
Forward = "BrowserForward"

```

Programmatic access is handled through the `Config` struct, which provides methods like `load_from_path()`:

```rust
use openlogi_core::config::Config;

let cfg = Config::load_from_path("/home/user/.config/openlogi/config.toml")?;
println!("Loaded {} device(s)", cfg.devices.len());

```

## Summary

- The configuration file uses **schema version 4**, defined by the integer `schema_version` field at the root level.
- Global preferences are stored in the **`app_settings`** table, while the optional **`selected_device`** field controls startup behavior.
- Per-device settings reside in the **`devices`** map, keyed by physical identifiers like `"receiver:abc123:slot:2"`.
- Each device supports **bindings**, **gesture mappings**, **per-application overrides**, **action ring** settings, **lighting** controls, and **SmartShift** configuration.
- System-wide keyboard shortcuts are defined in the **`keyboard.bindings`** table, independent of Logitech hardware.
- All schema definitions are located in **[`crates/openlogi-core/src/config.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/config.rs)**, with a complete example available in **[`docs/config.example.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/config.example.toml)**.

## Frequently Asked Questions

### Where is the OpenLogi configuration file stored on disk?

The file location follows platform-specific conventions for application configuration directories, typically within the user's config folder (e.g., `~/.config/openlogi/` on Linux or `~/Library/Application Support/` on macOS). You can load the file programmatically using `Config::load_from_path()` as implemented in the `openlogi_core` crate.

### What is the current schema version for OpenLogi TOML files?

The current configuration schema version is **4**, specified by the `schema_version` field at the top of the TOML document. This versioning allows the Rust deserializer in [`crates/openlogi-core/src/config.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/config.rs) to handle configuration migrations and reject incompatible legacy formats.

### How do I configure different button mappings for specific applications?

Use the `per_app_bindings` table within a device entry, keyed by the target application's bundle identifier (e.g., `per_app_bindings."com.example.App"`). This overrides the default `bindings` table for that device only when the specified application is in the foreground.

### Can I disable hardware features like the action ring via configuration?

Yes. Set `devices."<device-id>".action_ring.enabled = false` to disable the action ring, or adjust `devices."<device-id>".smartshift.mode` to change adaptive scroll behavior. These boolean and enum fields are deserialized directly into the device configuration struct defined in the source code.