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

> Learn how to add support for a new Logitech device in OpenLogi by updating its device registry with USB IDs and receiver protocols for seamless integration.

- Repository: [Xuan Zhang/OpenLogi](https://github.com/AprilNEA/OpenLogi)
- Tags: how-to-guide
- Published: 2026-09-13

---

**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`](https://github.com/AprilNEA/OpenLogi/blob/main/src/lib.rs), which declares the constant `LOGITECH_VENDOR_ID` (0x046d), while [`src/receiver.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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:

```rust
// 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`](https://github.com/AprilNEA/OpenLogi/blob/main/crates/openlogi-device-registry/src/litra.rs). Call `find_litra` with the vendor ID, product ID, lighting channel (typically `0xff43`), and firmware version:

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

```rust
#[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:

```bash
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`](https://github.com/AprilNEA/OpenLogi/blob/main/src/lib.rs) and `find_receiver` from [`src/receiver.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/src/receiver.rs).
- **Map the protocol**: Add a tuple mapping in [`receiver.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/receiver.rs) linking the product ID to the correct `ReceiverProtocol` variant.
- **Handle lighting**: For Litra devices, register lighting metadata in [`src/litra.rs`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`](https://github.com/AprilNEA/OpenLogi/blob/main/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`.