How to Configure Long-Press Bindings in OpenLogi TOML Files

OpenLogi supports dual-action button assignments by defining short and long keys in a TOML table, where actions trigger on quick release or after a built-in 500 ms hold threshold respectively.

OpenLogi is an open-source driver for Logitech input devices that enables granular control over button behavior through TOML configuration files. To configure long-press bindings in OpenLogi TOML files, you define a table structure that maps button names to distinct actions for quick taps versus sustained holds. This feature is implemented in the AprilNEA/OpenLogi repository and allows workflow optimizations like assigning Mission Control to a long press while keeping Show Desktop on a short press.

TOML Syntax for Long-Press Bindings

In the TOML configuration, long-press bindings use inline table syntax where the button name maps to an object containing short and long keys. As shown in docs/config.example.toml (lines 36-38), you assign one action to fire on quick release and another after the hold threshold:

[devices."receiver:aabbccdd:slot:1".bindings]
DpiToggle = { short = "ShowDesktop", long = "MissionControl" }

The short field executes if the button is released before the timeout, while long executes if held for the threshold duration or longer.

How the Timing Mechanism Works

OpenLogi distinguishes between short and long presses by measuring the duration between physical button-down and button-up events. According to crates/openlogi-agent-core/src/runtime/button.rs, the runtime tracks this timing and routes to the appropriate action:

• Short press: Triggered when the button releases before 500 ms
• Long press: Triggered when the button is held for 500 ms or more

The long action fires once upon reaching the threshold, not repeatedly while held.

Supported Action Values

Both short and long values accept any valid OpenLogi action identifier. As parsed in crates/openlogi-core/src/config.rs, these include:

• Action names: Strings like "ShowDesktop", "MissionControl", or "Copy"
• Keyboard shortcuts: Strings in standard notation ("Ctrl+Space")
• Custom shortcuts: Tables with syntax { CustomShortcut = "F1" }
• Hold shortcuts: Tables with syntax { HoldShortcut = "Ctrl+Space" } (fires only while physically held)

Device Configuration Placement

Bindings reside within device-specific tables under the bindings key. Devices are identified either by receiver slot (receiver:aabbccdd:slot:1) or persistent unit ID (unit:...). Place your long-press definitions inside this structure alongside other device settings like DPI or lighting:

[devices."receiver:abcd1234:slot:1".bindings]
Thumbwheel = { short = "AppExpose", long = { CustomShortcut = "F12" } }

Customizing the Hold Threshold

The default 500 ms threshold is defined by the HID++ short-long timeout feature. Advanced users can modify this via the Crown device feature, where the field short_long_timeout is defined in crates/openlogi-hidpp/src/feature/crown.rs. However, the default value suits most short-press versus long-press scenarios without adjustment.

Complete Configuration Examples

Here are three working configurations demonstrating different long-press patterns.

Dual-action DPI button:

[devices."receiver:abcd1234:slot:1".bindings]
DpiToggle = { short = "ShowDesktop", long = "MissionControl" }

Custom shortcut on long press:

[devices."receiver:abcd1234:slot:1".bindings]
Thumbwheel = { short = "AppExpose", long = { CustomShortcut = "F12" } }

Hold-style shortcut:

[devices."receiver:abcd1234:slot:1".bindings]
MiddleClick = { HoldShortcut = "Ctrl+Space" }

Summary

• OpenLogi uses TOML tables with short and long keys to define dual-action button bindings.
• The system measures hold duration against a 500 ms threshold defined in crates/openlogi-hidpp/src/feature/crown.rs.
• Short actions fire on quick release, while long actions trigger after holding the button for 500 ms or longer.
• Configuration belongs in device-specific bindings tables identified by receiver or unit IDs.
• Actions can be simple strings, keyboard shortcuts, or structured tables for custom behaviors.

Frequently Asked Questions

What is the default long-press threshold in OpenLogi?

OpenLogi uses a 500 ms threshold to distinguish between short and long presses. This value is defined by the short_long_timeout field in the HID++ Crown feature implementation at crates/openlogi-hidpp/src/feature/crown.rs. The button runtime in crates/openlogi-agent-core/src/runtime/button.rs uses this timing to route events to either the short or long action.

Can I use keyboard shortcuts instead of named actions for long presses?

Yes, the long value accepts any valid action type that OpenLogi supports. You can assign a string shortcut like "Ctrl+Space", a custom shortcut table like { CustomShortcut = "F12" }, or a hold shortcut like { HoldShortcut = "Alt+Tab" }. The configuration parser in crates/openlogi-core/src/config.rs handles all these variants when processing the TOML file.

Where should I place long-press bindings in my OpenLogi configuration?

Place bindings inside a device table under the bindings key, using the device route (receiver ID and slot) or unit ID as the table header. For example: [devices."receiver:aabbccdd:slot:1".bindings]. See docs/config.example.toml for the reference structure showing where to insert your button definitions.

Does the long action repeat if I keep holding the button?

No, the long action fires once when the 500 ms threshold is reached. If you need an action that repeats or only executes while the button is physically held, use the HoldShortcut syntax instead. This creates a different behavior where the shortcut is active only during the press duration, as distinct from the toggle-style long-press action.

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