接收器

接收器（receiver）是无线 Logitech 设备使用的 USB 适配器。OpenLogi 按 USB VID/PID 检测已知适配器。OpenLogi 通过 HID++ 1.0 设备索引 0xFF（RECEIVER_DEVICE_INDEX）控制该适配器。OpenLogi 使用已配对设备的槽位索引 寻址该设备。

**规格：**Logitech 未公开此规格。布局由 Logi Options+ 2.8（静态分析）逆向得出。**交叉核对：**Solaar。用于：连接设备和支持的设备。

检测

receiver::detect(chan: Arc<HidppChannel>) -> Option<Receiver> 会匹配精确的 USB VID/PID。该函数会对未列出的适配器返回 None。表中的所有设备都使用 Logitech VID 046D。

Receiver 只有 Bolt 和 Unifying 两种协议变体。因此，Nano 和 Lightspeed 适配器会返回 Receiver::Unifying(_)。Receiver::name() 也会为这些适配器返回 "Unifying Receiver"。

通用 API

Receiver 持有具体接收器的监听器。其接收器级操作使用设备索引 0xFF。其方法不公开 适配器的市场系列。

ReceiverError 为 UnknownReceiver 或 Protocol(Hidpp10Error)。非穷尽的 Receiver 和错误枚举可以在后续版本增加变体。

寄存器 0x00：通知标志

寄存器 0x00 是完整的 24 位 BE 字。NotificationFlags 从 read_notification_flags() 获得时，会保留未命名的位。调用方必须修改读取结果，才能调用 write_notification_flags()。

write_notification_flags() 会写入所提供值的全部 3 个字节。该函数不能恢复调用方遗漏的位。 unifying::Receiver::set_wireless_notifications() 会读取该字，只修改 WIRELESS，并跳过相同的写入。

Logi Bolt

Bolt 是 Bluetooth Low Energy 接收器。其包装器支持最多 6 台已配对设备、发现、 passkey 事件、配对、取消配对和已配对设备读取。Logitech 未公开其寄存器布局规格。

API

bolt::DeviceConnection 有 index、kind、encrypted、online 和 wpid。 bolt::DevicePairingInformation 有 wpid、kind、encrypted、online 和 unit_id: [u8; 4]。

bolt::DeviceKind 建模 Keyboard、Mouse、Numpad、Presenter、Remote、 Trackball、Touchpad、Tablet、Gamepad、Joystick、Headset 和 Unknown。 PairingPasskeyPressType 建模 Initialization（0x00）、Keypress（0x01）、 Submit（0x04）和 Other(u8)。

寄存器和配对消息

以下所有条目都使用接收器索引 0xFF。N 是已配对设备槽位的低 4 位。多字节 WPID 使用 LE。

包装器会发出以下未匹配的长通知。偏移从 HID++ 1.0 的两个字节头之后开始。除了 0x41 以外，所有通知都必须使用接收器索引 0xFF。

公共包装器会忽略这些布局中的未使用字节。包装器会丢弃格式错误的名称和 passkey 文本。 设备配对服务还会读取 0x54：字节 1 是接收器错误；字节 0 为 0x02 时，字节 8 是分配的槽位。

Unifying

Unifying 使用 2.4 GHz eQuad 无线协议。其包装器支持最多 6 台已配对设备、接收器信息、 已配对设备读取和 0x41 事件。该包装器不公开直接的发现、配对、取消配对或代号方法。

API

unifying::ReceiverInfo 有 serial_number 和 pairing_slots。 unifying::DevicePairingInformation 有 wpid、kind、encrypted、online 和 unit_id: [u8; 4]。unifying::Event 只有 DeviceConnection(DeviceConnection)。

Unifying 的设备类型表从 Keyboard 到 Presenter 与 Bolt 相同。Unifying 使用 Remote = 0x05、Trackball = 0x06 和 Touchpad = 0x07。Bolt 对这 3 种设备分别使用 0x07、0x08 和 0x09。两个包装器都会将未知设备类型转为 Unknown。

寄存器和配对锁

InfoSubRegister::DeviceCodename 以 0x60 存在，但 Unifying 包装器没有代号方法。 OpenLogi 的库存路径使用单独的 Unifying 专用读取来获取代号。

0x41 连接通知

两个接收器包装器都解析 sub-ID 0x41。头部中的设备索引是从 1 开始的已配对设备槽位。 触发请求会为每个已配对槽位生成一条报告，其中包括离线槽位。因此，0x41 报告是槽位报告， 不能证明设备在线。

下表描述 HID++ 1.0 头部之后的通知 payload。

OpenLogi 从字节 1 的位 5 或字节 0 的 0x10 计算 encrypted。事件中只建模 index、kind、encrypted、online 和 wpid。DeviceConnection 不保留字节 0、 位 4 或位 7。

枚举已配对设备

触发到达通知前，必须启用无线通知。Unifying 辅助方法会对寄存器 0x00 作读-改-写。 下面的 Bolt 示例同样从读取的标志派生写入值。

use std::sync::Arc;

use hidpp::{
    channel::HidppChannel,
    receiver::{self, unifying, NotificationFlags, Receiver, ReceiverError},
};

async fn enumerate_receiver(chan: Arc<HidppChannel>) -> Result<(), ReceiverError> {
    let Some(receiver) = receiver::detect(Arc::clone(&chan)) else {
        return Ok(());
    };
    println!("{} — {}", receiver.name(), receiver.get_unique_id().await?);

    match receiver {
        Receiver::Bolt(bolt) => {
            let flags = bolt.get_notification_flags().await?;
            bolt.set_notification_flags(flags | NotificationFlags::WIRELESS)
                .await?;
            for device in bolt.collect_paired_devices().await? {
                println!("slot {}: {:04X}", device.index, device.wpid);
            }
        }
        Receiver::Unifying(unifying_receiver) => {
            unifying_receiver.set_wireless_notifications(true).await?;
            let events = unifying_receiver.listen();
            unifying_receiver.trigger_device_arrival().await?;
            while let Ok(unifying::Event::DeviceConnection(device)) = events.recv().await {
                println!("slot {}: {:04X}", device.index, device.wpid);
            }
        }
        _ => {}
    }
    Ok(())
}

Bolt 辅助方法会在触发写入完成后停止收集。Unifying 包装器会发出单独事件，因此调用方选择 自己的收集边界。

OpenLogi 的用法

设备注册表会在库存和配对使用协议包装器之前，对 USB 接收器分类。与 Unifying 兼容的 Nano 和 Lightspeed 适配器使用 Unifying 路径。库存会以读-改-写启用 WIRELESS，然后触发 0x41 报告来枚举已配对槽位。

配对服务在完整会话期间持有一个接收器寄存器阶段。该服务读取完整的 0x00 字，添加 WIRELESS 和 SOFTWARE_PRESENT，并在监听器关闭后恢复原始字。从 v0.8.14 开始， 该流程会保留未知通知位，不再清除寄存器。

Bolt 会写入发现寄存器 0xC0，并在写入确认后报告 Searching。Unifying 会写入 0xB2 锁打开请求，然后最多等待 2 秒来接收确认位 0 的 0x4A。只有收到确认后， 该流程才会报告 Searching。错误、取消和超时会发送对应阶段的关闭或取消请求。

公共配对选择器只有 First 和 BoltUid(String)。服务可以通过路由保存的接收器 UID 匹配任一协议系列来取消配对。服务不能在开始新配对会话时按 UID 选择 Unifying 接收器。

未确认的细节

Logitech 未公开这些接收器寄存器布局的规格。本页描述 Options+ 2.8 的静态证据和 Solaar 交叉核对。本页不将静态证据表述为硬件观察结果。

Options+ 在 Unifying 0xB2 锁打开请求的第 3 个字节中写入 0。Solaar 支持 30 秒超时。 OpenLogi 写入 30。静态证据没有表明该值错误。硬件跟踪必须确认特定接收器的时序语义。

Options+ 会保留 0x41 的字节 0。Solaar 将字节 0 的 0x10 视为已加密的 Bolt 链路。 OpenLogi 在共享解码器中应用该哨兵，但不公开协议字节。该哨兵对未来 Unifying 协议值的含义 尚未确认。

OpenLogi 可以读取 Unifying 唯一 ID，但 ReceiverSelector 没有 UnifyingUid 变体。 因此，使用 First 的新配对请求可以打开找到的第一个受支持接收器。这是未解决的产品限制， 不是未确认的线格式结论。

无接收器

蓝牙直连和有线设备会作为独立库存设备出现。它们不使用接收器寄存器。参见 连接设备。