logiops_core/

protocol.rs

//! HID++ protocol constants, types, and helpers.

use hidpp_transport::channel::report;

/// Software ID to include in requests.
/// Used to match responses to requests.
pub const SOFTWARE_ID: u8 = 0x01;

/// Device index for direct USB/Bluetooth connections.
pub const DEVICE_INDEX_DIRECT: u8 = 0xFF;

/// Device indices for receivers (1-6 for paired devices).
pub const DEVICE_INDEX_RECEIVER_MIN: u8 = 0x01;
pub const DEVICE_INDEX_RECEIVER_MAX: u8 = 0x06;

/// HID++ 2.0 feature IDs.
pub mod feature_id {
    /// Root feature - always at index 0.
    pub const IROOT: u16 = 0x0000;
    /// Feature set enumeration.
    pub const IFEATURE_SET: u16 = 0x0001;
    /// Device firmware info.
    pub const FIRMWARE_INFO: u16 = 0x0003;
    /// Device name.
    pub const DEVICE_NAME: u16 = 0x0005;
    /// Unified battery.
    pub const UNIFIED_BATTERY: u16 = 0x1000;
    /// Battery status (older).
    pub const BATTERY_STATUS: u16 = 0x1001;
    /// Reprogrammable controls.
    pub const REPROG_CONTROLS: u16 = 0x1B04;
    /// `SmartShift` wheel.
    pub const SMART_SHIFT: u16 = 0x2110;
    /// Hi-res scrolling.
    pub const HIRES_SCROLLING: u16 = 0x2121;
    /// Low-res scrolling (legacy).
    pub const LOWRES_SCROLLING: u16 = 0x2130;
    /// Thumb wheel.
    pub const THUMB_WHEEL: u16 = 0x2150;
    /// Adjustable DPI.
    pub const ADJUSTABLE_DPI: u16 = 0x2201;
    /// On-board profiles.
    pub const ONBOARD_PROFILES: u16 = 0x8100;
}

/// HID++ protocol versions.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ProtocolVersion {
    /// HID++ 1.0 (legacy, limited support).
    V1_0,
    /// HID++ 2.0.
    V2_0,
    /// Unknown version.
    Unknown(u8, u8),
}

impl ProtocolVersion {
    /// Creates protocol version from major/minor bytes.
    #[must_use]
    pub fn new(major: u8, minor: u8) -> Self {
        match (major, minor) {
            (1, 0) => Self::V1_0,
            (2 | 4, _) => Self::V2_0, // 4.x is HID++ 2.0 with extensions
            _ => Self::Unknown(major, minor),
        }
    }

    /// Returns the major version number.
    #[must_use]
    pub fn major(&self) -> u8 {
        match self {
            Self::V1_0 => 1,
            Self::V2_0 => 2,
            Self::Unknown(major, _) => *major,
        }
    }

    /// Returns the minor version number.
    #[must_use]
    pub fn minor(&self) -> u8 {
        match self {
            Self::V1_0 | Self::V2_0 => 0,
            Self::Unknown(_, minor) => *minor,
        }
    }

    /// Returns true if this version supports HID++ 2.0 features.
    #[must_use]
    pub fn supports_hidpp2(&self) -> bool {
        matches!(self, Self::V2_0 | Self::Unknown(2..=4, _))
    }
}

impl std::fmt::Display for ProtocolVersion {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::V1_0 => write!(f, "HID++ 1.0"),
            Self::V2_0 => write!(f, "HID++ 2.0"),
            Self::Unknown(major, minor) => write!(f, "HID++ {major}.{minor}"),
        }
    }
}

/// Builds a short HID++ request (7 bytes).
///
/// # Arguments
/// * `device_index` - Device index (0xFF for direct, 1-6 for receiver)
/// * `feature_index` - Feature index from feature discovery
/// * `function_id` - Function ID within the feature
/// * `params` - Optional parameters (max 3 bytes)
#[must_use]
pub fn build_short_request(
    device_index: u8,
    feature_index: u8,
    function_id: u8,
    params: &[u8],
) -> [u8; report::SHORT_REPORT_LEN] {
    let mut buf = [0u8; report::SHORT_REPORT_LEN];
    buf[0] = report::SHORT_REPORT_ID;
    buf[1] = device_index;
    buf[2] = feature_index;
    buf[3] = (function_id << 4) | (SOFTWARE_ID & 0x0F);

    let param_len = params.len().min(3);
    buf[4..4 + param_len].copy_from_slice(&params[..param_len]);

    buf
}

/// Builds a long HID++ request (20 bytes).
///
/// # Arguments
/// * `device_index` - Device index (0xFF for direct, 1-6 for receiver)
/// * `feature_index` - Feature index from feature discovery
/// * `function_id` - Function ID within the feature
/// * `params` - Optional parameters (max 16 bytes)
#[must_use]
pub fn build_long_request(
    device_index: u8,
    feature_index: u8,
    function_id: u8,
    params: &[u8],
) -> [u8; report::LONG_REPORT_LEN] {
    let mut buf = [0u8; report::LONG_REPORT_LEN];
    buf[0] = report::LONG_REPORT_ID;
    buf[1] = device_index;
    buf[2] = feature_index;
    buf[3] = (function_id << 4) | (SOFTWARE_ID & 0x0F);

    let param_len = params.len().min(16);
    buf[4..4 + param_len].copy_from_slice(&params[..param_len]);

    buf
}

/// Parses the software ID from a response.
#[must_use]
pub fn parse_software_id(response: &[u8]) -> Option<u8> {
    response.get(3).map(|b| b & 0x0F)
}

/// Parses the function ID from a response.
#[must_use]
pub fn parse_function_id(response: &[u8]) -> Option<u8> {
    response.get(3).map(|b| b >> 4)
}

/// Checks if a response is an error response.
#[must_use]
pub fn is_error_response(response: &[u8]) -> bool {
    response.first() == Some(&0x8F)
}

/// Gets the error code from an error response.
#[must_use]
pub fn get_error_code(response: &[u8]) -> Option<u8> {
    if is_error_response(response) && response.len() >= 5 {
        Some(response[4])
    } else {
        None
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_build_short_request() {
        let request = build_short_request(0xFF, 0x00, 0x01, &[0x00, 0x00]);
        assert_eq!(request[0], report::SHORT_REPORT_ID);
        assert_eq!(request[1], 0xFF);
        assert_eq!(request[2], 0x00);
        assert_eq!(request[3], 0x11); // function_id=1 << 4 | software_id=1
    }

    #[test]
    fn test_protocol_version() {
        assert!(ProtocolVersion::V2_0.supports_hidpp2());
        assert!(!ProtocolVersion::V1_0.supports_hidpp2());

        let v45 = ProtocolVersion::new(4, 5);
        assert!(v45.supports_hidpp2());
    }
}