hsm_firmware/

animation.rs

// Copyright (c) 2026 Tuloup Simon
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with this program. If not, see <https://www.gnu.org/licenses/>.

//! LED animation task.
//!
//! Reads the current [`hsm_firmware_logic::TokenState`] off
//! [`crate::channels::TOKEN_STATE`] and drives the green (GP16) and yellow
//! (GP17) LEDs at the cadence dictated by the state's
//! [`hsm_firmware_logic::LedPattern`].
//!
//! The task runs an infinite loop with two interleaved concerns:
//!
//! 1. **Apply the current pattern.** Each pattern has a tick interval and
//!    a per-tick action (toggle green, toggle yellow, alternate, etc).
//!    The task sleeps for the tick interval, then performs the action.
//! 2. **React to state changes promptly.** Sleeping for a 500 ms tick
//!    would make a transition into `Error` invisible for half a second.
//!    To avoid that, the task races the tick timer against
//!    [`crate::channels::TOKEN_STATE`] using `embassy_futures::select`.
//!    Whichever fires first wins.
//!
//! # Testability
//!
//! The actual driving logic lives in [`apply_pattern`], which is generic
//! over the [`Led`] trait. The embassy task wrapper
//! [`animation_task`] is a thin shell that supplies real `Output<'static>`
//! values; host-side tests instantiate `apply_pattern` directly with
//! mock LEDs to assert on transition counts.

use defmt::info;
use embassy_futures::select::{select, Either};
use embassy_time::{Duration, Timer};

use hsm_firmware_logic::{Led, LedPattern};

use crate::channels::TOKEN_STATE;
use crate::hal_rp2040::Rp2040Led;

/// Tick interval for the slow pulse pattern (green, 1 Hz).
const SLOW_PULSE_INTERVAL: Duration = Duration::from_millis(500);

/// Tick interval for the fast blink pattern (5 Hz).
const FAST_BLINK_INTERVAL: Duration = Duration::from_millis(100);

/// Tick interval for the yellow blink pattern (2 Hz).
const YELLOW_BLINK_INTERVAL: Duration = Duration::from_millis(250);

/// Tick interval for the alternate-both pattern (5 Hz).
const ALTERNATE_INTERVAL: Duration = Duration::from_millis(100);

/// Drive the LEDs based on the current operating state. Spawn once at boot.
///
/// Both LEDs are owned by this task for the lifetime of the firmware.
#[embassy_executor::task]
pub(crate) async fn animation_task
(
    mut led_green: Rp2040Led,
    mut led_yellow: Rp2040Led,
) -> !
{
    // Wait for the first state publication. The state task always emits
    // the initial state at startup, so this returns promptly.
    let mut state = TOKEN_STATE.wait().await;
    info!("animation task started, initial state {:?}", state);

    // Tick phase: toggles every iteration to drive blink/pulse patterns.
    let mut tick_high = false;

    loop
    {
        // Apply the current pattern via the generic helper.
        let interval = apply_pattern
        (
            state.led_pattern(),
            tick_high,
            &mut led_green,
            &mut led_yellow,
        );
        tick_high = !tick_high;

        // Race the tick timer against a state change.
        match select(Timer::after(interval), TOKEN_STATE.wait()).await
        {
            Either::First(()) =>
            {
                // Tick elapsed, continue with the same pattern.
            }
            Either::Second(new_state) =>
            {
                // State changed: reset the tick phase and switch pattern
                // immediately.
                info!("animation: state {:?} -> {:?}", state, new_state);
                state = new_state;
                tick_high = false;
            }
        }
    }
}

/// Apply one tick of `pattern` to the LEDs and return the duration to wait
/// before the next tick.
///
/// `tick_high` alternates `false`/`true` each iteration. For static
/// patterns (solid, all-off) the value is ignored.
///
/// Generic over [`Led`] so the firmware task and host-side unit tests
/// can share the same code path.
pub(crate) fn apply_pattern<G, Y>
(
    pattern: LedPattern,
    tick_high: bool,
    led_green: &mut G,
    led_yellow: &mut Y,
) -> Duration
where
    G: Led,
    Y: Led,
{
    match pattern
    {
        LedPattern::AllOff =>
        {
            led_green.off();
            led_yellow.off();
            // No animation: long wait, the select will wake us on the
            // next state change.
            Duration::from_secs(60)
        }
        LedPattern::GreenSolid =>
        {
            led_green.on();
            led_yellow.off();
            Duration::from_secs(60)
        }
        LedPattern::GreenSlowPulse =>
        {
            led_yellow.off();
            led_green.set(tick_high);
            SLOW_PULSE_INTERVAL
        }
        LedPattern::GreenFastBlink =>
        {
            led_yellow.off();
            led_green.set(tick_high);
            FAST_BLINK_INTERVAL
        }
        LedPattern::YellowSolid =>
        {
            led_green.off();
            led_yellow.on();
            Duration::from_secs(60)
        }
        LedPattern::YellowBlink =>
        {
            led_green.off();
            led_yellow.set(tick_high);
            YELLOW_BLINK_INTERVAL
        }
        LedPattern::AlternateBoth =>
        {
            led_green.set(tick_high);
            led_yellow.set(!tick_high);
            ALTERNATE_INTERVAL
        }
    }
}

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

    /// Minimal mock LED that just tracks state and transitions.
    /// Mirrors the one in `hsm_firmware_logic::io::test_mocks` but lives
    /// here so this crate can test `apply_pattern` without exposing a
    /// `pub(crate)` mock across crates.
    #[derive(Debug, Default)]
    struct MockLed
    {
        state:       bool,
        transitions: u32,
    }

    impl Led for MockLed
    {
        fn on(&mut self)
        {
            if !self.state
            {
                self.transitions += 1;
            }
            self.state = true;
        }

        fn off(&mut self)
        {
            if self.state
            {
                self.transitions += 1;
            }
            self.state = false;
        }
    }

    #[test]
    fn green_solid_lights_green_and_kills_yellow()
    {
        let mut green = MockLed::default();
        let mut yellow = MockLed::default();
        green.off();
        yellow.on();
        let _ = apply_pattern(LedPattern::GreenSolid, false, &mut green, &mut yellow);
        assert!(green.state);
        assert!(!yellow.state);
    }

    #[test]
    fn alternate_both_swaps_each_tick()
    {
        let mut green = MockLed::default();
        let mut yellow = MockLed::default();
        let _ = apply_pattern(LedPattern::AlternateBoth, true, &mut green, &mut yellow);
        assert!(green.state);
        assert!(!yellow.state);
        let _ = apply_pattern(LedPattern::AlternateBoth, false, &mut green, &mut yellow);
        assert!(!green.state);
        assert!(yellow.state);
    }

    #[test]
    fn all_off_clears_both()
    {
        let mut green = MockLed::default();
        let mut yellow = MockLed::default();
        green.on();
        yellow.on();
        let _ = apply_pattern(LedPattern::AllOff, true, &mut green, &mut yellow);
        assert!(!green.state);
        assert!(!yellow.state);
    }

    #[test]
    fn green_slow_pulse_returns_500ms_interval()
    {
        let mut green = MockLed::default();
        let mut yellow = MockLed::default();
        let d = apply_pattern(LedPattern::GreenSlowPulse, true, &mut green, &mut yellow);
        assert_eq!(d, SLOW_PULSE_INTERVAL);
    }
}