logiops_core/features/

reprog_controls.rs

//! `Reprogrammable Controls` feature (0x1B04) - Button remapping.
//!
//! This feature allows querying and diverting button events. When a button
//! is "diverted", the device sends HID++ events instead of standard HID
//! reports, allowing the daemon to intercept and remap button presses.

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};

/// `Reprogrammable Controls` feature implementation.
pub struct ReprogControlsFeature {
    device_index: u8,
    feature_index: u8,
}

/// Information about a control (button).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ControlInfo {
    /// Control ID (e.g., 0x00c3 for thumb button).
    pub cid: u16,
    /// Default task ID.
    pub task_id: u16,
    /// Capability flags.
    pub flags: ControlFlags,
    /// Physical position on device.
    pub position: u8,
    /// Button group.
    pub group: u8,
    /// Group membership mask.
    pub group_mask: u8,
    /// Additional flags (for v4).
    pub additional_flags: u8,
}

bitflags! {
    /// Control capability flags.
    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
    pub struct ControlFlags: u16 {
        /// Control is a mouse button.
        const MOUSE_BUTTON   = 0x0001;
        /// Control is an Fn key.
        const FN_KEY         = 0x0002;
        /// Control is a hotkey.
        const HOTKEY         = 0x0004;
        /// Control toggles Fn mode.
        const FN_TOGGLE      = 0x0008;
        /// Control can be reprogrammed.
        const REPROGRAMMABLE = 0x0010;
        /// Control can be diverted.
        const DIVERTABLE     = 0x0020;
        /// Divert setting persists across power cycles.
        const PERSIST        = 0x0040;
        /// Control is virtual (software-generated).
        const VIRTUAL        = 0x0080;
        /// Control supports raw XY reporting.
        const RAW_XY         = 0x0100;
    }
}

/// Current reporting configuration for a control.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct CidReporting {
    /// Control ID.
    pub cid: u16,
    /// Whether the control is diverted to HID++ events.
    pub divert: bool,
    /// Whether the divert setting persists.
    pub persist: bool,
    /// Whether raw XY is enabled.
    pub raw_xy: bool,
}

/// A button event from a diverted control.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ButtonEvent {
    /// Button was pressed.
    Press(u16),
    /// Button was released.
    Release(u16),
}

impl ReprogControlsFeature {
    /// Creates a new reprogrammable controls 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,
        }
    }

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

    /// Gets the number of controls on the device.
    ///
    /// # Errors
    /// Returns an error if HID++ communication fails.
    pub async fn get_count(&self, channel: &HidapiChannel) -> Result<u8> {
        // getCount: function_id=0x00
        let request = build_long_request(self.device_index, self.feature_index, 0x00, &[]);

        trace!("getting control count");
        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(
                "control count response too short".to_string(),
            ));
        }

        let count = response[4];
        debug!(count, "got control count");
        Ok(count)
    }

    /// Gets information about a control by index.
    ///
    /// # Arguments
    /// * `channel` - HID channel
    /// * `index` - Control index (0 to count-1)
    ///
    /// # Errors
    /// Returns an error if HID++ communication fails.
    pub async fn get_control_info(
        &self,
        channel: &HidapiChannel,
        index: u8,
    ) -> Result<ControlInfo> {
        // getControlInfo: function_id=0x01
        let request = build_long_request(self.device_index, self.feature_index, 0x01, &[index]);

        trace!(index, "getting control 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() < 13 {
            return Err(ProtocolError::InvalidResponse(
                "control info response too short".to_string(),
            ));
        }

        // Response format:
        // [4:5] = CID (big-endian)
        // [6:7] = Task ID (big-endian)
        // [8:9] = Flags (big-endian)
        // [10] = Position
        // [11] = Group
        // [12] = Group mask
        // [13] = Additional flags (v4+)
        let cid = u16::from_be_bytes([response[4], response[5]]);
        let task_id = u16::from_be_bytes([response[6], response[7]]);
        let flags_raw = u16::from_be_bytes([response[8], response[9]]);
        let flags = ControlFlags::from_bits_truncate(flags_raw);
        let position = response[10];
        let group = response[11];
        let group_mask = response[12];
        let additional_flags = response.get(13).copied().unwrap_or(0);

        let info = ControlInfo {
            cid,
            task_id,
            flags,
            position,
            group,
            group_mask,
            additional_flags,
        };

        debug!(
            index,
            cid = format!("0x{:04X}", info.cid),
            task_id = format!("0x{:04X}", info.task_id),
            ?flags,
            "got control info"
        );

        Ok(info)
    }

    /// Gets information about all controls on the device.
    ///
    /// # Errors
    /// Returns an error if HID++ communication fails.
    pub async fn get_all_controls(&self, channel: &HidapiChannel) -> Result<Vec<ControlInfo>> {
        let count = self.get_count(channel).await?;
        let mut controls = Vec::with_capacity(count as usize);

        for i in 0..count {
            let info = self.get_control_info(channel, i).await?;
            controls.push(info);
        }

        debug!(count = controls.len(), "got all controls");
        Ok(controls)
    }

    /// Gets the current reporting configuration for a control.
    ///
    /// # Arguments
    /// * `channel` - HID channel
    /// * `cid` - Control ID
    ///
    /// # Errors
    /// Returns an error if HID++ communication fails.
    pub async fn get_cid_reporting(
        &self,
        channel: &HidapiChannel,
        cid: u16,
    ) -> Result<CidReporting> {
        // getCidReporting: function_id=0x02
        let cid_bytes = cid.to_be_bytes();
        let request = build_long_request(
            self.device_index,
            self.feature_index,
            0x02,
            &[cid_bytes[0], cid_bytes[1]],
        );

        trace!(cid = format!("0x{cid:04X}"), "getting CID 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)));
        }

        if response.len() < 8 {
            return Err(ProtocolError::InvalidResponse(
                "CID reporting response too short".to_string(),
            ));
        }

        // Response format:
        // [4:5] = CID (big-endian)
        // [6] = Reporting flags
        // Bit 0: Divert
        // Bit 1: Persist
        // Bit 4: Raw XY
        let response_cid = u16::from_be_bytes([response[4], response[5]]);
        let flags = response[6];

        let reporting = CidReporting {
            cid: response_cid,
            divert: flags & 0x01 != 0,
            persist: flags & 0x02 != 0,
            raw_xy: flags & 0x10 != 0,
        };

        debug!(
            cid = format!("0x{:04X}", reporting.cid),
            divert = reporting.divert,
            persist = reporting.persist,
            raw_xy = reporting.raw_xy,
            "got CID reporting"
        );

        Ok(reporting)
    }

    /// Sets the reporting configuration for a control.
    ///
    /// # Arguments
    /// * `channel` - HID channel
    /// * `reporting` - Reporting configuration
    ///
    /// # Errors
    /// Returns an error if HID++ communication fails.
    pub async fn set_cid_reporting(
        &self,
        channel: &HidapiChannel,
        reporting: &CidReporting,
    ) -> Result<()> {
        // setCidReporting: function_id=0x03
        let cid_bytes = reporting.cid.to_be_bytes();

        // Build reporting flags
        let mut flags: u8 = 0;
        if reporting.divert {
            flags |= 0x01;
        }
        if reporting.persist {
            flags |= 0x02;
        }
        if reporting.raw_xy {
            flags |= 0x10;
        }

        let request = build_long_request(
            self.device_index,
            self.feature_index,
            0x03,
            &[cid_bytes[0], cid_bytes[1], flags],
        );

        trace!(
            cid = format!("0x{:04X}", reporting.cid),
            divert = reporting.divert,
            persist = reporting.persist,
            "setting CID 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!(
            cid = format!("0x{:04X}", reporting.cid),
            divert = reporting.divert,
            "set CID reporting"
        );

        Ok(())
    }

    /// Parses button events from a HID++ notification.
    ///
    /// When buttons are diverted, the device sends HID++ notifications
    /// containing button state changes. This function parses such notifications.
    ///
    /// # Arguments
    /// * `data` - Raw HID++ report data
    /// * `feature_index` - Expected feature index
    ///
    /// # Returns
    /// A vector of button events, or None if this is not a button event notification.
    #[must_use]
    pub fn parse_button_event(data: &[u8], feature_index: u8) -> Option<Vec<ButtonEvent>> {
        // Check minimum length and report type
        if data.len() < 7 {
            return None;
        }

        // Check if this is for our feature
        // Report format: [report_id, device_idx, feature_idx, func_sw_id, ...]
        if data[2] != feature_index {
            return None;
        }

        // Function ID is in high nibble of byte 3
        let function_id = data[3] >> 4;

        // Function 0 is the divert event notification
        if function_id != 0 {
            return None;
        }

        // Parse button states from the notification
        // Format varies but typically: [CID hi, CID lo, state, ...]
        // Multiple buttons can be reported in one notification
        let mut events = Vec::new();
        let mut i = 4;

        while i + 1 < data.len() {
            let cid = u16::from_be_bytes([data[i], data[i + 1]]);
            if cid == 0 {
                break;
            }

            // Check if there's a state byte
            // In most notifications, presence in the report means pressed
            // and absence means released
            events.push(ButtonEvent::Press(cid));

            i += 2;
        }

        if events.is_empty() {
            // If all CIDs are 0, this is a release notification
            // We need to track previous state to determine which buttons were released
            // For now, return empty - the caller should track state
            return None;
        }

        Some(events)
    }

    /// Parses button events from a HID++ notification, tracking state changes.
    ///
    /// This version compares against the previous state to generate both
    /// press and release events.
    ///
    /// # Arguments
    /// * `data` - Raw HID++ report data
    /// * `feature_index` - Expected feature index
    /// * `previous_pressed` - Set of CIDs that were pressed in the previous state
    ///
    /// # Returns
    /// A tuple of (events, `new_pressed_set`), or None if not a button event.
    #[must_use]
    pub fn parse_button_event_with_state(
        data: &[u8],
        feature_index: u8,
        previous_pressed: &std::collections::HashSet<u16>,
    ) -> Option<(Vec<ButtonEvent>, std::collections::HashSet<u16>)> {
        // Check minimum length and report type
        if data.len() < 7 {
            return None;
        }

        // Check if this is for our feature
        if data[2] != feature_index {
            return None;
        }

        // Function ID is in high nibble of byte 3
        let function_id = data[3] >> 4;

        // Function 0 is the divert event notification
        if function_id != 0 {
            return None;
        }

        // Parse currently pressed buttons
        let mut current_pressed = std::collections::HashSet::new();
        let mut i = 4;

        while i + 1 < data.len() {
            let cid = u16::from_be_bytes([data[i], data[i + 1]]);
            if cid == 0 {
                break;
            }
            current_pressed.insert(cid);
            i += 2;
        }

        // Generate events by comparing states
        let mut events = Vec::new();

        // New presses: in current but not in previous
        for &cid in &current_pressed {
            if !previous_pressed.contains(&cid) {
                events.push(ButtonEvent::Press(cid));
            }
        }

        // Releases: in previous but not in current
        for &cid in previous_pressed {
            if !current_pressed.contains(&cid) {
                events.push(ButtonEvent::Release(cid));
            }
        }

        Some((events, current_pressed))
    }
}

/// Well-known Control IDs for Logitech mice.
pub mod cid {
    /// Left mouse button.
    pub const LEFT_CLICK: u16 = 0x0050;
    /// Right mouse button.
    pub const RIGHT_CLICK: u16 = 0x0051;
    /// Middle mouse button (wheel click).
    pub const MIDDLE_CLICK: u16 = 0x0052;
    /// Back button (thumb).
    pub const BACK: u16 = 0x0053;
    /// Forward button (thumb).
    pub const FORWARD: u16 = 0x0056;
    /// Thumb button (gesture button on MX mice).
    pub const THUMB_BUTTON: u16 = 0x00C3;
    /// Top button (near DPI button).
    pub const TOP_BUTTON: u16 = 0x00C4;
    /// Scroll wheel left tilt.
    pub const SCROLL_LEFT: u16 = 0x00D7;
    /// Scroll wheel right tilt.
    pub const SCROLL_RIGHT: u16 = 0x00D0;
}

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

    #[test]
    fn test_control_flags() {
        let flags = ControlFlags::DIVERTABLE | ControlFlags::REPROGRAMMABLE;
        assert!(flags.contains(ControlFlags::DIVERTABLE));
        assert!(flags.contains(ControlFlags::REPROGRAMMABLE));
        assert!(!flags.contains(ControlFlags::MOUSE_BUTTON));
    }

    #[test]
    fn test_cid_reporting() {
        let reporting = CidReporting {
            cid: 0x00C3,
            divert: true,
            persist: false,
            raw_xy: false,
        };
        assert!(reporting.divert);
        assert!(!reporting.persist);
    }

    #[test]
    fn test_button_event() {
        let press = ButtonEvent::Press(0x00C3);
        let release = ButtonEvent::Release(0x00C3);

        match press {
            ButtonEvent::Press(cid) => assert_eq!(cid, 0x00C3),
            ButtonEvent::Release(_) => panic!("expected press"),
        }

        match release {
            ButtonEvent::Release(cid) => assert_eq!(cid, 0x00C3),
            ButtonEvent::Press(_) => panic!("expected release"),
        }
    }

    #[test]
    fn test_parse_button_event_with_state() {
        use std::collections::HashSet;

        // Simulate a button press notification
        // Format: [report_id, device_idx, feature_idx, func_sw_id, cid_hi, cid_lo, 0, 0, ...]
        let feature_index = 0x05;
        let notification = [
            0x11, // Long report
            0xFF, // Device index
            feature_index,
            0x00, // Function 0, SW ID 0
            0x00,
            0xC3, // CID 0x00C3 (thumb button)
            0x00,
            0x00,
        ];

        let previous: HashSet<u16> = HashSet::new();
        let result = ReprogControlsFeature::parse_button_event_with_state(
            &notification,
            feature_index,
            &previous,
        );

        assert!(result.is_some());
        let (events, new_pressed) = result.unwrap();
        assert_eq!(events.len(), 1);
        assert!(matches!(events[0], ButtonEvent::Press(0x00C3)));
        assert!(new_pressed.contains(&0x00C3));
    }
}