How to Configure Global Keyboard Remapping with F-Key Triggers in OpenLogi

OpenLogi enables system-wide F-Key shortcuts through the [keyboard.bindings] table in ~/.config/openlogi/config.toml, where function keys like f1 through f12 map to built-in actions or custom key chords that execute regardless of the active Logitech device.

OpenLogi is an open-source input management framework that provides system-wide keyboard customization across Logitech peripherals. You can configure global keyboard remapping with F-Key triggers by editing a TOML configuration file, allowing function keys to trigger actions like Mission Control or complex shortcuts even when switching between different devices. This functionality is implemented in the core binding system and processed by the global input hook layer before any device-specific mappings are evaluated.

Configuration File Location and Structure

The keyboard.bindings Table

Every F-Key mapping resides in the [keyboard.bindings] section of your OpenLogi configuration. By default, OpenLogi looks for this file at ~/.config/openlogi/config.toml. Each entry in this table maps a key identifier to an Action variant supported by the codebase.

The parser processes this table in crates/openlogi-core/src/config.rs (referenced via openlogi-core/src/lib.rs), converting TOML entries into Binding structures. These bindings are stored in the KeyboardBindings map and evaluated by the input hook layer in crates/openlogi-hook/src/lib.rs.

Mapping F-Keys to Actions

For function-key triggers, use the lowercase key name (f1, f2, … f12) as the left-hand side of the binding. The right-hand side accepts either a built-in action string or a CustomShortcut object containing a key chord.

Simple F-Key mapping:

[keyboard.bindings]
f1 = "MissionControl"          # Pressing F1 opens Mission Control

f2 = "ShowDesktop"             # Pressing F2 shows the desktop

Modifier combinations:

[keyboard.bindings]
"shift+command+f5" = "ShowDesktop"

Custom shortcut chords:

[keyboard.bindings]
f3 = { CustomShortcut = "Ctrl+Shift+P" }   # F3 sends the chord Ctrl + Shift + P

Technical Implementation of Global Bindings

When OpenLogi loads, the configuration parser instantiates the Action enum defined in crates/openlogi-core/src/binding/action.rs. This enum includes the CustomShortcut(KeyCombo) variant, which handles complex key combinations for F-Key triggers.

The crates/openlogi-hook/src/lib.rs module consults the global KeyboardBindings map before checking any per-device bindings. This ensures that global keyboard remapping takes precedence over device-specific configurations. If an incoming keystroke matches an entry in the global map, OpenLogi executes the associated action immediately without passing the event to the active device's handler.

Cross-Platform F-Key Translation

OpenLogi translates F-Key virtual-key codes to platform-specific equivalents automatically. The injection logic in crates/openlogi-inject/src/inject/windows.rs and crates/openlogi-inject/src/inject/linux.rs handles the native API calls required to execute CustomShortcut chords on non-macOS systems.

This means the same f1 = "MissionControl" syntax works identically across macOS, Windows, and Linux, with the core injection layer abstracting platform differences.

Summary

• Configure F-Key triggers in the [keyboard.bindings] table inside ~/.config/openlogi/config.toml
• Use lowercase identifiers (f1 through f12) for function keys, optionally combined with modifiers like shift+command+f5
• Assign built-in actions such as MissionControl or custom chords via CustomShortcut = "KeyCombo"
• Global bindings are parsed in crates/openlogi-core/src/config.rs and stored in the KeyboardBindings map
• The input hook in crates/openlogi-hook/src/lib.rs processes global bindings before per-device mappings, ensuring system-wide precedence
• Platform-specific translation occurs in crates/openlogi-inject/src/inject/windows.rs and linux.rs

Frequently Asked Questions

Where does OpenLogi store global keyboard configuration?

OpenLogi reads global keyboard settings from ~/.config/openlogi/config.toml by default. This TOML file contains the [keyboard.bindings] table where you define F-Key mappings that apply across all connected Logitech devices. The parser builds the configuration from this file during application startup.

Can I use modifier keys like Command or Control with F-Keys?

Yes. Wrap the key combination in quotes within the TOML table, such as "shift+command+f5" = "ShowDesktop". The parser in crates/openlogi-core/src/config.rs handles these chord definitions and converts them into the appropriate Binding structures that the hook layer recognizes.

How do I map an F-Key to a custom keyboard shortcut instead of a built-in action?

Use the CustomShortcut variant with a key combination string. For example, f3 = { CustomShortcut = "Ctrl+Shift+P" } causes pressing F3 to inject the Ctrl+Shift+P chord into the system. This uses the CustomShortcut(KeyCombo) variant defined in crates/openlogi-core/src/binding/action.rs and is processed by the injection modules.

Do global F-Key bindings work on Windows and Linux?

Yes. While the configuration syntax uses macOS-style naming conventions, OpenLogi translates these bindings to native virtual-key codes on Windows and Linux through the platform-specific injection modules in crates/openlogi-inject/src/inject/windows.rs and linux.rs. The [keyboard.bindings] syntax remains identical across all supported platforms.

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