logiops_core/features/

onboard_profiles.rs

//! `On-board Profiles` feature (0x8100) - Device profile management.
//!
//! This feature provides control over on-board profiles stored in device
//! flash memory. Supports profile switching and DPI index selection.
//!
//! Note: Full profile read/write operations (sector I/O, macros, button
//! bindings) are complex and may be added in future versions.

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 On-board Profiles feature.
mod function_id {
    /// Get profiles description (capabilities).
    pub const GET_PROFILES_DESC: u8 = 0x00;
    /// Set onboard mode (host vs onboard control).
    pub const SET_ONBOARD_MODE: u8 = 0x01;
    /// Get onboard mode.
    pub const GET_ONBOARD_MODE: u8 = 0x02;
    /// Get current profile index.
    pub const GET_CURRENT_PROFILE: u8 = 0x04;
    /// Set current profile index.
    pub const SET_CURRENT_PROFILE: u8 = 0x05;
    /// Get current DPI index within profile.
    pub const GET_CURRENT_DPI_INDEX: u8 = 0x06;
    /// Set current DPI index within profile.
    pub const SET_CURRENT_DPI_INDEX: u8 = 0x07;
}

/// Memory model types for profile storage.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(u8)]
pub enum MemoryModel {
    /// No on-board memory.
    None = 0,
    /// G402 memory model.
    G402 = 1,
    /// G303 memory model.
    G303 = 2,
    /// G900 memory model.
    G900 = 3,
    /// G915 memory model.
    G915 = 4,
    /// Unknown model.
    Unknown(u8),
}

impl From<u8> for MemoryModel {
    fn from(value: u8) -> Self {
        match value {
            0 => Self::None,
            1 => Self::G402,
            2 => Self::G303,
            3 => Self::G900,
            4 => Self::G915,
            v => Self::Unknown(v),
        }
    }
}

/// Onboard mode - who controls the device configuration.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(u8)]
pub enum OnboardMode {
    /// Device uses onboard profiles.
    Onboard = 1,
    /// Host software controls device.
    Host = 2,
}

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

    fn try_from(value: u8) -> std::result::Result<Self, Self::Error> {
        match value {
            1 => Ok(Self::Onboard),
            2 => Ok(Self::Host),
            _ => Err(()),
        }
    }
}

/// Profile capabilities and description.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ProfilesDescription {
    /// Memory model type.
    pub memory_model: MemoryModel,
    /// Profile format version.
    pub profile_format: u8,
    /// Macro format version.
    pub macro_format: u8,
    /// Number of profiles.
    pub profile_count: u8,
    /// Maximum number of profiles supported.
    pub profile_count_oob: u8,
    /// Number of buttons per profile.
    pub button_count: u8,
    /// Number of sectors for profiles.
    pub sector_count: u8,
    /// Sector page size in bytes.
    pub sector_size: u16,
    /// Device mechanical layout.
    pub mechanical_layout: u8,
    /// Number of different modes.
    pub num_modes: u8,
}

/// `On-board Profiles` feature implementation.
pub struct OnboardProfilesFeature {
    device_index: u8,
    feature_index: u8,
}

impl OnboardProfilesFeature {
    /// Creates a new on-board profiles 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 the profiles description (device capabilities).
    ///
    /// # Errors
    /// Returns an error if HID++ communication fails.
    pub async fn get_profiles_description(
        &self,
        channel: &HidapiChannel,
    ) -> Result<ProfilesDescription> {
        let request = build_long_request(
            self.device_index,
            self.feature_index,
            function_id::GET_PROFILES_DESC,
            &[],
        );

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

        // Response format (bytes 4+):
        // [0]: memory model
        // [1]: profile format
        // [2]: macro format
        // [3]: profile count
        // [4]: profile count OOB
        // [5]: button count
        // [6]: sector count
        // [7-8]: sector size (big-endian)
        // [9]: mechanical layout
        // [10]: num modes
        let desc = ProfilesDescription {
            memory_model: MemoryModel::from(response[4]),
            profile_format: response[5],
            macro_format: response[6],
            profile_count: response[7],
            profile_count_oob: response[8],
            button_count: response[9],
            sector_count: response[10],
            sector_size: u16::from_be_bytes([response[11], response[12]]),
            mechanical_layout: response[13],
            num_modes: response[14],
        };

        debug!(
            memory_model = ?desc.memory_model,
            profile_count = desc.profile_count,
            button_count = desc.button_count,
            "got profiles description"
        );

        Ok(desc)
    }

    /// Gets the current onboard mode.
    ///
    /// # Errors
    /// Returns an error if HID++ communication fails.
    pub async fn get_onboard_mode(&self, channel: &HidapiChannel) -> Result<OnboardMode> {
        let request = build_long_request(
            self.device_index,
            self.feature_index,
            function_id::GET_ONBOARD_MODE,
            &[],
        );

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

        let mode = OnboardMode::try_from(response[4]).map_err(|()| {
            ProtocolError::InvalidResponse(format!("invalid onboard mode: {}", response[4]))
        })?;

        debug!(mode = ?mode, "got onboard mode");
        Ok(mode)
    }

    /// Sets the onboard mode.
    ///
    /// # Arguments
    /// * `channel` - HID channel
    /// * `mode` - Mode to set (Onboard or Host)
    ///
    /// # Errors
    /// Returns an error if HID++ communication fails.
    pub async fn set_onboard_mode(
        &self,
        channel: &HidapiChannel,
        mode: OnboardMode,
    ) -> Result<()> {
        let request = build_long_request(
            self.device_index,
            self.feature_index,
            function_id::SET_ONBOARD_MODE,
            &[mode as u8],
        );

        trace!(mode = ?mode, "setting onboard mode");
        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!(mode = ?mode, "set onboard mode");
        Ok(())
    }

    /// Gets the current active profile index.
    ///
    /// Profile indices are 1-based (1 = first profile).
    ///
    /// # Errors
    /// Returns an error if HID++ communication fails.
    pub async fn get_current_profile(&self, channel: &HidapiChannel) -> Result<u8> {
        let request = build_long_request(
            self.device_index,
            self.feature_index,
            function_id::GET_CURRENT_PROFILE,
            &[],
        );

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

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

    /// Sets the current active profile.
    ///
    /// # Arguments
    /// * `channel` - HID channel
    /// * `profile_index` - Profile index (1-based)
    ///
    /// # Errors
    /// Returns an error if HID++ communication fails or the profile index is invalid.
    pub async fn set_current_profile(
        &self,
        channel: &HidapiChannel,
        profile_index: u8,
    ) -> Result<()> {
        let request = build_long_request(
            self.device_index,
            self.feature_index,
            function_id::SET_CURRENT_PROFILE,
            &[profile_index],
        );

        trace!(profile = profile_index, "setting current profile");
        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!(profile = profile_index, "set current profile");
        Ok(())
    }

    /// Gets the current DPI index within the active profile.
    ///
    /// DPI indices are 0-based (0 = first DPI slot).
    ///
    /// # Errors
    /// Returns an error if HID++ communication fails.
    pub async fn get_current_dpi_index(&self, channel: &HidapiChannel) -> Result<u8> {
        let request = build_long_request(
            self.device_index,
            self.feature_index,
            function_id::GET_CURRENT_DPI_INDEX,
            &[],
        );

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

        let dpi_index = response[4];
        debug!(dpi_index, "got current DPI index");
        Ok(dpi_index)
    }

    /// Sets the current DPI index within the active profile.
    ///
    /// # Arguments
    /// * `channel` - HID channel
    /// * `dpi_index` - DPI slot index (0-based)
    ///
    /// # Errors
    /// Returns an error if HID++ communication fails or the index is invalid.
    pub async fn set_current_dpi_index(
        &self,
        channel: &HidapiChannel,
        dpi_index: u8,
    ) -> Result<()> {
        let request = build_long_request(
            self.device_index,
            self.feature_index,
            function_id::SET_CURRENT_DPI_INDEX,
            &[dpi_index],
        );

        trace!(dpi_index, "setting current DPI index");
        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!(dpi_index, "set current DPI index");
        Ok(())
    }
}

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

    #[test]
    fn test_memory_model() {
        assert_eq!(MemoryModel::from(0), MemoryModel::None);
        assert_eq!(MemoryModel::from(1), MemoryModel::G402);
        assert_eq!(MemoryModel::from(3), MemoryModel::G900);
        assert!(matches!(MemoryModel::from(99), MemoryModel::Unknown(99)));
    }

    #[test]
    fn test_onboard_mode() {
        assert_eq!(OnboardMode::try_from(1), Ok(OnboardMode::Onboard));
        assert_eq!(OnboardMode::try_from(2), Ok(OnboardMode::Host));
        assert!(OnboardMode::try_from(0).is_err());
        assert!(OnboardMode::try_from(3).is_err());
    }
}