OpenLogi TOML Configuration File Structure: Complete Schema Guide

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.

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, 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.

[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. This file demonstrates valid syntax for all supported features, including complex nested tables and array structures.

# 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():

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, with a complete example available in 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 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.

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