Add non-blocking asynch smart LED driver

robamu · robamu · commit f083668e0c21 · 2025-02-05T11:52:03.000+01:00
diff --git a/esp-hal-smartled/CHANGELOG.md b/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 `SmartLedsAdapterAsync` which is an asynchronous, non-blocking version of the driver.
+
+## 0.14.0
+
+## 0.13.1
+
 ### Added
 
 ### Changed
diff --git a/esp-hal-smartled/Cargo.toml b/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"
diff --git a/esp-hal-smartled/examples/hello_rgb.rs b/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();
diff --git a/esp-hal-smartled/src/lib.rs b/esp-hal-smartled/src/lib.rs
@@ -29,9 +29,16 @@ use esp_hal::{
     clock::Clocks,
     gpio::OutputPin,
     peripheral::Peripheral,
-    rmt::{Error as RmtError, PulseCode, TxChannel, TxChannelConfig, TxChannelCreator},
+    rmt::{
+        Error as RmtError, PulseCode, TxChannel, TxChannelAsync, TxChannelConfig, TxChannelCreator,
+        TxChannelCreatorAsync,
+    },
 };
-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 +63,89 @@ 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.
+///
+/// This buffer size is calculated for the synchronous API provided by the [SmartLedsAdapter].
+/// [buffer_size_async] should be used for the asynchronous 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,67 +174,16 @@ 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,
-                ),
-            ),
-        }
-    }
-
-    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,
-                }
+            pulses: led_pulses_for_clock(src_clock),
         }
-
-        Ok(())
     }
 }
 
@@ -185,7 +209,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 +229,98 @@ where
         }
     }
 }
+
+/// Support for asynchronous and non-blocking use of the RMT peripheral to drive smart LEDs.
+
+/// Function to calculate the required RMT buffer size for a given number of LEDs when using
+/// the asynchronous API. This buffer size is calculated for the asynchronous API provided by the
+/// [SmartLedsAdapterAsync]. [buffer_size] should be used for the synchronous API.
+pub const fn buffer_size_async(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 SmartLedsAdapterAsync<Tx, const BUFFER_SIZE: usize> {
+    channel: Tx,
+    rmt_buffer: [u32; BUFFER_SIZE],
+    pulses: (u32, u32),
+}
+
+impl<'d, Tx: TxChannelAsync, const BUFFER_SIZE: usize> SmartLedsAdapterAsync<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],
+    ) -> SmartLedsAdapterAsync<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 SmartLedsAdapterAsync<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(())
+    }
+}
