logiops_core/features/

battery.rs

//! Battery features (0x1000 Unified Battery, 0x1001 Battery Status).
//!
//! These features report battery level and charging status. Most modern
//! Logitech devices use Unified Battery (0x1000), while older devices
//! use Battery Status (0x1001).

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

/// Unified Battery feature (0x1000) implementation.
pub struct UnifiedBatteryFeature {
    device_index: u8,
    feature_index: u8,
}

/// Battery Status feature (0x1001) implementation.
pub struct BatteryStatusFeature {
    device_index: u8,
    feature_index: u8,
}

/// Battery level and status information.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct BatteryInfo {
    /// Battery level as percentage (0-100).
    pub level: u8,
    /// Charging status.
    pub status: ChargingStatus,
    /// Battery voltage in millivolts (if available).
    pub voltage_mv: Option<u16>,
}

/// Battery level buckets (for devices that don't report exact percentage).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum BatteryLevel {
    /// Full (> 80%).
    Full,
    /// Good (50-80%).
    Good,
    /// Low (20-50%).
    Low,
    /// Critical (< 20%).
    Critical,
    /// Empty/dead.
    Empty,
    /// Unknown level.
    Unknown,
}

impl BatteryLevel {
    /// Converts from byte value.
    #[must_use]
    pub fn from_byte(value: u8) -> Self {
        match value {
            0 => Self::Empty,
            1 => Self::Critical,
            2 => Self::Low,
            3 => Self::Good,
            4..=8 => Self::Full,
            _ => Self::Unknown,
        }
    }

    /// Returns an approximate percentage for this level.
    #[must_use]
    pub fn approximate_percent(&self) -> u8 {
        match self {
            Self::Full => 90,
            Self::Good => 65,
            Self::Low => 35,
            Self::Critical => 10,
            Self::Empty => 0,
            Self::Unknown => 50,
        }
    }
}

impl std::fmt::Display for BatteryLevel {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Full => write!(f, "Full"),
            Self::Good => write!(f, "Good"),
            Self::Low => write!(f, "Low"),
            Self::Critical => write!(f, "Critical"),
            Self::Empty => write!(f, "Empty"),
            Self::Unknown => write!(f, "Unknown"),
        }
    }
}

/// Battery charging status.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum ChargingStatus {
    /// Battery is discharging (normal use).
    #[default]
    Discharging,
    /// Battery is charging.
    Charging,
    /// Battery is fully charged (and charging complete).
    Full,
    /// Charging error or slow charging.
    ChargingError,
    /// Wireless charging in progress.
    WirelessCharging,
}

impl ChargingStatus {
    /// Converts from byte value (Unified Battery format).
    #[must_use]
    pub fn from_byte(value: u8) -> Self {
        match value {
            1 => Self::Charging,
            2 => Self::Full,
            3 => Self::ChargingError,
            4 => Self::WirelessCharging,
            _ => Self::Discharging,
        }
    }

    /// Returns true if the device is currently charging.
    #[must_use]
    pub fn is_charging(&self) -> bool {
        matches!(self, Self::Charging | Self::WirelessCharging)
    }
}

impl std::fmt::Display for ChargingStatus {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Discharging => write!(f, "Discharging"),
            Self::Charging => write!(f, "Charging"),
            Self::Full => write!(f, "Fully Charged"),
            Self::ChargingError => write!(f, "Charging Error"),
            Self::WirelessCharging => write!(f, "Wireless Charging"),
        }
    }
}

impl UnifiedBatteryFeature {
    /// Creates a new Unified Battery 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 battery capabilities.
    ///
    /// # Errors
    /// Returns an error if HID++ communication fails.
    pub async fn get_capabilities(&self, channel: &HidapiChannel) -> Result<u8> {
        // getCapabilities: function_id=0
        let request = build_long_request(self.device_index, self.feature_index, 0x00, &[]);

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

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

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

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

        // Response: [report_id, device_idx, feature_idx, func_sw_id, state_of_charge, battery_level, charging_status, ...]
        let level = response[4];
        let battery_level = BatteryLevel::from_byte(response[5]);
        let status = ChargingStatus::from_byte(response[6]);

        // Use the percentage if provided, otherwise estimate from level
        let percent = if level > 0 && level <= 100 {
            level
        } else {
            battery_level.approximate_percent()
        };

        let info = BatteryInfo {
            level: percent,
            status,
            voltage_mv: None,
        };

        debug!(
            level = info.level,
            status = %info.status,
            "got battery status"
        );

        Ok(info)
    }
}

impl BatteryStatusFeature {
    /// Creates a new Battery Status 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 current battery level.
    ///
    /// # Errors
    /// Returns an error if HID++ communication fails.
    pub async fn get_battery_level(&self, channel: &HidapiChannel) -> Result<BatteryInfo> {
        // getBatteryLevelStatus: function_id=0
        let request = build_long_request(self.device_index, self.feature_index, 0x00, &[]);

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

        // Response: [report_id, device_idx, feature_idx, func_sw_id, battery_discharge_level, battery_discharge_next_level, battery_status]
        let discharge_level = response[4];
        let next_level = response[5];
        let battery_status = response[6];

        // Interpret battery status for charging info
        let status = match battery_status {
            0x20..=0x3F => ChargingStatus::Charging,
            0x80..=0x8F => ChargingStatus::Full,
            _ => ChargingStatus::Discharging,
        };

        // Convert discharge level to percentage
        // discharge_level is 0-7, where 0 = empty, 7 = full
        let percent = if discharge_level <= 7 {
            (u16::from(discharge_level) * 100 / 7).min(100) as u8
        } else {
            // Some devices report percentage directly
            discharge_level.min(100)
        };

        let info = BatteryInfo {
            level: percent,
            status,
            voltage_mv: None,
        };

        debug!(
            level = info.level,
            status = %info.status,
            next_level,
            "got battery level"
        );

        Ok(info)
    }

    /// Gets the battery voltage.
    ///
    /// # Errors
    /// Returns an error if HID++ communication fails or the feature doesn't support voltage reporting.
    pub async fn get_battery_voltage(&self, channel: &HidapiChannel) -> Result<u16> {
        // getBatteryVoltage: function_id=1 (may not be supported on all devices)
        let request = build_long_request(self.device_index, self.feature_index, 0x01, &[]);

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

        let voltage = u16::from_be_bytes([response[4], response[5]]);
        debug!(voltage_mv = voltage, "got battery voltage");

        Ok(voltage)
    }
}

/// Unified interface for battery access regardless of feature version.
pub enum BatteryFeature {
    /// Unified Battery (0x1000) - modern devices.
    Unified(UnifiedBatteryFeature),
    /// Battery Status (0x1001) - older devices.
    Legacy(BatteryStatusFeature),
}

impl BatteryFeature {
    /// Gets the current battery status using the appropriate feature.
    ///
    /// # Errors
    /// Returns an error if HID++ communication fails.
    pub async fn get_battery(&self, channel: &HidapiChannel) -> Result<BatteryInfo> {
        match self {
            Self::Unified(f) => f.get_status(channel).await,
            Self::Legacy(f) => f.get_battery_level(channel).await,
        }
    }
}

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

    #[test]
    fn test_battery_level() {
        assert_eq!(BatteryLevel::from_byte(0), BatteryLevel::Empty);
        assert_eq!(BatteryLevel::from_byte(1), BatteryLevel::Critical);
        assert_eq!(BatteryLevel::from_byte(4), BatteryLevel::Full);
        assert_eq!(BatteryLevel::from_byte(255), BatteryLevel::Unknown);
    }

    #[test]
    fn test_charging_status() {
        assert!(!ChargingStatus::Discharging.is_charging());
        assert!(ChargingStatus::Charging.is_charging());
        assert!(ChargingStatus::WirelessCharging.is_charging());
        assert!(!ChargingStatus::Full.is_charging());
    }
}