use core::marker::PhantomData;
use embedded_hal::spi::SpiBus;
use heapless::Vec;
use crate::{
LedPixel, LedStripError, LedStripResult, SingleWireProtocol, TransportBackend, WireCodec,
};
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct SpiEncodingPlan {
spi_hz: u32,
zero_pattern: u8,
one_pattern: u8,
bits_per_symbol: u8,
extra_reset_ns: u32,
}
impl SpiEncodingPlan {
#[must_use]
pub const fn new(spi_hz: u32, zero_pattern: u8, one_pattern: u8, bits_per_symbol: u8) -> Self {
Self {
spi_hz,
zero_pattern,
one_pattern,
bits_per_symbol,
extra_reset_ns: 0,
}
}
#[must_use]
pub const fn ws2812_3bit() -> Self {
Self::new(2_400_000, 0b100, 0b110, 3)
}
#[must_use]
pub const fn sk6812_4bit() -> Self {
Self::new(3_200_000, 0b1000, 0b1100, 4)
}
#[must_use]
pub const fn ws2811_8bit() -> Self {
Self::new(3_200_000, 0b1100_0000, 0b1111_0000, 8)
}
#[must_use]
pub const fn ws2816_5bit() -> Self {
Self::new(4_000_000, 0b10000, 0b11100, 5)
}
#[must_use]
pub const fn with_extra_reset_ns(mut self, extra_reset_ns: u32) -> Self {
self.extra_reset_ns = extra_reset_ns;
self
}
#[must_use]
pub const fn spi_hz(&self) -> u32 {
self.spi_hz
}
#[must_use]
pub const fn zero_pattern(&self) -> u8 {
self.zero_pattern
}
#[must_use]
pub const fn one_pattern(&self) -> u8 {
self.one_pattern
}
#[must_use]
pub const fn bits_per_symbol(&self) -> u8 {
self.bits_per_symbol
}
#[must_use]
pub const fn extra_reset_ns(&self) -> u32 {
self.extra_reset_ns
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum TimingEdge {
ZeroHigh,
ZeroLow,
OneHigh,
OneLow,
}
impl core::fmt::Display for TimingEdge {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
let s = match self {
Self::ZeroHigh => "T0H",
Self::ZeroLow => "T0L",
Self::OneHigh => "T1H",
Self::OneLow => "T1L",
};
f.write_str(s)
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum SpiCodecPlanError {
ZeroClock,
ZeroBitsPerSymbol,
BitsPerSymbolTooWide {
bits_per_symbol: u8,
},
PatternOutOfRange {
pattern: u8,
bits_per_symbol: u8,
},
InvalidSymbolWaveform {
pattern: u8,
bits_per_symbol: u8,
},
IdenticalSymbolPatterns {
pattern: u8,
},
TimingOutOfTolerance {
edge: TimingEdge,
actual_ns: u32,
expected_ns: u32,
tolerance_ns: u32,
},
TimingOutOfRange {
edge: TimingEdge,
actual_ns: u32,
minimum_ns: u32,
maximum_ns: u32,
},
BitPeriodTooShort {
actual_ns: u32,
minimum_ns: u32,
},
ResetDurationOverflow {
total_reset_ns: u64,
spi_hz: u32,
},
}
impl core::fmt::Display for SpiCodecPlanError {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
match self {
Self::ZeroClock => f.write_str("invalid SPI plan: spi_hz must be non-zero"),
Self::ZeroBitsPerSymbol => {
f.write_str("invalid SPI plan: bits_per_symbol must be non-zero")
}
Self::BitsPerSymbolTooWide { bits_per_symbol } => write!(
f,
"invalid SPI plan: bits_per_symbol={bits_per_symbol} exceeds 8"
),
Self::PatternOutOfRange {
pattern,
bits_per_symbol,
} => write!(
f,
"invalid SPI plan: pattern=0x{pattern:02X} out of range for bits_per_symbol={bits_per_symbol}"
),
Self::InvalidSymbolWaveform {
pattern,
bits_per_symbol,
} => write!(
f,
"invalid SPI plan: pattern=0x{pattern:02X} must be contiguous high then contiguous low within bits_per_symbol={bits_per_symbol}"
),
Self::IdenticalSymbolPatterns { pattern } => write!(
f,
"invalid SPI plan: logical 0 and 1 use the same pattern=0x{pattern:02X}"
),
Self::TimingOutOfTolerance {
edge,
actual_ns,
expected_ns,
tolerance_ns,
} => write!(
f,
"timing out of tolerance: edge={edge} actual={actual_ns}ns expected={expected_ns}ns tolerance=\u{00B1}{tolerance_ns}ns"
),
Self::TimingOutOfRange {
edge,
actual_ns,
minimum_ns,
maximum_ns,
} => write!(
f,
"timing out of range: edge={edge} actual={actual_ns}ns permitted={minimum_ns}..={maximum_ns}ns"
),
Self::BitPeriodTooShort {
actual_ns,
minimum_ns,
} => write!(
f,
"bit period too short: actual={actual_ns}ns minimum={minimum_ns}ns"
),
Self::ResetDurationOverflow {
total_reset_ns,
spi_hz,
} => write!(
f,
"invalid SPI plan: reset duration overflow: total_reset_ns={total_reset_ns}ns \u{00D7} spi_hz={spi_hz}Hz exceeds the u64 fixed-point range"
),
}
}
}
impl core::error::Error for SpiCodecPlanError {}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum SpiEncodeError {
InternalConsistency {
stage: &'static str,
required: usize,
capacity: usize,
attempted_len: usize,
},
}
impl core::fmt::Display for SpiEncodeError {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
match self {
Self::InternalConsistency {
stage,
required,
capacity,
attempted_len,
} => write!(
f,
"internal consistency error at {stage}: encoded_len={required}, capacity={capacity}, attempted_len={attempted_len}"
),
}
}
}
impl core::error::Error for SpiEncodeError {}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct SpiCodec<P, Proto>
where
P: LedPixel,
Proto: SingleWireProtocol<P>,
{
plan: SpiEncodingPlan,
zero_pattern: u8,
one_pattern: u8,
reset_fill: u8,
_marker: PhantomData<(P, Proto)>,
}
impl<P, Proto> SpiCodec<P, Proto>
where
P: LedPixel,
Proto: SingleWireProtocol<P>,
{
#[must_use = "SPI codec construction validates the plan; ignoring the result would silently drop errors"]
pub fn new(plan: SpiEncodingPlan, invert_output: bool) -> Result<Self, SpiCodecPlanError> {
validate_plan(plan)?;
validate_reset_duration::<P, Proto>(&plan)?;
Ok(Self::from_plan(plan, invert_output))
}
#[must_use = "returns Err on timing violations; use new() to skip timing validation"]
pub fn for_protocol(
plan: SpiEncodingPlan,
invert_output: bool,
) -> Result<Self, SpiCodecPlanError> {
validate_plan(plan)?;
validate_timing::<P, Proto>(&plan)?;
validate_reset_duration::<P, Proto>(&plan)?;
Ok(Self::from_plan(plan, invert_output))
}
const fn from_plan(plan: SpiEncodingPlan, invert_output: bool) -> Self {
if invert_output {
let mask = pattern_mask(plan.bits_per_symbol());
Self {
zero_pattern: (!plan.zero_pattern()) & mask,
one_pattern: (!plan.one_pattern()) & mask,
reset_fill: u8::MAX,
plan,
_marker: PhantomData,
}
} else {
Self {
zero_pattern: plan.zero_pattern(),
one_pattern: plan.one_pattern(),
reset_fill: 0,
plan,
_marker: PhantomData,
}
}
}
#[must_use]
pub const fn plan(&self) -> SpiEncodingPlan {
self.plan
}
fn reset_bytes(&self) -> usize
where
P: LedPixel,
Proto: SingleWireProtocol<P>,
{
let total_reset_ns = u64::from(Proto::RESET_NS) + u64::from(self.plan.extra_reset_ns);
let scaled_cycles = total_reset_ns * u64::from(self.plan.spi_hz);
let total_bytes = scaled_cycles.div_ceil(8_000_000_000_u64);
usize::try_from(total_bytes).unwrap_or(usize::MAX)
}
}
impl<P, Proto> WireCodec<P, Proto, u8> for SpiCodec<P, Proto>
where
P: LedPixel,
Proto: SingleWireProtocol<P>,
{
type EncodeError = SpiEncodeError;
fn encoded_len(&self, pixel_count: usize) -> usize {
let frame_bytes = pixel_count.saturating_mul(P::BYTES_PER_PIXEL);
let payload_bits = frame_bytes
.saturating_mul(8)
.saturating_mul(usize::from(self.plan.bits_per_symbol));
let payload_bytes = payload_bits.saturating_add(7) / 8;
let total = payload_bytes.saturating_add(self.reset_bytes());
debug_assert!(
total < usize::MAX / 2,
"encoded_len overflowed: frame too large for usize"
);
total
}
fn encode<const TX_CAPACITY: usize>(
&self,
color_order: P::Order,
pixels: &[P],
out: &mut Vec<u8, TX_CAPACITY>,
) -> LedStripResult<(), Self::EncodeError> {
let required = self.encoded_len(pixels.len());
if required > TX_CAPACITY {
return Err(LedStripError::BufferTooSmall {
required,
capacity: TX_CAPACITY,
});
}
out.clear();
let mut current_byte = 0_u8;
let mut used_bits = 0_u8;
let mut raw = [0_u8; 6];
for pixel in pixels.iter().copied() {
pixel.encode(color_order, &mut raw[..P::BYTES_PER_PIXEL]);
for byte in &raw[..P::BYTES_PER_PIXEL] {
for bit_index in 0..8 {
let shift = bit_shift(bit_index);
let bit_is_set = ((*byte >> shift) & 1) != 0;
let pattern = if bit_is_set {
self.one_pattern
} else {
self.zero_pattern
};
append_pattern::<TX_CAPACITY>(
out,
pattern,
self.plan.bits_per_symbol(),
required,
&mut current_byte,
&mut used_bits,
)?;
}
}
}
debug_assert_eq!(used_bits, 0, "total encoded bits must be a multiple of 8");
let reset_bytes = self.reset_bytes();
let target_len = out.len().saturating_add(reset_bytes);
out.resize(target_len, self.reset_fill).map_err(|_| {
LedStripError::Operation(SpiEncodeError::InternalConsistency {
stage: "reset_tail_resize",
required,
capacity: TX_CAPACITY,
attempted_len: target_len,
})
})?;
Ok(())
}
}
#[derive(Debug)]
pub struct SpiBackend<SPI> {
spi: SPI,
}
impl<SPI> SpiBackend<SPI> {
#[must_use]
pub const fn new(spi: SPI) -> Self {
Self { spi }
}
#[must_use]
pub fn into_inner(self) -> SPI {
self.spi
}
#[must_use]
pub fn inner(&self) -> &SPI {
&self.spi
}
#[must_use]
pub fn inner_mut(&mut self) -> &mut SPI {
&mut self.spi
}
}
impl<SPI> TransportBackend for SpiBackend<SPI>
where
SPI: SpiBus<u8>,
{
type Word = u8;
type Error = SPI::Error;
fn transmit(&mut self, words: &[Self::Word]) -> Result<(), Self::Error> {
self.spi.write(words)?;
self.spi.flush()
}
}
const fn pattern_mask(bits_per_symbol: u8) -> u8 {
if bits_per_symbol == 8 {
u8::MAX
} else {
(1_u8 << bits_per_symbol) - 1
}
}
fn validate_plan(plan: SpiEncodingPlan) -> Result<(), SpiCodecPlanError> {
if plan.spi_hz == 0 {
return Err(SpiCodecPlanError::ZeroClock);
}
if plan.bits_per_symbol == 0 {
return Err(SpiCodecPlanError::ZeroBitsPerSymbol);
}
if plan.bits_per_symbol > 8 {
return Err(SpiCodecPlanError::BitsPerSymbolTooWide {
bits_per_symbol: plan.bits_per_symbol,
});
}
let limit = pattern_mask(plan.bits_per_symbol);
if plan.zero_pattern > limit {
return Err(SpiCodecPlanError::PatternOutOfRange {
pattern: plan.zero_pattern,
bits_per_symbol: plan.bits_per_symbol,
});
}
if plan.one_pattern > limit {
return Err(SpiCodecPlanError::PatternOutOfRange {
pattern: plan.one_pattern,
bits_per_symbol: plan.bits_per_symbol,
});
}
simulate_symbol_phases(plan.zero_pattern, plan.bits_per_symbol)?;
simulate_symbol_phases(plan.one_pattern, plan.bits_per_symbol)?;
if plan.zero_pattern == plan.one_pattern {
return Err(SpiCodecPlanError::IdenticalSymbolPatterns {
pattern: plan.zero_pattern,
});
}
Ok(())
}
fn validate_reset_duration<P, Proto>(plan: &SpiEncodingPlan) -> Result<(), SpiCodecPlanError>
where
P: LedPixel,
Proto: SingleWireProtocol<P>,
{
let total_reset_ns = u64::from(Proto::RESET_NS) + u64::from(plan.extra_reset_ns);
if total_reset_ns > u64::MAX / u64::from(plan.spi_hz) {
return Err(SpiCodecPlanError::ResetDurationOverflow {
total_reset_ns,
spi_hz: plan.spi_hz,
});
}
Ok(())
}
#[inline]
fn bit_shift(bit_index: u8) -> u8 {
7 - bit_index
}
#[inline]
fn append_pattern<const TX_CAPACITY: usize>(
out: &mut Vec<u8, TX_CAPACITY>,
pattern: u8,
bits_per_symbol: u8,
required: usize,
current_byte: &mut u8,
used_bits: &mut u8,
) -> LedStripResult<(), SpiEncodeError> {
for shift in (0..bits_per_symbol).rev() {
let bit = ((pattern >> shift) & 1) != 0;
if bit {
*current_byte |= 1_u8 << (7 - *used_bits);
}
*used_bits += 1;
if *used_bits == 8 {
out.push(*current_byte).map_err(|_| {
LedStripError::Operation(SpiEncodeError::InternalConsistency {
stage: "append_pattern_push",
required,
capacity: TX_CAPACITY,
attempted_len: out.len().saturating_add(1),
})
})?;
*current_byte = 0;
*used_bits = 0;
}
}
Ok(())
}
fn simulate_symbol_phases(pattern: u8, bits_per_symbol: u8) -> Result<(u8, u8), SpiCodecPlanError> {
let mut high_bits = 0_u8;
let mut low_bits = 0_u8;
let mut in_low_phase = false;
for shift in (0..bits_per_symbol).rev() {
let bit_is_high = ((pattern >> shift) & 1) != 0;
if !in_low_phase {
if bit_is_high {
high_bits += 1;
} else if high_bits == 0 {
return Err(SpiCodecPlanError::InvalidSymbolWaveform {
pattern,
bits_per_symbol,
});
} else {
in_low_phase = true;
low_bits = 1;
}
} else if bit_is_high {
return Err(SpiCodecPlanError::InvalidSymbolWaveform {
pattern,
bits_per_symbol,
});
} else {
low_bits += 1;
}
}
if high_bits == 0 || low_bits == 0 {
return Err(SpiCodecPlanError::InvalidSymbolWaveform {
pattern,
bits_per_symbol,
});
}
Ok((high_bits, low_bits))
}
fn validate_timing<P, Proto>(plan: &SpiEncodingPlan) -> Result<(), SpiCodecPlanError>
where
P: LedPixel,
Proto: SingleWireProtocol<P>,
{
let tolerance = Proto::TIMING_TOLERANCE_NS;
let (zero_high, zero_low) = simulate_symbol_phases(plan.zero_pattern, plan.bits_per_symbol)?;
let (one_high, one_low) = simulate_symbol_phases(plan.one_pattern, plan.bits_per_symbol)?;
check_timing(
zero_high,
plan.spi_hz,
Proto::ZERO.high_ns,
Proto::ZERO_MIN.high_ns,
Proto::ZERO_MAX.high_ns,
tolerance,
TimingEdge::ZeroHigh,
)?;
check_timing(
zero_low,
plan.spi_hz,
Proto::ZERO.low_ns,
Proto::ZERO_MIN.low_ns,
Proto::ZERO_MAX.low_ns,
tolerance,
TimingEdge::ZeroLow,
)?;
check_timing(
one_high,
plan.spi_hz,
Proto::ONE.high_ns,
Proto::ONE_MIN.high_ns,
Proto::ONE_MAX.high_ns,
tolerance,
TimingEdge::OneHigh,
)?;
check_timing(
one_low,
plan.spi_hz,
Proto::ONE.low_ns,
Proto::ONE_MIN.low_ns,
Proto::ONE_MAX.low_ns,
tolerance,
TimingEdge::OneLow,
)?;
if u64::from(plan.bits_per_symbol) * 1_000_000_000
< u64::from(Proto::MIN_BIT_PERIOD_NS) * u64::from(plan.spi_hz)
{
return Err(SpiCodecPlanError::BitPeriodTooShort {
actual_ns: rounded_duration_ns(plan.bits_per_symbol, plan.spi_hz),
minimum_ns: Proto::MIN_BIT_PERIOD_NS,
});
}
Ok(())
}
fn check_timing(
phase_bits: u8,
spi_hz: u32,
expected_ns: u32,
minimum_ns: u32,
maximum_ns: u32,
tolerance_ns: u32,
edge: TimingEdge,
) -> Result<(), SpiCodecPlanError> {
let scaled_duration = u64::from(phase_bits) * 1_000_000_000;
if scaled_duration < u64::from(minimum_ns) * u64::from(spi_hz)
|| scaled_duration > u64::from(maximum_ns) * u64::from(spi_hz)
{
let actual_ns = rounded_duration_ns(phase_bits, spi_hz);
if minimum_ns == expected_ns.saturating_sub(tolerance_ns)
&& maximum_ns == expected_ns.saturating_add(tolerance_ns)
{
return Err(SpiCodecPlanError::TimingOutOfTolerance {
edge,
actual_ns,
expected_ns,
tolerance_ns,
});
}
return Err(SpiCodecPlanError::TimingOutOfRange {
edge,
actual_ns,
minimum_ns,
maximum_ns,
});
}
Ok(())
}
fn rounded_duration_ns(bits: u8, spi_hz: u32) -> u32 {
let scaled_duration = u64::from(bits) * 1_000_000_000;
let actual_ns = (scaled_duration + u64::from(spi_hz) / 2) / u64::from(spi_hz);
u32::try_from(actual_ns).unwrap_or(u32::MAX)
}
#[cfg(test)]
mod tests {
use crate::{
Rgb, Rgb16, Rgbw, Sk6812, SpiBackend, TransportBackend, WireCodec, Ws2811, Ws2812B,
};
use super::{SpiCodec, SpiCodecPlanError, SpiEncodeError, SpiEncodingPlan, TimingEdge};
#[test]
fn ws2812_3bit_passes_ws2812b_timing() {
SpiCodec::<Rgb, Ws2812B>::for_protocol(SpiEncodingPlan::ws2812_3bit(), false).unwrap();
}
#[test]
fn sk6812_4bit_passes_sk6812_timing() {
SpiCodec::<Rgbw, Sk6812>::for_protocol(SpiEncodingPlan::sk6812_4bit(), false).unwrap();
}
#[test]
fn ws2812_3bit_rejects_sk6812_timing() {
let err = SpiCodec::<Rgbw, Sk6812>::for_protocol(SpiEncodingPlan::ws2812_3bit(), false)
.unwrap_err();
assert!(matches!(
err,
SpiCodecPlanError::TimingOutOfTolerance {
edge: TimingEdge::OneHigh,
..
}
));
}
#[test]
fn out_of_tolerance_plan_reports_first_failing_edge() {
let plan = SpiEncodingPlan::new(1_000_000, 0b100, 0b110, 3);
let err = SpiCodec::<Rgb, Ws2812B>::for_protocol(plan, false).unwrap_err();
assert_eq!(
err,
SpiCodecPlanError::TimingOutOfTolerance {
edge: TimingEdge::ZeroHigh,
actual_ns: 1000,
expected_ns: 400,
tolerance_ns: 150,
}
);
}
#[test]
fn timing_edge_display_uses_protocol_labels() {
assert_eq!(TimingEdge::ZeroHigh.to_string(), "T0H");
assert_eq!(TimingEdge::ZeroLow.to_string(), "T0L");
assert_eq!(TimingEdge::OneHigh.to_string(), "T1H");
assert_eq!(TimingEdge::OneLow.to_string(), "T1L");
}
#[test]
fn plan_error_display_zero_clock() {
let s = SpiCodecPlanError::ZeroClock.to_string();
assert!(s.contains("spi_hz"), "{s}");
}
#[test]
fn plan_error_display_zero_bits_per_symbol() {
let s = SpiCodecPlanError::ZeroBitsPerSymbol.to_string();
assert!(s.contains("bits_per_symbol"), "{s}");
}
#[test]
fn plan_error_display_bits_per_symbol_too_wide() {
let s = SpiCodecPlanError::BitsPerSymbolTooWide { bits_per_symbol: 9 }.to_string();
assert!(s.contains("bits_per_symbol=9"), "{s}");
}
#[test]
fn plan_error_display_pattern_out_of_range() {
let s = SpiCodecPlanError::PatternOutOfRange {
pattern: 0xFF,
bits_per_symbol: 3,
}
.to_string();
assert!(s.contains("0xFF"), "{s}");
assert!(s.contains("bits_per_symbol=3"), "{s}");
}
#[test]
fn plan_error_display_invalid_symbol_waveform() {
let s = SpiCodecPlanError::InvalidSymbolWaveform {
pattern: 0b101,
bits_per_symbol: 3,
}
.to_string();
assert!(s.contains("0x05"), "{s}");
assert!(s.contains("contiguous high then contiguous low"), "{s}");
}
#[test]
fn plan_error_display_timing_out_of_tolerance_includes_all_fields() {
let s = SpiCodecPlanError::TimingOutOfTolerance {
edge: TimingEdge::OneHigh,
actual_ns: 832,
expected_ns: 600,
tolerance_ns: 150,
}
.to_string();
assert!(s.contains("T1H"), "{s}");
assert!(s.contains("832"), "{s}");
assert!(s.contains("600"), "{s}");
assert!(s.contains("150"), "{s}");
}
#[test]
fn plan_error_display_reset_duration_overflow() {
let s = SpiCodecPlanError::ResetDurationOverflow {
total_reset_ns: 4_295_017_295,
spi_hz: u32::MAX,
}
.to_string();
assert!(s.contains("reset duration overflow"), "{s}");
assert!(s.contains("4295017295"), "{s}");
assert!(s.contains("4294967295"), "{s}");
}
#[test]
fn plan_error_is_core_error() {
let _: &dyn core::error::Error = &SpiCodecPlanError::ZeroClock;
}
use crate::{LedStripError, RgbOrder};
use heapless::Vec as HVec;
#[test]
fn encode_produces_nonempty_buffer() {
let codec =
SpiCodec::<Rgb, Ws2812B>::for_protocol(SpiEncodingPlan::ws2812_3bit(), false).unwrap();
let pixels = [Rgb::new(0, 255, 0)];
let mut out: HVec<u8, 64> = HVec::new();
codec.encode(RgbOrder::Grb, &pixels, &mut out).unwrap();
assert!(!out.is_empty(), "encoded output should not be empty");
assert!(out.len() >= 9, "expected >=9 bytes, got {}", out.len());
}
#[test]
fn encode_output_len_matches_encoded_len() {
let codec =
SpiCodec::<Rgb, Ws2812B>::for_protocol(SpiEncodingPlan::ws2812_3bit(), false).unwrap();
let pixel_count = 3;
let pixels = [
Rgb::new(255, 0, 0),
Rgb::new(0, 255, 0),
Rgb::new(0, 0, 255),
];
let mut out: HVec<u8, 256> = HVec::new();
codec.encode(RgbOrder::Grb, &pixels, &mut out).unwrap();
assert_eq!(
out.len(),
codec.encoded_len(pixel_count),
"output len must match encoded_len prediction"
);
}
#[test]
fn encode_rejects_buffer_too_small() {
let codec =
SpiCodec::<Rgb, Ws2812B>::for_protocol(SpiEncodingPlan::ws2812_3bit(), false).unwrap();
let pixels = [Rgb::new(0, 0, 0), Rgb::new(0, 0, 0)];
let mut out: HVec<u8, 5> = HVec::new();
let err = codec.encode(RgbOrder::Grb, &pixels, &mut out).unwrap_err();
assert!(matches!(err, LedStripError::BufferTooSmall { .. }));
}
#[test]
fn inverted_codec_precomputes_patterns_correctly() {
let plan = SpiEncodingPlan::ws2812_3bit(); let codec = SpiCodec::<Rgb, Ws2812B>::for_protocol(plan, true).unwrap();
assert_eq!(codec.zero_pattern, 0b011);
assert_eq!(codec.one_pattern, 0b001);
assert_eq!(codec.reset_fill, 0xFF);
}
#[test]
fn invert_output_produces_different_data_and_reset() {
let plan = SpiEncodingPlan::ws2812_3bit();
let codec_normal = SpiCodec::<Rgb, Ws2812B>::for_protocol(plan, false).unwrap();
let codec_inverted = SpiCodec::<Rgb, Ws2812B>::for_protocol(plan, true).unwrap();
let pixels = [Rgb::new(255, 0, 0)];
let mut out_normal: HVec<u8, 128> = HVec::new();
let mut out_inverted: HVec<u8, 128> = HVec::new();
codec_normal
.encode(RgbOrder::Grb, &pixels, &mut out_normal)
.unwrap();
codec_inverted
.encode(RgbOrder::Grb, &pixels, &mut out_inverted)
.unwrap();
assert_eq!(out_normal.len(), out_inverted.len());
assert_ne!(out_normal, out_inverted);
let last_normal = *out_normal.last().unwrap();
let last_inverted = *out_inverted.last().unwrap();
assert_eq!(last_normal, 0x00, "normal reset fill should be 0x00");
assert_eq!(last_inverted, 0xFF, "inverted reset fill should be 0xFF");
}
#[test]
fn black_pixel_produces_all_zero_patterns() {
let codec =
SpiCodec::<Rgb, Ws2812B>::for_protocol(SpiEncodingPlan::ws2812_3bit(), false).unwrap();
let pixels = [Rgb::BLACK];
let mut out: HVec<u8, 128> = HVec::new();
codec.encode(RgbOrder::Grb, &pixels, &mut out).unwrap();
let payload_bytes = out.len() - codec.reset_bytes();
assert_eq!(payload_bytes, 9);
let expected_cycle: [u8; 3] = [0x92, 0x49, 0x24];
for (i, &b) in out[..payload_bytes].iter().enumerate() {
assert_eq!(
b,
expected_cycle[i % 3],
"black pixel byte {i}: expected 0x{:02X}, got 0x{b:02X}",
expected_cycle[i % 3]
);
}
}
#[test]
fn white_pixel_produces_all_one_patterns() {
let codec =
SpiCodec::<Rgb, Ws2812B>::for_protocol(SpiEncodingPlan::ws2812_3bit(), false).unwrap();
let pixels = [Rgb::WHITE];
let mut out: HVec<u8, 128> = HVec::new();
codec.encode(RgbOrder::Grb, &pixels, &mut out).unwrap();
let payload_bytes = out.len() - codec.reset_bytes();
assert_eq!(payload_bytes, 9);
let expected_cycle: [u8; 3] = [0xDB, 0x6D, 0xB6];
for (i, &b) in out[..payload_bytes].iter().enumerate() {
assert_eq!(
b,
expected_cycle[i % 3],
"white pixel byte {i}: expected 0x{:02X}, got 0x{b:02X}",
expected_cycle[i % 3]
);
}
}
#[test]
fn green_pixel_produces_mixed_patterns_grb() {
let codec =
SpiCodec::<Rgb, Ws2812B>::for_protocol(SpiEncodingPlan::ws2812_3bit(), false).unwrap();
let pixels = [Rgb::new(0, 255, 0)];
let mut out: HVec<u8, 128> = HVec::new();
codec.encode(RgbOrder::Grb, &pixels, &mut out).unwrap();
let payload_bytes = out.len() - codec.reset_bytes();
assert_eq!(payload_bytes, 9);
let ones: [u8; 3] = [0xDB, 0x6D, 0xB6];
let zeros: [u8; 3] = [0x92, 0x49, 0x24];
assert_eq!(&out[0..3], &ones, "G channel (first) should be all-ones");
assert_eq!(&out[3..6], &zeros, "R channel (second) should be all-zeros");
assert_eq!(&out[6..9], &zeros, "B channel (third) should be all-zeros");
}
#[test]
fn validate_timing_reports_first_failing_edge() {
let plan = SpiEncodingPlan::new(4_000_000, 0b100, 0b110, 3);
let err = SpiCodec::<Rgb, Ws2812B>::for_protocol(plan, false).unwrap_err();
assert!(matches!(
err,
SpiCodecPlanError::TimingOutOfTolerance {
edge: TimingEdge::ZeroLow,
..
}
));
}
#[test]
fn timing_exactly_at_tolerance_boundary_passes() {
let plan = SpiEncodingPlan::new(5_000_000, 0b1100000, 0b1111000, 7);
SpiCodec::<Rgb, Ws2812B>::for_protocol(plan, false).unwrap();
}
#[test]
fn plan_getters_return_construction_values() {
let plan = SpiEncodingPlan::new(3_000_000, 0b1010, 0b1110, 4);
assert_eq!(plan.spi_hz(), 3_000_000);
assert_eq!(plan.zero_pattern(), 0b1010);
assert_eq!(plan.one_pattern(), 0b1110);
assert_eq!(plan.bits_per_symbol(), 4);
assert_eq!(plan.extra_reset_ns(), 0);
}
#[test]
fn plan_with_extra_reset_ns_stores_value() {
let plan = SpiEncodingPlan::ws2812_3bit().with_extra_reset_ns(10_000);
assert_eq!(plan.extra_reset_ns(), 10_000);
}
#[test]
fn spi_codec_new_with_valid_plan_succeeds() {
SpiCodec::<Rgb, Ws2812B>::new(SpiEncodingPlan::ws2812_3bit(), false).unwrap();
}
#[test]
fn spi_codec_new_with_inverted_output_succeeds() {
SpiCodec::<Rgb, Ws2812B>::new(SpiEncodingPlan::ws2812_3bit(), true).unwrap();
}
#[test]
fn spi_codec_new_rejects_zero_clock() {
let plan = SpiEncodingPlan::new(0, 0b100, 0b110, 3);
let err = SpiCodec::<Rgb, Ws2812B>::new(plan, false).unwrap_err();
assert_eq!(err, SpiCodecPlanError::ZeroClock);
}
#[test]
fn spi_codec_plan_accessor_returns_original_plan() {
let plan = SpiEncodingPlan::ws2812_3bit();
let codec = SpiCodec::<Rgb, Ws2812B>::new(plan, false).unwrap();
assert_eq!(codec.plan(), plan);
}
#[test]
fn spi_backend_new() {
let backend = SpiBackend::new(42_u32);
assert_eq!(*backend.inner(), 42);
}
#[test]
fn spi_backend_into_inner() {
let backend = SpiBackend::new("hello");
assert_eq!(backend.into_inner(), "hello");
}
#[test]
fn spi_backend_inner_mut_modifies_value() {
let mut backend = SpiBackend::new(10_u32);
*backend.inner_mut() = 99;
assert_eq!(*backend.inner(), 99);
}
use core::cell::Cell;
use embedded_hal::spi::SpiBus;
#[derive(Debug, Default)]
struct MockSpi(Cell<usize>);
impl embedded_hal::spi::ErrorType for MockSpi {
type Error = core::convert::Infallible;
}
impl SpiBus<u8> for MockSpi {
fn read(&mut self, _words: &mut [u8]) -> Result<(), Self::Error> {
Ok(())
}
fn write(&mut self, words: &[u8]) -> Result<(), Self::Error> {
self.0.set(words.len());
Ok(())
}
fn transfer(&mut self, _read: &mut [u8], _write: &[u8]) -> Result<(), Self::Error> {
Ok(())
}
fn transfer_in_place(&mut self, _words: &mut [u8]) -> Result<(), Self::Error> {
Ok(())
}
fn flush(&mut self) -> Result<(), Self::Error> {
Ok(())
}
}
#[test]
fn transmit_delegates_to_spi_bus_write() {
let mut backend = SpiBackend::new(MockSpi::default());
let data = [1_u8, 2, 3, 4, 5];
backend.transmit(&data).unwrap();
assert_eq!(backend.inner().0.get(), 5);
}
use crate::{Rgb16Order, RgbwOrder, Ws2816};
#[test]
fn encode_sk6812_produces_correct_length() {
let codec =
SpiCodec::<Rgbw, Sk6812>::for_protocol(SpiEncodingPlan::sk6812_4bit(), false).unwrap();
let pixel_count = 2;
let pixels = [Rgbw::new(0, 0, 0, 0), Rgbw::new(0, 0, 0, 0)];
let mut out: HVec<u8, 256> = HVec::new();
codec.encode(RgbwOrder::Grbw, &pixels, &mut out).unwrap();
assert_eq!(out.len(), codec.encoded_len(pixel_count));
}
#[test]
fn encode_ws2811_produces_correct_length() {
let codec =
SpiCodec::<Rgb, Ws2811>::for_protocol(SpiEncodingPlan::ws2811_8bit(), false).unwrap();
let pixel_count = 2;
let pixels = [Rgb::new(0, 0, 0), Rgb::new(0, 0, 0)];
let mut out: HVec<u8, 256> = HVec::new();
codec.encode(RgbOrder::Rgb, &pixels, &mut out).unwrap();
assert_eq!(out.len(), codec.encoded_len(pixel_count));
}
#[test]
fn encode_ws2816_produces_correct_length() {
let codec =
SpiCodec::<Rgb16, Ws2816>::for_protocol(SpiEncodingPlan::ws2816_5bit(), false).unwrap();
let pixel_count = 1;
let pixels = [Rgb16::new(0, 0, 0)];
let mut out: HVec<u8, 256> = HVec::new();
codec.encode(Rgb16Order::Grb, &pixels, &mut out).unwrap();
assert_eq!(out.len(), codec.encoded_len(pixel_count));
assert_eq!(out.len(), 180);
}
#[test]
fn ws2816_black_and_white_have_different_payloads() {
let codec =
SpiCodec::<Rgb16, Ws2816>::for_protocol(SpiEncodingPlan::ws2816_5bit(), false).unwrap();
let mut black: HVec<u8, 180> = HVec::new();
let mut white: HVec<u8, 180> = HVec::new();
codec
.encode(Rgb16Order::Grb, &[Rgb16::BLACK], &mut black)
.unwrap();
codec
.encode(Rgb16Order::Grb, &[Rgb16::WHITE], &mut white)
.unwrap();
assert_ne!(&black[..30], &white[..30]);
assert_eq!(&black[30..], &[0; 150]);
assert_eq!(&white[30..], &[0; 150]);
}
#[test]
fn ws2816_rejects_the_previous_four_bit_plan() {
let plan = SpiEncodingPlan::new(4_000_000, 0b1000, 0b1100, 4);
assert_eq!(
SpiCodec::<Rgb16, Ws2816>::for_protocol(plan, false).unwrap_err(),
SpiCodecPlanError::TimingOutOfRange {
edge: TimingEdge::ZeroLow,
actual_ns: 750,
minimum_ns: 800,
maximum_ns: 1_200,
}
);
}
#[test]
fn ws2816_checks_the_bit_period_independently_of_phase_limits() {
let plan = SpiEncodingPlan::new(5_000_000, 0b100000, 0b111000, 6);
assert_eq!(
SpiCodec::<Rgb16, Ws2816>::for_protocol(plan, false).unwrap_err(),
SpiCodecPlanError::BitPeriodTooShort {
actual_ns: 1_200,
minimum_ns: 1_250,
}
);
}
#[test]
fn ws2816_does_not_round_a_short_bit_period_up_to_the_limit() {
SpiCodec::<Rgb16, Ws2816>::for_protocol(SpiEncodingPlan::ws2816_5bit(), false).unwrap();
let plan = SpiEncodingPlan::new(4_000_001, 0b10000, 0b11100, 5);
assert_eq!(
SpiCodec::<Rgb16, Ws2816>::for_protocol(plan, false).unwrap_err(),
SpiCodecPlanError::BitPeriodTooShort {
actual_ns: 1_250,
minimum_ns: 1_250,
}
);
}
#[test]
fn ws2816_accepts_inclusive_phase_boundaries() {
let plans = [
SpiEncodingPlan::new(5_000_000, 0b1000000, 0b1111000, 7),
SpiEncodingPlan::new(6_250_000, 0b11000000, 0b11111000, 8),
];
for plan in plans {
SpiCodec::<Rgb16, Ws2816>::for_protocol(plan, false).unwrap();
}
}
#[test]
fn ws2816_rejects_fractional_phase_boundary_violations() {
let cases = [
(
SpiEncodingPlan::new(5_000_001, 0b1000000, 0b1111000, 7),
TimingEdge::ZeroHigh,
),
(
SpiEncodingPlan::new(4_999_999, 0b1000000, 0b1111000, 7),
TimingEdge::ZeroLow,
),
(
SpiEncodingPlan::new(6_249_999, 0b11000000, 0b11111000, 8),
TimingEdge::ZeroHigh,
),
(
SpiEncodingPlan::new(6_250_001, 0b11000000, 0b11111000, 8),
TimingEdge::OneLow,
),
];
for (plan, expected_edge) in cases {
assert!(matches!(
SpiCodec::<Rgb16, Ws2816>::for_protocol(plan, false),
Err(SpiCodecPlanError::TimingOutOfRange { edge, .. }) if edge == expected_edge
));
}
}
#[test]
fn ws2816_checks_the_fractional_one_high_lower_boundary() {
let inside = SpiEncodingPlan::new(3_846_153, 0b10000, 0b11000, 5);
SpiCodec::<Rgb16, Ws2816>::for_protocol(inside, false).unwrap();
let outside = SpiEncodingPlan::new(3_846_154, 0b10000, 0b11000, 5);
assert_eq!(
SpiCodec::<Rgb16, Ws2816>::for_protocol(outside, false).unwrap_err(),
SpiCodecPlanError::TimingOutOfRange {
edge: TimingEdge::OneHigh,
actual_ns: 520,
minimum_ns: 520,
maximum_ns: 800,
}
);
}
#[test]
fn timing_accepts_valid_fractional_phases_without_rounding_each_spi_cycle() {
let plan = SpiEncodingPlan::new(4_284_000, 0b11000, 0b11100, 5);
SpiCodec::<Rgb, Ws2812B>::for_protocol(plan, false).unwrap();
let plan = SpiEncodingPlan::new(3_241_500, 0b11000000, 0b11110000, 8);
SpiCodec::<Rgb, Ws2811>::for_protocol(plan, false).unwrap();
}
#[test]
fn timing_rejects_fractional_phases_outside_the_legacy_tolerance() {
let plan = SpiEncodingPlan::new(2_860_000, 0b100, 0b110, 3);
assert!(matches!(
SpiCodec::<Rgb, Ws2812B>::for_protocol(plan, false),
Err(SpiCodecPlanError::TimingOutOfTolerance {
edge: TimingEdge::ZeroLow,
..
})
));
}
#[test]
fn timing_returns_an_error_for_one_hz_without_overflowing() {
let plan = SpiEncodingPlan::new(1, 0b111110, 0b100000, 6);
assert_eq!(
SpiCodec::<Rgb, Ws2812B>::for_protocol(plan, false).unwrap_err(),
SpiCodecPlanError::TimingOutOfTolerance {
edge: TimingEdge::ZeroHigh,
actual_ns: u32::MAX,
expected_ns: 400,
tolerance_ns: 150,
}
);
}
#[test]
fn constructors_reject_identical_symbols() {
let plan = SpiEncodingPlan::new(4_000_000, 0b100, 0b100, 3);
let expected = SpiCodecPlanError::IdenticalSymbolPatterns { pattern: 0b100 };
assert_eq!(
SpiCodec::<Rgb, Ws2812B>::new(plan, false).unwrap_err(),
expected
);
assert_eq!(
SpiCodec::<Rgb16, Ws2816>::for_protocol(plan, false).unwrap_err(),
expected
);
}
#[test]
fn extra_reset_ns_increases_encoded_len() {
let plan_normal = SpiEncodingPlan::ws2812_3bit();
let plan_extra = SpiEncodingPlan::ws2812_3bit().with_extra_reset_ns(100_000);
let codec_normal = SpiCodec::<Rgb, Ws2812B>::for_protocol(plan_normal, false).unwrap();
let codec_extra = SpiCodec::<Rgb, Ws2812B>::for_protocol(plan_extra, false).unwrap();
let pixel_count = 1;
let len_normal = codec_normal.encoded_len(pixel_count);
let len_extra = codec_extra.encoded_len(pixel_count);
assert!(
len_extra > len_normal,
"extra reset should increase encoded length"
);
}
#[test]
fn validate_plan_rejects_zero_bits_per_symbol() {
let plan = SpiEncodingPlan::new(2_400_000, 0b100, 0b110, 0);
let err = SpiCodec::<Rgb, Ws2812B>::new(plan, false).unwrap_err();
assert_eq!(err, SpiCodecPlanError::ZeroBitsPerSymbol);
}
#[test]
fn validate_plan_rejects_bits_per_symbol_too_wide() {
let plan = SpiEncodingPlan::new(2_400_000, 0b1, 0b1, 9);
let err = SpiCodec::<Rgb, Ws2812B>::new(plan, false).unwrap_err();
assert_eq!(
err,
SpiCodecPlanError::BitsPerSymbolTooWide { bits_per_symbol: 9 }
);
}
#[test]
fn validate_plan_rejects_zero_pattern_out_of_range() {
let plan = SpiEncodingPlan::new(2_400_000, 0b1111, 0b110, 3);
let err = SpiCodec::<Rgb, Ws2812B>::new(plan, false).unwrap_err();
assert!(matches!(
err,
SpiCodecPlanError::PatternOutOfRange {
pattern: 0b1111,
bits_per_symbol: 3,
}
));
}
#[test]
fn validate_plan_rejects_one_pattern_out_of_range() {
let plan = SpiEncodingPlan::new(2_400_000, 0b100, 0b1111, 3);
let err = SpiCodec::<Rgb, Ws2812B>::new(plan, false).unwrap_err();
assert!(matches!(
err,
SpiCodecPlanError::PatternOutOfRange {
pattern: 0b1111,
bits_per_symbol: 3,
}
));
}
#[test]
fn validate_plan_rejects_non_contiguous_waveform() {
let plan = SpiEncodingPlan::new(2_400_000, 0b101, 0b110, 3);
let err = SpiCodec::<Rgb, Ws2812B>::new(plan, false).unwrap_err();
assert!(matches!(
err,
SpiCodecPlanError::InvalidSymbolWaveform {
pattern: 0b101,
bits_per_symbol: 3,
}
));
}
#[test]
fn validate_plan_rejects_low_leading_waveform() {
let plan = SpiEncodingPlan::new(2_400_000, 0b011, 0b110, 3);
let err = SpiCodec::<Rgb, Ws2812B>::new(plan, false).unwrap_err();
assert!(matches!(
err,
SpiCodecPlanError::InvalidSymbolWaveform {
pattern: 0b011,
bits_per_symbol: 3,
}
));
}
#[test]
fn validate_plan_rejects_reset_duration_overflow() {
let plan = SpiEncodingPlan::new(u32::MAX, 0b100, 0b110, 3).with_extra_reset_ns(u32::MAX);
let err = SpiCodec::<Rgb, Ws2812B>::new(plan, false).unwrap_err();
assert!(matches!(
err,
SpiCodecPlanError::ResetDurationOverflow {
total_reset_ns: 4_295_017_295,
spi_hz: u32::MAX,
}
));
}
#[test]
fn encode_error_display_internal_consistency() {
let s = SpiEncodeError::InternalConsistency {
stage: "append_pattern_push",
required: 64,
capacity: 64,
attempted_len: 65,
}
.to_string();
assert!(s.contains("internal consistency error"), "{s}");
assert!(s.contains("append_pattern_push"), "{s}");
assert!(s.contains("attempted_len=65"), "{s}");
}
}