pennant 0.5.0

Reusable LED animation effects for embedded projects
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117

use core::convert::Infallible;

use rgb::RGB8;

use crate::AsyncStatusLed;
use crate::StatusLed;

/// A no-op LED stub that satisfies the [`StatusLed`] trait without any hardware dependency.
///
/// Use `NoLed` when a type parameter requires a [`StatusLed`] implementation but no
/// physical LED is present — for example in unit tests, CI environments, or board
/// configurations that omit the status LED.
///
/// All operations succeed silently; no color data is stored or transmitted.
///
/// # Example
///
/// ```
/// use pennant::{NoLed, StatusLed};
/// use rgb::RGB8;
///
/// let mut led = NoLed::default();
/// led.set_color(RGB8::new(255, 0, 0)).unwrap(); // always Ok
/// ```
#[derive(Copy, Clone, Default, Debug)]
pub struct NoLed;

impl StatusLed for NoLed {
    type Error = Infallible;

    fn set_color(&mut self, _color: RGB8) -> Result<(), Self::Error> {
        Ok(())
    }
}

impl AsyncStatusLed for NoLed {
    type Error = Infallible;

    async fn set_color(&mut self, _color: RGB8) -> Result<(), Self::Error> {
        Ok(())
    }
}

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

    #[test]
    fn set_color_always_returns_ok() {
        let mut led = NoLed;
        assert!(StatusLed::set_color(&mut led, RGB8::new(255, 0, 0)).is_ok());
        assert!(StatusLed::set_color(&mut led, RGB8::new(0, 255, 0)).is_ok());
        assert!(StatusLed::set_color(&mut led, RGB8::new(0, 0, 255)).is_ok());
        assert!(StatusLed::set_color(&mut led, RGB8::new(0, 0, 0)).is_ok());
        assert!(StatusLed::set_color(&mut led, RGB8::new(255, 255, 255)).is_ok());
    }

    #[test]
    fn error_type_is_infallible() {
        let mut led = NoLed;
        // Unwrap is safe because the error type is Infallible
        let _: () = StatusLed::set_color(&mut led, RGB8::new(128, 64, 32)).unwrap();
    }

    /// Drives a future that is contractually guaranteed to be ready on the first poll.
    ///
    /// Uses a no-op waker; if the future ever returns `Poll::Pending` it will panic
    /// rather than spin or deadlock. Intended only for `NoLed`'s async impls, which
    /// complete synchronously. Do **not** copy this helper into contexts where the
    /// future may suspend — use a real executor (embassy, tokio) instead.
    fn block_on_ready<F: core::future::Future>(f: F) -> F::Output {
        use core::pin::pin;
        use core::task::{Context, Poll, RawWaker, RawWakerVTable, Waker};
        const VTABLE: RawWakerVTable = RawWakerVTable::new(
            |_| RawWaker::new(core::ptr::null(), &VTABLE),
            |_| {},
            |_| {},
            |_| {},
        );
        // SAFETY: The waker is a no-op; it is only valid for futures that
        // complete in a single poll (i.e. never return Poll::Pending), which
        // is guaranteed for NoLed's async impls.
        let waker = unsafe { Waker::from_raw(RawWaker::new(core::ptr::null(), &VTABLE)) };
        let mut cx = Context::from_waker(&waker);
        let mut f = pin!(f);
        match f.as_mut().poll(&mut cx) {
            Poll::Ready(v) => v,
            Poll::Pending => panic!(
                "block_on_ready: future returned Poll::Pending, but the contract \
                 requires it to complete on the first poll (no real executor here)"
            ),
        }
    }

    #[test]
    fn async_set_color_always_returns_ok() {
        let mut led = NoLed;
        block_on_ready(async {
            assert!(AsyncStatusLed::set_color(&mut led, RGB8::new(255, 0, 0))
                .await
                .is_ok());
            assert!(AsyncStatusLed::set_color(&mut led, RGB8::new(0, 0, 0))
                .await
                .is_ok());
        });
    }

    #[test]
    fn async_error_type_is_infallible() {
        let mut led = NoLed;
        block_on_ready(async {
            let _: () = AsyncStatusLed::set_color(&mut led, RGB8::new(128, 64, 32))
                .await
                .unwrap();
        });
    }
}