Skip to main content

led_strip/
protocol.rs

1use crate::pixel::{LedPixel, Rgb, Rgb16, Rgb16Order, RgbOrder, Rgbw, RgbwOrder};
2
3/// Sealed trait — prevents external crates from implementing `SingleWireProtocol`.
4/// New protocol markers must be added in `protocol.rs` alongside the `<pixel, protocol>` impl matrix.
5mod private {
6    use super::{Sk6812, Ws2811, Ws2812B, Ws2816};
7
8    pub trait ProtocolSealed {}
9
10    impl ProtocolSealed for Ws2812B {}
11    impl ProtocolSealed for Ws2811 {}
12    impl ProtocolSealed for Sk6812 {}
13    impl ProtocolSealed for Ws2816 {}
14}
15
16/// High/low pulse widths for a single protocol bit.
17#[derive(Debug, Clone, Copy, PartialEq, Eq)]
18pub struct PulseTiming {
19    /// High-level duration in nanoseconds.
20    pub high_ns: u32,
21    /// Low-level duration in nanoseconds.
22    pub low_ns: u32,
23}
24
25/// Describes the wire-level electrical characteristics of a single-wire LED
26/// protocol (pulse timings, reset duration).
27///
28/// Each protocol is a zero-sized marker type (`Ws2812B`, `Sk6812`, …) that
29/// implements this trait for the pixel formats it can drive. An incompatible
30/// `<pixel, protocol>` pair fails at compile time — no runtime check is needed.
31///
32/// Constants:
33/// - `ZERO`/`ONE`: nominal `(high_ns, low_ns)` for a logical 0 and 1 bit.
34/// - `RESET_NS`: minimum low-level time to latch the frame.
35/// - `ZERO_MIN`/`ZERO_MAX` and `ONE_MIN`/`ONE_MAX`: inclusive timing limits.
36///   By default these are derived from the nominal timings and
37///   `TIMING_TOLERANCE_NS`; protocols can override each limit independently.
38/// - `MIN_BIT_PERIOD_NS`: minimum high-plus-low duration for either bit value.
39pub trait SingleWireProtocol<P>: private::ProtocolSealed
40where
41    P: LedPixel,
42{
43    /// Human-readable protocol name (e.g. "WS2812B").
44    const NAME: &'static str;
45    /// Default on-wire color channel order for this protocol.
46    const DEFAULT_COLOR_ORDER: P::Order;
47    /// Minimum reset (latch) duration in nanoseconds.
48    const RESET_NS: u32;
49    /// Nominal pulse timing for a logical 0 bit.
50    const ZERO: PulseTiming;
51    /// Nominal pulse timing for a logical 1 bit.
52    const ONE: PulseTiming;
53
54    /// Symmetric tolerance used to derive the default timing limits.
55    /// Defaults to 150 ns (common tolerance for WS2812B-class protocols).
56    /// Explicit `ZERO_MIN`/`ZERO_MAX` and `ONE_MIN`/`ONE_MAX` overrides take
57    /// precedence when a protocol has different limits for each phase.
58    const TIMING_TOLERANCE_NS: u32 = 150;
59
60    /// Inclusive minimum high/low durations for a logical 0 bit.
61    const ZERO_MIN: PulseTiming = PulseTiming {
62        high_ns: Self::ZERO.high_ns.saturating_sub(Self::TIMING_TOLERANCE_NS),
63        low_ns: Self::ZERO.low_ns.saturating_sub(Self::TIMING_TOLERANCE_NS),
64    };
65    /// Inclusive maximum high/low durations for a logical 0 bit.
66    const ZERO_MAX: PulseTiming = PulseTiming {
67        high_ns: Self::ZERO.high_ns.saturating_add(Self::TIMING_TOLERANCE_NS),
68        low_ns: Self::ZERO.low_ns.saturating_add(Self::TIMING_TOLERANCE_NS),
69    };
70    /// Inclusive minimum high/low durations for a logical 1 bit.
71    const ONE_MIN: PulseTiming = PulseTiming {
72        high_ns: Self::ONE.high_ns.saturating_sub(Self::TIMING_TOLERANCE_NS),
73        low_ns: Self::ONE.low_ns.saturating_sub(Self::TIMING_TOLERANCE_NS),
74    };
75    /// Inclusive maximum high/low durations for a logical 1 bit.
76    const ONE_MAX: PulseTiming = PulseTiming {
77        high_ns: Self::ONE.high_ns.saturating_add(Self::TIMING_TOLERANCE_NS),
78        low_ns: Self::ONE.low_ns.saturating_add(Self::TIMING_TOLERANCE_NS),
79    };
80    /// Minimum high-plus-low duration for either bit value, or 0 if unrestricted.
81    const MIN_BIT_PERIOD_NS: u32 = 0;
82}
83
84/// Protocol marker for WS2812B (3-channel 8-bit RGB, GRB order, 800 kbps).
85#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
86pub struct Ws2812B;
87
88/// Protocol marker for WS2811 (3-channel 8-bit RGB, RGB order, 400 kbps slow mode).
89#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
90pub struct Ws2811;
91
92/// Protocol marker for SK6812 (4-channel 8-bit RGBW, GRBW order).
93#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
94pub struct Sk6812;
95
96/// Protocol marker for the 48-bit WS2816B/WS2816C variants
97/// (3-channel 16-bit RGB, GRB order).
98///
99/// Uses the manufacturer's per-phase limits and a minimum bit period of
100/// 1250 ns. Other WS2816 variants may use a different wire format.
101#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
102pub struct Ws2816;
103
104impl SingleWireProtocol<Rgb> for Ws2812B {
105    const NAME: &'static str = "WS2812B";
106    const DEFAULT_COLOR_ORDER: RgbOrder = RgbOrder::Grb;
107    const RESET_NS: u32 = 50_000;
108    const ZERO: PulseTiming = PulseTiming {
109        high_ns: 400,
110        low_ns: 850,
111    };
112    const ONE: PulseTiming = PulseTiming {
113        high_ns: 800,
114        low_ns: 450,
115    };
116}
117
118impl SingleWireProtocol<Rgb> for Ws2811 {
119    const NAME: &'static str = "WS2811";
120    const DEFAULT_COLOR_ORDER: RgbOrder = RgbOrder::Rgb;
121    const RESET_NS: u32 = 50_000;
122    // WS2811 uses 400 kbps slow-mode timing (≈ 2.5 µs per bit vs ≈ 1.25 µs for WS2812B).
123    // Datasheet: T0H>200 ns, T0L>1300 ns → nominal (500, 2000); T1H>800 ns, T1L>500 ns → nominal (1200, 1300).
124    const ZERO: PulseTiming = PulseTiming {
125        high_ns: 500,
126        low_ns: 2_000,
127    };
128    const ONE: PulseTiming = PulseTiming {
129        high_ns: 1_200,
130        low_ns: 1_300,
131    };
132}
133
134impl SingleWireProtocol<Rgbw> for Sk6812 {
135    const NAME: &'static str = "SK6812";
136    const DEFAULT_COLOR_ORDER: RgbwOrder = RgbwOrder::Grbw;
137    const RESET_NS: u32 = 80_000;
138    const ZERO: PulseTiming = PulseTiming {
139        high_ns: 300,
140        low_ns: 900,
141    };
142    const ONE: PulseTiming = PulseTiming {
143        high_ns: 600,
144        low_ns: 600,
145    };
146}
147
148impl SingleWireProtocol<Rgb16> for Ws2816 {
149    const NAME: &'static str = "WS2816";
150    const DEFAULT_COLOR_ORDER: Rgb16Order = Rgb16Order::Grb;
151    const RESET_NS: u32 = 300_000;
152    // Midpoints of the manufacturer's WS2816B/C 48-bit timing ranges.
153    const ZERO: PulseTiming = PulseTiming {
154        high_ns: 260,
155        low_ns: 1_000,
156    };
157    const ONE: PulseTiming = PulseTiming {
158        high_ns: 660,
159        low_ns: 740,
160    };
161    const ZERO_MIN: PulseTiming = PulseTiming {
162        high_ns: 200,
163        low_ns: 800,
164    };
165    const ZERO_MAX: PulseTiming = PulseTiming {
166        high_ns: 320,
167        low_ns: 1_200,
168    };
169    const ONE_MIN: PulseTiming = PulseTiming {
170        high_ns: 520,
171        low_ns: 480,
172    };
173    const ONE_MAX: PulseTiming = PulseTiming {
174        high_ns: 800,
175        low_ns: 1_000,
176    };
177    const MIN_BIT_PERIOD_NS: u32 = 1_250;
178}