Differences Between openlogi-hidpp Fork and Upstream hidpp Crate

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 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. 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. This registry maps feature IDs to their corresponding Rust type implementations, enabling type-safe feature discovery via the device.get_feature::<T>() 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 and individual test modules within feature directories (e.g., 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 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:

// 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::<hidpp::feature::AdjustableDpiFeature>().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 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 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, 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.

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