How to Develop OpenLogi Without Hardware: Complete Mock Agent Guide

OpenLogi supports hardware-free development through a mock agent that implements the same tarpc IPC contract as the real background agent, serving a scripted in-memory inventory of virtual Logitech devices.

OpenLogi’s architecture cleanly separates the GUI desktop client from the background agent that communicates with physical HID++ devices. This separation allows developers to replace the real agent with a hardware-free mock when no physical Logitech hardware is available. By running the mock agent on the same development profile (openlogi‑dev) as the GUI, you can iterate on UI components, test configuration flows, and validate IPC logic entirely without USB devices attached.

Understanding the Mock Agent Architecture

The mock agent resides in crates/openlogi-agent/src/bin/mock_agent.rs and simulates a complete device ecosystem by implementing the identical tarpc IPC interface used by the production agent. Instead of querying physical USB HID++ endpoints, the mock maintains an in-memory inventory of scripted virtual devices.

When the mock agent runs under the openlogi‑dev profile, it exposes a development IPC socket that the GUI automatically detects and connects to. This allows the desktop client to execute all standard operations—reading device settings, modifying DPI values, or triggering SmartShift torque adjustments—against the virtual inventory.

Simulated Device Inventory

At the top of mock_agent.rs (lines 21-31), the mock defines a comprehensive hardware inventory that includes:

• A Bolt receiver with full pairing flow simulation
• An online mouse with battery reporting
• An offline mouse to test disconnected states
• A lighting-capable keyboard for RGB control testing
• A directly-attached mouse for wired connection scenarios
• A standalone Litra light for illumination device testing

The mock simulates the complete Bolt pairing workflow—from device discovery through passkey entry to final pairing—allowing you to test receiver management logic without physical peripherals.

Step-by-Step Hardware-Free Development

Follow these steps to launch a complete OpenLogi development environment without physical hardware:

1. Start the mock agent in one terminal to provide the virtual device backend:

   cargo run -p openlogi-agent --bin openlogi-agent-mock

2. Launch the GUI in a second terminal, disabling the embedded real agent to force connection to the mock:

   OPENLOGI_DEV_AGENT=0 cargo run -p openlogi-desktop

3. Verify the connection by checking that the GUI displays the scripted devices (Bolt receiver, virtual mice, and keyboard) in the device list.

The mock persists all write operations—such as DPI modifications, lighting adjustments, or SmartShift torque settings—in memory, allowing you to observe realistic state changes in the UI without hardware attached.

Environment Variable Configuration

The mock_agent.rs source (lines 61-71) handles profile defaults and socket locking to prevent conflicts with production agents. You can control the development behavior through specific environment variables.

Preventing Embedded Agent Loading

Set OPENLOGI_DEV_AGENT=0 before launching the GUI to stop the desktop client from spawning the real agent binary. This forces the GUI to connect exclusively to your running mock instance via the development IPC socket.

Connecting to External Production Agents

If you have a production agent already running and want the dev GUI to connect to it instead of the mock, export:

OPENLOGI_ALLOW_EXTERNAL_AGENT=1

This permits the development GUI to communicate with an externally managed real agent, useful for comparing mock behavior against actual hardware responses.

Testing Production Sockets

To validate production socket compatibility while maintaining the mock inventory, override the default profile:

OPENLOGI_PROFILE=prod cargo run -p openlogi-agent --bin openlogi-agent-mock

This configuration runs the mock against the production IPC socket, ensuring your code changes work with the exact communication paths used in release builds.

Key Source Files for Hardware-Free Development

File Path	Purpose	Relevant Lines
crates/openlogi-agent/src/bin/mock_agent.rs	Mock agent implementation with scripted inventory and IPC service	Lines 21-31 (device definitions), 61-71 (profile handling)
docs/DEVELOPMENT.md	Official documentation for GUI development without hardware	Developing the GUI without hardware section

The mock agent implementation demonstrates how OpenLogi’s abstraction layers enable complete hardware decoupling. By examining mock_agent.rs, you can extend the virtual inventory with additional device types or modify the Bolt pairing simulation to test edge cases in the pairing flow.

Summary

• OpenLogi’s architecture separates the GUI from the hardware agent via tarpc IPC, enabling mock-based development.
• The mock agent (mock_agent.rs) provides scripted virtual devices including Bolt receivers, mice, keyboards, and Litra lights.
• Run cargo run -p openlogi-agent --bin openlogi-agent-mock to start the hardware-free backend.
• Use OPENLOGI_DEV_AGENT=0 when launching the GUI to connect to the mock instead of the real agent.
• Environment variables OPENLOGI_ALLOW_EXTERNAL_AGENT and OPENLOGI_PROFILE control advanced testing scenarios against production agents or sockets.
• All device state changes persist in memory, delivering realistic UI feedback without physical hardware.

Frequently Asked Questions

What is the OpenLogi mock agent?

The mock agent is a development tool in crates/openlogi-agent/src/bin/mock_agent.rs that implements the same tarpc IPC interface as the real background agent but serves virtual Logitech devices from memory instead of USB HID++ hardware. It simulates complete device behaviors including battery reporting, DPI adjustments, and Bolt receiver pairing flows.

Can I test the Bolt pairing process without a physical receiver?

Yes. The mock agent simulates the entire Bolt pairing workflow from device discovery through passkey entry to final pairing. When you trigger pairing in the GUI connected to the mock, you can test the complete UI flow and backend logic without physical Bolt receivers or devices attached to your development machine.

How do I switch between the mock agent and real hardware testing?

Set OPENLOGI_ALLOW_EXTERNAL_AGENT=1 when launching the GUI to permit connections to a running production agent instead of the mock. Alternatively, keep the mock running but switch to the production IPC socket by setting OPENLOGI_PROFILE=prod when starting the mock agent, allowing you to verify socket compatibility while maintaining the scripted virtual inventory.

Where is the virtual device inventory defined in the source code?

The virtual device list—including the Bolt receiver, online/offline mice, lighting keyboard, and Litra light—is defined at lines 21-31 in crates/openlogi-agent/src/bin/mock_agent.rs. You can modify this section to add custom virtual devices or adjust the simulated hardware properties for specific test scenarios.

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