openlogi-hidpp vs hidpp: Protocol Differences Between the OpenLogi Fork and Upstream Crate

The openlogi-hidpp fork extends the upstream hidpp crate with Logitech-specific protocol extensions including advanced features like SmartShift, RGB effects, extended DPI ranges, and receiver-specific handling for Unifying and Bolt devices.

The openlogi-hidpp crate is a hard fork of the community hidpp Rust crate, which serves as the reference implementation of Logitech's HID++ protocol. While the upstream crate provides the foundational HID++ 1.0 and 2.0 specifications, the fork adds substantial Logitech-specific extensions required by the OpenLogi project for comprehensive device support. Understanding these protocol differences helps developers choose the right implementation for Logitech peripheral configuration tools.

Protocol Version Coverage

The upstream hidpp crate focuses strictly on base protocol compliance. It implements core HID++ 1.0 messages in src/protocol/v10.rs and HID++ 2.0 messages in src/protocol/v20.rs without deviation from Logitech's published specifications.

The openlogi-hidpp fork preserves these foundational modules intact but layers additional feature-specific modules that expose newer HID++ 2.0 commands absent from upstream. This includes extended DPI reporting, SmartShift-enhanced controls, and battery-status extensions that Logitech devices expose through feature indices beyond the base specification.

Feature Set Extensions

The most significant divergence lies in the feature hierarchy. Upstream hidpp provides only minimal capabilities: basic device identification, standard DPI queries, simple DPI changes, and rudimentary LED on/off control.

The fork introduces a comprehensive src/feature/ directory containing specialized protocol handlers:

• smartshift.rs and smartshift_enhanced.rs — Free-wheel scrolling configuration with enhanced sensitivity curves
• rgb_effects.rs — Full programmable RGB lighting with breathing, color cycle, and wave patterns
• color_led_effects/ — Zone-based LED control for multi-light devices
• extended_dpi/ — Per-sensor DPI ranges, lift-off distance, and angle snapping
• solar_dashboard.rs — Solar panel telemetry and power management
• touchpad_raw_xy.rs — Raw touchpad coordinate streaming for gesture engines

These additions enable OpenLogi to expose high-level device capabilities that upstream cannot access.

Message Encoding and Transport

Both crates share core encoding logic through channel::raw and channel::message modules. However, the fork adds architectural wrappers that simplify extended command transmission.

The src/emitter.rs module provides a structured interface for dispatching feature-specific HID++ messages, while src/device.rs implements a high-level feature API that abstracts protocol indices and payload construction. This design pattern allows OpenLogi components to work with type-safe Rust structs rather than raw byte buffers.

Receiver and Connection Handling

Upstream hidpp treats all transport backends uniformly through generic HID interfaces.

The fork distinguishes between connection methods through dedicated modules:

• src/receiver/unifying.rs — Handles Logitech Unifying receiver pairing, device enumeration, and multiplexer channel allocation
• src/receiver/bolt.rs — Implements Bolt receiver protocol extensions and Bluetooth-direct paths
• src/receiver/mod.rs — Unified abstraction for cross-receiver compatibility

These protocol differences matter for applications that must enumerate receivers, manage multiple paired devices, or handle connection-type-specific quirks like Bolt's encrypted payload framing.

Testing and Validation Coverage

Upstream validation focuses on protocol parsing correctness with minimal device interaction testing.

The fork expands verification through:

• src/feature/*/tests.rs — Unit tests for each extended feature against captured device traces
• src/channel/tests.rs — Round-trip validation of custom emitter/receiver pairs
• Integration tests verifying backward compatibility with upstream protocol definitions

This expanded test matrix ensures that protocol extensions remain stable across Logitech firmware variations.

Documentation and Licensing

Aspect	Upstream hidpp	openlogi-hidpp Fork
License	MIT/Apache-2.0	Custom LICENSE with fork attribution
Documentation	Generic protocol README	README.md + AGENTS.md explaining extension rationale
Feature contract	Implicit base spec	Explicit feature capability documentation

The AGENTS.md file specifically documents why each protocol extension exists and which Logitech product families require it, serving as the definitive reference for the fork's design decisions.

Code Comparison: Basic vs. Extended Protocol Usage

Accessing standard device information works identically in both implementations:

// Common to both crates: basic HID++ 1.0 device query
let dev = hidpp::Device::new(&backend)?;
let info = dev.get_device_info()?;

Extended features require the fork's feature API:

// openlogi-hidpp fork: extended DPI range query (HID++ 2.0 feature 0x1001)
use openlogi_hidpp::feature::extended_dpi::ExtendedDpi;

let dev = openlogi_hidpp::Device::new(&backend)?;
let dpi = dev.get_feature::<ExtendedDpi>()?;
println!("Supported range: {}-{} DPI", dpi.min, dpi.max);

RGB effect configuration demonstrates the fork's protocol depth:

// openlogi-hidpp: complex lighting effect via HID++ 2.0 feature 0x8070
use openlogi_hidpp::feature::rgb_effects::{RgbEffect, Zone};

let effect = RgbEffect::Breathing {
    zone: Zone::Logo,
    hue: 180,
    saturation: 80,
    brightness: 60,
    period_ms: 1500,
};
dev.set_feature(effect)?;

Key Source Files Defining Protocol Differences

Path	Purpose
crates/openlogi-hidpp/src/protocol/v10.rs	HID++ 1.0 base messages (preserved from upstream)
crates/openlogi-hidpp/src/protocol/v20.rs	HID++ 2.0 base messages (preserved from upstream)
crates/openlogi-hidpp/src/feature/extended_dpi.rs	Extended DPI protocol implementation
crates/openlogi-hidpp/src/feature/rgb_effects.rs	RGB lighting control protocol
crates/openlogi-hidpp/src/feature/smartshift_enhanced.rs	Enhanced scroll wheel protocol
crates/openlogi-hidpp/src/receiver/unifying.rs	Unifying receiver protocol layer
crates/openlogi-hidpp/src/receiver/bolt.rs	Bolt receiver protocol layer
crates/openlogi-hidpp/src/device.rs	Unified device API exposing all extensions
crates/openlogi-hidpp/AGENTS.md	Protocol extension rationale and contracts

Summary

• openlogi-hidpp preserves upstream compatibility for base HID++ 1.0/2.0 while adding feature-rich extensions for modern Logitech peripherals
• Feature modules in src/feature/ provide type-safe access to device capabilities like SmartShift, RGB effects, and extended DPI that upstream cannot address
• Receiver-specific code handles Logitech's Unifying and Boltecosystem quirks absent from the generic upstream implementation
• Enhanced test coverage validates protocol extensions against real device behavior
• Explicit documentation in AGENTS.md explains design decisions and capability contracts

Frequently Asked Questions

Can I use openlogi-hidpp as a drop-in replacement for upstream hidpp?

Yes, for base functionality. The fork maintains API compatibility for standard HID++ operations through preserved protocol/v10.rs and protocol/v20.rs modules. However, migrating to extended features requires adopting the fork's get_feature<T>() generic API rather than direct protocol calls.

Why wasn't the extended protocol merged upstream?

The upstream hidpp crate intentionally limits scope to documented, specification-stable protocol elements. Logitech's extended features vary by firmware version and lack public documentation, making them unsuitable for a reference implementation. The fork accepts this maintenance burden to enable full device support.

How does the fork handle protocol version detection?

The src/device.rs implementation queries the HID++ 2.0 feature set (feature 0x0001) to build a capability map. Extended features are exposed only when the device reports supporting indices. This runtime detection prevents protocol errors on older hardware while enabling advanced features when present.

Are the protocol differences documented for security auditing?

Yes. The AGENTS.md file in the fork root documents each protocol extension's purpose, the Logitech feature index it utilizes, and any security-relevant behaviors like persistent configuration storage or wireless transmission characteristics.

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