umsh_ux_tracker/

led.rs

//! LED sequence engine.
//!
//! Owns the heartbeat (always-on; never suppressed) and arbitrates
//! one-shot sequences layered on top: power-on, power-off, location
//! advert.
//!
//! Pure logic over a monotonic-millisecond clock. The engine reports the
//! LED state to apply *right now* and the absolute time at which the
//! caller should re-invoke [`LedEngine::tick`] for the next transition.
//! No async, no I/O — fully unit-testable with synthetic time.
//!
//! # Heartbeat semantics
//!
//! The heartbeat is anchored at the engine's start time. After every
//! `heartbeat_interval`, the LED pulses for `heartbeat_pulse` (defaults:
//! 2 s and 50 ms). When a one-shot sequence is active it preempts the
//! heartbeat for the sequence's duration; once the sequence completes
//! the heartbeat resumes on its original rhythm (i.e. it is *not*
//! re-anchored), so the user-perceived 2-second cadence stays consistent
//! across overlays.

use core::time::Duration;

use crate::battery::BatteryState;

/// A one-shot LED flash sequence.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum LedSequence {
    /// One short flash confirming an accepted local action.
    ActionConfirm,
    /// 1 s on at boot.
    PowerOn,
    /// Three short flashes just before System OFF.
    PowerOff,
    /// Quick double-blink on outgoing location advert.
    LocationAdvert,
    /// The GNSS receiver was switched on: two pips resolving into a
    /// long hold.
    GnssOn,
    /// The GNSS receiver was switched off: a long hold breaking into
    /// two pips — the mirror of [`GnssOn`](Self::GnssOn).
    GnssOff,
}

impl LedSequence {
    fn pattern(self) -> &'static Pattern {
        match self {
            Self::ActionConfirm => &patterns::ACTION_CONFIRM,
            Self::PowerOn => &patterns::POWER_ON,
            Self::PowerOff => &patterns::POWER_OFF,
            Self::LocationAdvert => &patterns::LOCATION_ADVERT,
            Self::GnssOn => &patterns::GNSS_ON,
            Self::GnssOff => &patterns::GNSS_OFF,
        }
    }
}

/// Tunable heartbeat timings.
#[derive(Debug, Clone, Copy)]
pub struct LedTimings {
    pub heartbeat_interval: Duration,
    pub heartbeat_pulse: Duration,
}

impl Default for LedTimings {
    fn default() -> Self {
        Self {
            heartbeat_interval: Duration::from_millis(4_000),
            heartbeat_pulse: Duration::from_millis(20),
        }
    }
}

/// The result of a [`LedEngine::tick`]: the LED state to apply now and
/// the absolute monotonic-millisecond deadline at which to tick again.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct LedDecision {
    pub on: bool,
    pub next_deadline_ms: u64,
}

/// PWM brightness decision for the T1000-E's state-aware indicator.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct BrightnessDecision {
    /// Linear brightness in the inclusive range 0..=1000.
    pub brightness: u16,
    pub next_deadline_ms: u64,
}

/// Illuminance at or above which the indicator runs at full brightness:
/// 10 lux, in millilux.
pub const DIM_FULL_MLUX: u32 = 10_000;

/// The dimming floor, in permille of normal brightness: 1/20th. Reached
/// at zero illuminance.
pub const DIM_MIN_PERMILLE: u16 = 50;

/// Ambient dimming scale, in permille of normal brightness: 1000 at or
/// above [`DIM_FULL_MLUX`], falling linearly to [`DIM_MIN_PERMILLE`] at
/// zero. `None` — no reading yet — is full brightness, so a board whose
/// sensor never answers keeps its ordinary indicator.
///
/// A free function rather than an engine method so writers that bypass
/// the engine (the firmware's BLE status blink) and future consumers of
/// ambient light apply the same curve.
pub fn ambient_dim_permille(millilux: Option<u32>) -> u16 {
    let Some(millilux) = millilux else {
        return 1_000;
    };
    if millilux >= DIM_FULL_MLUX {
        return 1_000;
    }
    let span = u32::from(1_000 - DIM_MIN_PERMILLE);
    (u32::from(DIM_MIN_PERMILLE) + span * millilux / DIM_FULL_MLUX) as u16
}

/// Scale a decision's brightness by the ambient dim factor. Deadlines
/// are untouched: dimming changes how bright a phase is, never when the
/// next one starts.
fn dim_decision(decision: BrightnessDecision, dim_permille: u16) -> BrightnessDecision {
    BrightnessDecision {
        brightness: ((u32::from(decision.brightness) * u32::from(dim_permille)) / 1_000) as u16,
        next_deadline_ms: decision.next_deadline_ms,
    }
}

/// Scale a binary pulse's duration by the ambient dim factor, floored at
/// one millisecond so the pulse never disappears entirely.
///
/// The heartbeat dims by *shortening* rather than by duty: a brief
/// full-brightness tick stays legible as a heartbeat in the dark, where
/// the same energy spread over 20 ms would read as a dim smudge.
fn dim_pulse_ms(pulse_ms: u64, dim_permille: u16) -> u64 {
    (pulse_ms * u64::from(dim_permille) / 1_000).max(1)
}

/// State-aware T1000-E LED policy. One-shot confirmations preempt persistent
/// state; Charging and Low Battery preempt Attention; Attention replaces only
/// the ordinary heartbeat.
#[derive(Debug)]
pub struct T1000eLedEngine {
    timings: LedTimings,
    heartbeat_anchor_ms: u64,
    battery: BatteryState,
    attention: bool,
    /// Most recent ambient light reading, for [`ambient_dim_permille`];
    /// `None` until one exists.
    ambient_millilux: Option<u32>,
    active: Option<ActiveSequence>,
    /// A running locate alert; see [`LedEngine::start_alert`].
    alert_since_ms: Option<u64>,
}

impl T1000eLedEngine {
    pub fn new(start_ms: u64) -> Self {
        Self {
            timings: LedTimings::default(),
            heartbeat_anchor_ms: start_ms,
            battery: BatteryState::BatteryOnly,
            attention: false,
            ambient_millilux: None,
            active: None,
            alert_since_ms: None,
        }
    }

    /// Start the locate alert. Idempotent, like [`LedEngine::start_alert`].
    pub fn start_alert(&mut self, now_ms: u64) {
        if self.alert_since_ms.is_none() {
            self.alert_since_ms = Some(now_ms);
        }
    }

    /// Stop the locate alert.
    pub fn stop_alert(&mut self) {
        self.alert_since_ms = None;
    }

    /// Whether the locate alert is running.
    pub fn alert_active(&self) -> bool {
        self.alert_since_ms.is_some()
    }

    pub fn set_battery(&mut self, battery: BatteryState) {
        self.battery = battery;
    }

    pub fn set_attention(&mut self, attention: bool) {
        self.attention = attention;
    }

    /// Feed the most recent ambient light reading. Everything the engine
    /// shows except the locate alert dims with it — the alert stays at
    /// full brightness because a radio being searched for values being
    /// seen over being comfortable, the same priority that lets it
    /// outrank the critical-battery blackout.
    pub fn set_ambient_millilux(&mut self, millilux: Option<u32>) {
        self.ambient_millilux = millilux;
    }

    pub fn play(&mut self, sequence: LedSequence, now_ms: u64) {
        self.active = Some(ActiveSequence {
            pattern: sequence.pattern(),
            started_at_ms: now_ms,
        });
    }

    pub fn tick(&mut self, now_ms: u64) -> BrightnessDecision {
        // The alert outranks every other LED duty, including the
        // battery-critical blackout: a radio being searched for shows
        // itself while it still has the charge to.
        if let Some(started_at_ms) = self.alert_since_ms {
            let elapsed = now_ms.saturating_sub(started_at_ms);
            let cycle_start_ms = now_ms - (elapsed % LedEngine::ALERT_PERIOD_MS);
            let blink = ActiveSequence {
                pattern: &patterns::LOCATE,
                started_at_ms: cycle_start_ms,
            };
            return match blink.resolve(now_ms) {
                Some((on, deadline)) => BrightnessDecision {
                    brightness: if on { 1_000 } else { 0 },
                    next_deadline_ms: deadline,
                },
                None => BrightnessDecision {
                    brightness: 0,
                    next_deadline_ms: cycle_start_ms + LedEngine::ALERT_PERIOD_MS,
                },
            };
        }
        let dim = ambient_dim_permille(self.ambient_millilux);
        if let Some(sequence) = &self.active {
            if let Some((on, deadline)) = sequence.resolve(now_ms) {
                return dim_decision(
                    BrightnessDecision {
                        brightness: if on { 1_000 } else { 0 },
                        next_deadline_ms: deadline,
                    },
                    dim,
                );
            }
            self.active = None;
        }

        // The binary heartbeats dim by pulse duration (see
        // [`dim_pulse_ms`]); everything else is a shape whose meaning
        // lives in its envelope, so those dim by brightness.
        match self.battery {
            BatteryState::BatteryCharging => dim_decision(breathing(now_ms, 3_000, 20), dim),
            BatteryState::BatteryLow => {
                dim_decision(low_battery(now_ms, self.heartbeat_anchor_ms, 4_000), dim)
            }
            BatteryState::BatteryCritical => BrightnessDecision {
                brightness: 0,
                next_deadline_ms: now_ms.saturating_add(1_000),
            },
            BatteryState::BatteryOnly | BatteryState::BatteryCharged if self.attention => {
                dim_decision(
                    attention_pulse(
                        now_ms,
                        self.heartbeat_anchor_ms,
                        self.timings.heartbeat_interval.as_millis() as u64,
                    ),
                    dim,
                )
            }
            BatteryState::BatteryCharged => binary_heartbeat(
                now_ms,
                self.heartbeat_anchor_ms,
                self.timings.heartbeat_interval.as_millis() as u64,
                dim_pulse_ms(60, dim),
            ),
            BatteryState::BatteryOnly => binary_heartbeat(
                now_ms,
                self.heartbeat_anchor_ms,
                self.timings.heartbeat_interval.as_millis() as u64,
                dim_pulse_ms(self.timings.heartbeat_pulse.as_millis() as u64, dim),
            ),
        }
    }
}

fn breathing(now_ms: u64, cycle_ms: u64, step_ms: u64) -> BrightnessDecision {
    let phase = now_ms % cycle_ms;
    let half = cycle_ms / 2;
    let ramp = if phase < half {
        phase
    } else {
        cycle_ms - phase
    };
    BrightnessDecision {
        brightness: ((1_000 * ramp) / half) as u16,
        next_deadline_ms: now_ms.saturating_add(step_ms),
    }
}

fn attention_pulse(now_ms: u64, anchor_ms: u64, interval_ms: u64) -> BrightnessDecision {
    const PULSE_MS: u64 = 300;
    const STEP_MS: u64 = 10;
    let elapsed = now_ms.saturating_sub(anchor_ms);
    let phase = elapsed % interval_ms;
    let cycle_start = now_ms - phase;
    if phase >= PULSE_MS {
        return BrightnessDecision {
            brightness: 0,
            next_deadline_ms: cycle_start + interval_ms,
        };
    }
    let half = PULSE_MS / 2;
    let ramp = if phase < half {
        phase
    } else {
        PULSE_MS - phase
    };
    BrightnessDecision {
        brightness: ((1_000 * ramp) / half) as u16,
        next_deadline_ms: (now_ms + STEP_MS).min(cycle_start + PULSE_MS),
    }
}

fn low_battery(now_ms: u64, anchor_ms: u64, interval_ms: u64) -> BrightnessDecision {
    let elapsed = now_ms.saturating_sub(anchor_ms);
    let phase = elapsed % interval_ms;
    let cycle_start = now_ms - phase;
    let (on, boundary) = match phase {
        0..100 => (true, 100),
        100..200 => (false, 200),
        200..300 => (true, 300),
        _ => (false, interval_ms),
    };
    BrightnessDecision {
        brightness: if on { 1_000 } else { 0 },
        next_deadline_ms: cycle_start + boundary,
    }
}

fn binary_heartbeat(
    now_ms: u64,
    anchor_ms: u64,
    interval_ms: u64,
    pulse_ms: u64,
) -> BrightnessDecision {
    let elapsed = now_ms.saturating_sub(anchor_ms);
    let phase = elapsed % interval_ms;
    let cycle_start = now_ms - phase;
    if phase < pulse_ms {
        BrightnessDecision {
            brightness: 1_000,
            next_deadline_ms: cycle_start + pulse_ms,
        }
    } else {
        BrightnessDecision {
            brightness: 0,
            next_deadline_ms: cycle_start + interval_ms,
        }
    }
}

/// A pre-computed LED pattern. `steps` is an alternating list of
/// durations starting with the ON phase: `[on_0, off_0, on_1, off_1, ...]`.
#[derive(Debug)]
pub struct Pattern {
    steps: &'static [Duration],
}

mod patterns {
    use super::Pattern;
    use core::time::Duration;

    pub static ACTION_CONFIRM: Pattern = Pattern {
        steps: &[Duration::from_millis(100)],
    };

    pub static POWER_ON: Pattern = Pattern {
        steps: &[Duration::from_millis(1_000)],
    };

    /// Three flashes: ON 100, OFF 100, ON 100, OFF 100, ON 100.
    pub static POWER_OFF: Pattern = Pattern {
        steps: &[
            Duration::from_millis(100),
            Duration::from_millis(100),
            Duration::from_millis(100),
            Duration::from_millis(100),
            Duration::from_millis(100),
        ],
    };

    /// Quick double-blink: ON 50, OFF 50, ON 50.
    pub static LOCATION_ADVERT: Pattern = Pattern {
        steps: &[
            Duration::from_millis(50),
            Duration::from_millis(50),
            Duration::from_millis(50),
        ],
    };

    /// Receiver switched on: ON 60, OFF 60, ON 60, OFF 60, ON 500.
    ///
    /// The long segment lands *last*, which is the whole design: at a
    /// glance the operator reads where the light lingers, and a switch
    /// whose two directions differ only in tempo would be a switch
    /// nobody can read in daylight from a jacket pocket.
    pub static GNSS_ON: Pattern = Pattern {
        steps: &[
            Duration::from_millis(60),
            Duration::from_millis(60),
            Duration::from_millis(60),
            Duration::from_millis(60),
            Duration::from_millis(500),
        ],
    };

    /// Receiver switched off: ON 500, OFF 60, ON 60, OFF 60, ON 60 —
    /// [`GNSS_ON`] played backwards, so the light dies away rather than
    /// settling.
    pub static GNSS_OFF: Pattern = Pattern {
        steps: &[
            Duration::from_millis(500),
            Duration::from_millis(60),
            Duration::from_millis(60),
            Duration::from_millis(60),
            Duration::from_millis(60),
        ],
    };

    /// Locate alert: an urgent triple-blink, replayed on a period by
    /// [`LedEngine::start_alert`](super::LedEngine::start_alert). On a
    /// board with no buzzer this *is* the alert, so it is deliberately
    /// brighter and busier than any other sequence.
    pub static LOCATE: Pattern = Pattern {
        steps: &[
            Duration::from_millis(120),
            Duration::from_millis(120),
            Duration::from_millis(120),
            Duration::from_millis(120),
            Duration::from_millis(120),
        ],
    };
}

#[derive(Debug)]
struct ActiveSequence {
    pattern: &'static Pattern,
    started_at_ms: u64,
}

impl ActiveSequence {
    /// Resolve the current step. Returns `Some((on, end_of_step_ms))` if
    /// the sequence is still running, `None` if it has completed.
    fn resolve(&self, now_ms: u64) -> Option<(bool, u64)> {
        let elapsed = now_ms.saturating_sub(self.started_at_ms);
        let mut cumulative_ms: u64 = 0;
        let mut state = true; // patterns start with ON
        for step in self.pattern.steps {
            cumulative_ms = cumulative_ms.saturating_add(step.as_millis() as u64);
            if elapsed < cumulative_ms {
                return Some((state, self.started_at_ms + cumulative_ms));
            }
            state = !state;
        }
        None
    }
}

/// LED sequence engine.
#[derive(Debug)]
pub struct LedEngine {
    timings: LedTimings,
    heartbeat_anchor_ms: u64,
    active: Option<ActiveSequence>,
    /// When a locate alert started, if one is running. Outranks both the
    /// one-shot sequences and the heartbeat, and repeats until stopped:
    /// on a board with no buzzer this is the whole alert.
    alert_since_ms: Option<u64>,
}

impl LedEngine {
    /// Create a new engine anchored at `start_ms`. The first heartbeat
    /// pulse begins at `start_ms`.
    pub fn new(timings: LedTimings, start_ms: u64) -> Self {
        Self {
            timings,
            heartbeat_anchor_ms: start_ms,
            active: None,
            alert_since_ms: None,
        }
    }

    /// An engine for an indicator that idles **dark**: no heartbeat, only
    /// the locate alert and one-shot sequences.
    ///
    /// For a board with two LEDs, where one carries the "this board is
    /// alive and here is its link state" story and the other is reserved
    /// for the things meant to catch an eye. A second heartbeat would
    /// only compete with the first.
    ///
    /// Implemented as a zero-length heartbeat pulse, which
    /// [`heartbeat_decision`](Self::heartbeat_decision) resolves to
    /// permanently off. The interval then only sets how often the loop
    /// wakes to find nothing to do, so it is long.
    pub fn attention_only(start_ms: u64) -> Self {
        Self::new(
            LedTimings {
                heartbeat_interval: Duration::from_secs(60),
                heartbeat_pulse: Duration::ZERO,
            },
            start_ms,
        )
    }

    /// How often the locate blink repeats.
    const ALERT_PERIOD_MS: u64 = 1_500;

    /// Start the locate alert. Idempotent: re-starting a running alert
    /// keeps its existing rhythm rather than restarting the blink, so a
    /// host re-arming the deadline does not produce a visible stutter.
    pub fn start_alert(&mut self, now_ms: u64) {
        if self.alert_since_ms.is_none() {
            self.alert_since_ms = Some(now_ms);
        }
    }

    /// Stop the locate alert, returning the LED to sequences and the
    /// heartbeat.
    pub fn stop_alert(&mut self) {
        self.alert_since_ms = None;
    }

    /// Whether the locate alert is running.
    pub fn alert_active(&self) -> bool {
        self.alert_since_ms.is_some()
    }

    /// Start a one-shot sequence, preempting any currently active
    /// sequence and any in-progress heartbeat pulse.
    pub fn play(&mut self, seq: LedSequence, now_ms: u64) {
        self.active = Some(ActiveSequence {
            pattern: seq.pattern(),
            started_at_ms: now_ms,
        });
    }

    /// Compute the LED state to apply at `now_ms` and the next deadline.
    pub fn tick(&mut self, now_ms: u64) -> LedDecision {
        // The alert outranks everything: someone is looking for this
        // board right now.
        if let Some(started_at_ms) = self.alert_since_ms {
            let elapsed = now_ms.saturating_sub(started_at_ms);
            let cycle_start_ms = now_ms - (elapsed % Self::ALERT_PERIOD_MS);
            let blink = ActiveSequence {
                pattern: &patterns::LOCATE,
                started_at_ms: cycle_start_ms,
            };
            return match blink.resolve(now_ms) {
                Some((on, end_ms)) => LedDecision {
                    on,
                    next_deadline_ms: end_ms,
                },
                // Past the blink: dark until the next period.
                None => LedDecision {
                    on: false,
                    next_deadline_ms: cycle_start_ms + Self::ALERT_PERIOD_MS,
                },
            };
        }
        if let Some(seq) = &self.active {
            if let Some((on, end_ms)) = seq.resolve(now_ms) {
                return LedDecision {
                    on,
                    next_deadline_ms: end_ms,
                };
            }
            self.active = None;
        }
        self.heartbeat_decision(now_ms)
    }

    fn heartbeat_decision(&self, now_ms: u64) -> LedDecision {
        let interval = self.timings.heartbeat_interval.as_millis() as u64;
        let pulse = self.timings.heartbeat_pulse.as_millis() as u64;
        debug_assert!(pulse < interval, "heartbeat pulse must fit inside interval");

        let elapsed = now_ms.saturating_sub(self.heartbeat_anchor_ms);
        let cycle_start = now_ms - (elapsed % interval);
        let phase = elapsed % interval;

        // A zero-length pulse is never entered, which is what makes
        // `attention_only` idle dark.
        if phase < pulse {
            LedDecision {
                on: true,
                next_deadline_ms: cycle_start + pulse,
            }
        } else {
            LedDecision {
                on: false,
                next_deadline_ms: cycle_start + interval,
            }
        }
    }
}

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

    /// Engine with fixed test timings (2 s interval, 50 ms pulse).
    ///
    /// Deliberately *not* `LedTimings::default()`: every assertion below
    /// hardcodes deadlines derived from these numbers, and the product
    /// defaults are tuning knobs that have changed before (2000/50 →
    /// 4000/20 in commit 65d8d4e6, which silently broke this module's
    /// tests). Pinning the timings here keeps the tests about the engine's
    /// *logic*, not the current tuning.
    fn engine(start: u64) -> LedEngine {
        LedEngine::new(
            LedTimings {
                heartbeat_interval: Duration::from_millis(2_000),
                heartbeat_pulse: Duration::from_millis(50),
            },
            start,
        )
    }

    #[test]
    fn heartbeat_starts_on_at_anchor() {
        let mut e = engine(0);
        let d = e.tick(0);
        assert_eq!(
            d,
            LedDecision {
                on: true,
                next_deadline_ms: 50
            }
        );
    }

    #[test]
    fn heartbeat_turns_off_after_pulse() {
        let mut e = engine(0);
        let d = e.tick(50);
        assert_eq!(
            d,
            LedDecision {
                on: false,
                next_deadline_ms: 2_000
            }
        );
    }

    #[test]
    fn heartbeat_pulses_at_regular_interval() {
        let mut e = engine(0);
        // First pulse.
        assert_eq!(e.tick(0).on, true);
        assert_eq!(e.tick(49).on, true);
        // Off gap.
        assert_eq!(e.tick(50).on, false);
        assert_eq!(e.tick(1_999).on, false);
        // Second pulse.
        let d = e.tick(2_000);
        assert_eq!(
            d,
            LedDecision {
                on: true,
                next_deadline_ms: 2_050
            }
        );
        // Off.
        let d = e.tick(2_050);
        assert_eq!(
            d,
            LedDecision {
                on: false,
                next_deadline_ms: 4_000
            }
        );
    }

    #[test]
    fn heartbeat_handles_skipped_ticks() {
        // tick() should still return correct phase if called late.
        let mut e = engine(0);
        // Skip to mid-pulse of cycle 5: 5*2000 + 20 = 10_020.
        let d = e.tick(10_020);
        assert_eq!(
            d,
            LedDecision {
                on: true,
                next_deadline_ms: 10_050
            }
        );

        // Skip to mid-gap of cycle 7: 7*2000 + 500 = 14_500.
        let d = e.tick(14_500);
        assert_eq!(
            d,
            LedDecision {
                on: false,
                next_deadline_ms: 16_000
            }
        );
    }

    #[test]
    fn power_on_sequence_holds_for_one_second() {
        let mut e = engine(0);
        e.play(LedSequence::PowerOn, 100);
        // During the sequence: ON until 100 + 1000 = 1100.
        assert_eq!(
            e.tick(100),
            LedDecision {
                on: true,
                next_deadline_ms: 1_100
            }
        );
        assert_eq!(
            e.tick(500),
            LedDecision {
                on: true,
                next_deadline_ms: 1_100
            }
        );
        assert_eq!(
            e.tick(1_099),
            LedDecision {
                on: true,
                next_deadline_ms: 1_100
            }
        );
    }

    #[test]
    fn power_on_sequence_releases_to_heartbeat() {
        let mut e = engine(0);
        e.play(LedSequence::PowerOn, 100);
        // After the sequence: heartbeat. At t=1100, we're in cycle 0's
        // off-gap (since first pulse was 0..50). Next ON is 2000.
        let d = e.tick(1_100);
        assert_eq!(
            d,
            LedDecision {
                on: false,
                next_deadline_ms: 2_000
            }
        );
    }

    #[test]
    fn power_off_sequence_flashes_three_times() {
        // ON 100, OFF 100, ON 100, OFF 100, ON 100.
        let mut e = engine(0);
        e.play(LedSequence::PowerOff, 0);
        assert_eq!(e.tick(0).on, true); // start of 1st ON
        assert_eq!(e.tick(99).on, true);
        assert_eq!(e.tick(100).on, false); // 1st OFF
        assert_eq!(e.tick(199).on, false);
        assert_eq!(e.tick(200).on, true); // 2nd ON
        assert_eq!(e.tick(299).on, true);
        assert_eq!(e.tick(300).on, false); // 2nd OFF
        assert_eq!(e.tick(399).on, false);
        assert_eq!(e.tick(400).on, true); // 3rd ON
        assert_eq!(e.tick(499).on, true);
        // After 500ms, sequence done → heartbeat. At t=500 we're past
        // the heartbeat ON pulse (0..50), in the off-gap → false.
        assert_eq!(e.tick(500).on, false);
    }

    #[test]
    fn sequence_preempts_in_progress_heartbeat_pulse() {
        // Engine anchored at 0; heartbeat would be ON at t=2000..2050.
        // Request location advert at t=2010 (during a heartbeat pulse).
        // The sequence takes over immediately (ON for 50ms).
        let mut e = engine(0);
        // Confirm heartbeat is currently ON.
        assert_eq!(e.tick(2_010).on, true);
        e.play(LedSequence::LocationAdvert, 2_010);
        let d = e.tick(2_010);
        assert_eq!(
            d,
            LedDecision {
                on: true,
                next_deadline_ms: 2_060
            }
        );
    }

    #[test]
    fn heartbeat_rhythm_preserved_across_sequence() {
        // Heartbeat ON expected at t=2000, 4000, 6000, ...
        let mut e = engine(0);
        e.play(LedSequence::PowerOn, 100); // 1s sequence
        // Sequence runs 100..1100; we evaluate after it ends.
        let _ = e.tick(100);
        let _ = e.tick(1_100); // clears the sequence
        // Engine should still align with heartbeat anchor=0, i.e. next
        // pulse is t=2000, not 1100 + 2000.
        let d = e.tick(2_000);
        assert_eq!(
            d,
            LedDecision {
                on: true,
                next_deadline_ms: 2_050
            }
        );
    }

    #[test]
    fn sequence_overrides_active_sequence() {
        // Start PowerOff (3 flashes), then mid-flash request PowerOn.
        let mut e = engine(0);
        e.play(LedSequence::PowerOff, 0);
        assert_eq!(e.tick(50).on, true); // still in 1st PowerOff ON
        e.play(LedSequence::PowerOn, 50);
        // PowerOn is 1s ON starting at 50; ends at 1050.
        let d = e.tick(50);
        assert_eq!(
            d,
            LedDecision {
                on: true,
                next_deadline_ms: 1_050
            }
        );
    }

    #[test]
    fn location_advert_double_blink() {
        // ON 50, OFF 50, ON 50.
        let mut e = engine(0);
        e.play(LedSequence::LocationAdvert, 0);
        assert_eq!(e.tick(0).on, true);
        assert_eq!(e.tick(49).on, true);
        assert_eq!(e.tick(50).on, false);
        assert_eq!(e.tick(99).on, false);
        assert_eq!(e.tick(100).on, true);
        assert_eq!(e.tick(149).on, true);
        // After 150ms → back to heartbeat (off-gap since past pulse window).
        assert_eq!(e.tick(150).on, false);
    }

    #[test]
    fn alert_blinks_on_its_period_until_stopped() {
        // LOCATE is ON/OFF/ON/OFF/ON at 120 ms, repeating every 1500 ms.
        let mut e = engine(0);
        e.start_alert(0);
        assert!(e.alert_active());
        assert_eq!(e.tick(0).on, true);
        assert_eq!(e.tick(120).on, false);
        assert_eq!(e.tick(240).on, true);
        // Dark for the rest of the period...
        assert_eq!(e.tick(600).on, false);
        assert_eq!(e.tick(1_499).on, false);
        // ...then again, indefinitely.
        assert_eq!(e.tick(1_500).on, true);
        assert_eq!(e.tick(1_500 * 100).on, true);

        e.stop_alert();
        assert!(!e.alert_active());
    }

    #[test]
    fn alert_outranks_sequences_and_the_heartbeat() {
        let mut e = engine(0);
        e.start_alert(0);
        // A one-shot fired mid-alert must not show through.
        e.play(LedSequence::PowerOn, 0);
        assert_eq!(e.tick(600).on, false, "alert gap, not the 1 s PowerOn hold");

        // Stopping the alert releases the LED to what was underneath.
        e.stop_alert();
        assert_eq!(e.tick(600).on, true, "the preempted PowerOn resumes");
    }

    #[test]
    fn re_starting_a_running_alert_keeps_its_rhythm() {
        let mut e = engine(0);
        e.start_alert(0);
        // A host re-arming the deadline must not restart the blink.
        e.start_alert(700);
        assert_eq!(e.tick(1_500).on, true, "still on the original period");
    }

    #[test]
    fn attention_replaces_each_heartbeat_with_smooth_300ms_pulse() {
        let mut e = T1000eLedEngine::new(0);
        e.set_attention(true);
        assert_eq!(e.tick(0).brightness, 0);
        assert!(e.tick(75).brightness > 0);
        assert_eq!(e.tick(150).brightness, 1_000);
        assert!(e.tick(225).brightness > 0);
        assert_eq!(e.tick(300).brightness, 0);
        assert_eq!(e.tick(4_150).brightness, 1_000);
    }

    #[test]
    fn t1000e_alert_outranks_even_a_critical_battery() {
        let mut e = T1000eLedEngine::new(0);
        e.set_battery(BatteryState::BatteryCritical);
        assert_eq!(e.tick(0).brightness, 0, "critical is dark");

        e.start_alert(0);
        assert_eq!(e.tick(0).brightness, 1_000);
        assert_eq!(e.tick(120).brightness, 0);
        assert_eq!(e.tick(240).brightness, 1_000);
        assert_eq!(e.tick(1_500).brightness, 1_000, "and again next period");

        e.stop_alert();
        assert_eq!(e.tick(0).brightness, 0, "back to the critical blackout");
    }

    #[test]
    fn charging_preempts_attention() {
        let mut e = T1000eLedEngine::new(0);
        e.set_attention(true);
        e.set_battery(BatteryState::BatteryCharging);
        assert_eq!(e.tick(1_500).brightness, 1_000);
        assert_eq!(e.tick(3_000).brightness, 0);
    }

    #[test]
    fn low_battery_is_a_double_flash() {
        let mut e = T1000eLedEngine::new(0);
        e.set_battery(BatteryState::BatteryLow);
        assert_eq!(e.tick(0).brightness, 1_000);
        assert_eq!(e.tick(100).brightness, 0);
        assert_eq!(e.tick(200).brightness, 1_000);
        assert_eq!(e.tick(300).brightness, 0);
    }

    #[test]
    fn ambient_dim_is_linear_between_the_floor_and_full() {
        assert_eq!(ambient_dim_permille(None), 1_000, "no reading = full");
        assert_eq!(ambient_dim_permille(Some(DIM_FULL_MLUX)), 1_000);
        assert_eq!(ambient_dim_permille(Some(u32::MAX)), 1_000);
        assert_eq!(ambient_dim_permille(Some(0)), DIM_MIN_PERMILLE);
        // Halfway in lux is halfway between the floor and full.
        assert_eq!(ambient_dim_permille(Some(DIM_FULL_MLUX / 2)), 525);
    }

    /// The heartbeat dims by duration, not duty: in darkness the default
    /// 20 ms pulse becomes a 1 ms full-brightness tick.
    #[test]
    fn darkness_shortens_the_heartbeat_pulse() {
        let mut e = T1000eLedEngine::new(0);
        e.set_ambient_millilux(Some(0));
        let d = e.tick(0);
        assert_eq!(d.brightness, 1_000, "duty stays full");
        assert_eq!(d.next_deadline_ms, 1, "1/20th of 20 ms, floored at 1");
        assert_eq!(e.tick(1).brightness, 0);
    }

    /// PWM envelopes — the charging breathe here — dim by brightness,
    /// and a one-shot sequence dims the same way.
    #[test]
    fn darkness_dims_pwm_envelopes_by_duty() {
        let mut e = T1000eLedEngine::new(0);
        e.set_battery(BatteryState::BatteryCharging);
        assert_eq!(e.tick(1_500).brightness, 1_000, "lit room: full peak");
        e.set_ambient_millilux(Some(0));
        assert_eq!(e.tick(1_500).brightness, DIM_MIN_PERMILLE);

        e.play(LedSequence::PowerOn, 3_000);
        assert_eq!(e.tick(3_000).brightness, DIM_MIN_PERMILLE);
    }

    /// The locate alert is exempt: a radio being searched for shows
    /// itself at full brightness however dark the room is.
    #[test]
    fn the_locate_alert_ignores_ambient_dimming() {
        let mut e = T1000eLedEngine::new(0);
        e.set_ambient_millilux(Some(0));
        e.start_alert(0);
        assert_eq!(e.tick(0).brightness, 1_000);
    }

    /// An attention-only indicator says nothing on its own — including at
    /// t=0, where an ordinary engine's first heartbeat pulse begins.
    #[test]
    fn an_attention_only_engine_idles_dark() {
        let mut e = LedEngine::attention_only(0);
        for now in [0, 1, 20, 4_000, 60_000, 123_456] {
            assert!(!e.tick(now).on, "lit with nothing to say at {now}");
        }
    }

    /// It is still an indicator: what it is *for* still reaches it, and
    /// the alert still outranks a sequence.
    #[test]
    fn an_attention_only_engine_still_confirms_and_alerts() {
        let mut e = LedEngine::attention_only(0);
        e.play(LedSequence::ActionConfirm, 1_000);
        assert!(e.tick(1_000).on);

        e.start_alert(2_000);
        assert!(e.tick(2_000).on);
        e.stop_alert();
        assert!(!e.tick(30_000).on);
    }
}