hidpp/receiver/

unifying.rs

//! Implements the Unifying Receiver.
//!
//! Unifying is a versatile receiver that can pair up to 6 devices using the
//! 2.4 GHz eQuad radio protocol. It uses HID++ 1.0 registers for receiver
//! control; paired devices speak HID++ 2.0 once addressed via their slot index.
//!
//! The register layout for device enumeration (`0xB5/0x5N`, `0xB5/0x6N`) is
//! identical to Bolt's. The device-kind encoding differs from Bolt at values 5+
//! (see [`DeviceKind`]).

use std::sync::Arc;

use num_enum::{FromPrimitive, IntoPrimitive, TryFromPrimitive};

use crate::{
    channel::{HidppChannel, MessageListenerGuard},
    event::EventEmitter,
    protocol::v10,
    receiver::{RECEIVER_DEVICE_INDEX, ReceiverError},
};

/// All USB vendor & product ID pairs that are known to identify Unifying
/// receivers.
///
/// `046d:c539` is the Lightspeed gaming receiver; `046d:c53f` is the Lightspeed
/// nano receiver (bundled with G-series wireless mice such as the G305). Both
/// answer the same HID++ 1.0 registers (pairing count, connection state, pairing
/// information) as Unifying receivers. Callers that surface a user-facing
/// receiver name label Lightspeed PIDs separately (see `openlogi-hid`).
/// `0xc53f` was verified against a G305 (paired device wpid `0x4074`).
pub const VPID_PAIRS: &[(u16, u16)] = &[
    (0x046d, 0xc52b),
    (0x046d, 0xc532),
    (0x046d, 0xc539),
    (0x046d, 0xc53f),
];

/// All known registers of the Unifying receiver.
#[derive(Clone, Copy, PartialEq, Eq, Hash, Debug, IntoPrimitive, TryFromPrimitive)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[non_exhaustive]
#[repr(u8)]
pub enum Register {
    /// Controls which notifications the receiver emits. Wireless device-arrival
    /// (`0x41`) events are only re-broadcast while wireless notifications are
    /// enabled here; see [`Receiver::set_wireless_notifications`].
    Notifications = 0x00,

    /// Enables or disables wireless device-connection notifications; also used
    /// to read the pairing count and to trigger device-arrival events.
    Connections = 0x02,

    /// Provides information about the receiver and paired devices. It uses
    /// sub-registers, as defined in [`InfoSubRegister`], to differentiate
    /// between different kinds of information.
    ReceiverInfo = 0xb5,
}

/// Represents the known sub-registers of the [`Register::ReceiverInfo`]
/// register.
#[derive(Clone, Copy, PartialEq, Eq, Hash, Debug, IntoPrimitive, TryFromPrimitive)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[non_exhaustive]
#[repr(u8)]
pub enum InfoSubRegister {
    /// Provides general information about the receiver (serial number, pairing
    /// slot count).
    ReceiverInfo = 0x03,

    /// Provides information about a specific paired device. The device index
    /// (4 bits) must be added to this base address to form the actual
    /// sub-register: `0x50 | (device_index & 0x0f)`.
    DevicePairingInformation = 0x50,

    /// Provides the codename of a specific paired device. The device index (4
    /// bits) must be added: `0x60 | (device_index & 0x0f)`.
    ///
    /// NOTE: `0x60` is the *Bolt* base. Wire-verified Unifying receivers store
    /// names at base `0x40 + (n-1)` instead, so name reads go directly through
    /// `read_codename_unifying` in `inventory.rs` rather than this constant —
    /// don't reuse `DeviceCodename` for Unifying name reads.
    DeviceCodename = 0x60,
}

/// Implements the Unifying wireless receiver.
#[derive(Clone)]
pub struct Receiver {
    chan: Arc<HidppChannel>,
    emitter: Arc<EventEmitter<Event>>,
    _listener: Arc<MessageListenerGuard>,
}

impl Receiver {
    /// Tries to initialize a new [`Receiver`] from a raw HID++ channel.
    ///
    /// Returns [`ReceiverError::UnknownReceiver`] when the channel's VID/PID
    /// doesn't match any known Unifying receiver.
    pub fn new(chan: Arc<HidppChannel>) -> Result<Self, ReceiverError> {
        if !VPID_PAIRS.contains(&(chan.vendor_id, chan.product_id)) {
            return Err(ReceiverError::UnknownReceiver);
        }

        let emitter = Arc::new(EventEmitter::new());

        let listener = chan.add_msg_listener_guarded({
            let emitter = Arc::clone(&emitter);
            move |raw, matched| {
                if matched {
                    return;
                }

                let parsed = v10::Message::from(raw);
                let header = parsed.header();
                let payload = parsed.extend_payload();

                // Device-connection notifications are directed at a specific slot
                // (header.device_index = slot) with sub_id 0x41.
                if header.sub_id != 0x41 {
                    return;
                }

                // Kind is identity-only; an unrecognised nibble folds to
                // `Unknown` — dropping the event would hide the device
                // entirely (arrival notifications are the only device
                // source on this path).
                emitter.emit(Event::DeviceConnection(DeviceConnection {
                    index: header.device_index,
                    kind: DeviceKind::from(payload[1] & 0x0f),
                    encrypted: payload[1] & (1 << 4) != 0,
                    online: payload[1] & (1 << 6) == 0,
                    wpid: u16::from_le_bytes(payload[2..=3].try_into().unwrap()),
                }));
            }
        });

        Ok(Receiver {
            _listener: Arc::new(listener),
            chan,
            emitter,
        })
    }

    /// Creates a new listener for receiving receiver events.
    pub fn listen(&self) -> async_channel::Receiver<Event> {
        self.emitter.create_receiver()
    }

    /// Counts the number of devices currently paired to this receiver.
    /// Offline (sleeping) devices are included since pairings are persistent.
    pub async fn count_pairings(&self) -> Result<u8, ReceiverError> {
        let response = self
            .chan
            .read_register(
                RECEIVER_DEVICE_INDEX,
                Register::Connections.into(),
                [0u8; 3],
            )
            .await?;

        Ok(response[1])
    }

    /// Enables or disables wireless device-connection notifications.
    ///
    /// The receiver only re-broadcasts `0x41` device-arrival events (the source
    /// for [`Self::trigger_device_arrival`]) while this is on. With it off the
    /// trigger write is ACK'd but emits nothing — which is why a paired, online
    /// device can fail to enumerate. Solaar enables this before listing.
    ///
    /// Read-modify-write of just the `WIRELESS` bit so it can't clobber other
    /// flags already set on register `0x00` — notably `SOFTWARE_PRESENT` (0x08),
    /// which the pairing flow enables (`pairing.rs` writes `[0x00, 0x09, 0x00]`)
    /// and a concurrent inventory poll would otherwise drop.
    pub async fn set_wireless_notifications(&self, enabled: bool) -> Result<(), ReceiverError> {
        // Notification flags are a 3-byte big-endian word; the receiver-reporting
        // bits live in byte 1 (WIRELESS = 0x000100, SOFTWARE_PRESENT = 0x000800).
        const WIRELESS: u8 = 0x01;
        let mut flags = self
            .chan
            .read_register(
                RECEIVER_DEVICE_INDEX,
                Register::Notifications.into(),
                [0; 3],
            )
            .await?;
        if enabled {
            flags[1] |= WIRELESS;
        } else {
            flags[1] &= !WIRELESS;
        }
        self.chan
            .write_register(RECEIVER_DEVICE_INDEX, Register::Notifications.into(), flags)
            .await?;

        Ok(())
    }

    /// Triggers device-arrival notifications for all currently connected
    /// devices. Used to enumerate online devices at startup.
    pub async fn trigger_device_arrival(&self) -> Result<(), ReceiverError> {
        self.chan
            .write_register(
                RECEIVER_DEVICE_INDEX,
                Register::Connections.into(),
                [0x02, 0x00, 0x00],
            )
            .await?;

        Ok(())
    }

    /// Provides general information about the receiver (serial number and
    /// pairing slot count).
    pub async fn get_receiver_info(&self) -> Result<ReceiverInfo, ReceiverError> {
        let response = self
            .chan
            .read_long_register(
                RECEIVER_DEVICE_INDEX,
                Register::ReceiverInfo.into(),
                [InfoSubRegister::ReceiverInfo.into(), 0, 0],
            )
            .await?;

        Ok(ReceiverInfo {
            serial_number: hex::encode_upper(&response[1..=4]),
            pairing_slots: response[6],
        })
    }

    /// Retrieves the pairing information for the device at `device_index`
    /// (1-based slot number).
    pub async fn get_device_pairing_information(
        &self,
        device_index: u8,
    ) -> Result<DevicePairingInformation, ReceiverError> {
        let response = self
            .chan
            .read_long_register(
                RECEIVER_DEVICE_INDEX,
                Register::ReceiverInfo.into(),
                [
                    u8::from(InfoSubRegister::DevicePairingInformation) | (device_index & 0x0f),
                    0x00,
                    0x00,
                ],
            )
            .await?;

        Ok(DevicePairingInformation {
            wpid: u16::from_le_bytes(response[2..=3].try_into().unwrap()),
            // Kind is identity-only: an unrecognised nibble folds to
            // `Unknown` instead of failing the whole pairing-info read.
            kind: DeviceKind::from(response[1] & 0x0f),
            encrypted: response[1] & (1 << 4) != 0,
            online: response[1] & (1 << 6) == 0,
            unit_id: response[4..=7].try_into().unwrap(),
        })
    }

    /// Provides the unique ID of the receiver (serial number).
    pub async fn get_unique_id(&self) -> Result<String, ReceiverError> {
        self.get_receiver_info().await.map(|i| i.serial_number)
    }
}

/// Represents some general information about a Unifying receiver.
#[derive(Clone, PartialEq, Eq, Hash, Debug)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[non_exhaustive]
pub struct ReceiverInfo {
    /// Receiver serial number.
    pub serial_number: String,
    /// Number of available pairing slots.
    pub pairing_slots: u8,
}

/// Represents information about a paired device as read from the pairing
/// register.
#[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[non_exhaustive]
pub struct DevicePairingInformation {
    /// Wireless product ID of the paired device.
    pub wpid: u16,
    /// Device kind reported by the receiver.
    pub kind: DeviceKind,
    /// Whether the link is encrypted.
    pub encrypted: bool,
    /// Whether the device is currently online.
    pub online: bool,
    /// Device unit ID.
    pub unit_id: [u8; 4],
}

/// Represents the kind of a device paired to a Unifying receiver.
///
/// The encoding matches Bolt for values 1–4; from 5 onwards Unifying uses a
/// shifted table (Remote=5, Trackball=6, Touchpad=7) while Bolt reserves those
/// values and places them at 7–9.
#[derive(Clone, Copy, PartialEq, Eq, Hash, Debug, IntoPrimitive, FromPrimitive)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[non_exhaustive]
#[repr(u8)]
pub enum DeviceKind {
    /// Unknown device kind — also the fold target for values this crate
    /// does not model (kind is identity-only and must never drop an event).
    #[num_enum(default)]
    Unknown = 0x00,
    /// Keyboard device.
    Keyboard = 0x01,
    /// Mouse device.
    Mouse = 0x02,
    /// Numeric keypad device.
    Numpad = 0x03,
    /// Presenter device.
    Presenter = 0x04,
    /// Remote-control device.
    Remote = 0x05,
    /// Trackball device.
    Trackball = 0x06,
    /// Touchpad device.
    Touchpad = 0x07,
}

/// Represents a device-connection event fired by the receiver when a paired
/// device comes online (or in response to [`Receiver::trigger_device_arrival`]).
#[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[non_exhaustive]
pub struct DeviceConnection {
    /// Slot index (1-based) of the device.
    pub index: u8,
    /// Device kind reported by the receiver.
    pub kind: DeviceKind,
    /// Whether the link is encrypted.
    pub encrypted: bool,
    /// Whether the device is currently online.
    pub online: bool,
    /// Wireless product ID of the device.
    pub wpid: u16,
}

/// Represents an event emitted by the Unifying receiver.
#[derive(Clone, PartialEq, Eq, Hash, Debug)]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[non_exhaustive]
pub enum Event {
    /// Fired whenever a paired device connects or reconnects, and for all
    /// online devices in response to [`Receiver::trigger_device_arrival`].
    DeviceConnection(DeviceConnection),
}