# Differences Between openlogi-hidpp Fork and Upstream hidpp Crate > Explore the openlogi-hidpp fork, a fork of the hidpp crate, offering expanded HID++ 2.0 support via type safe wrappers and improved error handling while maintaining API compatibility. - Repository: [Xuan Zhang/OpenLogi](https://github.com/AprilNEA/OpenLogi) - Tags: deep-dive - Published: 2026-09-03 --- **The openlogi-hidpp fork is a hard fork of the upstream hidpp crate that maintains API compatibility while expanding support to dozens of HID++ 2.0 features through type-safe wrappers and comprehensive error handling.** The openlogi-hidpp library originates from the [AprilNEA/OpenLogi](https://github.com/AprilNEA/OpenLogi) repository as a hard fork of the upstream `hidpp` crate (specifically version 0.3.0 at commit `135c5600`). While the upstream crate provides foundational protocol primitives for Logitech HID++ communication, the openlogi-hidpp fork extends this foundation to implement complete feature coverage required for modern device management software, highlighting the key **differences between openlogi-hidpp fork and upstream hidpp crate** capabilities. ## Architecture and Compatibility ### Hard Fork Origins The openlogi-hidpp fork diverges from the upstream repository as a **hard fork** integrated directly into the OpenLogi workspace. Unlike a soft fork or wrapper, this implementation modifies the original source tree to add extensive HID++ 2.0 functionality while maintaining the **same crate name** (`hidpp`). This design choice ensures that existing code using `use hidpp::...` continues to function without modification, allowing seamless migration for dependent crates like `openlogi-device` and `openlogi-hid`. ### Versioning and Workspace Integration Whereas the upstream crate follows independent semantic versioning, the openlogi-hidpp fork is versioned in lockstep with the OpenLogi workspace as defined in the workspace [`Cargo.toml`](https://github.com/AprilNEA/OpenLogi/blob/main/Cargo.toml). This integration strategy ensures consistency across the entire OpenLogi application stack while clearly distinguishing the forked lineage from the original 0.3.0 upstream release. Both projects retain the **0BSD license** without modification. ## Feature Coverage Expansion The primary distinction between these crates lies in the breadth of HID++ 2.0 feature implementations. The upstream crate exposes low-level protocol commands, while the openlogi-hidpp fork adds **typed, ergonomic wrappers** for features covering device control, power management, input configuration, and lighting control. ### HID++ 2.0 Feature Registry All implemented features are registered in the central **feature registry** located at [`crates/openlogi-hidpp/src/feature/registry.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-hidpp/src/feature/registry.rs). This registry maps feature IDs to their corresponding Rust type implementations, enabling type-safe feature discovery via the `device.get_feature::()` method pattern. ### Supported Feature Categories The fork introduces structured implementations in `src/feature/*.rs` files for the following capability domains: - **Device and Power Management**: `Root`, `FeatureSet`, `DeviceInformation`, `DeviceTypeAndName`, `DeviceFriendlyName`, `UnifiedBattery`, and `WirelessDeviceStatus` - **Host Platform Support**: `HostsInfo`, `ChangeHost`, `MultiPlatform`, and `DualPlatform` - **Pointer and Wheel Control**: `MousePointer`, `AdjustableDpi`, `ExtendedAdjustableDpi`, `VerticalScrolling`, `HiResWheel`, `Thumbwheel`, and `SmartShift` (including enhanced variants) - **Input Remapping**: `ReprogControls` with named constant definitions for control IDs and task IDs, plus `PersistentRemappableAction` - **Keyboard Configuration**: `FnInversion` (legacy and multi-host variants), `DisableKeys`, `DisableKeysByUsage`, and `ModeStatus` - **Lighting Systems**: `Backlight`, `Illumination`, `BrightnessControl`, `ColorLedEffects`, `RgbEffects`, and `PerKeyLighting` - **Audio Controls**: `Sidetone` and `Equalizer` - **Report Rate Configuration**: `AdjustableReportRate` and `ExtendedAdjustableReportRate` - **Advanced Input**: `Crown`, `TouchpadRawXy`, `TouchMouseRaw`, and `SolarKeyboardDashboard` Each feature implementation handles wire-format encoding and decoding internally, exposing rich Rust types including `enum`, `bitflags`, and newtype wrappers that eliminate manual byte manipulation. ## Error Handling and Robustness The upstream crate returns generic errors when encountering unsupported device responses. In contrast, the openlogi-hidpp fork introduces specific error variants such as **`Hidpp20Error::UnsupportedResponse`** to handle unknown wire values explicitly. This approach prevents guesswork in protocol parsing and improves application stability when communicating with diverse Logitech hardware. ## Testing and Documentation Coverage ### Unit Test Implementation The fork adds extensive unit tests for each feature implementation, located in [`src/feature/tests.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/src/feature/tests.rs) and individual test modules within feature directories (e.g., [`src/feature/adjustable_dpi.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/src/feature/adjustable_dpi.rs)). These tests verify correct parsing behavior and validate error handling for edge cases such as malformed device responses or out-of-range values. ### Documentation Standards Whereas the upstream crate provides minimal documentation, the openlogi-hidpp fork includes a detailed README at [`crates/openlogi-hidpp/README.md`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-hidpp/README.md) that enumerates all supported features and links directly to the registry implementation. This documentation serves as the primary reference for developers implementing device control logic according to the AprilNEA/OpenLogi source code. ## Practical Implementation Example The following example demonstrates the type-safe API for configuring mouse DPI settings using the fork's `AdjustableDpiFeature` implementation: ```rust // Device creation uses the openlogi-hid layer, which implements the hidpp crate interface let dev = openlogi_hid::Device::new(...).await?; // Retrieve the typed feature handle from the registry let dpi_feat = dev.get_feature::().await?; // Query sensor configuration let sensor_cnt = dpi_feat.get_sensor_count().await?; println!("Available sensors: {}", sensor_cnt); // Retrieve supported DPI values for the first sensor let dpi_list = dpi_feat.get_sensor_dpi_list(0).await?; println!("Supported DPI values: {:?}", dpi_list); // Set specific DPI value with type-checked parameters dpi_feat.set_sensor_dpi(0, 1200).await?; println!("DPI successfully configured to 1200"); ``` This code compiles against both the upstream and forked crates, but the fork guarantees the availability of `AdjustableDpiFeature` and its associated methods, whereas upstream implementations would require manual protocol command construction. ## Summary - **openlogi-hidpp** is a hard fork of upstream `hidpp` version 0.3.0 integrated into the AprilNEA/OpenLogi workspace - The fork preserves the `hidpp` crate name for API compatibility while adding comprehensive HID++ 2.0 feature wrappers - **Type-safe feature structs** in [`src/feature/registry.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/src/feature/registry.rs) replace low-level byte manipulation for dozens of device capabilities - **Enhanced error handling** via `Hidpp20Error::UnsupportedResponse` provides robust handling of unknown device responses - **Extensive unit tests** in [`src/feature/tests.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/src/feature/tests.rs) ensure reliable parsing across diverse hardware implementations - Both crates maintain the **0BSD license** with no licensing changes between upstream and fork ## Frequently Asked Questions ### Is openlogi-hidpp backward compatible with upstream hidpp code? Yes, the fork deliberately maintains the `hidpp` crate name and core API structure so that `use hidpp::...` statements function identically. However, the fork adds numerous feature-specific types (such as `AdjustableDpiFeature` and `SmartShiftFeature`) that do not exist in the upstream crate, so code utilizing these extensions will not compile against upstream versions. ### What specific HID++ features does the fork add beyond upstream? The fork implements typed wrappers for over twenty HID++ 2.0 features including `AdjustableDpiFeature`, `SmartShift`, `UnifiedBattery`, `ReprogControls`, `Backlight`, and `ColorLedEffects`. These implementations reside in individual files under `crates/openlogi-hidpp/src/feature/` and are indexed in [`src/feature/registry.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/src/feature/registry.rs), covering device information, power management, input remapping, lighting control, and platform switching. ### How does error handling differ between the two crates? The upstream crate returns generic errors for protocol mismatches, while openlogi-hidpp returns specific error variants such as `Hidpp20Error::UnsupportedResponse` when devices report unrecognized values. This distinction prevents silent failures and enables applications to distinguish between communication errors and unsupported hardware capabilities. ### Can openlogi-hidpp be used outside the OpenLogi application? Yes, the crate is published and can be used as a standalone dependency. However, it is optimized for the OpenLogi workspace architecture and follows the workspace's versioning scheme rather than independent semantic versioning. Developers seeking the specific HID++ 2.0 feature set implemented in `src/feature/` will find the fork more complete than upstream for Logitech device management tasks.