# How to Develop OpenLogi Without Hardware: Complete Mock Agent Guide

> Develop OpenLogi without hardware using a mock agent. This guide explains how the mock agent mimics the real agent for seamless virtual device inventory testing.

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

---

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

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

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

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

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