Add non-blocking asynch smart LED driver

Author: robamu

esp-hal-smartled/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+## 0.15.0
+
+### Added
+
+- New `asynch::SmartLedsAdapter` which is an asynchronous, non-blocking version of the driver.
+
+## 0.14.0
+
+## 0.13.1
+
 ### Added
 
 ### Changed

esp-hal-smartled/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name         = "esp-hal-smartled"
-version      = "0.14.0"
+version      = "0.15.0"
 edition      = "2021"
 rust-version = "1.84.0"
 description  = "RMT peripheral adapter for smart LEDs"
@@ -16,7 +16,7 @@ defmt             = { version = "0.3.10", optional = true }
 document-features = "0.2.10"
 esp-hal           = "0.23.1"
 fugit             = "0.3.7"
-smart-leds-trait  = "0.3.0"
+smart-leds-trait  = "0.3.1"
 
 [dev-dependencies]
 cfg-if = "1.0.0"

esp-hal-smartled/examples/hello_rgb.rs

@@ -24,7 +24,7 @@
 
 use esp_backtrace as _;
 use esp_hal::{delay::Delay, main, rmt::Rmt, time::RateExtU32};
-use esp_hal_smartled::{smartLedBuffer, SmartLedsAdapter};
+use esp_hal_smartled::{smart_led_buffer, SmartLedsAdapter};
 use smart_leds::{
     brightness, gamma,
     hsv::{hsv2rgb, Hsv},
@@ -64,7 +64,7 @@ fn main() -> ! {
 
     // We use one of the RMT channels to instantiate a `SmartLedsAdapter` which can
     // be used directly with all `smart_led` implementations
-    let rmt_buffer = smartLedBuffer!(1);
+    let rmt_buffer = smart_led_buffer!(1);
     let mut led = SmartLedsAdapter::new(rmt.channel0, led_pin, rmt_buffer);
 
     let delay = Delay::new();

esp-hal-smartled/src/lib.rs

@@ -31,7 +31,11 @@ use esp_hal::{
     peripheral::Peripheral,
     rmt::{Error as RmtError, PulseCode, TxChannel, TxChannelConfig, TxChannelCreator},
 };
-use smart_leds_trait::{SmartLedsWrite, RGB8};
+use smart_leds_trait::{SmartLedsWrite, SmartLedsWriteAsync, RGB8};
+
+// Required RMT RAM to drive one LED.
+// number of channels (r,g,b -> 3) * pulses per channel 8)
+const RMT_RAM_ONE_LED: usize = 3 * 8;
 
 const SK68XX_CODE_PERIOD: u32 = 1250; // 800kHz
 const SK68XX_T0H_NS: u32 = 400; // 300ns per SK6812 datasheet, 400 per WS2812. Some require >350ns for T0H. Others <500ns for T0H.
@@ -56,21 +60,86 @@ impl From<RmtError> for LedAdapterError {
     }
 }
 
+fn led_pulses_for_clock(src_clock: u32) -> (u32, u32) {
+    (
+        PulseCode::new(
+            true,
+            ((SK68XX_T0H_NS * src_clock) / 1000) as u16,
+            false,
+            ((SK68XX_T0L_NS * src_clock) / 1000) as u16,
+        ),
+        PulseCode::new(
+            true,
+            ((SK68XX_T1H_NS * src_clock) / 1000) as u16,
+            false,
+            ((SK68XX_T1L_NS * src_clock) / 1000) as u16,
+        ),
+    )
+}
+
+fn led_config() -> TxChannelConfig {
+    TxChannelConfig {
+        clk_divider: 1,
+        idle_output_level: false,
+        carrier_modulation: false,
+        idle_output: true,
+
+        ..TxChannelConfig::default()
+    }
+}
+
+fn convert_rgb_to_pulses(
+    value: RGB8,
+    mut_iter: &mut IterMut<u32>,
+    pulses: (u32, u32),
+) -> Result<(), LedAdapterError> {
+    convert_rgb_channel_to_pulses(value.g, mut_iter, pulses)?;
+    convert_rgb_channel_to_pulses(value.r, mut_iter, pulses)?;
+    convert_rgb_channel_to_pulses(value.b, mut_iter, pulses)?;
+    Ok(())
+}
+
+fn convert_rgb_channel_to_pulses(
+    channel_value: u8,
+    mut_iter: &mut IterMut<u32>,
+    pulses: (u32, u32),
+) -> Result<(), LedAdapterError> {
+    for position in [128, 64, 32, 16, 8, 4, 2, 1] {
+        *mut_iter.next().ok_or(LedAdapterError::BufferSizeExceeded)? =
+            match channel_value & position {
+                0 => pulses.0,
+                _ => pulses.1,
+            }
+    }
+
+    Ok(())
+}
+
+/// Function to calculate the required RMT buffer size for a given number of LEDs when using
+/// the blocking API.
+pub const fn buffer_size(num_leds: usize) -> usize {
+    // 1 additional pulse for the end delimiter
+    num_leds * RMT_RAM_ONE_LED + 1
+}
+
 /// Macro to allocate a buffer sized for a specific number of LEDs to be
 /// addressed.
 ///
 /// Attempting to use more LEDs that the buffer is configured for will result in
 /// an `LedAdapterError:BufferSizeExceeded` error.
 #[macro_export]
+macro_rules! smart_led_buffer {
+    ( $num_leds: expr ) => {
+        [0u32; $crate::buffer_size($num_leds)]
+    };
+}
+
+/// Deprecated alias for [smart_led_buffer] macro.
+#[macro_export]
+#[deprecated]
 macro_rules! smartLedBuffer {
-    ( $buffer_size: literal ) => {
-        // The size we're assigning here is calculated as following
-        //  (
-        //   Nr. of LEDs
-        //   * channels (r,g,b -> 3)
-        //   * pulses per channel 8)
-        //  ) + 1 additional pulse for the end delimiter
-        [0u32; $buffer_size * 24 + 1]
+    ( $num_leds: expr ) => {
+        smart_led_buffer!($num_leds);
     };
 }
 
@@ -99,68 +168,17 @@ where
         O: OutputPin + 'd,
         C: TxChannelCreator<'d, TX, O>,
     {
-        let config = TxChannelConfig {
-            clk_divider: 1,
-            idle_output_level: false,
-            carrier_modulation: false,
-            idle_output: true,
-
-            ..TxChannelConfig::default()
-        };
-
-        let channel = channel.configure(pin, config).unwrap();
+        let channel = channel.configure(pin, led_config()).unwrap();
 
         // Assume the RMT peripheral is set up to use the APB clock
-        let clocks = Clocks::get();
-        let src_clock = clocks.apb_clock.to_MHz();
+        let src_clock = Clocks::get().apb_clock.to_MHz();
 
         Self {
             channel: Some(channel),
             rmt_buffer,
-            pulses: (
-                PulseCode::new (
-                    true,
-                    ((SK68XX_T0H_NS * src_clock) / 1000) as u16,
-                    false,
-                    ((SK68XX_T0L_NS * src_clock) / 1000) as u16,
-                ),
-                PulseCode::new (
-                    true,
-                    ((SK68XX_T1H_NS * src_clock) / 1000) as u16,
-                    false,
-                    ((SK68XX_T1L_NS * src_clock) / 1000) as u16,
-                ),
-            ),
+            pulses: led_pulses_for_clock(src_clock),
         }
     }
-
-    fn convert_rgb_to_pulse(
-        value: RGB8,
-        mut_iter: &mut IterMut<u32>,
-        pulses: (u32, u32),
-    ) -> Result<(), LedAdapterError> {
-        Self::convert_rgb_channel_to_pulses(value.g, mut_iter, pulses)?;
-        Self::convert_rgb_channel_to_pulses(value.r, mut_iter, pulses)?;
-        Self::convert_rgb_channel_to_pulses(value.b, mut_iter, pulses)?;
-
-        Ok(())
-    }
-
-    fn convert_rgb_channel_to_pulses(
-        channel_value: u8,
-        mut_iter: &mut IterMut<u32>,
-        pulses: (u32, u32),
-    ) -> Result<(), LedAdapterError> {
-        for position in [128, 64, 32, 16, 8, 4, 2, 1] {
-            *mut_iter.next().ok_or(LedAdapterError::BufferSizeExceeded)? =
-                match channel_value & position {
-                    0 => pulses.0,
-                    _ => pulses.1,
-                }
-        }
-
-        Ok(())
-    }
 }
 
 impl<TX, const BUFFER_SIZE: usize> SmartLedsWrite for SmartLedsAdapter<TX, BUFFER_SIZE>
@@ -185,7 +203,7 @@ where
         // This will result in an `BufferSizeExceeded` error in case
         // the iterator provides more elements than the buffer can take.
         for item in iterator {
-            Self::convert_rgb_to_pulse(item.into(), &mut seq_iter, self.pulses)?;
+            convert_rgb_to_pulses(item.into(), &mut seq_iter, self.pulses)?;
         }
 
         // Finally, add an end element.
@@ -205,3 +223,106 @@ where
         }
     }
 }
+
+/// Support for asynchronous and non-blocking use of the RMT peripheral to drive smart LEDs.
+pub mod asynch {
+    use super::*;
+    use esp_hal::{
+        clock::Clocks,
+        gpio::OutputPin,
+        peripheral::Peripheral,
+        rmt::{TxChannelAsync, TxChannelCreatorAsync},
+    };
+
+    /// Function to calculate the required RMT buffer size for a given number of LEDs when using
+    /// the asynchronous API.
+    pub const fn buffer_size(num_leds: usize) -> usize {
+        // 1 byte end delimiter for each transfer.
+        num_leds * (RMT_RAM_ONE_LED + 1)
+    }
+
+    /// Adapter taking an RMT channel and a specific pin and providing RGB LED
+    /// interaction functionality.
+    pub struct SmartLedAdapterAsync<Tx, const BUFFER_SIZE: usize> {
+        channel: Tx,
+        rmt_buffer: [u32; BUFFER_SIZE],
+        pulses: (u32, u32),
+    }
+
+    impl<'d, Tx: TxChannelAsync, const BUFFER_SIZE: usize> SmartLedAdapterAsync<Tx, BUFFER_SIZE> {
+        /// Create a new adapter object that drives the pin using the RMT channel.
+        pub fn new<C, O>(
+            channel: C,
+            pin: impl Peripheral<P = O> + 'd,
+            rmt_buffer: [u32; BUFFER_SIZE],
+        ) -> SmartLedAdapterAsync<Tx, BUFFER_SIZE>
+        where
+            O: OutputPin + 'd,
+            C: TxChannelCreatorAsync<'d, Tx, O>,
+        {
+            let channel = channel.configure(pin, led_config()).unwrap();
+
+            // Assume the RMT peripheral is set up to use the APB clock
+            let src_clock = Clocks::get().apb_clock.to_MHz();
+
+            Self {
+                channel,
+                rmt_buffer,
+                pulses: led_pulses_for_clock(src_clock),
+            }
+        }
+
+        fn prepare_rmt_buffer<I: Into<RGB8>>(
+            &mut self,
+            iterator: impl IntoIterator<Item = I>,
+        ) -> Result<(), LedAdapterError> {
+            // We always start from the beginning of the buffer
+            let mut seq_iter = self.rmt_buffer.iter_mut();
+
+            // Add all converted iterator items to the buffer.
+            // This will result in an `BufferSizeExceeded` error in case
+            // the iterator provides more elements than the buffer can take.
+            for item in iterator {
+                Self::convert_rgb_to_pulse(item.into(), &mut seq_iter, self.pulses)?;
+            }
+            Ok(())
+        }
+
+        /// Converts a RGB value to the correspodnign pulse value.
+        fn convert_rgb_to_pulse(
+            value: RGB8,
+            mut_iter: &mut IterMut<u32>,
+            pulses: (u32, u32),
+        ) -> Result<(), LedAdapterError> {
+            convert_rgb_to_pulses(value, mut_iter, pulses)?;
+            *mut_iter.next().ok_or(LedAdapterError::BufferSizeExceeded)? = 0;
+
+            Ok(())
+        }
+    }
+
+    impl<Tx: TxChannelAsync, const BUFFER_SIZE: usize> SmartLedsWriteAsync
+        for SmartLedAdapterAsync<Tx, BUFFER_SIZE>
+    {
+        type Error = LedAdapterError;
+        type Color = RGB8;
+
+        /// Convert all RGB8 items of the iterator to the RMT format and
+        /// add them to internal buffer, then start perform all asynchronous operations based on
+        /// that buffer.
+        async fn write<T, I>(&mut self, iterator: T) -> Result<(), Self::Error>
+        where
+            T: IntoIterator<Item = I>,
+            I: Into<Self::Color>,
+        {
+            self.prepare_rmt_buffer(iterator)?;
+            for chunk in self.rmt_buffer.chunks(RMT_RAM_ONE_LED + 1) {
+                self.channel
+                    .transmit(chunk)
+                    .await
+                    .map_err(LedAdapterError::TransmissionError)?;
+            }
+            Ok(())
+        }
+    }
+}