# OpenLogi Configuration File Format: TOML Structure and Implementation

> Discover the TOML structure for OpenLogi configuration files. Learn how to define device profiles and application settings in a human-readable format. Explore the config.toml file.

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

---

**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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/config.rs).

## TOML File Location and Naming Conventions

OpenLogi expects its configuration as a TOML file, conventionally named [`config.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/config.toml) in the application directory. The repository provides a comprehensive reference file at [`docs/config.example.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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:

```rust
// 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:

```toml

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

```toml
[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`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/config.rs).
- Configuration files typically use the name [`config.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/config.toml) and follow the structure defined in [`docs/config.example.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/config.toml) in the application directory. While the parser can technically read any TOML file path provided at runtime, [`config.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/docs/config.example.toml) that demonstrates every valid section, data type, and configuration key. Additionally, [`docs/CONFIGURATION.md`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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.