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

> Discover the protocol differences between openlogi-hidpp and upstream hidpp. Learn about Logitech-specific extensions like SmartShift and RGB effects.

- Repository: [Xuan Zhang/OpenLogi](https://github.com/AprilNEA/OpenLogi)
- Tags: deep-dive
- Published: 2026-09-06

---

**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`](https://github.com/AprilNEA/OpenLogi/blob/main/src/protocol/v10.rs) and HID++ 2.0 messages in [`src/protocol/v20.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/smartshift.rs)** and **[`smartshift_enhanced.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/smartshift_enhanced.rs)** — Free-wheel scrolling configuration with enhanced sensitivity curves
- **[`rgb_effects.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/solar_dashboard.rs)** — Solar panel telemetry and power management
- **[`touchpad_raw_xy.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/src/emitter.rs) module provides a structured interface for dispatching feature-specific HID++ messages, while [`src/device.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/src/receiver/unifying.rs)** — Handles Logitech Unifying receiver pairing, device enumeration, and multiplexer channel allocation
- **[`src/receiver/bolt.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/src/receiver/bolt.rs)** — Implements Bolt receiver protocol extensions and Bluetooth-direct paths
- **[`src/receiver/mod.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/README.md) + [`AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/AGENTS.md) explaining extension rationale |
| Feature contract | Implicit base spec | Explicit feature capability documentation |

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

```rust
// 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:

```rust
// 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:

```rust
// 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`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-hidpp/src/protocol/v10.rs) | HID++ 1.0 base messages (preserved from upstream) |
| [`crates/openlogi-hidpp/src/protocol/v20.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-hidpp/src/protocol/v20.rs) | HID++ 2.0 base messages (preserved from upstream) |
| [`crates/openlogi-hidpp/src/feature/extended_dpi.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-hidpp/src/feature/extended_dpi.rs) | Extended DPI protocol implementation |
| [`crates/openlogi-hidpp/src/feature/rgb_effects.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-hidpp/src/feature/rgb_effects.rs) | RGB lighting control protocol |
| [`crates/openlogi-hidpp/src/feature/smartshift_enhanced.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-hidpp/src/feature/smartshift_enhanced.rs) | Enhanced scroll wheel protocol |
| [`crates/openlogi-hidpp/src/receiver/unifying.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-hidpp/src/receiver/unifying.rs) | Unifying receiver protocol layer |
| [`crates/openlogi-hidpp/src/receiver/bolt.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-hidpp/src/receiver/bolt.rs) | Bolt receiver protocol layer |
| [`crates/openlogi-hidpp/src/device.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-hidpp/src/device.rs) | Unified device API exposing all extensions |
| [`crates/openlogi-hidpp/AGENTS.md`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/protocol/v10.rs) and [`protocol/v20.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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.