OpenLogi Agent Mock: Testing Without Hardware Using `openlogi-agent-mock`

The OpenLogi agent mock lets you develop and test Logitech HID++ device management interfaces without any physical hardware by running cargo run -p openlogi-agent --bin openlogi-agent-mock to serve a scripted device inventory over IPC.

The openlogi-agent-mock binary in the AprilNEA/OpenLogi repository provides a complete software-only replacement for the real hardware agent. It implements the same IPC contract as the production agent, enabling GUI development, integration testing, and debugging when no Logitech devices are available. This guide covers how to run the mock, configure its behavior, and integrate it into your development workflow.

What Is the OpenLogi Agent Mock?

The mock agent is a hardware-free simulation that ships as a separate binary within the openlogi-agent crate. Located at crates/openlogi-agent/src/bin/mock_agent.rs, it:

• Serves a scripted device inventory over the agent IPC socket
• Uses the openlogi-dev profile by default (equivalent to OPENLOGI_PROFILE=dev)
• Reports a version string with -mock suffix for easy identification
• Competes for the same single-instance lock as the real agent

The mock does not implement hardware-dependent actions like SmartShift torque control or Actions Ring actuation. However, it fully supports the IPC surface required by the UI for device discovery, capability enumeration, and state management.

Running openlogi-agent-mock

Basic Startup

Start the mock agent with Cargo:

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

This compiles and runs the mock binary defined in crates/openlogi-agent/Cargo.toml (lines 17–22), which points path = "src/bin/mock_agent.rs" to the mock implementation.

Connecting a Client

With the mock running, launch any client in a second terminal:

# Start the desktop UI

cargo run -p openlogi-desktop

The GUI automatically discovers and connects to the mock's IPC socket, displaying the scripted device inventory as if real hardware were present.

Verifying Mock Mode

Check that your client detects the mock session by examining the agent version string. The mock appends -mock to its version (e.g., 0.9.0-mock), which the UI displays wherever agent version information appears.

Configuration Options

Profile Selection

The mock defaults to the openlogi-dev profile. Override this with environment variables:

# Explicitly use the development profile

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

# Use a custom profile you've defined

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

Additional configuration patterns are documented in docs/DEVELOPMENT.md (lines 123–150), which covers environment setup and mock integration workflows.

Critical Usage Constraints

Single-Instance Lock Behavior

The mock competes for the same system-wide lock as the real openlogi-agent binary. To avoid conflicts:

• Start the mock before the real agent, or
• Run the mock in complete isolation with no other agent instances

Attempting to run both simultaneously results in a lock contention failure in the second process.

Hardware Action Limitations

The mock explicitly refuses hardware-dependent operations:

Capability	Mock Support	Real Agent
Device discovery & inventory	✅ Full	✅ Full
Capability enumeration	✅ Full	✅ Full
State reading	✅ Full	✅ Full
SmartShift torque adjustment	❌ None	✅ Hardware
Actions Ring activation	❌ None	✅ Hardware
LED/DPI hardware control	❌ None	✅ Hardware

Design your tests around these boundaries—verify hardware interactions through integration tests with physical devices when needed.

Complete Development Workflow

For comprehensive GUI development without hardware:

# Terminal 1: Start the mock agent

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

# Terminal 2: Launch the desktop application

cargo run -p openlogi-desktop

# Terminal 3: Optional—run automated tests against the mock

cargo test -p openlogi-desktop -- --test-threads=1

The mock's scripted inventory remains consistent across restarts, enabling reproducible test scenarios that would be impossible with physical hardware state variations.

Key Source Files

Understanding these files deepens your ability to extend or debug the mock:

• crates/openlogi-agent/src/bin/mock_agent.rs — Core mock implementation with scripted inventory serving and IPC handling
• crates/openlogi-agent/Cargo.toml — Binary declaration for openlogi-agent-mock
• docs/DEVELOPMENT.md — Official development guide with mock usage patterns
• AGENTS.md — High-level agent architecture overview with mock references (lines 177–180)

Summary

• The openlogi-agent-mock binary provides complete hardware-free testing for OpenLogi development
• Run with cargo run -p openlogi-agent --bin openlogi-agent-mock to start the IPC server
• Single-instance lock requires isolation from the real agent—start mock first or run exclusively
• -mock version suffix enables client-side detection of mock sessions
• Hardware actions are stubbed—torque, ring, and LED controls return errors or no-ops

Frequently Asked Questions

How do I know if my UI is connected to the mock or real agent?

Check the agent version string displayed in your UI's connection status or about dialog. The mock reports a version ending in -mock (e.g., 0.9.0-mock), while the real agent reports a clean semantic version without this suffix. This distinction is implemented in mock_agent.rs to prevent confusion during development.

Can I run the mock and real agent simultaneously on the same machine?

No. Both binaries acquire a system-wide single-instance lock, causing the second process to fail on startup. Per AGENTS.md, you must either start the mock before any real agent instance, or ensure no other agent process is running. For CI environments, consider container isolation or dedicated mock-only test runners.

What device capabilities are actually simulated by the mock?

The mock serves a static scripted inventory that includes complete device metadata, capability flags, and readable state values. However, any IPC call requiring hardware manipulation—such as SmartShift torque configuration, Actions Ring hardware triggers, or DPI/lift-off distance changes—receives an error response or silent no-op. The exact capability matrix depends on the scripted inventory defined in the mock source.

Is the mock suitable for production deployments?

Absolutely not. The mock is strictly a development tool as documented in docs/DEVELOPMENT.md. It never accesses HID++ devices, provides no hardware control, and is excluded from production release builds. Deploying the mock in production would result in non-functional device management and potential security implications from its permissive simulated state.

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