How to Configure the Actions Ring in OpenLogi

Configure the Actions Ring in OpenLogi by editing the TOML configuration file to define device-specific settings with eight customizable slots, or use the built-in GUI editor in openlogi-desktop for live adjustments without manual file editing.

The Actions Ring is an eight-slot radial menu system in OpenLogi that provides contextual shortcuts for Logitech devices. This feature allows you to bind actions like opening applications or triggering system commands to specific positions on a circular overlay. Learning how to configure the Actions Ring in OpenLogi enables per-device customization that persists across sessions and adapts to different application contexts.

Understanding the Actions Ring Structure

The Actions Ring configuration resides in the user-level config.toml file and follows a device-specific hierarchy. Each physical device is identified by its device_key (e.g., "Logitech G502"), allowing distinct ring layouts for different mice or keyboards.

The configuration consists of three primary components:

• enabled – A boolean flag that activates or deactivates the ring for the specific device
• slots – An array of exactly eight entries defining the actions bound to each position (arranged clockwise from the top)
• icon (optional) – Custom glyph or literal label overrides for individual slots

Editing the Configuration File

Device-Specific Settings

Configuration blocks use TOML table syntax with quoted device names. To enable the Actions Ring for a device, set actions_ring.enabled = true within the device block.

The parser at crates/openlogi-core/src/config.rs deserializes these settings into a DeviceConfig structure at startup. Each device section isolates settings, preventing configuration conflicts between different hardware models.

[device."Logitech G502"]
actions_ring.enabled = true

Configuring the Eight Slots

The slots array requires exactly eight entries. Each slot accepts an action parameter and optional display overrides using either icon or label. The available actions are defined in crates/openlogi-core/src/binding/action_ring.rs and include:

• ShowActionsRing – Toggles the ring visibility
• OpenApplication – Launches a specified program
• DoNothing – Leaves the slot empty

[[device."Logitech G502".actions_ring.slots]]
action = "ShowActionsRing"
icon   = "grid"

[[device."Logitech G502".actions_ring.slots]]
action = "OpenApplication"
label  = "Chrome"

[[device."Logitech G502".actions_ring.slots]]
action = "DoNothing"

After modifying config.toml, restart the OpenLogi agent or trigger a configuration reload to apply changes. The validator in crates/openlogi-core/src/binding/action_ring.rs rejects illegal assignments, such as nesting Show Actions Ring inside the ring itself.

Available Actions and Validation

The core crate defines the action taxonomy in crates/openlogi-core/src/binding/action_ring.rs. This module validates slot assignments during configuration loading, ensuring that action strings match supported variants. Invalid configurations log errors and fall back to default profiles.

Supported actions extend beyond basic navigation to include any system command exposed through the OpenLogi action framework. The validation layer enforces type safety and prevents recursive ring triggers that could cause interface conflicts.

Runtime Architecture and IPC

Once loaded, the runtime state management occurs in crates/openlogi-agent-core/src/action_ring.rs. This module maintains the current session state and exposes RPCs through the IPC layer defined in crates/openlogi-ipc/src/ipc.rs. The overlay component (openlogi-overlay) queries this state via the IPC bus to render the ring on-screen.

To read configuration programmatically:

use openlogi_core::config::Config;
use std::path::Path;

fn load_device_config(path: &Path, device_key: &str) {
    let cfg = Config::load(path).expect("could not load config");
    let dev_cfg = cfg.device(device_key).expect("device not found");
    println!("Actions Ring enabled: {}", dev_cfg.actions_ring.enabled);
    for (i, slot) in dev_cfg.actions_ring.slots.iter().enumerate() {
        println!("Slot {} → {:?}", i + 1, slot);
    }
}

To trigger the ring from a custom extension:

use openlogi_agent_core::action_ring::ActionRingClient;
use openlogi_ipc::ipc::ShowActionsRingRequest;

async fn show_ring(client: ActionRingClient) -> anyhow::Result<()> {
    client.show_ring(ShowActionsRingRequest {}).await?;
    Ok(())
}

Using the GUI Editor

The openlogi-desktop application provides a graphical interface for configuring the Actions Ring without editing TOML directly. Navigate to the Actions Ring tab in the device settings panel to enable the ring and assign actions to each of the eight positions via drag-and-drop or dropdown menus.

Changes made through the GUI persist back to config.toml immediately, and the application signals the agent to reload the configuration without requiring a restart. This approach reduces syntax errors and provides visual feedback for icon selection and label formatting.

Summary

• The Actions Ring configuration lives in config.toml under device-specific sections identified by device_key
• Each device supports exactly eight slots arranged clockwise, configured via the slots array
• Available actions include ShowActionsRing, OpenApplication, and DoNothing, validated by crates/openlogi-core/src/binding/action_ring.rs
• Runtime state management runs through crates/openlogi-agent-core/src/action_ring.rs with IPC handled in crates/openlogi-ipc/src/ipc.rs
• The openlogi-desktop GUI offers live editing capabilities that write back to the configuration file automatically

Frequently Asked Questions

Where is the Actions Ring configuration stored in OpenLogi?

The configuration resides in the user's config.toml file, typically located in the OpenLogi configuration directory. Device-specific settings are nested under [device."Device Name"] tables with an actions_ring subkey. The parser implementation in crates/openlogi-core/src/config.rs handles the deserialization of these settings at application startup.

How many slots does the OpenLogi Actions Ring support?

The Actions Ring supports exactly eight slots arranged in a radial pattern starting from the top position and moving clockwise. The system expects an array of eight entries in the slots configuration; deviations may trigger validation errors or default fallbacks defined in the core binding validation logic.

Can I use custom icons or labels for ring slots?

Yes. Each slot accepts an optional icon parameter referencing built-in glyph names, or a label parameter for plain text display. The label field overrides icon rendering, displaying literal text instead of graphical symbols. Custom icon sets are inherited from the built-in icon registry defined in the OpenLogi core resources.

Why is my Actions Ring configuration not applying after editing?

Configuration changes require either restarting the OpenLogi agent or triggering a configuration reload via the IPC interface. If issues persist, check the validation logs for illegal action assignments. The validator in crates/openlogi-core/src/binding/action_ring.rs rejects invalid configurations, causing the system to fall back to default profiles without applying malformed settings.

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