led_strip/lib.rs
1//! `no_std` driver for single-wire addressable LED strips (WS2812, SK6812, WS2811, WS2816).
2//!
3//! # Architecture
4//!
5//! ```text
6//! LedStrip --> WireCodec (pixels => transport words) --> TransportBackend (transmit)
7//! | |
8//! +-- SpiCodec (SPI bit-banging) +-- SpiBackend (SPI)
9//! ```
10//!
11//! The [`WireCodec`] / [`TransportBackend`] traits are intentionally generic:
12//! `SpiCodec` / `SpiBackend` are the current production implementation,
13//! but the trait design accommodates future backends (RMT, PIO, etc.) without
14//! API changes.
15//!
16//! # Features
17//!
18//! | Feature | Default | Description |
19//! |---------|---------|-------------|
20//! | `spi` | Yes | SPI backend, requires `embedded-hal` |
21//!
22//! # Quick start
23//!
24//! ```
25//! # #[cfg(feature = "spi")]
26//! # {
27//! # use core::convert::Infallible;
28//! # use embedded_hal::spi::{ErrorType, SpiBus};
29//! # struct MockSpi;
30//! # impl ErrorType for MockSpi { type Error = Infallible; }
31//! # impl SpiBus<u8> for MockSpi {
32//! # fn read(&mut self, _: &mut [u8]) -> Result<(), Self::Error> { Ok(()) }
33//! # fn write(&mut self, words: &[u8]) -> Result<(), Self::Error> {
34//! # assert_eq!(words.len(), 555);
35//! # Ok(())
36//! # }
37//! # fn transfer(&mut self, _: &mut [u8], _: &[u8]) -> Result<(), Self::Error> { Ok(()) }
38//! # fn transfer_in_place(&mut self, _: &mut [u8]) -> Result<(), Self::Error> { Ok(()) }
39//! # fn flush(&mut self) -> Result<(), Self::Error> { Ok(()) }
40//! # }
41//! # let spi_peripheral = MockSpi;
42//! use led_strip::{LedStrip, SpiCodec, SpiBackend, SpiEncodingPlan, Rgb, RgbOrder, Ws2812B};
43//!
44//! let codec = SpiCodec::<Rgb, Ws2812B>::for_protocol(
45//! SpiEncodingPlan::ws2812_3bit(), false
46//! ).unwrap();
47//! let backend = SpiBackend::new(spi_peripheral);
48//! // 60 pixels need 60 × 9 payload bytes + 15 reset bytes = 555 bytes.
49//! let mut strip: LedStrip<Rgb, Ws2812B, _, _, 1024> =
50//! LedStrip::new(RgbOrder::Grb, codec, backend);
51//!
52//! let pixels = [Rgb::new(255, 0, 0); 60];
53//! strip.write(&pixels).unwrap();
54//! # }
55//! ```
56
57#![cfg_attr(not(test), no_std)]
58#![forbid(unsafe_code)]
59
60mod api;
61mod error;
62mod pixel;
63mod protocol;
64#[cfg(feature = "spi")]
65mod spi;
66
67pub use api::{LedStrip, RefreshError, TransportBackend, WireCodec};
68pub use error::{LedStripError, LedStripResult};
69pub use pixel::{LedPixel, Rgb, Rgb16, Rgb16Order, RgbOrder, Rgbw, RgbwOrder};
70pub use protocol::{PulseTiming, SingleWireProtocol, Sk6812, Ws2811, Ws2812B, Ws2816};
71#[cfg(feature = "spi")]
72pub use spi::{
73 SpiBackend, SpiCodec, SpiCodecPlanError, SpiEncodeError, SpiEncodingPlan, TimingEdge,
74};