logiops_core/features/

thumb_wheel.rs

//! `Thumb Wheel` feature (0x2150) - Horizontal thumb wheel configuration.
//!
//! This feature provides control over the thumb wheel found on mice
//! like the MX Master series. It supports divert mode, inversion,
//! touch detection, and event reporting.

use bitflags::bitflags;
use hidpp_transport::HidapiChannel;
use tracing::{debug, trace};

use crate::error::{HidppErrorCode, ProtocolError, Result};
use crate::protocol::{build_long_request, get_error_code, is_error_response};

/// Function IDs for the Thumb Wheel feature.
mod function_id {
    /// Get thumb wheel information.
    pub const GET_INFO: u8 = 0x00;
    /// Get current status.
    pub const GET_STATUS: u8 = 0x01;
    /// Set reporting mode.
    pub const SET_REPORTING: u8 = 0x02;
}

bitflags! {
    /// Thumb wheel capability flags.
    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
    pub struct ThumbWheelCapabilities: u8 {
        /// Supports timestamp in events.
        const TIMESTAMP = 0x01;
        /// Supports touch detection.
        const TOUCH = 0x02;
        /// Supports proximity detection.
        const PROXY = 0x04;
        /// Supports single tap detection.
        const SINGLE_TAP = 0x08;
    }
}

/// Rotation status in thumb wheel events.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(u8)]
pub enum RotationStatus {
    /// No rotation activity.
    Inactive = 0,
    /// Rotation just started.
    Start = 1,
    /// Rotation in progress.
    Active = 2,
    /// Rotation stopped.
    Stop = 3,
}

impl TryFrom<u8> for RotationStatus {
    type Error = ();

    fn try_from(value: u8) -> std::result::Result<Self, Self::Error> {
        match value {
            0 => Ok(Self::Inactive),
            1 => Ok(Self::Start),
            2 => Ok(Self::Active),
            3 => Ok(Self::Stop),
            _ => Err(()),
        }
    }
}

/// Thumb wheel hardware information.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ThumbWheelInfo {
    /// Native resolution (counts per rotation).
    pub native_resolution: u16,
    /// Diverted resolution (when diverted to software).
    pub diverted_resolution: u16,
    /// Default scroll direction (true = natural/inverted).
    pub default_direction: bool,
    /// Hardware capabilities.
    pub capabilities: ThumbWheelCapabilities,
    /// Time window for events (in ms).
    pub time_elapsed: u16,
}

/// Current thumb wheel status.
#[derive(Debug, Clone, PartialEq, Eq)]
#[allow(clippy::struct_excessive_bools)] // Reflects hardware state flags
pub struct ThumbWheelStatus {
    /// Whether events are diverted to software.
    pub divert: bool,
    /// Whether scroll direction is inverted.
    pub invert: bool,
    /// Whether touch is currently detected.
    pub touch: bool,
    /// Whether proximity is currently detected.
    pub proxy: bool,
}

/// Thumb wheel configuration for set operations.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct ThumbWheelConfig {
    /// Divert thumb wheel events to software.
    pub divert: bool,
    /// Invert scroll direction.
    pub invert: bool,
}

/// Thumb wheel rotation event.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ThumbWheelEvent {
    /// Rotation delta (positive = clockwise from user perspective).
    pub rotation: i16,
    /// Event timestamp (if supported).
    pub timestamp: u16,
    /// Current rotation status.
    pub status: RotationStatus,
    /// Touch detected during event.
    pub touch: bool,
    /// Proximity detected during event.
    pub proxy: bool,
    /// Single tap detected.
    pub single_tap: bool,
}

/// `Thumb Wheel` feature implementation.
pub struct ThumbWheelFeature {
    device_index: u8,
    feature_index: u8,
}

impl ThumbWheelFeature {
    /// Creates a new thumb wheel feature accessor.
    ///
    /// # Arguments
    /// * `device_index` - Device index (0xFF for direct)
    /// * `feature_index` - Feature index from root feature discovery
    #[must_use]
    pub fn new(device_index: u8, feature_index: u8) -> Self {
        Self {
            device_index,
            feature_index,
        }
    }

    /// Gets thumb wheel hardware information.
    ///
    /// Returns resolution, capabilities, and timing information.
    ///
    /// # Errors
    /// Returns an error if HID++ communication fails.
    pub async fn get_info(&self, channel: &HidapiChannel) -> Result<ThumbWheelInfo> {
        let request = build_long_request(
            self.device_index,
            self.feature_index,
            function_id::GET_INFO,
            &[],
        );

        trace!("getting thumb wheel info");
        let response = channel.request(&request, 5).await?;

        if is_error_response(&response) {
            let code = get_error_code(&response).unwrap_or(0);
            return Err(ProtocolError::HidppError(HidppErrorCode::from_byte(code)));
        }

        if response.len() < 12 {
            return Err(ProtocolError::InvalidResponse(
                "thumb wheel info response too short".to_string(),
            ));
        }

        // Response format:
        // [4-5]: native resolution (big-endian)
        // [6-7]: diverted resolution (big-endian)
        // [8]: default direction (0 = normal, 1 = inverted)
        // [9]: capabilities
        // [10-11]: time elapsed (big-endian)
        let native_resolution = u16::from_be_bytes([response[4], response[5]]);
        let diverted_resolution = u16::from_be_bytes([response[6], response[7]]);
        let default_direction = response[8] != 0;
        let capabilities = ThumbWheelCapabilities::from_bits_truncate(response[9]);
        let time_elapsed = u16::from_be_bytes([response[10], response[11]]);

        let info = ThumbWheelInfo {
            native_resolution,
            diverted_resolution,
            default_direction,
            capabilities,
            time_elapsed,
        };

        debug!(
            native = native_resolution,
            diverted = diverted_resolution,
            caps = ?capabilities,
            "got thumb wheel info"
        );

        Ok(info)
    }

    /// Gets the current thumb wheel status.
    ///
    /// # Errors
    /// Returns an error if HID++ communication fails.
    pub async fn get_status(&self, channel: &HidapiChannel) -> Result<ThumbWheelStatus> {
        let request = build_long_request(
            self.device_index,
            self.feature_index,
            function_id::GET_STATUS,
            &[],
        );

        trace!("getting thumb wheel status");
        let response = channel.request(&request, 5).await?;

        if is_error_response(&response) {
            let code = get_error_code(&response).unwrap_or(0);
            return Err(ProtocolError::HidppError(HidppErrorCode::from_byte(code)));
        }

        if response.len() < 5 {
            return Err(ProtocolError::InvalidResponse(
                "thumb wheel status response too short".to_string(),
            ));
        }

        // Response format: [4] = flags
        // bit 0: divert
        // bit 1: invert
        // bit 2: touch
        // bit 3: proxy
        let flags = response[4];
        let status = ThumbWheelStatus {
            divert: (flags & 0x01) != 0,
            invert: (flags & 0x02) != 0,
            touch: (flags & 0x04) != 0,
            proxy: (flags & 0x08) != 0,
        };

        debug!(
            divert = status.divert,
            invert = status.invert,
            touch = status.touch,
            proxy = status.proxy,
            "got thumb wheel status"
        );

        Ok(status)
    }

    /// Sets the thumb wheel reporting mode.
    ///
    /// # Arguments
    /// * `channel` - HID channel
    /// * `config` - Configuration to apply
    ///
    /// # Errors
    /// Returns an error if HID++ communication fails.
    pub async fn set_reporting(
        &self,
        channel: &HidapiChannel,
        config: &ThumbWheelConfig,
    ) -> Result<()> {
        let mut flags: u8 = 0;
        if config.divert {
            flags |= 0x01;
        }
        if config.invert {
            flags |= 0x02;
        }

        let request = build_long_request(
            self.device_index,
            self.feature_index,
            function_id::SET_REPORTING,
            &[flags],
        );

        trace!(
            divert = config.divert,
            invert = config.invert,
            "setting thumb wheel reporting"
        );
        let response = channel.request(&request, 5).await?;

        if is_error_response(&response) {
            let code = get_error_code(&response).unwrap_or(0);
            return Err(ProtocolError::HidppError(HidppErrorCode::from_byte(code)));
        }

        debug!(
            divert = config.divert,
            invert = config.invert,
            "set thumb wheel reporting"
        );

        Ok(())
    }

    /// Parses a thumb wheel event from a HID++ report.
    ///
    /// This should be called when receiving event reports from the device
    /// after enabling divert mode.
    ///
    /// # Arguments
    /// * `report` - Raw HID++ report data
    ///
    /// # Returns
    /// `Some(ThumbWheelEvent)` if this is a valid thumb wheel event, `None` otherwise.
    #[must_use]
    pub fn parse_event(report: &[u8]) -> Option<ThumbWheelEvent> {
        // Event format (starting at byte 4):
        // [4-5]: rotation (signed, big-endian)
        // [6-7]: timestamp (big-endian)
        // [8]: rotation status (bits 0-1)
        // [9]: flags (touch, proxy, single_tap)
        if report.len() < 10 {
            return None;
        }

        let rotation = i16::from_be_bytes([report[4], report[5]]);
        let timestamp = u16::from_be_bytes([report[6], report[7]]);
        let status = RotationStatus::try_from(report[8] & 0x03).unwrap_or(RotationStatus::Inactive);
        let flags = report[9];

        Some(ThumbWheelEvent {
            rotation,
            timestamp,
            status,
            touch: (flags & 0x01) != 0,
            proxy: (flags & 0x02) != 0,
            single_tap: (flags & 0x04) != 0,
        })
    }
}

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

    #[test]
    fn test_capability_flags() {
        let caps = ThumbWheelCapabilities::TOUCH | ThumbWheelCapabilities::SINGLE_TAP;
        assert!(caps.contains(ThumbWheelCapabilities::TOUCH));
        assert!(caps.contains(ThumbWheelCapabilities::SINGLE_TAP));
        assert!(!caps.contains(ThumbWheelCapabilities::TIMESTAMP));
    }

    #[test]
    fn test_rotation_status() {
        assert_eq!(RotationStatus::try_from(0), Ok(RotationStatus::Inactive));
        assert_eq!(RotationStatus::try_from(1), Ok(RotationStatus::Start));
        assert_eq!(RotationStatus::try_from(2), Ok(RotationStatus::Active));
        assert_eq!(RotationStatus::try_from(3), Ok(RotationStatus::Stop));
        assert!(RotationStatus::try_from(4).is_err());
    }

    #[test]
    fn test_parse_event() {
        // Simulate an event report: rotation=100, timestamp=500, status=Active, touch=true
        let mut report = vec![0u8; 10];
        report[4] = 0x00;
        report[5] = 0x64; // rotation = 100
        report[6] = 0x01;
        report[7] = 0xF4; // timestamp = 500
        report[8] = 0x02; // status = Active
        report[9] = 0x01; // touch = true

        let event = ThumbWheelFeature::parse_event(&report).unwrap();
        assert_eq!(event.rotation, 100);
        assert_eq!(event.timestamp, 500);
        assert_eq!(event.status, RotationStatus::Active);
        assert!(event.touch);
        assert!(!event.proxy);
    }

    #[test]
    fn test_config_default() {
        let config = ThumbWheelConfig::default();
        assert!(!config.divert);
        assert!(!config.invert);
    }
}