add support for non-blocking smart LED driver

Author: robamu

esp-hal-smartled/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name         = "esp-hal-smartled"
-version      = "0.13.1"
+version      = "0.14.0"
 edition      = "2021"
 rust-version = "1.76.0"
 description  = "RMT peripheral adapter for smart LEDs"
@@ -25,7 +25,7 @@ esp-backtrace = { version = "0.14.2", features = [
     "panic-handler",
     "println",
 ] }
-esp-println = "0.12.0"
+esp-println = { version = "0.12.0"}
 smart-leds = "0.4.0"
 
 [features]

esp-hal-smartled/examples/hello_rgb.rs

@@ -24,7 +24,7 @@
 
 use esp_backtrace as _;
 use esp_hal::{delay::Delay, gpio::Io, prelude::*, rmt::Rmt};
-use esp_hal_smartled::{smartLedBuffer, SmartLedsAdapter};
+use esp_hal_smartled::{smart_led_buffer, SmartLedsAdapter};
 use smart_leds::{
     brightness, gamma,
     hsv::{hsv2rgb, Hsv},
@@ -66,7 +66,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

@@ -34,6 +34,10 @@ use esp_hal::{
 };
 use smart_leds_trait::{SmartLedsWrite, 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.
 const SK68XX_T0L_NS: u32 = SK68XX_CODE_PERIOD - SK68XX_T0H_NS;
@@ -51,24 +55,90 @@ pub enum LedAdapterError {
     TransmissionError(RmtError),
 }
 
+fn led_pulses_for_clock(src_clock: u32) -> (u32, u32) {
+    (
+        u32::from(PulseCode {
+            level1: true,
+            length1: ((SK68XX_T0H_NS * src_clock) / 1000) as u16,
+            level2: false,
+            length2: ((SK68XX_T0L_NS * src_clock) / 1000) as u16,
+        }),
+        u32::from(PulseCode {
+            level1: true,
+            length1: ((SK68XX_T1H_NS * src_clock) / 1000) as u16,
+            level2: false,
+            length2: ((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);
     };
 }
 
+
 /// Adapter taking an RMT channel and a specific pin and providing RGB LED
 /// interaction functionality using the `smart-leds` crate
 pub struct SmartLedsAdapter<TX, const BUFFER_SIZE: usize>
@@ -94,68 +164,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: (
-                u32::from(PulseCode {
-                    level1: true,
-                    length1: ((SK68XX_T0H_NS * src_clock) / 1000) as u16,
-                    level2: false,
-                    length2: ((SK68XX_T0L_NS * src_clock) / 1000) as u16,
-                }),
-                u32::from(PulseCode {
-                    level1: true,
-                    length1: ((SK68XX_T1H_NS * src_clock) / 1000) as u16,
-                    level2: false,
-                    length2: ((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>
@@ -180,7 +199,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.
@@ -200,3 +219,98 @@ 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::PeripheralOutput,
+        peripheral::Peripheral,
+        rmt::{asynch::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: PeripheralOutput + '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),
+            }
+        }
+
+        /// 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.
+        pub async fn write(
+            &mut self,
+            led: impl IntoIterator<Item = RGB8>,
+        ) -> Result<(), LedAdapterError> {
+            self.prepare_rmt_buffer(led)?;
+            for chunk in self.rmt_buffer.chunks(RMT_RAM_ONE_LED + 1) {
+                self.channel
+                    .transmit(chunk)
+                    .await
+                    .map_err(LedAdapterError::TransmissionError)?;
+            }
+            Ok(())
+        }
+
+        fn prepare_rmt_buffer(
+            &mut self,
+            iterator: impl IntoIterator<Item = RGB8>,
+        ) -> 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, &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(())
+        }
+    }
+}