logiops_core/

device.rs

//! Device abstraction for HID++ communication.

use std::collections::HashMap;

use hidpp_transport::HidapiChannel;
use tracing::{debug, info, warn};

use crate::error::Result;
use crate::features::device_name::DeviceKind;
use crate::features::{DeviceNameFeature, RootFeature};
use crate::protocol::{feature_id, ProtocolVersion, DEVICE_INDEX_DIRECT};

/// Information about a connected HID++ device.
#[derive(Debug, Clone)]
pub struct DeviceInfo {
    /// Device name from HID++ query.
    pub name: String,
    /// HID++ protocol version.
    pub protocol_version: ProtocolVersion,
    /// Device kind (mouse, keyboard, etc.).
    pub device_kind: DeviceKind,
    /// Feature index mapping (`feature_id` -> index).
    pub features: HashMap<u16, u8>,
}

/// A HID++ device with protocol support.
pub struct HidppDevice {
    channel: HidapiChannel,
    device_index: u8,
    info: Option<DeviceInfo>,
}

impl HidppDevice {
    /// Creates a new HID++ device wrapper.
    ///
    /// # Arguments
    /// * `channel` - HID channel for communication
    /// * `device_index` - Device index (0xFF for direct, 1-6 for receiver)
    #[must_use]
    pub fn new(channel: HidapiChannel, device_index: u8) -> Self {
        Self {
            channel,
            device_index,
            info: None,
        }
    }

    /// Creates a device for direct USB/Bluetooth connection.
    #[must_use]
    pub fn direct(channel: HidapiChannel) -> Self {
        Self::new(channel, DEVICE_INDEX_DIRECT)
    }

    /// Returns the underlying HID channel.
    #[must_use]
    pub fn channel(&self) -> &HidapiChannel {
        &self.channel
    }

    /// Returns the device index.
    #[must_use]
    pub fn device_index(&self) -> u8 {
        self.device_index
    }

    /// Returns device info if initialized.
    #[must_use]
    pub fn info(&self) -> Option<&DeviceInfo> {
        self.info.as_ref()
    }

    /// Initializes the device by querying protocol version, name, and features.
    ///
    /// This should be called after creating the device to populate device info.
    ///
    /// # Errors
    /// Returns an error if HID++ communication fails or the device doesn't respond.
    ///
    /// # Panics
    /// Panics if called after successful initialization (info already set).
    pub async fn initialize(&mut self) -> Result<&DeviceInfo> {
        info!(
            path = %self.channel.path(),
            device_index = self.device_index,
            "initializing HID++ device"
        );

        let root = RootFeature::new(self.device_index);

        // Ping to get protocol version
        let protocol_version = root.ping(&self.channel).await?;

        if !protocol_version.supports_hidpp2() {
            warn!(
                version = %protocol_version,
                "device uses HID++ 1.0, limited support available"
            );
        }

        // Discover features
        let mut features = HashMap::new();

        // Always have IRoot at index 0
        features.insert(feature_id::IROOT, 0);

        // Try to find common features
        let feature_ids = [
            feature_id::IFEATURE_SET,
            feature_id::DEVICE_NAME,
            feature_id::FIRMWARE_INFO,
            feature_id::UNIFIED_BATTERY,
            feature_id::BATTERY_STATUS,
            feature_id::REPROG_CONTROLS,
            feature_id::SMART_SHIFT,
            feature_id::HIRES_SCROLLING,
            feature_id::THUMB_WHEEL,
            feature_id::ADJUSTABLE_DPI,
            feature_id::ONBOARD_PROFILES,
        ];

        for &fid in &feature_ids {
            match root.get_feature_index(&self.channel, fid).await {
                Ok(Some(idx)) => {
                    features.insert(fid, idx);
                }
                Ok(None) => {
                    debug!(feature_id = format!("0x{fid:04X}"), "feature not supported");
                }
                Err(e) => {
                    warn!(
                        feature_id = format!("0x{fid:04X}"),
                        error = %e,
                        "error querying feature"
                    );
                }
            }
        }

        // Get device name if supported
        let name = if let Some(&name_idx) = features.get(&feature_id::DEVICE_NAME) {
            let name_feature = DeviceNameFeature::new(self.device_index, name_idx);
            match name_feature.get_name(&self.channel).await {
                Ok(name) => name,
                Err(e) => {
                    warn!(error = %e, "failed to get device name");
                    "Unknown Device".to_string()
                }
            }
        } else {
            "Unknown Device".to_string()
        };

        // Get device type if supported
        let device_kind = if let Some(&name_idx) = features.get(&feature_id::DEVICE_NAME) {
            let name_feature = DeviceNameFeature::new(self.device_index, name_idx);
            match name_feature.get_device_type(&self.channel).await {
                Ok(kind) => kind,
                Err(e) => {
                    warn!(error = %e, "failed to get device type");
                    DeviceKind::Unknown(0xFF)
                }
            }
        } else {
            DeviceKind::Unknown(0xFF)
        };

        let info = DeviceInfo {
            name,
            protocol_version,
            device_kind,
            features,
        };

        info!(
            name = %info.name,
            version = %info.protocol_version,
            device_type = %info.device_kind,
            feature_count = info.features.len(),
            "device initialized"
        );

        self.info = Some(info);
        Ok(self.info.as_ref().unwrap())
    }

    /// Checks if a feature is supported by this device.
    #[must_use]
    pub fn has_feature(&self, feature_id: u16) -> bool {
        self.info
            .as_ref()
            .is_some_and(|i| i.features.contains_key(&feature_id))
    }

    /// Gets the feature index for a given feature ID.
    #[must_use]
    pub fn get_feature_index(&self, feature_id: u16) -> Option<u8> {
        self.info.as_ref()?.features.get(&feature_id).copied()
    }
}

impl std::fmt::Debug for HidppDevice {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("HidppDevice")
            .field("path", &self.channel.path())
            .field("device_index", &self.device_index)
            .field("info", &self.info)
            .finish()
    }
}