OpenLogi

Architecture

How OpenLogi's desktop, agent, overlay, CLI, shared crates, and hardware boundaries fit together.

OpenLogi separates one authoritative background agent from two GPUI clients. The agent owns HID++ inventory and channels, input capture, binding resolution, device writes, and action execution. The settings app mirrors agent snapshots and sends commands. The overlay renders the Actions Ring and the on-screen notices, and reports ring interactions back. openlogi list prefers a compatible agent snapshot and falls back to direct enumeration. openlogi api uses agent IPC exclusively; hardware-diagnostic CLI commands open devices directly.

Components

  • OpenLogi agent (openlogi-agent) — the background process: HID++ device I/O, input hooks and capture sessions, per-app watching, pairing, action dispatch, low-battery and lock-key events, the menu-bar / tray item, and supervision of the overlay helper.
  • OpenLogi desktop (openlogi-desktop) — the GPUI settings app. Its local state is a presentation and editing mirror; HID++ reads and writes go through the agent. Webcam preview and UVC controls remain direct desktop operations. The desktop also runs the app's update check: Sparkle on macOS and the MSI updater on Windows.
  • Overlay (openlogi-overlay) — a warm, separately supervised GPUI process. It draws the Actions Ring from presentation-only snapshots and returns hover, activation, and cancellation events; the agent retains and executes actions. It also draws the notices and indicators the agent marks as current: the low-battery notice, the lock-key indicator, and the keyboard backlight level. See On-screen notices.
  • OpenLogi CLI (openlogi) — headless inventory, asset sync, light and camera control, fixture capture and verification, and HID++ diagnostics. Inventory can use agent IPC; openlogi api provides JSON output and device control through the agent. Hardware diagnostics remain direct operations. See the CLI guide.
  • assets.openlogi.org — a static host serving per-device renders and clickable-hotspot metadata, keyed by each device's modelId; a Cloudflare Pages alias and jsDelivr npm shards that follow the newest release of the asset release line are raced as mirrors.

Component relationships

Processes and local state

openlogi-ipc is a shared contract and transport library, not another process. The desktop and overlay connect to the same endpoint. Each client uses the shared version handshake; incompatible clients do not exchange runtime data.

openlogi-desktop ── snapshots + commands ──┐
openlogi-overlay ── ring + notices ────────┼── openlogi-ipc ── openlogi-agent
openlogi list ───── inventory snapshot ────┤                        │
openlogi api ────── status + control ──────┘                        │
                                                                  ├── HID I/O
openlogi diagnostics ─────────────────────── direct HID I/O         └── OS input

The agent supervises the separate overlay. The desktop writes config.toml and requests a validated reload. For UI development, openlogi-agent-mock can replace the real agent on the development socket.

Runtime and I/O boundaries

The agent is authoritative for HID++ and native input capture. The desktop only opens UVC cameras directly; both the desktop and CLI can populate the verified asset cache.

openlogi-device implements discovery, probing, sessions, pairing, and device writes against the HidBackend interface. It does not open host devices itself. openlogi-hid supplies the real async-hid transport, permissions, and probe cache. A recording or replay backend can exercise the same device layer without changing its protocol logic. Native input capture and synthesis stay in openlogi-hook and openlogi-inject respectively.

Crates

CrateRole
openlogi-coreLeaf-level types, TOML config, paths, device models, the button / action catalog, and locale negotiation
openlogi-hidpp-derivePrivate proc macros that generate HID++ feature boilerplate
openlogi-hidppWorkspace hard fork of the HID++ protocol crate (lib name hidpp): channels, features, receivers
openlogi-device-registryPure receiver-protocol and standalone-device identity metadata
openlogi-fixtureHost-free fixture schemas, synthetic identities, and privacy / relationship verification
openlogi-deviceBackend-independent enumeration, probing, sessions, pairing, and device writes
openlogi-hidHost HID transport, permission integration, and on-disk probe cache
openlogi-hookOS input hook and frontmost-app lookup: macOS CGEventTap; Linux evdev/uinput with X11, wlroots, and GNOME Shell window lookup; Windows WH_MOUSE_LL and WH_KEYBOARD_LL
openlogi-injectOS event synthesis: macOS CGEvent, with keys typed on a virtual HID keyboard when the signed agent can create one; Linux uinput, MPRIS, KWin and GNOME D-Bus calls, and Hyprland dispatch; Windows SendInput
openlogi-cameraUVC webcam discovery, capture, and image controls
openlogi-permissionsRead-only permission status and System Settings links; camera permission APIs live in openlogi-camera
openlogi-assetsDevice-render registry schema and cached mirror fetches
openlogi-ipcThe tarpc service contract and bincode transport over Unix sockets or Windows named pipes
openlogi-agent-coreHeadless orchestration, capture planning, hardware operations, action dispatch, and Actions Ring sessions
openlogi-uiShared GPUI action icons, colors, and locale catalogs
openlogi-cli / openlogiCLI implementation library and its thin binary wrapper
openlogi-agentThe real agent and openlogi-agent-mock binary targets
openlogi-desktopGPUI settings application and agent IPC client
openlogi-overlaySeparate GPUI renderer for the Actions Ring, notices, and keyboard indicators; agent IPC client
xtaskCI, packaging, bundling, and release tooling

How a button press becomes an action

  1. The control is captured: either by the OS hook (middle / back / forward) or diverted over HID++ 0x1b04 (gesture button, haptic panel, mode-shift, keyboard F-row) by a per-device capture session the agent rebuilds whenever bindings change. The same session diverts the main wheel over 0x2121 for Smooth wheel, and reads raw wheel input over 0x1b04 for Hold to scroll sideways.
  2. The agent resolves the binding: the target app's overlay first, then the device's global map. Mouse profiles default to the app under the pointer; mouse_profile_target = "focused" selects the focused app instead. Keyboard profiles always follow focus. See Per-app profiles.
  3. The agent dispatches it: host actions go through openlogi-inject; device actions use an agent-owned openlogi-hid channel.
  4. For ShowActionsRing, the agent selects the focused app's complete layout and snapshots a presentation for the overlay. It accepts hover / activate / cancel RPCs, validates the session and slot, then executes the selected action itself.

Configuration is a plain TOML file; there is no cloud or account. The desktop loads and atomically writes the file, then requests reload_config. The agent independently loads it at startup and validates it again on reload before replacing live state.

Some settings live in volatile device RAM and are lost when a device reconnects. The agent writes them again after a reconnect or a system wake: DPI, report rate, SmartShift, the native wheel mode (resolution and inversion), keyboard lighting, Fn-lock, Keep OS layout, and Litra light settings. A disabled device gets no writes.

Developing without hardware

openlogi-agent-mock serves the real IPC contract from a scripted in-memory inventory without opening HID devices or installing input hooks, so the desktop and overlay can be developed with no Logitech device attached. It can load a recorded device profile instead of the built-in inventory. HID++ cassettes test the separate device layer through a replay backend; they are not a live input stream for the UI mock. See Contributing and MOCK_DEVICE_TESTING.md.

On this page