How to Add Support for a New Logitech Device in OpenLogi's Registry

Adding support for a new Logitech device in OpenLogi requires updating the centralized device registry in crates/openlogi-device-registry to map USB vendor and product IDs to the correct HID++ receiver protocol and any device-specific metadata.

OpenLogi maintains a pure-Rust device registry that enables automatic discovery and protocol negotiation for Logitech peripherals. To add support for a new Logitech device in OpenLogi's registry, you must extend the lookup tables that connect USB hardware identifiers to their respective receiver protocols and feature sets.

Overview of the Device Registry Architecture

The registry is located in crates/openlogi-device-registry and serves as the single source of truth for hardware identification across the workspace. According to the OpenLogi source code, the entry point is src/lib.rs, which declares the constant LOGITECH_VENDOR_ID (0x046d), while src/receiver.rs implements the find_receiver function that maps vendor/product ID pairs to ReceiverProtocol variants. The HID++ implementation in crates/openlogi-hidpp/src/receiver/*.rs relies on this registry to instantiate the correct protocol handler.

Implementation Steps

Identify USB Vendor and Product IDs

Before modifying code, determine the hardware identifiers. All Logitech devices use vendor ID 0x046d, exposed in the codebase as LOGITECH_VENDOR_ID. Use lsusb on Linux or Device Manager on Windows to obtain the 16-bit product ID of your specific hardware.

Register the Receiver Protocol

Edit crates/openlogi-device-registry/src/receiver.rs to add a mapping in the find_receiver function. This associates the product ID with the appropriate protocol variant:

// In crates/openlogi-device-registry/src/receiver.rs
match (vendor_id, product_id) {
    // ... existing entries ...
    (LOGITECH_VENDOR_ID, 0x1234) => ReceiverProtocol::Bolt, // Your new device
    // ...
}

Valid protocol variants include Bolt, Unifying, and RawHid, depending on the receiver technology your device uses.

Add Lighting Support for Litra Devices

If the device includes a Litra lighting element, register it in crates/openlogi-device-registry/src/litra.rs. Call find_litra with the vendor ID, product ID, lighting channel (typically 0xff43), and firmware version:

// In crates/openlogi-device-registry/src/litra.rs
find_litra(
    LOGITECH_VENDOR_ID,
    0x1234,            // Product ID
    0xff43,            // Lighting channel
    0x0202,            // Firmware version
).expect("NewLitradDevice identity");

Register Custom HID++ Features (Optional)

Some devices expose non-standard HID++ features. If your hardware requires features not present in crates/openlogi-hidpp/src/feature/registry.rs, add version-gated entries there to enable the HID++ layer to recognize and utilize advanced capabilities.

Add Compile-Time Tests

Validate your changes by adding unit tests to crates/openlogi-device-registry/src/lib.rs or a dedicated test module. Verify that find_receiver returns the expected protocol and that find_litra resolves correctly for lighting devices:

#[test]
fn finds_new_logitech_device() {
    let protocol = find_receiver(LOGITECH_VENDOR_ID, 0x1234)
        .expect("receiver should be known");
    assert_eq!(protocol, ReceiverProtocol::Bolt);
}

Run the targeted test suites to ensure integration:

cargo test -p openlogi-device-registry
cargo test -p openlogi-hidpp

Summary

• Locate the registry: The device registry lives in crates/openlogi-device-registry and exports LOGITECH_VENDOR_ID from src/lib.rs and find_receiver from src/receiver.rs.
• Map the protocol: Add a tuple mapping in receiver.rs linking the product ID to the correct ReceiverProtocol variant.
• Handle lighting: For Litra devices, register lighting metadata in src/litra.rs using the find_litra function with the appropriate channel and firmware version.
• Extend features: Optionally add custom HID++ feature entries in crates/openlogi-hidpp/src/feature/registry.rs for advanced capabilities.
• Validate: Write unit tests calling find_receiver and run cargo test -p openlogi-device-registry to verify the new entries work correctly.

Frequently Asked Questions

What is the Logitech vendor ID constant in OpenLogi?

The vendor ID is defined as LOGITECH_VENDOR_ID with the hexadecimal value 0x046d in crates/openlogi-device-registry/src/lib.rs. All Logitech USB devices share this identifier.

How does OpenLogi determine which protocol to use for a receiver?

The find_receiver function in src/receiver.rs performs a pattern match on the vendor and product ID tuple, returning the corresponding ReceiverProtocol enum variant (such as Bolt or Unifying). The HID++ layer in crates/openlogi-hidpp calls this function during device initialization.

Do I need to modify the HID++ crate to support a new device?

Usually no. If the device uses standard HID++ features, only the device registry requires updates. You only need to modify crates/openlogi-hidpp/src/feature/registry.rs if the device exposes custom features not already defined in the codebase.

Where should I add tests for new device entries?

Add compile-time tests in crates/openlogi-device-registry/src/lib.rs or create a new test file in crates/openlogi-device-registry/tests/. Test that find_receiver returns the expected protocol variant and that lighting devices are discoverable via find_litra.

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