aranet_core/

history.rs

//! Historical data download.
//!
//! This module provides functionality to download historical sensor
//! readings stored on an Aranet device.
//!
//! # Supported Devices
//!
//! | Device | History Support | Notes |
//! |--------|-----------------|-------|
//! | Aranet4 | Full | CO₂, temperature, pressure, humidity |
//! | Aranet2 | Full | Temperature, humidity |
//! | AranetRn+ (Radon) | Full | Radon, temperature, pressure, humidity |
//! | Aranet Radiation | Not supported | BLE protocol undocumented by manufacturer |
//!
//! **Note:** Aranet Radiation devices do not support history download because
//! the BLE protocol for historical radiation data is not publicly documented
//! by SAF Tehnika. Attempting to download history will return [`Error::Unsupported`].
//! Use [`Device::read_current()`](crate::device::Device::read_current) for
//! current radiation readings.
//!
//! # Index Convention
//!
//! **All history indices are 1-based**, following the Aranet device protocol:
//! - Index 1 = oldest reading
//! - Index N = newest reading (where N = total_readings)
//!
//! This matches the device's internal indexing. When specifying ranges:
//! ```ignore
//! let options = HistoryOptions {
//!     start_index: Some(1),    // First reading
//!     end_index: Some(100),    // 100th reading
//!     ..Default::default()
//! };
//! ```
//!
//! # Protocols
//!
//! Aranet devices support two history protocols:
//! - **V1**: Notification-based (older devices) - uses characteristic notifications
//! - **V2**: Read-based (newer devices, preferred) - direct read/write operations

use std::collections::BTreeMap;
use std::sync::Arc;
use std::time::Duration;

use bytes::Buf;
use time::OffsetDateTime;
use tokio::time::sleep;
use tracing::{debug, info, warn};

use crate::commands::{HISTORY_V1_REQUEST, HISTORY_V2_REQUEST};
use crate::device::Device;
use crate::error::{Error, Result};
use crate::uuid::{COMMAND, HISTORY_V2, READ_INTERVAL, SECONDS_SINCE_UPDATE, TOTAL_READINGS};
use aranet_types::HistoryRecord;

/// Progress information for history download.
#[derive(Debug, Clone)]
pub struct HistoryProgress {
    /// Current parameter being downloaded.
    pub current_param: HistoryParam,
    /// Parameter index (1-based, e.g., 1 of 4).
    pub param_index: usize,
    /// Total number of parameters to download.
    pub total_params: usize,
    /// Number of values downloaded for current parameter.
    pub values_downloaded: usize,
    /// Total values to download for current parameter.
    pub total_values: usize,
    /// Overall progress (0.0 to 1.0).
    pub overall_progress: f32,
}

impl HistoryProgress {
    /// Create a new progress struct.
    pub fn new(
        param: HistoryParam,
        param_idx: usize,
        total_params: usize,
        total_values: usize,
    ) -> Self {
        Self {
            current_param: param,
            param_index: param_idx,
            total_params,
            values_downloaded: 0,
            total_values,
            overall_progress: 0.0,
        }
    }

    fn update(&mut self, values_downloaded: usize) {
        self.values_downloaded = values_downloaded;
        let param_progress = if self.total_values > 0 {
            values_downloaded as f32 / self.total_values as f32
        } else {
            1.0
        };
        // Guard against division by zero when total_params is 0
        if self.total_params == 0 {
            self.overall_progress = 1.0;
            return;
        }
        let base_progress = (self.param_index - 1) as f32 / self.total_params as f32;
        let param_contribution = param_progress / self.total_params as f32;
        self.overall_progress = base_progress + param_contribution;
    }
}

/// Type alias for progress callback function.
pub type ProgressCallback = Arc<dyn Fn(HistoryProgress) + Send + Sync>;

/// Type alias for checkpoint callback function.
pub type CheckpointCallback = Arc<dyn Fn(HistoryCheckpoint) + Send + Sync>;

/// Checkpoint data for resuming interrupted history downloads.
///
/// This can be serialized and saved to disk to allow resuming downloads
/// after disconnection or application restart.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct HistoryCheckpoint {
    /// Device identifier this checkpoint belongs to.
    pub device_id: String,
    /// The parameter currently being downloaded.
    pub current_param: HistoryParamCheckpoint,
    /// Index where download should resume for current parameter.
    pub resume_index: u16,
    /// Total readings on the device when checkpoint was created.
    pub total_readings: u16,
    /// Which parameters have been fully downloaded.
    pub completed_params: Vec<HistoryParamCheckpoint>,
    /// Timestamp when checkpoint was created.
    pub created_at: time::OffsetDateTime,
    /// Downloaded values for completed parameters (serialized).
    pub downloaded_data: Option<PartialHistoryData>,
}

/// Serializable version of HistoryParam for checkpoints.
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub enum HistoryParamCheckpoint {
    Temperature,
    Humidity,
    Pressure,
    Co2,
    Humidity2,
    Radon,
}

impl From<HistoryParam> for HistoryParamCheckpoint {
    fn from(param: HistoryParam) -> Self {
        match param {
            HistoryParam::Temperature => HistoryParamCheckpoint::Temperature,
            HistoryParam::Humidity => HistoryParamCheckpoint::Humidity,
            HistoryParam::Pressure => HistoryParamCheckpoint::Pressure,
            HistoryParam::Co2 => HistoryParamCheckpoint::Co2,
            HistoryParam::Humidity2 => HistoryParamCheckpoint::Humidity2,
            HistoryParam::Radon => HistoryParamCheckpoint::Radon,
        }
    }
}

impl From<HistoryParamCheckpoint> for HistoryParam {
    fn from(param: HistoryParamCheckpoint) -> Self {
        match param {
            HistoryParamCheckpoint::Temperature => HistoryParam::Temperature,
            HistoryParamCheckpoint::Humidity => HistoryParam::Humidity,
            HistoryParamCheckpoint::Pressure => HistoryParam::Pressure,
            HistoryParamCheckpoint::Co2 => HistoryParam::Co2,
            HistoryParamCheckpoint::Humidity2 => HistoryParam::Humidity2,
            HistoryParamCheckpoint::Radon => HistoryParam::Radon,
        }
    }
}

#[derive(Debug, Clone, Copy)]
struct U16HistoryStep {
    param: HistoryParam,
    step: usize,
    total_steps: usize,
    next_param: Option<HistoryParamCheckpoint>,
}

/// Partially downloaded history data for checkpoint resume.
#[derive(Debug, Clone, Default, serde::Serialize, serde::Deserialize)]
pub struct PartialHistoryData {
    pub co2_values: Vec<u16>,
    pub temp_values: Vec<u16>,
    pub pressure_values: Vec<u16>,
    pub humidity_values: Vec<u16>,
    pub radon_values: Vec<u32>,
}

impl HistoryCheckpoint {
    /// Create a new checkpoint for starting a fresh download.
    pub fn new(device_id: &str, total_readings: u16, first_param: HistoryParam) -> Self {
        Self {
            device_id: device_id.to_string(),
            current_param: first_param.into(),
            resume_index: 1,
            total_readings,
            completed_params: Vec::new(),
            created_at: time::OffsetDateTime::now_utc(),
            downloaded_data: Some(PartialHistoryData::default()),
        }
    }

    /// Check if this checkpoint is still valid for the given device state.
    pub fn is_valid(&self, current_total_readings: u16) -> bool {
        // Checkpoint is valid if the device hasn't collected more readings
        // (which would shift the indices)
        self.total_readings == current_total_readings
    }

    /// Update the checkpoint after completing a parameter.
    pub fn complete_param(&mut self, param: HistoryParam, values: Vec<u16>) {
        self.completed_params.push(param.into());
        if let Some(ref mut data) = self.downloaded_data {
            match param {
                HistoryParam::Co2 => data.co2_values = values,
                HistoryParam::Temperature => data.temp_values = values,
                HistoryParam::Pressure => data.pressure_values = values,
                HistoryParam::Humidity | HistoryParam::Humidity2 => data.humidity_values = values,
                HistoryParam::Radon => {} // Radon uses u32, handled separately
            }
        }
    }

    /// Update the checkpoint after completing a radon parameter.
    pub fn complete_radon_param(&mut self, values: Vec<u32>) {
        self.completed_params.push(HistoryParamCheckpoint::Radon);
        if let Some(ref mut data) = self.downloaded_data {
            data.radon_values = values;
        }
    }
}

/// Parameter types for history requests.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(u8)]
pub enum HistoryParam {
    Temperature = 1,
    Humidity = 2,
    Pressure = 3,
    Co2 = 4,
    /// Humidity for Aranet2/Radon (different encoding).
    Humidity2 = 5,
    /// Radon concentration (Bq/m³) for AranetRn+.
    Radon = 10,
}

/// Options for downloading history.
///
/// # Index Convention
///
/// Indices are **1-based** to match the Aranet device protocol:
/// - `start_index: Some(1)` means the first (oldest) reading
/// - `end_index: Some(100)` means the 100th reading
/// - `start_index: None` defaults to 1 (beginning)
/// - `end_index: None` defaults to total_readings (end)
///
/// # Progress Reporting
///
/// Use `with_progress` to receive updates during download:
/// ```ignore
/// let options = HistoryOptions::default()
///     .with_progress(|p| println!("Progress: {:.1}%", p.overall_progress * 100.0));
/// ```
///
/// # Adaptive Read Delay
///
/// Use `adaptive_delay` to automatically adjust delay based on signal quality:
/// ```ignore
/// let options = HistoryOptions::default().adaptive_delay(true);
/// ```
///
/// # Resume Support
///
/// For long downloads, use checkpointing to allow resume on failure:
/// ```ignore
/// let checkpoint = HistoryCheckpoint::load("device_123")?;
/// let options = HistoryOptions::default().resume_from(checkpoint);
/// ```
#[derive(Clone)]
pub struct HistoryOptions {
    /// Starting index (1-based, inclusive). If None, downloads from the beginning (index 1).
    pub start_index: Option<u16>,
    /// Ending index (1-based, inclusive). If None, downloads to the end (index = total_readings).
    pub end_index: Option<u16>,
    /// Delay between read operations to avoid overwhelming the device.
    pub read_delay: Duration,
    /// Progress callback (optional).
    pub progress_callback: Option<ProgressCallback>,
    /// Whether to use adaptive delay based on signal quality.
    pub use_adaptive_delay: bool,
    /// Checkpoint callback for saving progress during download (optional).
    /// Called periodically with the current checkpoint state.
    pub checkpoint_callback: Option<CheckpointCallback>,
    /// How often to call the checkpoint callback (in records).
    pub checkpoint_interval: usize,
}

impl std::fmt::Debug for HistoryOptions {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("HistoryOptions")
            .field("start_index", &self.start_index)
            .field("end_index", &self.end_index)
            .field("read_delay", &self.read_delay)
            .field("progress_callback", &self.progress_callback.is_some())
            .field("use_adaptive_delay", &self.use_adaptive_delay)
            .field("checkpoint_callback", &self.checkpoint_callback.is_some())
            .field("checkpoint_interval", &self.checkpoint_interval)
            .finish()
    }
}

impl Default for HistoryOptions {
    fn default() -> Self {
        Self {
            start_index: None,
            end_index: None,
            read_delay: Duration::from_millis(50),
            progress_callback: None,
            use_adaptive_delay: false,
            checkpoint_callback: None,
            checkpoint_interval: 100, // Checkpoint every 100 records
        }
    }
}

impl HistoryOptions {
    /// Create new history options with default settings.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Set the starting index (1-based).
    #[must_use]
    pub fn start_index(mut self, index: u16) -> Self {
        self.start_index = Some(index);
        self
    }

    /// Set the ending index (1-based).
    #[must_use]
    pub fn end_index(mut self, index: u16) -> Self {
        self.end_index = Some(index);
        self
    }

    /// Set the delay between read operations.
    #[must_use]
    pub fn read_delay(mut self, delay: Duration) -> Self {
        self.read_delay = delay;
        self
    }

    /// Set a progress callback.
    #[must_use]
    pub fn with_progress<F>(mut self, callback: F) -> Self
    where
        F: Fn(HistoryProgress) + Send + Sync + 'static,
    {
        self.progress_callback = Some(Arc::new(callback));
        self
    }

    /// Report progress if a callback is set.
    pub fn report_progress(&self, progress: &HistoryProgress) {
        if let Some(cb) = &self.progress_callback {
            cb(progress.clone());
        }
    }

    /// Enable or disable adaptive delay based on signal quality.
    ///
    /// When enabled, the read delay will be automatically adjusted based on
    /// the connection's signal strength:
    /// - Excellent signal: 30ms delay
    /// - Good signal: 50ms delay
    /// - Fair signal: 100ms delay
    /// - Poor signal: 200ms delay
    #[must_use]
    pub fn adaptive_delay(mut self, enable: bool) -> Self {
        self.use_adaptive_delay = enable;
        self
    }

    /// Set a checkpoint callback for saving download progress.
    ///
    /// The callback will be invoked periodically (based on `checkpoint_interval`)
    /// with the current checkpoint state, allowing recovery from interruptions.
    #[must_use]
    pub fn with_checkpoint<F>(mut self, callback: F) -> Self
    where
        F: Fn(HistoryCheckpoint) + Send + Sync + 'static,
    {
        self.checkpoint_callback = Some(Arc::new(callback));
        self
    }

    /// Set how often to call the checkpoint callback (in records).
    ///
    /// Default: 100 records
    #[must_use]
    pub fn checkpoint_interval(mut self, interval: usize) -> Self {
        self.checkpoint_interval = interval;
        self
    }

    /// Resume from a previous checkpoint.
    ///
    /// This sets the start_index based on the checkpoint's resume position.
    #[must_use]
    pub fn resume_from(mut self, checkpoint: &HistoryCheckpoint) -> Self {
        self.start_index = Some(checkpoint.resume_index);
        self
    }

    /// Report a checkpoint if a callback is set.
    pub fn report_checkpoint(&self, checkpoint: &HistoryCheckpoint) {
        if let Some(cb) = &self.checkpoint_callback {
            cb(checkpoint.clone());
        }
    }

    /// Get the effective read delay, optionally adjusted for signal quality.
    pub fn effective_read_delay(
        &self,
        signal_quality: Option<crate::device::SignalQuality>,
    ) -> Duration {
        if self.use_adaptive_delay
            && let Some(quality) = signal_quality
        {
            return quality.recommended_read_delay();
        }
        self.read_delay
    }
}

/// Information about the device's stored history.
#[derive(Debug, Clone)]
pub struct HistoryInfo {
    /// Total number of readings stored.
    pub total_readings: u16,
    /// Measurement interval in seconds.
    pub interval_seconds: u16,
    /// Seconds since the last reading.
    pub seconds_since_update: u16,
}

/// Wall-clock reference for converting device history indices to timestamps.
///
/// Captured once, immediately after `seconds_since_update` is read, so the
/// timestamps don't shift by however long the download takes. Index
/// `total_readings` is the newest record on the device; each lower index is
/// one interval older.
#[derive(Debug, Clone, Copy)]
struct HistoryAnchor {
    newest_record_at: OffsetDateTime,
    total_readings: u16,
    interval_seconds: u16,
}

impl HistoryAnchor {
    fn new(info: &HistoryInfo, read_at: OffsetDateTime) -> Self {
        Self {
            newest_record_at: read_at
                - time::Duration::seconds(i64::from(info.seconds_since_update)),
            total_readings: info.total_readings,
            interval_seconds: info.interval_seconds,
        }
    }

    /// Timestamp of the record at 1-based device `index`.
    fn timestamp_for(&self, index: u32) -> OffsetDateTime {
        let readings_ago = i64::from(self.total_readings) - i64::from(index);
        self.newest_record_at
            - time::Duration::seconds(readings_ago * i64::from(self.interval_seconds))
    }
}

impl Device {
    /// Get information about the stored history.
    pub async fn get_history_info(&self) -> Result<HistoryInfo> {
        // Read total readings count
        let total_data = self.read_characteristic(TOTAL_READINGS).await?;
        let total_readings = if total_data.len() >= 2 {
            u16::from_le_bytes([total_data[0], total_data[1]])
        } else {
            return Err(Error::InvalidData(
                "Invalid total readings data".to_string(),
            ));
        };

        // Read interval
        let interval_data = self.read_characteristic(READ_INTERVAL).await?;
        let interval_seconds = if interval_data.len() >= 2 {
            u16::from_le_bytes([interval_data[0], interval_data[1]])
        } else {
            return Err(Error::InvalidData("Invalid interval data".to_string()));
        };

        // Read seconds since update
        let age_data = self.read_characteristic(SECONDS_SINCE_UPDATE).await?;
        let seconds_since_update = if age_data.len() >= 2 {
            u16::from_le_bytes([age_data[0], age_data[1]])
        } else {
            0
        };

        Ok(HistoryInfo {
            total_readings,
            interval_seconds,
            seconds_since_update,
        })
    }

    /// Download all historical readings from the device.
    pub async fn download_history(&self) -> Result<Vec<HistoryRecord>> {
        self.download_history_with_options(HistoryOptions::default())
            .await
    }

    /// Download historical readings with custom options.
    ///
    /// # Device Support
    ///
    /// - **Aranet4**: Downloads CO₂, temperature, pressure, humidity
    /// - **Aranet2**: Downloads temperature, humidity
    /// - **AranetRn+ (Radon)**: Downloads radon, temperature, pressure, humidity
    /// - **Aranet Radiation**: **Not supported** - returns an error. The device protocol
    ///   for historical radiation data requires additional documentation. Use
    ///   [`Device::read_current()`](crate::device::Device::read_current) to get
    ///   current radiation readings.
    ///
    /// # Adaptive Delay
    ///
    /// If `options.use_adaptive_delay` is enabled, the read delay will be
    /// automatically adjusted based on the connection's signal quality.
    ///
    /// # Checkpointing
    ///
    /// If a checkpoint callback is set, progress will be saved periodically
    /// to allow resuming interrupted downloads.
    pub async fn download_history_with_options(
        &self,
        options: HistoryOptions,
    ) -> Result<Vec<HistoryRecord>> {
        use aranet_types::DeviceType;

        let info = self.get_history_info().await?;
        // Capture "now" as close as possible to the seconds-since-update read so
        // every sync maps the same device record to the same timestamp.
        let anchor = HistoryAnchor::new(&info, OffsetDateTime::now_utc());
        info!(
            "Device has {} readings, interval {}s, last update {}s ago",
            info.total_readings, info.interval_seconds, info.seconds_since_update
        );

        if info.total_readings == 0 {
            return Ok(Vec::new());
        }

        let start_idx = options.start_index.unwrap_or(1);
        let end_idx = options.end_index.unwrap_or(info.total_readings);

        if start_idx > end_idx {
            return Err(Error::InvalidConfig(format!(
                "start_index ({start_idx}) must be <= end_index ({end_idx})"
            )));
        }
        if start_idx == 0 {
            return Err(Error::InvalidConfig(
                "start_index must be >= 1 (indices are 1-based)".into(),
            ));
        }

        // Get signal quality for adaptive delay if enabled
        let signal_quality = if options.use_adaptive_delay {
            match self.signal_quality().await {
                Some(quality) => {
                    info!(
                        "Signal quality: {:?} - using {} ms read delay",
                        quality,
                        quality.recommended_read_delay().as_millis()
                    );
                    Some(quality)
                }
                None => {
                    debug!("Could not read signal quality, using default delay");
                    None
                }
            }
        } else {
            None
        };

        // Calculate effective read delay
        let effective_delay = options.effective_read_delay(signal_quality);

        // Dispatch based on device type
        match self.device_type() {
            Some(DeviceType::AranetRadiation) => {
                // Aranet Radiation history download is not supported.
                // The BLE protocol for historical radiation data differs from other
                // Aranet devices and is not publicly documented by SAF Tehnika.
                Err(Error::Unsupported(
                    "History download is not available for Aranet Radiation devices. \
                     The radiation history protocol is not documented. \
                     Use read_current() for current radiation readings."
                        .to_string(),
                ))
            }
            Some(DeviceType::AranetRadon) => {
                // For radon devices, download radon instead of CO2, and use Humidity2
                self.download_radon_history_internal(
                    &info,
                    anchor,
                    start_idx,
                    end_idx,
                    &options,
                    effective_delay,
                )
                .await
            }
            Some(DeviceType::Aranet2) => {
                // For Aranet2, download temperature and humidity only
                self.download_aranet2_history_internal(
                    &info,
                    anchor,
                    start_idx,
                    end_idx,
                    &options,
                    effective_delay,
                )
                .await
            }
            _ => {
                // For Aranet4 (and unknown devices), download CO2, temp, pressure, humidity
                self.download_aranet4_history_internal(
                    &info,
                    anchor,
                    start_idx,
                    end_idx,
                    &options,
                    effective_delay,
                )
                .await
            }
        }
    }

    /// Download a u16 parameter with progress reporting and checkpoint updates.
    ///
    /// This is the common pattern shared by all parameter downloads except radon (u32).
    /// Returns the downloaded values.
    async fn download_u16_param_with_checkpoint(
        &self,
        step_info: U16HistoryStep,
        start_idx: u16,
        end_idx: u16,
        effective_delay: Duration,
        options: &HistoryOptions,
        checkpoint: &mut Option<HistoryCheckpoint>,
    ) -> Result<Vec<u16>> {
        let total_values = (end_idx - start_idx + 1) as usize;
        let mut progress = HistoryProgress::new(
            step_info.param,
            step_info.step,
            step_info.total_steps,
            total_values,
        );
        options.report_progress(&progress);

        let values = self
            .download_param_history_with_progress(
                step_info.param,
                start_idx,
                end_idx,
                effective_delay,
                |downloaded| {
                    progress.update(downloaded);
                    options.report_progress(&progress);
                },
            )
            .await?;

        if let Some(cp) = checkpoint {
            cp.complete_param(step_info.param, values.clone());
            if let Some(next) = step_info.next_param {
                cp.current_param = next;
                cp.resume_index = start_idx;
            }
            options.report_checkpoint(cp);
        }

        Ok(values)
    }

    /// Download history for Aranet4 devices (CO2, temp, pressure, humidity).
    async fn download_aranet4_history_internal(
        &self,
        info: &HistoryInfo,
        anchor: HistoryAnchor,
        start_idx: u16,
        end_idx: u16,
        options: &HistoryOptions,
        effective_delay: Duration,
    ) -> Result<Vec<HistoryRecord>> {
        if start_idx > end_idx {
            return Ok(Vec::new());
        }

        let device_id = self.address().to_string();
        let mut checkpoint = if options.checkpoint_callback.is_some() {
            Some(HistoryCheckpoint::new(
                &device_id,
                info.total_readings,
                HistoryParam::Co2,
            ))
        } else {
            None
        };

        let co2_values = self
            .download_u16_param_with_checkpoint(
                U16HistoryStep {
                    param: HistoryParam::Co2,
                    step: 1,
                    total_steps: 4,
                    next_param: Some(HistoryParamCheckpoint::Temperature),
                },
                start_idx,
                end_idx,
                effective_delay,
                options,
                &mut checkpoint,
            )
            .await?;

        let temp_values = self
            .download_u16_param_with_checkpoint(
                U16HistoryStep {
                    param: HistoryParam::Temperature,
                    step: 2,
                    total_steps: 4,
                    next_param: Some(HistoryParamCheckpoint::Pressure),
                },
                start_idx,
                end_idx,
                effective_delay,
                options,
                &mut checkpoint,
            )
            .await?;

        let pressure_values = self
            .download_u16_param_with_checkpoint(
                U16HistoryStep {
                    param: HistoryParam::Pressure,
                    step: 3,
                    total_steps: 4,
                    next_param: Some(HistoryParamCheckpoint::Humidity),
                },
                start_idx,
                end_idx,
                effective_delay,
                options,
                &mut checkpoint,
            )
            .await?;

        let humidity_values = self
            .download_u16_param_with_checkpoint(
                U16HistoryStep {
                    param: HistoryParam::Humidity,
                    step: 4,
                    total_steps: 4,
                    next_param: None,
                },
                start_idx,
                end_idx,
                effective_delay,
                options,
                &mut checkpoint,
            )
            .await?;

        let records = build_history_records(
            &anchor,
            start_idx,
            &co2_values,
            &temp_values,
            &pressure_values,
            &humidity_values,
            &[],
        );

        info!("Downloaded {} history records", records.len());
        Ok(records)
    }

    /// Download history for Aranet2 devices (temperature, humidity only).
    async fn download_aranet2_history_internal(
        &self,
        info: &HistoryInfo,
        anchor: HistoryAnchor,
        start_idx: u16,
        end_idx: u16,
        options: &HistoryOptions,
        effective_delay: Duration,
    ) -> Result<Vec<HistoryRecord>> {
        if start_idx > end_idx {
            return Ok(Vec::new());
        }

        let device_id = self.address().to_string();
        let mut checkpoint = if options.checkpoint_callback.is_some() {
            Some(HistoryCheckpoint::new(
                &device_id,
                info.total_readings,
                HistoryParam::Temperature,
            ))
        } else {
            None
        };

        let temp_values = self
            .download_u16_param_with_checkpoint(
                U16HistoryStep {
                    param: HistoryParam::Temperature,
                    step: 1,
                    total_steps: 2,
                    next_param: Some(HistoryParamCheckpoint::Humidity2),
                },
                start_idx,
                end_idx,
                effective_delay,
                options,
                &mut checkpoint,
            )
            .await?;

        let humidity_values = self
            .download_u16_param_with_checkpoint(
                U16HistoryStep {
                    param: HistoryParam::Humidity2,
                    step: 2,
                    total_steps: 2,
                    next_param: None,
                },
                start_idx,
                end_idx,
                effective_delay,
                options,
                &mut checkpoint,
            )
            .await?;

        // Build records with no CO2, no pressure, no radon
        let records = build_history_records(
            &anchor,
            start_idx,
            &[],
            &temp_values,
            &[],
            &humidity_values,
            &[],
        );

        info!("Downloaded {} Aranet2 history records", records.len());
        Ok(records)
    }

    /// Download history for AranetRn+ devices (radon, temp, pressure, humidity).
    async fn download_radon_history_internal(
        &self,
        info: &HistoryInfo,
        anchor: HistoryAnchor,
        start_idx: u16,
        end_idx: u16,
        options: &HistoryOptions,
        effective_delay: Duration,
    ) -> Result<Vec<HistoryRecord>> {
        if start_idx > end_idx {
            return Ok(Vec::new());
        }
        let total_values = (end_idx - start_idx + 1) as usize;

        let device_id = self.address().to_string();
        let mut checkpoint = if options.checkpoint_callback.is_some() {
            Some(HistoryCheckpoint::new(
                &device_id,
                info.total_readings,
                HistoryParam::Radon,
            ))
        } else {
            None
        };

        // Download radon values (4 bytes each, uses u32 variant)
        let mut progress = HistoryProgress::new(HistoryParam::Radon, 1, 4, total_values);
        options.report_progress(&progress);

        let radon_values = self
            .download_param_history_u32_with_progress(
                HistoryParam::Radon,
                start_idx,
                end_idx,
                effective_delay,
                |downloaded| {
                    progress.update(downloaded);
                    options.report_progress(&progress);
                },
            )
            .await?;

        if let Some(ref mut cp) = checkpoint {
            cp.complete_radon_param(radon_values.clone());
            cp.current_param = HistoryParamCheckpoint::Temperature;
            cp.resume_index = start_idx;
            options.report_checkpoint(cp);
        }

        let temp_values = self
            .download_u16_param_with_checkpoint(
                U16HistoryStep {
                    param: HistoryParam::Temperature,
                    step: 2,
                    total_steps: 4,
                    next_param: Some(HistoryParamCheckpoint::Pressure),
                },
                start_idx,
                end_idx,
                effective_delay,
                options,
                &mut checkpoint,
            )
            .await?;

        let pressure_values = self
            .download_u16_param_with_checkpoint(
                U16HistoryStep {
                    param: HistoryParam::Pressure,
                    step: 3,
                    total_steps: 4,
                    next_param: Some(HistoryParamCheckpoint::Humidity2),
                },
                start_idx,
                end_idx,
                effective_delay,
                options,
                &mut checkpoint,
            )
            .await?;

        let humidity_values = self
            .download_u16_param_with_checkpoint(
                U16HistoryStep {
                    param: HistoryParam::Humidity2,
                    step: 4,
                    total_steps: 4,
                    next_param: None,
                },
                start_idx,
                end_idx,
                effective_delay,
                options,
                &mut checkpoint,
            )
            .await?;

        let records = build_history_records(
            &anchor,
            start_idx,
            &[],
            &temp_values,
            &pressure_values,
            &humidity_values,
            &radon_values,
        );

        info!("Downloaded {} radon history records", records.len());
        Ok(records)
    }

    /// Download a single parameter's history using V2 protocol with progress callback.
    ///
    /// This is a generic implementation that handles different value sizes:
    /// - 1 byte: humidity
    /// - 2 bytes: CO2, temperature, pressure, humidity2
    /// - 4 bytes: radon
    #[allow(clippy::too_many_arguments)]
    async fn download_param_history_generic_with_progress<T, F>(
        &self,
        param: HistoryParam,
        start_idx: u16,
        end_idx: u16,
        read_delay: Duration,
        value_parser: impl Fn(&[u8], usize) -> Option<T>,
        value_size: usize,
        mut on_progress: F,
    ) -> Result<Vec<T>>
    where
        T: Default + Clone,
        F: FnMut(usize),
    {
        debug!(
            "Downloading {:?} history from {} to {} (value_size={})",
            param, start_idx, end_idx, value_size
        );

        let mut values: BTreeMap<u16, T> = BTreeMap::new();
        let mut current_idx = start_idx;
        let mut consecutive_wrong_param = 0u32;
        const MAX_WRONG_PARAM_RETRIES: u32 = 5;
        let mut consecutive_stalls = 0u32;
        const MAX_STALLED_PACKETS: u32 = 5;

        while current_idx <= end_idx {
            // Send V2 history request using command constant
            let cmd = [
                HISTORY_V2_REQUEST,
                param as u8,
                (current_idx & 0xFF) as u8,
                ((current_idx >> 8) & 0xFF) as u8,
            ];

            self.write_characteristic(COMMAND, &cmd).await?;
            sleep(read_delay).await;

            // Read response
            let response = self.read_characteristic(HISTORY_V2).await?;

            // V2 response format (10-byte header):
            // Byte 0: param (1 byte)
            // Bytes 1-2: interval (2 bytes, little-endian)
            // Bytes 3-4: total_readings (2 bytes, little-endian)
            // Bytes 5-6: ago (2 bytes, little-endian)
            // Bytes 7-8: start index (2 bytes, little-endian)
            // Byte 9: count (1 byte)
            // Bytes 10+: data values
            if response.len() < 10 {
                warn!(
                    "Invalid history response: too short ({} bytes)",
                    response.len()
                );
                break;
            }

            let resp_param = response[0];
            if resp_param != param as u8 {
                consecutive_wrong_param += 1;
                warn!(
                    "Unexpected parameter in response: {} (retry {}/{})",
                    resp_param, consecutive_wrong_param, MAX_WRONG_PARAM_RETRIES
                );
                if consecutive_wrong_param >= MAX_WRONG_PARAM_RETRIES {
                    warn!("Too many wrong parameter responses, aborting download");
                    break;
                }
                // Wait and retry - device may not have processed command yet
                sleep(read_delay).await;
                continue;
            }
            consecutive_wrong_param = 0;

            // Parse header
            let resp_start = u16::from_le_bytes([response[7], response[8]]);
            let resp_count = response[9] as usize;

            debug!(
                "History response: param={}, start={}, count={}",
                resp_param, resp_start, resp_count
            );

            // Check if we've reached the end (count == 0)
            if resp_count == 0 {
                debug!("Reached end of history (count=0)");
                break;
            }

            // Parse data values and decide what to request next
            let data = &response[10..];
            match apply_v2_packet(
                &mut values,
                current_idx,
                end_idx,
                resp_start,
                resp_count,
                data,
                value_size,
                &value_parser,
            ) {
                PacketProgress::Done => {
                    on_progress(values.len());
                    debug!("Reached end of requested range");
                    break;
                }
                PacketProgress::Continue(next_idx) => {
                    consecutive_stalls = 0;
                    current_idx = next_idx;
                    debug!(
                        "Downloaded {} values, next index: {}",
                        values.len(),
                        current_idx
                    );
                    on_progress(values.len());
                }
                PacketProgress::Stalled => {
                    consecutive_stalls += 1;
                    warn!(
                        "History packet for {:?} made no progress at index {} (retry {}/{})",
                        param, current_idx, consecutive_stalls, MAX_STALLED_PACKETS
                    );
                    if consecutive_stalls >= MAX_STALLED_PACKETS {
                        return Err(Error::InvalidData(format!(
                            "History download for {param:?} stalled at index {current_idx}"
                        )));
                    }
                    sleep(read_delay).await;
                }
            }
        }

        // Convert to ordered vector (BTreeMap already maintains order)
        Ok(values.into_values().collect())
    }

    /// Download a single parameter's history using V2 protocol (u16 values) with progress.
    async fn download_param_history_with_progress<F>(
        &self,
        param: HistoryParam,
        start_idx: u16,
        end_idx: u16,
        read_delay: Duration,
        on_progress: F,
    ) -> Result<Vec<u16>>
    where
        F: FnMut(usize),
    {
        let value_size = if param == HistoryParam::Humidity {
            1
        } else {
            2
        };

        self.download_param_history_generic_with_progress(
            param,
            start_idx,
            end_idx,
            read_delay,
            |data, i| {
                if param == HistoryParam::Humidity {
                    data.get(i).map(|&b| b as u16)
                } else {
                    let offset = i * 2;
                    if offset + 1 < data.len() {
                        Some(u16::from_le_bytes([data[offset], data[offset + 1]]))
                    } else {
                        None
                    }
                }
            },
            value_size,
            on_progress,
        )
        .await
    }

    /// Download a single parameter's history using V2 protocol (u32 values) with progress.
    async fn download_param_history_u32_with_progress<F>(
        &self,
        param: HistoryParam,
        start_idx: u16,
        end_idx: u16,
        read_delay: Duration,
        on_progress: F,
    ) -> Result<Vec<u32>>
    where
        F: FnMut(usize),
    {
        self.download_param_history_generic_with_progress(
            param,
            start_idx,
            end_idx,
            read_delay,
            |data, i| {
                let offset = i * 4;
                if offset + 3 < data.len() {
                    Some(u32::from_le_bytes([
                        data[offset],
                        data[offset + 1],
                        data[offset + 2],
                        data[offset + 3],
                    ]))
                } else {
                    None
                }
            },
            4,
            on_progress,
        )
        .await
    }

    /// Download history using V1 protocol (notification-based).
    ///
    /// This is used for older devices that don't support the V2 read-based protocol.
    /// V1 uses notifications on the HISTORY_V1 characteristic.
    pub async fn download_history_v1(&self) -> Result<Vec<HistoryRecord>> {
        use crate::uuid::HISTORY_V1;
        use tokio::sync::mpsc;

        let info = self.get_history_info().await?;
        info!(
            "V1 download: {} readings, interval {}s",
            info.total_readings, info.interval_seconds
        );

        if info.total_readings == 0 {
            return Ok(Vec::new());
        }

        // Subscribe to notifications
        let (tx, mut rx) = mpsc::channel::<Vec<u8>>(256);

        // Set up notification handler
        self.subscribe_to_notifications(HISTORY_V1, move |data| {
            if let Err(e) = tx.try_send(data.to_vec()) {
                warn!(
                    "V1 history notification channel full or closed, data may be lost: {}",
                    e
                );
            }
        })
        .await?;

        // Request history for each parameter
        let mut co2_values = Vec::new();
        let mut temp_values = Vec::new();
        let mut pressure_values = Vec::new();
        let mut humidity_values = Vec::new();

        for param in [
            HistoryParam::Co2,
            HistoryParam::Temperature,
            HistoryParam::Pressure,
            HistoryParam::Humidity,
        ] {
            // Send V1 history request using command constant
            let cmd = [
                HISTORY_V1_REQUEST,
                param as u8,
                0x01,
                0x00,
                (info.total_readings & 0xFF) as u8,
                ((info.total_readings >> 8) & 0xFF) as u8,
            ];

            if let Err(e) = self.write_characteristic(COMMAND, &cmd).await {
                // The unsubscribe after the loop is skipped on this path; stop
                // the notification task here. The write error is the one to
                // report.
                let _ = self.unsubscribe_from_notifications(HISTORY_V1).await;
                return Err(e);
            }

            // Collect notifications until we have all values
            let mut values = Vec::new();
            let expected = info.total_readings as usize;

            let mut consecutive_timeouts = 0;
            const MAX_CONSECUTIVE_TIMEOUTS: u32 = 3;

            while values.len() < expected {
                match tokio::time::timeout(Duration::from_secs(5), rx.recv()).await {
                    Ok(Some(data)) => {
                        consecutive_timeouts = 0; // Reset on successful receive
                        // Parse notification data
                        if data.len() >= 3 {
                            let resp_param = data[0];
                            if resp_param == param as u8 {
                                let mut buf = &data[3..];
                                while buf.len() >= 2 && values.len() < expected {
                                    values.push(buf.get_u16_le());
                                }
                            }
                        }
                    }
                    Ok(None) => {
                        warn!(
                            "V1 history channel closed for {:?}: got {}/{} values",
                            param,
                            values.len(),
                            expected
                        );
                        break;
                    }
                    Err(_) => {
                        consecutive_timeouts += 1;
                        warn!(
                            "Timeout waiting for V1 history notification ({}/{}), {:?}: {}/{} values",
                            consecutive_timeouts,
                            MAX_CONSECUTIVE_TIMEOUTS,
                            param,
                            values.len(),
                            expected
                        );
                        if consecutive_timeouts >= MAX_CONSECUTIVE_TIMEOUTS {
                            warn!(
                                "Too many consecutive timeouts for {:?}, proceeding with partial data",
                                param
                            );
                            break;
                        }
                    }
                }
            }

            // Log if we got incomplete data
            if values.len() < expected {
                warn!(
                    "V1 history download incomplete for {:?}: got {}/{} values ({:.1}%)",
                    param,
                    values.len(),
                    expected,
                    (values.len() as f64 / expected as f64) * 100.0
                );
            }

            match param {
                HistoryParam::Co2 => co2_values = values,
                HistoryParam::Temperature => temp_values = values,
                HistoryParam::Pressure => pressure_values = values,
                HistoryParam::Humidity => humidity_values = values,
                // V1 protocol doesn't support radon or humidity2
                HistoryParam::Humidity2 | HistoryParam::Radon => {}
            }
        }

        // Unsubscribe from notifications
        self.unsubscribe_from_notifications(HISTORY_V1).await?;

        // Build history records
        let now = OffsetDateTime::now_utc();
        let latest_reading_time = now - time::Duration::seconds(info.seconds_since_update as i64);

        let mut records = Vec::new();
        let count = co2_values.len();

        // Warn if parameter arrays have mismatched lengths (partial download)
        if temp_values.len() != count
            || pressure_values.len() != count
            || humidity_values.len() != count
        {
            warn!(
                "V1 history arrays have mismatched lengths: co2={}, temp={}, pressure={}, humidity={} — \
                 records with missing values will use defaults",
                count,
                temp_values.len(),
                pressure_values.len(),
                humidity_values.len()
            );
        }

        for i in 0..count {
            let readings_ago = (count - 1 - i) as i64;
            let timestamp = latest_reading_time
                - time::Duration::seconds(readings_ago * info.interval_seconds as i64);

            let record = HistoryRecord {
                timestamp,
                co2: co2_values.get(i).copied().unwrap_or(0),
                temperature: raw_to_temperature(temp_values.get(i).copied().unwrap_or(0)),
                pressure: raw_to_pressure(pressure_values.get(i).copied().unwrap_or(0)),
                humidity: humidity_values.get(i).copied().unwrap_or(0) as u8,
                radon: None,
                radiation_rate: None,
                radiation_total: None,
            };
            records.push(record);
        }

        info!("V1 download complete: {} records", records.len());
        Ok(records)
    }
}

/// Outcome of applying one V2 history response packet.
#[derive(Debug, PartialEq, Eq)]
enum PacketProgress {
    /// More records remain; request the next packet starting at this index.
    Continue(u16),
    /// The packet reached `end_idx`; there is nothing more to request.
    Done,
    /// The packet did not move the download forward (stale repeat, or a
    /// count with no payload). The caller should retry, then give up.
    Stalled,
}

/// Store the values from one V2 history packet and decide what to request next.
///
/// `resp_start` and `resp_count` come from the packet header; `data` is the
/// payload after the 10-byte header. `end_idx` is inclusive.
#[allow(clippy::too_many_arguments)]
fn apply_v2_packet<T>(
    values: &mut BTreeMap<u16, T>,
    current_idx: u16,
    end_idx: u16,
    resp_start: u16,
    resp_count: usize,
    data: &[u8],
    value_size: usize,
    value_parser: &impl Fn(&[u8], usize) -> Option<T>,
) -> PacketProgress {
    let num_values = (data.len() / value_size).min(resp_count);
    if num_values == 0 {
        return PacketProgress::Stalled;
    }

    for i in 0..num_values {
        let Some(idx) = resp_start.checked_add(i as u16) else {
            break;
        };
        if idx > end_idx {
            break;
        }
        // A stale packet can start below the index we asked for. Keep only the
        // requested range: callers stamp element i as device index start_idx + i.
        if idx < current_idx {
            continue;
        }
        if let Some(value) = value_parser(data, i) {
            values.insert(idx, value);
        }
    }

    // Index of the last value carried by this packet (num_values >= 1).
    let last_idx = u32::from(resp_start) + num_values as u32 - 1;
    if last_idx >= u32::from(end_idx) {
        return PacketProgress::Done;
    }
    // last_idx < end_idx <= u16::MAX, so this fits in u16.
    let next_idx = (last_idx + 1) as u16;
    if next_idx <= current_idx {
        return PacketProgress::Stalled;
    }
    PacketProgress::Continue(next_idx)
}

/// Build history records from downloaded parameter arrays.
///
/// Element `i` of each array is the record at 1-based device index
/// `start_idx + i`; its timestamp comes from `anchor` for that index, so a
/// partial download (e.g. `end_index < total_readings`) keeps the device's
/// real record times instead of being stamped as the newest records.
///
/// For Aranet4: pass co2_values and empty radon_values.
/// For AranetRn+: pass empty co2_values and radon_values.
/// Humidity is converted differently based on whether radon_values is populated
/// (radon devices use Humidity2 encoding: tenths of a percent).
fn build_history_records(
    anchor: &HistoryAnchor,
    start_idx: u16,
    co2_values: &[u16],
    temp_values: &[u16],
    pressure_values: &[u16],
    humidity_values: &[u16],
    radon_values: &[u32],
) -> Vec<HistoryRecord> {
    let is_radon = !radon_values.is_empty();
    let is_aranet2 = co2_values.is_empty() && radon_values.is_empty();
    let count = if is_radon {
        radon_values.len()
    } else if is_aranet2 {
        temp_values.len()
    } else {
        co2_values.len()
    };

    // Warn if parameter arrays have mismatched lengths (partial download)
    let expected = count;
    if temp_values.len() != expected
        || pressure_values.len() != expected
        || humidity_values.len() != expected
    {
        warn!(
            "History arrays have mismatched lengths: primary={expected}, temp={}, pressure={}, humidity={} — \
             records with missing values will use defaults",
            temp_values.len(),
            pressure_values.len(),
            humidity_values.len()
        );
    }

    (0..count)
        .map(|i| {
            let timestamp = anchor.timestamp_for(u32::from(start_idx) + i as u32);

            let humidity = if is_radon || is_aranet2 {
                // Humidity2 is stored as tenths of a percent
                let raw = humidity_values.get(i).copied().unwrap_or(0);
                (raw / 10).min(100) as u8
            } else {
                humidity_values.get(i).copied().unwrap_or(0) as u8
            };

            HistoryRecord {
                timestamp,
                co2: if is_radon {
                    0
                } else {
                    co2_values.get(i).copied().unwrap_or(0)
                },
                temperature: raw_to_temperature(temp_values.get(i).copied().unwrap_or(0)),
                pressure: raw_to_pressure(pressure_values.get(i).copied().unwrap_or(0)),
                humidity,
                radon: if is_radon {
                    Some(radon_values.get(i).copied().unwrap_or(0))
                } else {
                    None
                },
                radiation_rate: None,
                radiation_total: None,
            }
        })
        .collect()
}

/// Convert raw temperature value to Celsius.
pub fn raw_to_temperature(raw: u16) -> f32 {
    raw as f32 / 20.0
}

/// Convert raw pressure value to hPa.
pub fn raw_to_pressure(raw: u16) -> f32 {
    raw as f32 / 10.0
}

// NOTE: The HistoryValueConverter trait was removed as it was dead code.
// Use the standalone functions raw_to_temperature, raw_to_pressure, etc. directly.

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

    // --- raw_to_temperature tests ---

    #[test]
    fn test_raw_to_temperature_typical_values() {
        // 22.5°C = 450 raw (450/20 = 22.5)
        assert!((raw_to_temperature(450) - 22.5).abs() < 0.001);

        // 20.0°C = 400 raw
        assert!((raw_to_temperature(400) - 20.0).abs() < 0.001);

        // 25.0°C = 500 raw
        assert!((raw_to_temperature(500) - 25.0).abs() < 0.001);
    }

    #[test]
    fn test_raw_to_temperature_edge_cases() {
        // 0°C = 0 raw
        assert!((raw_to_temperature(0) - 0.0).abs() < 0.001);

        // Very cold: -10°C would be negative, but raw is u16 so minimum is 0
        // Raw values represent actual temperature * 20

        // Very hot: 50°C = 1000 raw
        assert!((raw_to_temperature(1000) - 50.0).abs() < 0.001);

        // Maximum u16 would be 65535/20 = 3276.75°C (unrealistic but tests overflow handling)
        assert!((raw_to_temperature(u16::MAX) - 3276.75).abs() < 0.01);
    }

    #[test]
    fn test_raw_to_temperature_precision() {
        // Test fractional values
        // 22.55°C = 451 raw
        assert!((raw_to_temperature(451) - 22.55).abs() < 0.001);

        // 22.05°C = 441 raw
        assert!((raw_to_temperature(441) - 22.05).abs() < 0.001);
    }

    // --- raw_to_pressure tests ---

    #[test]
    fn test_raw_to_pressure_typical_values() {
        // 1013.2 hPa = 10132 raw
        assert!((raw_to_pressure(10132) - 1013.2).abs() < 0.01);

        // 1000.0 hPa = 10000 raw
        assert!((raw_to_pressure(10000) - 1000.0).abs() < 0.01);

        // 1050.0 hPa = 10500 raw
        assert!((raw_to_pressure(10500) - 1050.0).abs() < 0.01);
    }

    #[test]
    fn test_raw_to_pressure_edge_cases() {
        // 0 hPa = 0 raw
        assert!((raw_to_pressure(0) - 0.0).abs() < 0.01);

        // Low pressure: 950 hPa = 9500 raw
        assert!((raw_to_pressure(9500) - 950.0).abs() < 0.01);

        // High pressure: 1100 hPa = 11000 raw
        assert!((raw_to_pressure(11000) - 1100.0).abs() < 0.01);

        // Maximum u16 would be 65535/10 = 6553.5 hPa (unrealistic but tests bounds)
        assert!((raw_to_pressure(u16::MAX) - 6553.5).abs() < 0.1);
    }

    // --- HistoryParam tests ---

    #[test]
    fn test_history_param_values() {
        assert_eq!(HistoryParam::Temperature as u8, 1);
        assert_eq!(HistoryParam::Humidity as u8, 2);
        assert_eq!(HistoryParam::Pressure as u8, 3);
        assert_eq!(HistoryParam::Co2 as u8, 4);
    }

    #[test]
    fn test_history_param_debug() {
        assert_eq!(format!("{:?}", HistoryParam::Temperature), "Temperature");
        assert_eq!(format!("{:?}", HistoryParam::Co2), "Co2");
    }

    // --- HistoryOptions tests ---

    #[test]
    fn test_history_options_default() {
        let options = HistoryOptions::default();

        assert!(options.start_index.is_none());
        assert!(options.end_index.is_none());
        assert_eq!(options.read_delay, Duration::from_millis(50));
    }

    #[test]
    fn test_history_options_custom() {
        let options = HistoryOptions::new()
            .start_index(10)
            .end_index(100)
            .read_delay(Duration::from_millis(100));

        assert_eq!(options.start_index, Some(10));
        assert_eq!(options.end_index, Some(100));
        assert_eq!(options.read_delay, Duration::from_millis(100));
    }

    #[test]
    fn test_history_options_with_progress() {
        use std::sync::Arc;
        use std::sync::atomic::{AtomicUsize, Ordering};

        let call_count = Arc::new(AtomicUsize::new(0));
        let call_count_clone = Arc::clone(&call_count);

        let options = HistoryOptions::new().with_progress(move |_progress| {
            call_count_clone.fetch_add(1, Ordering::SeqCst);
        });

        assert!(options.progress_callback.is_some());

        // Test that the callback can be invoked
        let progress = HistoryProgress::new(HistoryParam::Co2, 1, 4, 100);
        options.report_progress(&progress);
        assert_eq!(call_count.load(Ordering::SeqCst), 1);
    }

    // --- HistoryInfo tests ---

    #[test]
    fn test_history_info_creation() {
        let info = HistoryInfo {
            total_readings: 1000,
            interval_seconds: 300,
            seconds_since_update: 120,
        };

        assert_eq!(info.total_readings, 1000);
        assert_eq!(info.interval_seconds, 300);
        assert_eq!(info.seconds_since_update, 120);
    }

    #[test]
    fn test_history_info_debug() {
        let info = HistoryInfo {
            total_readings: 500,
            interval_seconds: 60,
            seconds_since_update: 30,
        };

        let debug_str = format!("{:?}", info);
        assert!(debug_str.contains("total_readings"));
        assert!(debug_str.contains("500"));
    }

    // --- apply_v2_packet tests ---

    fn parse_u16(data: &[u8], i: usize) -> Option<u16> {
        data.get(i * 2..i * 2 + 2)
            .map(|b| u16::from_le_bytes([b[0], b[1]]))
    }

    fn u16_payload(values: &[u16]) -> Vec<u8> {
        values.iter().flat_map(|v| v.to_le_bytes()).collect()
    }

    #[test]
    fn test_apply_v2_packet_does_not_stop_one_record_early() {
        let mut values = BTreeMap::new();
        let payload = u16_payload(&(1..=99).collect::<Vec<u16>>());
        let progress = apply_v2_packet(&mut values, 1, 100, 1, 99, &payload, 2, &parse_u16);
        assert_eq!(progress, PacketProgress::Continue(100));
        assert_eq!(values.len(), 99);
    }

    #[test]
    fn test_apply_v2_packet_done_after_last_index() {
        let mut values = BTreeMap::new();
        let payload = u16_payload(&[42]);
        let progress = apply_v2_packet(&mut values, 100, 100, 100, 1, &payload, 2, &parse_u16);
        assert_eq!(progress, PacketProgress::Done);
        assert_eq!(values.get(&100), Some(&42));
    }

    #[test]
    fn test_apply_v2_packet_ignores_values_past_end() {
        let mut values = BTreeMap::new();
        let payload = u16_payload(&[1, 2, 3, 4]);
        let progress = apply_v2_packet(&mut values, 9, 10, 9, 4, &payload, 2, &parse_u16);
        assert_eq!(progress, PacketProgress::Done);
        assert_eq!(values.keys().copied().collect::<Vec<_>>(), vec![9, 10]);
    }

    #[test]
    fn test_apply_v2_packet_count_without_payload_is_stalled() {
        let mut values: BTreeMap<u16, u16> = BTreeMap::new();
        let progress = apply_v2_packet(&mut values, 1, 100, 1, 5, &[], 2, &parse_u16);
        assert_eq!(progress, PacketProgress::Stalled);
    }

    #[test]
    fn test_apply_v2_packet_repeated_old_packet_is_stalled() {
        let mut values = BTreeMap::new();
        let payload = u16_payload(&[1, 2, 3]);
        // We asked for index 50; the device repeated the packet for 1..=3.
        let progress = apply_v2_packet(&mut values, 50, 100, 1, 3, &payload, 2, &parse_u16);
        assert_eq!(progress, PacketProgress::Stalled);
        // Values from below the requested range must not be kept: element i of
        // the downloaded array is stamped as device index start_idx + i.
        assert!(values.is_empty());
    }

    #[test]
    fn test_apply_v2_packet_same_packet_twice_is_stalled() {
        let mut values = BTreeMap::new();
        let payload = u16_payload(&[1, 2, 3]);
        let progress = apply_v2_packet(&mut values, 1, 100, 1, 3, &payload, 2, &parse_u16);
        assert_eq!(progress, PacketProgress::Continue(4));
        // Asked for index 4, the device sent the same packet (1..=3) again.
        let progress = apply_v2_packet(&mut values, 4, 100, 1, 3, &payload, 2, &parse_u16);
        assert_eq!(progress, PacketProgress::Stalled);
        assert_eq!(values.keys().copied().collect::<Vec<_>>(), vec![1, 2, 3]);
    }

    #[test]
    fn test_apply_v2_packet_drops_values_below_current_index() {
        let mut values = BTreeMap::new();
        let payload = u16_payload(&(1..=60).collect::<Vec<u16>>());
        // Asked for index 50; a stale packet starting at 1 overlaps the range.
        let progress = apply_v2_packet(&mut values, 50, 100, 1, 60, &payload, 2, &parse_u16);
        assert_eq!(progress, PacketProgress::Continue(61));
        assert_eq!(
            values.keys().copied().collect::<Vec<_>>(),
            (50..=60).collect::<Vec<u16>>()
        );
        assert_eq!(values.get(&50), Some(&50));
    }

    #[test]
    fn test_apply_v2_packet_stale_packet_past_end_keeps_only_requested_range() {
        let mut values = BTreeMap::new();
        let payload = u16_payload(&(1..=117).collect::<Vec<u16>>());
        let progress = apply_v2_packet(&mut values, 50, 55, 1, 117, &payload, 2, &parse_u16);
        assert_eq!(progress, PacketProgress::Done);
        assert_eq!(
            values.keys().copied().collect::<Vec<_>>(),
            (50..=55).collect::<Vec<u16>>()
        );
    }

    #[test]
    fn test_apply_v2_packet_near_u16_max_does_not_overflow() {
        let mut values = BTreeMap::new();
        let payload = u16_payload(&[1, 2, 3, 4, 5]);
        let progress = apply_v2_packet(
            &mut values,
            65534,
            u16::MAX,
            65534,
            5,
            &payload,
            2,
            &parse_u16,
        );
        assert_eq!(progress, PacketProgress::Done);
        assert_eq!(values.len(), 2);
    }

    // --- HistoryAnchor / build_history_records timestamp tests ---

    fn anchor_fixture(total: u16, interval: u16, ago: u16) -> (HistoryAnchor, OffsetDateTime) {
        let read_at = OffsetDateTime::from_unix_timestamp(1_700_000_000).unwrap();
        let info = HistoryInfo {
            total_readings: total,
            interval_seconds: interval,
            seconds_since_update: ago,
        };
        (HistoryAnchor::new(&info, read_at), read_at)
    }

    #[test]
    fn test_history_anchor_newest_record_time() {
        let (anchor, read_at) = anchor_fixture(100, 600, 120);
        assert_eq!(
            anchor.timestamp_for(100),
            read_at - time::Duration::seconds(120)
        );
        assert_eq!(
            anchor.timestamp_for(99),
            read_at - time::Duration::seconds(120 + 600)
        );
    }

    #[test]
    fn test_build_history_records_timestamps_follow_device_indices() {
        // Downloading only the three OLDEST records of a 1000-record buffer must
        // stamp them ~999 intervals ago, not as the newest three.
        let (anchor, read_at) = anchor_fixture(1000, 600, 120);
        let records = build_history_records(
            &anchor,
            1,
            &[800, 810, 820],
            &[450; 3],
            &[10130; 3],
            &[45; 3],
            &[],
        );
        let newest = read_at - time::Duration::seconds(120);
        assert_eq!(records.len(), 3);
        assert_eq!(
            records[0].timestamp,
            newest - time::Duration::seconds(999 * 600)
        );
        assert_eq!(
            records[2].timestamp,
            newest - time::Duration::seconds(997 * 600)
        );
    }

    #[test]
    fn test_build_history_records_newest_record_matches_anchor() {
        let (anchor, read_at) = anchor_fixture(1000, 600, 120);
        let records = build_history_records(
            &anchor,
            998,
            &[800, 810, 820],
            &[450; 3],
            &[10130; 3],
            &[45; 3],
            &[],
        );
        assert_eq!(records[2].timestamp, read_at - time::Duration::seconds(120));
    }
}