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

> Configure global keyboard remapping with F-Key triggers in OpenLogi. Map F1-F12 keys to actions or custom chords using the config.toml file for system-wide shortcuts.

- Repository: [Xuan Zhang/OpenLogi](https://github.com/AprilNEA/OpenLogi)
- Tags: how-to-guide
- Published: 2026-09-06

---

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

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

f2 = "ShowDesktop"             # Pressing F2 shows the desktop

```

**Modifier combinations:**

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

```

**Custom shortcut chords:**

```toml
[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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-inject/src/inject/windows.rs) and [`crates/openlogi-inject/src/inject/linux.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/config.rs) and stored in the `KeyboardBindings` map
- The input hook in [`crates/openlogi-hook/src/lib.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-inject/src/inject/windows.rs) and [`linux.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-inject/src/inject/windows.rs) and [`linux.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/linux.rs). The `[keyboard.bindings]` syntax remains identical across all supported platforms.