OpenLogi DPI Cycle System HID++ Interaction: Architecture and Implementation

OpenLogi implements DPI cycling through a thread-safe shared state that translates user actions into HID++ commands via the 0x2201 (AdjustableDpi) or 0x2202 (ExtendedAdjustableDpi) features, enabling seamless preset rotation across Logitech devices.

The OpenLogi DPI cycle system HID++ interaction enables users to switch between predefined mouse sensitivity presets through low-level device communication. This Rust-based implementation in the AprilNEA/OpenLogi repository abstracts hardware differences by mapping UI actions to standardized HID++ feature calls. Understanding this architecture reveals how open-source tools can safely manipulate proprietary device firmware through a layered state management approach.

Architecture Overview

The implementation spans four distinct architectural layers that decouple user interface events from hardware-specific HID++ protocols. At the top sits the shared state (DpiCycles) held by the background agent, accessed concurrently by the OS hook thread and the GUI. Below that, the orchestrator manages device lifecycle events, populating state with capabilities queried directly from hardware. The hook runtime translates abstract actions into I/O requests, while the device I/O layer handles the actual HID++ feature negotiation.

This design allows the same DPI cycling code to work transparently across different Logitech hardware generations, whether they expose the legacy 0x2201 feature or the modern 0x2202 extended interface.

Shared State Management (DpiCycles)

The core state resides in crates/openlogi-agent-core/src/dpi.rs, where the DpiCycles struct maintains a thread-safe registry of per-device configuration.

State Structure

Each device tracked by the system receives a dedicated DpiCycleState containing:

• presets: Vec<Dpi> – The ordered list of DPI values defined in user configuration
• index: usize – Current position within the preset array
• target: Option<DeviceRoute> – The HID++ route used for writes (direct mouse or receiver slot)
• capabilities: Option<DpiCapabilities> – Cached hardware limits used to normalize values

#[derive(Debug, Clone, Default)]
pub struct DpiCycles {
    pub selected: Option<String>,
    pub by_key: HashMap<String, DpiCycleState>,
}

Key State Methods

The DpiCycleState implementation provides three critical operations:

• cycle(&mut self) – Advances the index with wrapping arithmetic, returning the new DPI value and its write target
• set(&mut self, i: usize) – Jumps directly to a specific preset index, enabling one-click selection
• normalize(&self, dpi: Dpi) – Snaps requested values to the nearest hardware-supported DPI when capabilities are known

These methods ensure that all DPI values sent to hardware fall within valid ranges, preventing failed HID++ transactions.

Orchestrator Initialization

During agent startup, the orchestrator (crates/openlogi-agent-core/src/orchestrator.rs) instantiates a shared Arc<RwLock<DpiCycles>> at lines 90-98, making the state accessible across threads:

pub struct SharedRuntime {
    pub dpi_cycle: Arc<RwLock<DpiCycles>>,
    // ...
}

When devices connect or disconnect, the rebuild_dpi_cycles helper (around line 321) performs capability discovery:

1. Enumerates online devices and creates per-device DpiCycleState instances keyed by configuration strings
2. Queries hardware limits via write::dpi::get_dpi and write::dpi::supported_dpi
3. Stores the DeviceRoute and normalized capabilities for later write operations

This population phase ensures that the hook runtime never attempts to write invalid DPI values or communicate through stale device routes.

Hook Runtime Action Handling

The OS hook thread (crates/openlogi-agent-core/src/hook_runtime.rs) receives abstract actions from physical buttons or IPC messages from the GUI. At lines 579-591, the runtime handles two specific variants:

Action::CycleDpiPresets => match dpi_cycle.write() {
    Ok(mut guard) => { /* advance one preset */ }
    Err(e) => warn!(error = %e, "dpi_cycle lock poisoned — cycle skipped");
},
Action::SetDpiPreset(i) => match dpi_cycle.write() {
    Ok(mut guard) => { /* jump to preset i */ }
    Err(e) => warn!(error = %e, "dpi_cycle lock poisoned — set skipped");
},

Both execution paths follow the same sequence:

1. Acquire a write lock on the shared DpiCycles instance
2. Retrieve the (Dpi, Option<DeviceRoute>) tuple from cycle() or set()
3. Dispatch to write::dpi::set_dpi when a valid route exists

This architecture isolates the action handling from transport details, allowing the same code to service both physical DPI buttons and software UI controls.

HID++ Feature Implementation

The device I/O layer (crates/openlogi-device/src/write/dpi.rs) abstracts over two mutually exclusive HID++ features:

AdjustableDpi Feature (0x2201)

The legacy implementation in crates/openlogi-hidpp/src/feature/adjustable_dpi.rs provides simple single-axis DPI control. When present, the system uses this feature for basic value read/write operations without independent X/Y control.

ExtendedAdjustableDpi Feature (0x2202)

Modern Logitech devices expose the extended feature implemented in crates/openlogi-hidpp/src/feature/extended_dpi.rs. This interface supports:

• Independent X and Y axis DPI values
• Lift-off distance (LOD) configuration
• Stepped DPI ranges with non-linear intervals

When writing values, the write::dpi module preserves existing LOD settings and secondary axis values to avoid unintended side effects.

The write::dpi Abstraction

The high-level API unifies both features behind an internal enum:

enum DpiFeature {
    Adjustable(Arc<AdjustableDpiFeature>),
    Extended(Arc<ExtendedDpiFeature>),
}

The set_dpi function (lines 53-60) handles feature negotiation automatically, preferring 0x2201 for simpler devices while falling back to extended parameters for hardware requiring LOD preservation.

Desktop GUI Integration

The desktop application (crates/openlogi-desktop/src/state/dpi.rs) participates in the cycle system through IPC channels rather than direct state access. When users interact with DPI controls, the GUI emits:

• Action::CycleDpiPresets – Triggered by the "Next DPI" button or physical button mapping
• Action::SetDpiPreset(i) – Sent when selecting a specific preset from a dropdown menu

The agent processes these messages through the hook runtime, ensuring that GUI state remains synchronized with hardware configuration even when multiple input methods trigger simultaneously.

Practical Implementation Example

The following Rust function demonstrates manual DPI cycling without GUI involvement, showing the complete stack from state acquisition to HID++ transmission:

use openlogi_agent_core::{
    shared::SharedRuntime,
    dpi::DpiCycles,
};
use openlogi_core::bindings::Action;
use std::sync::Arc;

async fn advance_dpi_cycle(
    shared: &SharedRuntime
) -> anyhow::Result<()> {
    // Acquire exclusive access to the cycle state
    let mut guard = shared.dpi_cycle.write()
        .map_err(|e| anyhow::anyhow!("State poisoned: {}", e))?;
    
    // Retrieve the currently selected device's state and advance
    let (new_dpi, target) = match guard.state_for(None).and_then(|s| s.cycle()) {
        Some(v) => v,
        None => return Err(anyhow::anyhow!("No presets configured")),
    };
    
    // Transmit via HID++ if device is online
    if let Some(route) = target {
        openlogi_device::write::dpi::set_dpi(
            &shared.device_backend,
            &route,
            new_dpi
        ).await?;
    }
    
    // Notify GUI of state change
    shared.ipc.send(Action::CycleDpiPresets);
    Ok(())
}

This pattern transparently supports both 0x2201 and 0x2202 devices, handling feature detection and value normalization automatically.

Summary

• Shared state architecture – DpiCycles and DpiCycleState in dpi.rs provide thread-safe storage for preset lists and current indices
• Automatic capability detection – The orchestrator queries hardware limits during device enumeration to prevent invalid writes
• Unified HID++ abstraction – The write::dpi module handles both legacy (0x2201) and extended (0x2202) features through a common interface
• Decoupled action handling – The hook runtime processes CycleDpiPresets and SetDpiPreset actions without hardware-specific logic
• IPC-based GUI sync – State changes propagate to the desktop UI through message passing rather than shared memory

Frequently Asked Questions

What HID++ features does OpenLogi use for DPI cycling?

OpenLogi utilizes either feature 0x2201 (AdjustableDpi) or feature 0x2202 (ExtendedAdjustableDpi) depending on hardware capability. The legacy 0x2201 feature handles simple single-value DPI changes, while 0x2202 provides independent X/Y control and lift-off distance management. The write::dpi module in crates/openlogi-device/src/write/dpi.rs automatically negotiates the appropriate feature during device initialization.

How does OpenLogi handle DPI cycling for different Logitech mouse models?

The system abstracts hardware differences through the DpiCapabilities struct cached during orchestrator initialization. When cycling presets, the normalize method snaps requested values to the nearest supported DPI reported by write::dpi::supported_dpi. This ensures that devices with non-standard DPI steps (such as those requiring specific intervals) receive valid values regardless of user configuration.

Can I trigger DPI cycles programmatically without the GUI?

Yes. You can acquire a write lock on the SharedRuntime.dpi_cycle field and call DpiCycleState::cycle() directly, then pass the resulting DPI value to openlogi_device::write::dpi::set_dpi. This bypasses the IPC mechanism used by the GUI while maintaining proper HID++ protocol adherence. The code example in the article's implementation section demonstrates this exact pattern.

What happens if the DPI cycle state becomes corrupted?

The system uses std::sync::RwLock for state protection rather than unsafe shared mutability. If a thread panics while holding the lock (poisoning), subsequent access attempts return Err(PoisonError). The hook runtime catches these errors at lines 579-591 and logs a warning while skipping the action, preventing crashes or undefined behavior during DPI transitions.

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