Receivers
Logitech wireless receivers use HID++ 1.0 registers for detection, paired-device enumeration, notifications, and pairing.
A receiver is a USB adapter for wireless Logitech devices. OpenLogi detects a
known adapter by USB VID/PID. It then controls the adapter at HID++ 1.0 device
index 0xFF (RECEIVER_DEVICE_INDEX). Paired devices use their assigned slot
index when OpenLogi addresses them.
Spec: No public Logitech specification. Layout reverse-engineered from Logi Options+ 2.8 (static analysis). Cross-checked: Solaar. Used by: Connect a device and Supported devices.
Detection
receiver::detect(chan: Arc<HidppChannel>) -> Option<Receiver> matches an exact
USB VID/PID. It returns None for every unlisted adapter. All listed IDs use
Logitech VID 046D.
| Market family | VID:PID | OpenLogi receiver protocol |
|---|---|---|
| Logi Bolt | 046D:C548 | Bolt |
| Unifying | 046D:C52B, 046D:C532 | Unifying |
| Nano | 046D:C534, 046D:C537 | Unifying-compatible |
| Lightspeed | 046D:C539, 046D:C53A, 046D:C53F, 046D:C541, 046D:C547, 046D:C54D | Unifying-compatible |
Receiver has only Bolt and Unifying protocol variants. Therefore, Nano and
Lightspeed adapters return Receiver::Unifying(_). Receiver::name() also
returns "Unifying Receiver" for those Unifying-compatible adapters.
Common API
Receiver owns the concrete receiver listener. Its receiver-wide operations
use device index 0xFF. Its methods do not expose the adapter market family.
| Item | Signature or value | Purpose |
|---|---|---|
| Receiver address | RECEIVER_DEVICE_INDEX = 0xFF | HID++ 1.0 receiver device index. |
| Detection | detect(Arc<HidppChannel>) -> Option<Receiver> | Classifies a known VID/PID. |
| Receiver kind | Receiver::Bolt(bolt::Receiver) / Receiver::Unifying(unifying::Receiver) | Selects the protocol wrapper. |
| Display name | name(&self) -> String | Returns "Logi Bolt Receiver" or "Unifying Receiver". |
| Unique ID | get_unique_id(&self) -> Result<String, ReceiverError> | Returns the family-specific receiver identifier. |
| Notifications read | read_notification_flags(&HidppChannel) -> Result<NotificationFlags, Hidpp10Error> | Reads register 0x00. |
| Notifications write | write_notification_flags(&HidppChannel, NotificationFlags) -> Result<(), Hidpp10Error> | Writes register 0x00. |
ReceiverError is either UnknownReceiver or Protocol(Hidpp10Error). The
non-exhaustive Receiver and error enums can add variants in later releases.
Register 0x00: notification flags
Register 0x00 is a complete 24-bit BE word. NotificationFlags retains
unnamed bits when it comes from read_notification_flags(). A caller must edit
that read value before it calls write_notification_flags().
| Word bit | Mask | Meaning | OpenLogi handling |
|---|---|---|---|
| 8 | 0x000100 | WIRELESS: device-arrival/removal (0x41) notifications | Modelled. |
| 11 | 0x000800 | SOFTWARE_PRESENT: host software is present | Modelled. Pairing needs this bit and WIRELESS. |
| All other bits | All remaining bits | Receiver- or software-specific notifications | Retained from a read value, but not named. |
write_notification_flags() writes all three bytes of the supplied value. It
cannot recover bits that a caller omitted. unifying::Receiver::set_wireless_notifications()
reads the word, changes only WIRELESS, and skips an identical write.
Logi Bolt
Bolt is a Bluetooth Low Energy receiver. Its wrapper supports up to six paired devices, discovery, passkey events, pairing, unpairing, and paired-device reads. Its register layout has no public Logitech specification.
API
| Method | Signature | Returns |
|---|---|---|
| Construct | new(Arc<HidppChannel>) | Result<bolt::Receiver, ReceiverError> |
| Subscribe | listen(&self) | async_channel::Receiver<bolt::Event> |
| Read notification flags | get_notification_flags(&self) | Result<NotificationFlags, ReceiverError> |
| Write notification flags | set_notification_flags(&self, flags: NotificationFlags) | Result<(), ReceiverError> |
| Count pairings | count_pairings(&self) | Result<u8, ReceiverError> |
| Trigger arrival | trigger_device_arrival(&self) | Result<(), ReceiverError> |
| Collect paired devices | collect_paired_devices(&self) | Result<Vec<bolt::DeviceConnection>, ReceiverError> |
| Read unique ID | get_unique_id(&self) | Result<String, ReceiverError> |
| Read pairing information | get_device_pairing_information(&self, device_index: u8) | Result<bolt::DevicePairingInformation, ReceiverError> |
| Read codename | get_device_codename(&self, device_index: u8) | Result<String, ReceiverError> |
| Unpair | unpair_device(&self, device_index: u8) | Result<(), ReceiverError> |
| Pair | pair_device(&self, slot: u8, address: [u8; 6], authentication: u8, entropy: u8) | Result<(), ReceiverError> |
| Start discovery | discover_devices(&self, timeout: Option<u8>) | Result<(), ReceiverError> |
| Cancel discovery | cancel_device_discovery(&self) | Result<(), ReceiverError> |
bolt::DeviceConnection has index, kind, encrypted, online, and
wpid. bolt::DevicePairingInformation has wpid, kind, encrypted,
online, and unit_id: [u8; 4].
bolt::DeviceKind models Keyboard, Mouse, Numpad, Presenter, Remote,
Trackball, Touchpad, Tablet, Gamepad, Joystick, Headset, and
Unknown. PairingPasskeyPressType models Initialization (0x00),
Keypress (0x01), Submit (0x04), and Other(u8).
Registers and pairing messages
All entries below use receiver index 0xFF. N is the low four bits of a
paired-device slot. Multi-byte WPIDs are LE.
| Register or sub-ID | Request or payload layout | OpenLogi handling |
|---|---|---|
0x02 read | Short read payload [00, 00, 00]; response byte 1 is the pairing count | count_pairings() reads byte 1. |
0x02 write | [02, 00, 00] | trigger_device_arrival() requests one 0x41 report per paired slot. |
0xB5 / 0x5N | Long sub-register read with request [00, 00]; response byte 1 is device info, bytes 2–3 are WPID LE, bytes 4–7 are unit ID | get_device_pairing_information() models these fields. |
0xB5 / 0x6N | Long sub-register read with request [01, 00]; response byte 2 is a name length, followed by UTF-8 bytes at byte 3 | get_device_codename() returns at most the 13 bytes in one response. It rejects invalid UTF-8. |
0xFB | Long-register read with [00, 00, 00] | get_unique_id() parses the complete response as UTF-8. The value is not the Bolt serial number. |
0xC0 discovery | Start [timeout, 01, 00]; cancel [00, 02, 00] | None writes timeout 0. The receiver maximum is 60 seconds. |
0xC1 pair | Long payload: [01, slot, address[0..6], authentication, entropy, 00 × 6] | pair_device() sends the supplied slot. The device layer uses slot 0 for auto-assignment. |
0xC1 cancel or unpair | Cancel [02, 00 × 15]; unpair [03, slot, 00 × 14] | The wrapper and device layer use these fixed action values. |
The wrapper emits the following unmatched long notifications. The offsets start
after the HID++ 1.0 two-byte header. Every notification except 0x41 must use
receiver index 0xFF.
| Sub-ID | Payload layout | bolt::Event result |
|---|---|---|
0x4D passkey request | Bytes 1–6: NUL-padded ASCII digits. Bytes 7–12: device address. | PairingPasskeyRequest { device_address, passkey } |
0x4E passkey press | Byte 0: press type. Bytes 1–6: device address. | PairingPasskeyPressed { device_address, press_type } |
0x4F discovery details | Bytes 0–1: counter LE. Byte 2: 0. Byte 4: kind. Bytes 5–6: WPID LE. Bytes 7–12: address. Byte 15: authentication. | DeviceDiscoveryDeviceDetails |
0x4F discovery name | Bytes 0–1: counter LE. Byte 2: 1. Byte 3: UTF-8 length. Bytes 4 onward: name. | DeviceDiscoveryDeviceName |
0x53 discovery status | Byte 0: 0 means discovery enabled. | DeviceDiscoveryStatus { discovery_enabled } |
The public wrapper ignores unused bytes in those layouts. It drops malformed
name and passkey text. The device pairing service also reads 0x54: byte 1 is
a receiver error, and byte 8 is the assigned slot when byte 0 is 0x02.
Unifying
Unifying uses the 2.4 GHz eQuad radio protocol. Its wrapper supports up to six
paired devices, receiver information, paired-device reads, and 0x41 events.
It does not expose direct discovery, pairing, unpairing, or codename methods.
API
| Method | Signature | Returns |
|---|---|---|
| Construct | new(Arc<HidppChannel>) | Result<unifying::Receiver, ReceiverError> |
| Subscribe | listen(&self) | async_channel::Receiver<unifying::Event> |
| Count pairings | count_pairings(&self) | Result<u8, ReceiverError> |
| Set wireless notifications | set_wireless_notifications(&self, enabled: bool) | Result<(), ReceiverError> |
| Trigger arrival | trigger_device_arrival(&self) | Result<(), ReceiverError> |
| Read receiver information | get_receiver_info(&self) | Result<unifying::ReceiverInfo, ReceiverError> |
| Read pairing information | get_device_pairing_information(&self, device_index: u8) | Result<unifying::DevicePairingInformation, ReceiverError> |
| Read unique ID | get_unique_id(&self) | Result<String, ReceiverError> |
unifying::ReceiverInfo has serial_number and pairing_slots.
unifying::DevicePairingInformation has wpid, kind, encrypted, online,
and unit_id: [u8; 4]. unifying::Event has only
DeviceConnection(DeviceConnection).
The Unifying kind table matches Bolt for Keyboard through Presenter.
Unifying uses Remote = 0x05, Trackball = 0x06, and Touchpad = 0x07.
Bolt uses 0x07, 0x08, and 0x09 for those three kinds. Unknown kind values
become Unknown in both wrappers.
Registers and pairing lock
| Register or sub-ID | Request or payload layout | OpenLogi handling |
|---|---|---|
0x02 read | Short read payload [00, 00, 00]; response byte 1 is the pairing count | count_pairings() reads byte 1. |
0x02 write | [02, 00, 00] | trigger_device_arrival() requests reports for online and offline paired slots. |
0xB5 / 0x03 | Long sub-register read with [00, 00]; response bytes 1–4 form the receiver serial, and byte 6 is the slot count | get_receiver_info() renders bytes 1–4 as uppercase hexadecimal. |
0xB5 / 0x5N | Long sub-register read with [00, 00]; byte 1 is device info, bytes 2–3 are WPID LE, bytes 4–7 are unit ID | get_device_pairing_information() models these fields. |
0xB2 lock | Open [01, 00, 30]; close [02, 00, 00]; unpair [03, slot, 00] | The device pairing service controls this register. |
0x4A lock state | Byte 0 bit 0: lock open. Byte 1: non-zero receiver error. | The pairing service confirms an open lock before it reports Searching. |
InfoSubRegister::DeviceCodename exists as 0x60, but the Unifying wrapper
has no codename method. OpenLogi's inventory path uses a separate
Unifying-specific read for codenames.
The 0x41 connection notification
Both receiver wrappers decode sub-ID 0x41. The header device index is the
one-based paired-device slot. A trigger request produces one report for every
paired slot, including offline slots. A 0x41 report is therefore a slot
report, not proof that its device is online.
The table describes the notification payload after the HID++ 1.0 header.
| Byte or bits | Wire meaning | OpenLogi handling |
|---|---|---|
| Byte 0 | Protocol byte | 0x10 makes encrypted true. The value is otherwise not exposed. Options+ 2.8 and Solaar evidence identify this as the Bolt encrypted-link sentinel. |
| Byte 1, bits 0–3 | Device kind | Modelled with the family-specific kind table. Unknown values become Unknown. |
Byte 1, bit 4 (0x10) | Software present | Ignored by the event decoders. It reflects register 0x00 SOFTWARE_PRESENT; it is not encryption. |
Byte 1, bit 5 (0x20) | Link encrypted | Modelled as encrypted. |
Byte 1, bit 6 (0x40) | Link not established | Modelled as online = false. Clear means online = true. |
Byte 1, bit 7 (0x80) | A payload packet follows | Ignored by the event decoders. |
| Bytes 2–3 | Wireless product ID | Modelled as wpid, LE. |
OpenLogi computes encrypted from byte 1 bit 5 or byte 0 0x10. It
models only index, kind, encrypted, online, and wpid in the event.
It does not retain byte 0, bit 4, or bit 7 in DeviceConnection.
Enumerating paired devices
Enable wireless notifications before you trigger arrivals. The Unifying helper
performs a read-modify-write of register 0x00. The Bolt example below derives
its write from the read flags for the same reason.
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(())
}The Bolt helper stops collecting after the trigger write completes. The Unifying wrapper emits individual events, so callers choose their own collection boundary.
How OpenLogi uses it
The device registry classifies USB receivers before inventory and pairing use
their protocol wrapper. Unifying-compatible Nano and Lightspeed adapters use
the Unifying path. Inventory enables WIRELESS with a read-modify-write, then
triggers 0x41 reports to enumerate paired slots.
The pairing service holds one receiver register phase for its full session. It
reads the complete 0x00 word, adds WIRELESS and SOFTWARE_PRESENT, then
restores the original word after the listener closes. Since v0.8.14, this keeps
unknown notification bits instead of clearing the register.
Bolt writes discovery 0xC0 and reports Searching after its write
acknowledgement. Unifying writes the 0xB2 lock-open request, then waits up to
2 seconds for 0x4A to confirm bit 0. It reports Searching only after that
confirmation. Errors, cancellation, and timeouts send the phase-appropriate
close or cancel request.
The public pairing selector has First and BoltUid(String). The service can
match either family by a route's stored receiver UID for unpairing. It cannot
select a Unifying receiver by UID when it starts a new pairing session.
Open questions
No public Logitech receiver specification defines these register layouts. The page describes static Options+ 2.8 evidence and Solaar cross-checks. It does not claim hardware observation.
Options+ writes 0 as the third byte of the Unifying 0xB2 lock-open request.
Solaar supports a 30-second timeout. OpenLogi writes 30; no static evidence
shows that value is wrong. Hardware traces must resolve the receiver-specific
timing semantics.
Options+ retains byte 0 of 0x41. Solaar treats byte 0 0x10 as an encrypted
Bolt link. OpenLogi applies that sentinel in the shared decoder and does not
expose the protocol byte. The sentinel's meaning for a future Unifying protocol
value remains unverified.
OpenLogi can read a Unifying unique ID, but ReceiverSelector has no
UnifyingUid variant. A new-pairing request with First can therefore open the
first supported receiver found. This is an open product limitation, not an
uncertain wire-format claim.
No receiver
Bluetooth-direct and wired devices appear as independent inventory devices. They do not use receiver registers. See Connect a device.