Merge pull request #40 from smart-leds-rs/reset_prerendered_full

Optionally include reset sequences in prerendered transactions

Author: david-sawatzke

CHANGELOG.md

@@ -5,6 +5,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+### Added
+- Add a `reset_single_transaction` feature for the `prerendered` version, which uses a single SPI transaction for a `write` call. Can be useful if using a DMA-approach or you're experiencing glitches due to the SPI peripheral turning high between the data and the reset.
+
+### Changed
+- Using the `mosi_idle_high` feature with the `prerendered` version now sends out the first reset together with the data, thus requiring a larger data buffer (but avoids potentially long dead-time between the first reset and the data being sent).
 
 ## [0.5.0] - 2024-07-29
 ### Added

Cargo.toml

@@ -20,4 +20,6 @@ embedded-hal = "1.0.0"
 
 [features]
 mosi_idle_high = []
+# Send the reset command in one single transaction
+reset_single_transaction = []
 std = []

README.md

@@ -39,7 +39,7 @@ It provides three variants:
   It may also be a timing issue with the first bit being sent, this is the case
   on the stm32f030 with 2MHz.
 
-  You could try using the `mosi_idle_high` feature, it might help.
+  You could try using the `mosi_idle_high` and `reset_single_transaction` features, they might help.
 
   If this does not help you can try different `embedded_hal::spi::Mode` parameters. For example on
   stm32f411 (as used for example on the Black Pill board) you have to set `phase` to

src/lib.rs

@@ -104,7 +104,7 @@ where
         Ok(())
     }
 
-    fn flush(&mut self) -> Result<(), E> {
+    fn reset(&mut self) -> Result<(), E> {
         // Should be > 300μs, so for an SPI Freq. of 3.8MHz, we have to send at least 1140 low bits or 140 low bytes
         for _ in 0..140 {
             self.spi.write(from_ref(&0))?;
@@ -126,7 +126,7 @@ where
         I: Into<Self::Color>,
     {
         if cfg!(feature = "mosi_idle_high") {
-            self.flush()?;
+            self.reset()?;
         }
 
         for item in iterator {
@@ -135,7 +135,7 @@ where
             self.write_byte(item.r)?;
             self.write_byte(item.b)?;
         }
-        self.flush()?;
+        self.reset()?;
         Ok(())
     }
 }
@@ -153,7 +153,7 @@ where
         I: Into<Self::Color>,
     {
         if cfg!(feature = "mosi_idle_high") {
-            self.flush()?;
+            self.reset()?;
         }
 
         for item in iterator {
@@ -163,7 +163,7 @@ where
             self.write_byte(item.b)?;
             self.write_byte(item.a.0)?;
         }
-        self.flush()?;
+        self.reset()?;
         Ok(())
     }
 }

src/prerendered.rs

@@ -8,10 +8,11 @@ use embedded_hal as hal;
 use hal::spi::{Mode, Phase, Polarity, SpiBus};
 
 use core::marker::PhantomData;
-use core::slice::from_ref;
 
 use smart_leds_trait::{SmartLedsWrite, RGB8, RGBW};
 
+const RESET_DATA_LEN: usize = 140;
+
 /// SPI mode that can be used for this crate
 ///
 /// Provided for convenience
@@ -43,16 +44,19 @@ impl<'a, SPI, E> Ws2812<'a, SPI>
 where
     SPI: SpiBus<u8, Error = E>,
 {
-    /// Use ws2812 devices via spi
+    /// Use WS2812 devices via SPI
     ///
     /// The SPI bus should run within 2 MHz to 3.8 MHz
     ///
-    /// You may need to look at the datasheet and your own hal to verify this.
+    /// You may need to look at the datasheet and your own HAL to verify this.
     ///
-    /// You need to provide a buffer `data`, whoose length is at least 12 * the
-    /// length of the led strip + 20 byes (or 40, if using the `mosi_idle_high` feature)
+    /// You need to provide a buffer `data`, whose length is at least 12 * the
+    /// length of the led strip
+    /// - + 140 bytes if using the `reset_single_transaction` feature
+    /// - + 140 bytes if using the `mosi_idle_high` feature
+    /// - + 280 bytes if using the `mosi_idle_high` and `reset_single_transaction` features
     ///
-    /// Please ensure that the mcu is pretty fast, otherwise weird timing
+    /// Please ensure that the MCU is pretty fast, otherwise weird timing
     /// issues will occur
     pub fn new(spi: SPI, data: &'a mut [u8]) -> Self {
         Self {
@@ -68,18 +72,21 @@ impl<'a, SPI, E> Ws2812<'a, SPI, devices::Sk6812w>
 where
     SPI: SpiBus<u8, Error = E>,
 {
-    /// Use sk6812w devices via spi
+    /// Use SK6812W devices via SPI
     ///
     /// The SPI bus should run within 2.3 MHz to 3.8 MHz at least.
     ///
-    /// You may need to look at the datasheet and your own hal to verify this.
+    /// You may need to look at the datasheet and your own HAL to verify this.
     ///
-    /// You need to provide a buffer `data`, whoose length is at least 12 * the
+    /// You need to provide a buffer `data`, whose length is at least 16 * the
     /// length of the led strip
+    /// - + 140 bytes if using the `reset_single_transaction` feature
+    /// - + 140 bytes if using the `mosi_idle_high` feature
+    /// - + 280 bytes if using the `mosi_idle_high` and `reset_single_transaction` features
     ///
-    /// Please ensure that the mcu is pretty fast, otherwise weird timing
+    /// Please ensure that the MCU is pretty fast, otherwise weird timing
     /// issues will occur
-    // The spi frequencies are just the limits, the available timing data isn't
+    // The SPI frequencies are just the limits, the available timing data isn't
     // complete
     pub fn new_sk6812w(spi: SPI, data: &'a mut [u8]) -> Self {
         Self {
@@ -95,7 +102,7 @@ impl<'a, SPI, D, E> Ws2812<'a, SPI, D>
 where
     SPI: SpiBus<u8, Error = E>,
 {
-    /// Write a single byte for ws2812 devices
+    /// Write a single byte for WS2812-like devices
     fn write_byte(&mut self, mut data: u8) -> Result<(), Error<E>> {
         // Send two bits in one spi byte. High time first, then the low time
         // The maximum for T0H is 500ns, the minimum for one bit 1063 ns.
@@ -114,19 +121,31 @@ where
         Ok(())
     }
 
-    fn send_data(&mut self) -> Result<(), E> {
-        if cfg!(feature = "mosi_idle_high") {
-            for _ in 0..140 {
-                self.spi.write(from_ref(&0))?;
-            }
+    /// Add a reset sequence (140 zeroes) to the data buffer
+    // Is always used for `mosi_idle_high`, as otherwise the time required to fill the buffer can lead to idle cycles on the SPI bus
+    fn write_reset(&mut self) -> Result<(), Error<E>> {
+        if self.index + RESET_DATA_LEN > self.data.len() {
+            return Err(Error::OutOfBounds);
+        }
+        for _ in 0..RESET_DATA_LEN {
+            self.data[self.index] = 0;
+            self.index += 1;
         }
+        Ok(())
+    }
 
-        self.spi.write(&self.data[..self.index])?;
-        for _ in 0..140 {
-            self.spi.write(from_ref(&0))?;
+    /// Send a reset sequence (140 zeroes) on the bus
+    fn send_reset(&mut self) -> Result<(), Error<E>> {
+        for _ in 0..RESET_DATA_LEN {
+            self.spi.write(&[0]).map_err(Error::Spi)?;
         }
+
         Ok(())
     }
+
+    fn send_data(&mut self) -> Result<(), E> {
+        self.spi.write(&self.data[..self.index])
+    }
 }
 
 impl<'a, SPI, E> SmartLedsWrite for Ws2812<'a, SPI>
@@ -135,21 +154,35 @@ where
 {
     type Error = Error<E>;
     type Color = RGB8;
-    /// Write all the items of an iterator to a ws2812 strip
+    /// Write all the items of an iterator to a WS2812 strip
     fn write<T, I>(&mut self, iterator: T) -> Result<(), Error<E>>
     where
         T: IntoIterator<Item = I>,
         I: Into<Self::Color>,
     {
         self.index = 0;
 
+        if cfg!(feature = "mosi_idle_high") {
+            self.write_reset()?;
+        }
+
         for item in iterator {
             let item = item.into();
             self.write_byte(item.g)?;
             self.write_byte(item.r)?;
             self.write_byte(item.b)?;
         }
-        self.send_data().map_err(|e| Error::Spi(e))
+
+        if cfg!(feature = "reset_single_transaction") {
+            self.write_reset()?;
+        }
+
+        self.send_data().map_err(Error::Spi)?;
+
+        if !cfg!(feature = "reset_single_transaction") {
+            self.send_reset()?;
+        }
+        Ok(())
     }
 }
 
@@ -159,21 +192,35 @@ where
 {
     type Error = Error<E>;
     type Color = RGBW<u8, u8>;
-    /// Write all the items of an iterator to a ws2812 strip
+    /// Write all the items of an iterator to a SK6812W strip
     fn write<T, I>(&mut self, iterator: T) -> Result<(), Error<E>>
     where
         T: IntoIterator<Item = I>,
         I: Into<Self::Color>,
     {
         self.index = 0;
 
+        if cfg!(feature = "mosi_idle_high") {
+            self.write_reset()?;
+        }
+
         for item in iterator {
             let item = item.into();
             self.write_byte(item.g)?;
             self.write_byte(item.r)?;
             self.write_byte(item.b)?;
             self.write_byte(item.a.0)?;
         }
-        self.send_data().map_err(|e| Error::Spi(e))
+
+        if cfg!(feature = "reset_single_transaction") {
+            self.write_reset()?;
+        }
+
+        self.send_data().map_err(Error::Spi)?;
+
+        if !cfg!(feature = "reset_single_transaction") {
+            self.send_reset()?;
+        }
+        Ok(())
     }
 }