# How to Configure the Actions Ring in OpenLogi

> Learn to configure the Actions Ring in OpenLogi using TOML files or the openlogi-desktop GUI. Customize device settings with eight slots for efficient control.

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

---

**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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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.

```toml
[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`](https://github.com/AprilNEA/OpenLogi/blob/main/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

```toml
[[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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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:

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

```rust
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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/binding/action_ring.rs)
- Runtime state management runs through [`crates/openlogi-agent-core/src/action_ring.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-agent-core/src/action_ring.rs) with IPC handled in [`crates/openlogi-ipc/src/ipc.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-core/src/binding/action_ring.rs) rejects invalid configurations, causing the system to fall back to default profiles without applying malformed settings.