OpenLogi Configuration File Format: TOML Structure and Implementation

OpenLogi uses TOML (Tom's Obvious, Minimal Language) as its configuration file format, allowing users to define device profiles, global defaults, and per-application settings in a human-readable file typically named config.toml.

OpenLogi stores user-defined settings in a TOML configuration file that provides strict data typing while remaining straightforward to edit manually. Located in the AprilNEA/OpenLogi repository, the configuration file format supports complex nested structures required for Logitech HID++ device customization. The application leverages Rust's toml crate to deserialize configuration values directly into strongly-typed structs defined in crates/openlogi-core/src/config.rs.

TOML File Location and Naming Conventions

OpenLogi expects its configuration as a TOML file, conventionally named config.toml in the application directory. The repository provides a comprehensive reference file at docs/config.example.toml that demonstrates every available configuration section and valid syntax. Users should copy this example file as the starting point for their custom configurations, while detailed key descriptions reside in docs/CONFIGURATION.md.

Core Configuration Sections

The OpenLogi TOML structure organizes settings into three primary tables that control different aspects of device behavior.

The [global] Section

The [global] table defines default values that apply when no specific profile matches the active application. This section typically contains fallback DPI settings and base button behaviors that ensure consistent device operation across all contexts.

The [profile] Section

Per-application configurations reside under [profile."application.identifier"] tables, where the quoted string represents the target application's identifier (such as com.example.app). These sections override global settings with context-specific values, including custom DPI levels, button remappings, and macro definitions stored as arrays of key combinations.

The [device] Section

Device-specific hardware overrides appear in [device."Device Name"] tables, which configure hardware features like SmartShift settings. These settings apply regardless of the active application profile, making them ideal for persistent device-level customizations that survive context switches.

Configuration Parsing Implementation

The actual deserialization logic resides in crates/openlogi-core/src/config.rs, where the Rust implementation uses the toml crate to parse configuration files into internal structs. This approach provides compile-time guarantees about configuration structure and type safety when accessing values.

The loading process follows this pattern:

// Loading the configuration (simplified)
use openlogi_core::config::Config;
let cfg: Config = toml::from_str(&std::fs::read_to_string("config.toml")?)?;
println!("Default DPI: {}", cfg.global.dpi);

This implementation ensures that invalid TOML syntax or type mismatches—such as assigning a string to a numeric DPI field—result in clear deserialization errors before the application attempts hardware communication.

Practical Configuration Examples

A minimal valid configuration demonstrating the three core sections follows this structure:

# config.example.toml – minimal OpenLogi configuration

[global]
dpi = 800                   # Default DPI if no profile specifies one

[profile."com.apple.Terminal"]
dpi = 1200
button_1 = "scroll_up"

[device."Logitech G502"]
smart_shift = true

Complex configurations support nested arrays for macro definitions, as shown in this profile-specific example:

[profile."com.example.app"]
dpi = 1600
button_1 = "macro"
macro_1 = ["Ctrl+Shift+X", "Alt+F4"]

The TOML syntax supports strings, integers, booleans, and arrays, accommodating the hierarchical data requirements of advanced Logitech device configuration without sacrificing readability.

Summary

• OpenLogi uses TOML as its sole configuration file format, parsed via the Rust toml crate into strongly-typed structs defined in crates/openlogi-core/src/config.rs.
• Configuration files typically use the name config.toml and follow the structure defined in docs/config.example.toml.
• Three primary sections control behavior: [global] for defaults, [profile] for application-specific overrides, and [device] for hardware settings.
• The parsing implementation ensures type safety and provides detailed error messages for malformed configurations before hardware initialization.
• Detailed documentation for all available keys resides in docs/CONFIGURATION.md.

Frequently Asked Questions

What is the default configuration file name for OpenLogi?

By convention, OpenLogi looks for a file named config.toml in the application directory. While the parser can technically read any TOML file path provided at runtime, config.toml is the standard expected by the application's default loading routines.

Where can I find a complete example of the OpenLogi configuration file format?

The repository contains a comprehensive reference at docs/config.example.toml that demonstrates every valid section, data type, and configuration key. Additionally, docs/CONFIGURATION.md provides detailed explanations of each setting's purpose and acceptable values.

Does OpenLogi support configuration formats other than TOML?

No, the current implementation exclusively supports TOML. The deserialization code in crates/openlogi-core/src/config.rs specifically uses the toml crate to parse configuration strings into Rust structs, and no alternative parsers for YAML or JSON are implemented in the codebase.

How do I validate my OpenLogi configuration before running the application?

Since OpenLogi uses strongly-typed deserialization, the most reliable validation method is attempting to load the configuration file using the openlogi_core::config::Config struct. Any syntax errors, missing required fields, or type mismatches will trigger informative error messages during the toml::from_str() parsing operation, preventing the application from starting with invalid settings.

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