PWM WS2812B example and per sequence config

Demonstrates how to set the colour of a WS2812B to blue using PWM, and the use of multiple sequences along with their own config. This required an API change.

4 files changed, 145 insertions, 36 deletions

diff --git a/embassy-nrf/src/pwm.rs b/embassy-nrf/src/pwm.rs
index a77cd6332..21b450b19 100644
--- a/embassy-nrf/src/pwm.rs
+++ b/embassy-nrf/src/pwm.rs
@@ -45,6 +45,8 @@ pub enum Error {
     DMABufferNotInDataMemory,
 }
 
+const MAX_SEQUENCE_LEN: usize = 32767;
+
 impl<'d, T: Instance> SequencePwm<'d, T> {
     /// Creates the interface to a `SequencePwm`.
     ///
@@ -62,7 +64,7 @@ impl<'d, T: Instance> SequencePwm<'d, T> {
         ch1: impl Unborrow<Target = impl GpioOptionalPin> + 'd,
         ch2: impl Unborrow<Target = impl GpioOptionalPin> + 'd,
         ch3: impl Unborrow<Target = impl GpioOptionalPin> + 'd,
-        config: SequenceConfig,
+        config: Config,
     ) -> Result<Self, Error> {
         unborrow!(ch0, ch1, ch2, ch3);
 
@@ -117,16 +119,6 @@ impl<'d, T: Instance> SequencePwm<'d, T> {
         r.countertop
             .write(|w| unsafe { w.countertop().bits(config.max_duty) });
 
-        r.seq0.refresh.write(|w| unsafe { w.bits(config.refresh) });
-        r.seq0
-            .enddelay
-            .write(|w| unsafe { w.bits(config.end_delay) });
-
-        r.seq1.refresh.write(|w| unsafe { w.bits(config.refresh) });
-        r.seq1
-            .enddelay
-            .write(|w| unsafe { w.bits(config.end_delay) });
-
         Ok(Self {
             phantom: PhantomData,
             ch0: ch0.degrade_optional(),
@@ -136,12 +128,28 @@ impl<'d, T: Instance> SequencePwm<'d, T> {
         })
     }
 
-    /// Start or restart playback
+    /// Start or restart playback. Takes at least one sequence along with its
+    /// configuration. Optionally takes a second sequence and/or its configuration.
+    /// In the case where no second sequence is provided then the first sequence
+    /// is used. In the case where no second sequence configuration is supplied,
+    /// the first sequence configuration is used. The sequence mode applies to both
+    /// sequences combined as one.
     #[inline(always)]
-    pub fn start(&mut self, sequence: &'d [u16], times: SequenceMode) -> Result<(), Error> {
-        slice_in_ram_or(sequence, Error::DMABufferNotInDataMemory)?;
-
-        if sequence.len() > 32767 {
+    pub fn start(
+        &mut self,
+        sequence0: &'d [u16],
+        sequence_config0: SequenceConfig,
+        sequence1: Option<&'d [u16]>,
+        sequence_config1: Option<SequenceConfig>,
+        times: SequenceMode,
+    ) -> Result<(), Error> {
+        let alt_sequence = sequence1.unwrap_or(sequence0);
+        let alt_sequence_config = (&sequence_config1).as_ref().unwrap_or(&sequence_config0);
+
+        slice_in_ram_or(sequence0, Error::DMABufferNotInDataMemory)?;
+        slice_in_ram_or(alt_sequence, Error::DMABufferNotInDataMemory)?;
+
+        if sequence0.len() > MAX_SEQUENCE_LEN || alt_sequence.len() > MAX_SEQUENCE_LEN {
             return Err(Error::SequenceTooLong);
         }
 
@@ -154,18 +162,30 @@ impl<'d, T: Instance> SequencePwm<'d, T> {
         let r = T::regs();
 
         r.seq0
+            .refresh
+            .write(|w| unsafe { w.bits(sequence_config0.refresh) });
+        r.seq0
+            .enddelay
+            .write(|w| unsafe { w.bits(sequence_config0.end_delay) });
+        r.seq0
             .ptr
-            .write(|w| unsafe { w.bits(sequence.as_ptr() as u32) });
+            .write(|w| unsafe { w.bits(sequence0.as_ptr() as u32) });
         r.seq0
             .cnt
-            .write(|w| unsafe { w.bits(sequence.len() as u32) });
+            .write(|w| unsafe { w.bits(sequence0.len() as u32) });
 
         r.seq1
+            .refresh
+            .write(|w| unsafe { w.bits(alt_sequence_config.refresh) });
+        r.seq1
+            .enddelay
+            .write(|w| unsafe { w.bits(alt_sequence_config.end_delay) });
+        r.seq1
             .ptr
-            .write(|w| unsafe { w.bits(sequence.as_ptr() as u32) });
+            .write(|w| unsafe { w.bits(alt_sequence.as_ptr() as u32) });
         r.seq1
             .cnt
-            .write(|w| unsafe { w.bits(sequence.len() as u32) });
+            .write(|w| unsafe { w.bits(alt_sequence.len() as u32) });
 
         r.enable.write(|w| w.enable().enabled());
 
@@ -356,9 +376,8 @@ impl<'a, T: Instance> Drop for SequencePwm<'a, T> {
     }
 }
 
-/// Configure an infinite looping sequence for `SequencePwm`
 #[non_exhaustive]
-pub struct SequenceConfig {
+pub struct Config {
     /// Selects up mode or up-and-down mode for the counter
     pub counter_mode: CounterMode,
     /// Top value to be compared against buffer values
@@ -367,6 +386,21 @@ pub struct SequenceConfig {
     pub prescaler: Prescaler,
     /// How a sequence is read from RAM and is spread to the compare register
     pub sequence_load: SequenceLoad,
+}
+
+impl Default for Config {
+    fn default() -> Config {
+        Config {
+            counter_mode: CounterMode::Up,
+            max_duty: 1000,
+            prescaler: Prescaler::Div16,
+            sequence_load: SequenceLoad::Common,
+        }
+    }
+}
+
+#[non_exhaustive]
+pub struct SequenceConfig {
     /// Number of PWM periods to delay between each sequence sample
     pub refresh: u32,
     /// Number of PWM periods after the sequence ends before starting the next sequence
@@ -376,10 +410,6 @@ pub struct SequenceConfig {
 impl Default for SequenceConfig {
     fn default() -> SequenceConfig {
         SequenceConfig {
-            counter_mode: CounterMode::Up,
-            max_duty: 1000,
-            prescaler: Prescaler::Div16,
-            sequence_load: SequenceLoad::Common,
             refresh: 0,
             end_delay: 0,
         }
@@ -389,7 +419,12 @@ impl Default for SequenceConfig {
 /// How many times to run the sequence
 #[derive(Debug, Eq, PartialEq, Clone, Copy)]
 pub enum SequenceMode {
-    /// Run sequence n Times total
+    /// Run sequence n Times total.
+    /// 1 = Run sequence 0 once
+    /// 2 = Run sequence 0 and then sequence 1
+    /// 3 to 4 = Run sequence 0, sequence 1, sequence 0 and then sequence 1
+    /// 5 to 6 = Run sequence 0, sequence 1, sequence 0, sequence 1, sequence 0 and then sequence 1
+    /// i.e the when >= 2 the loop count is determined by dividing by 2 and rounding up
     Times(u16),
     /// Repeat until `stop` is called.
     Infinite,
diff --git a/examples/nrf/src/bin/pwm_sequence.rs b/examples/nrf/src/bin/pwm_sequence.rs
index 56c865d1c..2dcbc7475 100644
--- a/examples/nrf/src/bin/pwm_sequence.rs
+++ b/examples/nrf/src/bin/pwm_sequence.rs
@@ -8,7 +8,7 @@ use defmt::*;
 use embassy::executor::Spawner;
 use embassy::time::{Duration, Timer};
 use embassy_nrf::gpio::NoPin;
-use embassy_nrf::pwm::{Prescaler, SequenceConfig, SequenceMode, SequencePwm};
+use embassy_nrf::pwm::{Config, Prescaler, SequenceMode, SequencePwm};
 use embassy_nrf::Peripherals;
 
 #[embassy::main]
@@ -16,26 +16,39 @@ async fn main(_spawner: Spawner, p: Peripherals) {
     let seq_values_1: [u16; 5] = [1000, 250, 100, 50, 0];
     let seq_values_2: [u16; 5] = [0, 50, 100, 250, 1000];
 
-    let mut config = SequenceConfig::default();
+    let mut config = Config::default();
     config.prescaler = Prescaler::Div128;
     // 1 period is 1000 * (128/16mhz = 0.000008s = 0.008ms) = 8us
     // but say we want to hold the value for 5000ms
     // so we want to repeat our value as many times as necessary until 5000ms passes
     // want 5000/8 = 625 periods total to occur, so 624 (we get the one period for free remember)
-    config.refresh = 624;
+    let mut seq_config = Config::default();
+    seq_config.refresh = 624;
     // thus our sequence takes 5 * 5000ms or 25 seconds
 
     let mut pwm = unwrap!(SequencePwm::new(
         p.PWM0, p.P0_13, NoPin, NoPin, NoPin, config,
     ));
-    let _ = pwm.start(&seq_values_1, SequenceMode::Infinite);
+    let _ = pwm.start(
+        &seq_values_1,
+        seq_config,
+        None,
+        None,
+        SeqSequenceMode::Infinite,
+    );
 
     info!("pwm started!");
 
     Timer::after(Duration::from_millis(20000)).await;
     info!("pwm starting with another sequence!");
 
-    let _ = pwm.start(&seq_values_2, SequenceMode::Infinite);
+    let _ = pwm.start(
+        &seq_values_2,
+        seq_config,
+        None,
+        None,
+        SequenceMode::Infinite,
+    );
 
     // we can abort a sequence if we need to before its complete with pwm.stop()
     // or stop is also implicitly called when the pwm peripheral is dropped
diff --git a/examples/nrf/src/bin/pwm_sequence_ppi.rs b/examples/nrf/src/bin/pwm_sequence_ppi.rs
index f03c5716a..9523671a4 100644
--- a/examples/nrf/src/bin/pwm_sequence_ppi.rs
+++ b/examples/nrf/src/bin/pwm_sequence_ppi.rs
@@ -11,26 +11,27 @@ use embassy::executor::Spawner;
 use embassy_nrf::gpio::{Input, NoPin, Pull};
 use embassy_nrf::gpiote::{InputChannel, InputChannelPolarity};
 use embassy_nrf::ppi::Ppi;
-use embassy_nrf::pwm::{Prescaler, SequenceConfig, SequenceMode, SequencePwm};
+use embassy_nrf::pwm::{Config, Prescaler, SequenceConfig, SequenceMode, SequencePwm};
 use embassy_nrf::Peripherals;
 
 #[embassy::main]
 async fn main(_spawner: Spawner, p: Peripherals) {
     let seq_values: [u16; 5] = [1000, 250, 100, 50, 0];
 
-    let mut config = SequenceConfig::default();
+    let mut config = Config::default();
     config.prescaler = Prescaler::Div128;
     // 1 period is 1000 * (128/16mhz = 0.000008s = 0.008ms) = 8us
     // but say we want to hold the value for 250ms 250ms/8 = 31.25 periods
     // so round to 31 - 1 (we get the one period for free remember)
     // thus our sequence takes 5 * 250ms or 1.25 seconds
-    config.refresh = 30;
+    let mut seq_config = SequenceConfig::default();
+    seq_config.refresh = 30;
 
     let mut pwm = unwrap!(SequencePwm::new(
         p.PWM0, p.P0_13, NoPin, NoPin, NoPin, config,
     ));
 
-    let _ = pwm.start(&seq_values, SequenceMode::Times(1));
+    let _ = pwm.start(&seq_values, seq_config, None, None, SequenceMode::Infinite);
     // pwm.stop() deconfigures pins, and then the task_start_seq0 task cant work
     // so its going to have to start running in order load the configuration
 
diff --git a/examples/nrf/src/bin/pwm_sequence_ws2812b.rs b/examples/nrf/src/bin/pwm_sequence_ws2812b.rs
new file mode 100644
index 000000000..01afd043b
--- /dev/null
+++ b/examples/nrf/src/bin/pwm_sequence_ws2812b.rs
@@ -0,0 +1,60 @@
+#![no_std]
+#![no_main]
+#![feature(type_alias_impl_trait)]
+
+#[path = "../example_common.rs"]
+mod example_common;
+use defmt::*;
+use embassy::executor::Spawner;
+use embassy::time::{Duration, Timer};
+use embassy_nrf::gpio::NoPin;
+use embassy_nrf::pwm::{
+    Config, Prescaler, SequenceConfig, SequenceLoad, SequenceMode, SequencePwm,
+};
+use embassy_nrf::Peripherals;
+
+// WS2812B LED light demonstration. Drives just one light.
+// The following reference on WS2812B may be of use:
+// https://cdn-shop.adafruit.com/datasheets/WS2812B.pdf
+
+// In the following declarations, setting the high bit tells the PWM
+// to reverse polarity, which is what the WS2812B expects.
+
+const T1H: u16 = 0x8000 | 13; // Duty = 13/20 ticks (0.8us/1.25us) for a 1
+const T0H: u16 = 0x8000 | 7; // Duty 7/20 ticks (0.4us/1.25us) for a 0
+const RES: u16 = 0x8000;
+
+// Provides data to a WS2812b (Neopixel) LED and makes it go blue. The data
+// line is assumed to be P1_05.
+#[embassy::main]
+async fn main(_spawner: Spawner, p: Peripherals) {
+    // Declare the bits of 24 bits
+    let mut blue_seq: [u16; 8 * 3] = [
+        T0H, T0H, T0H, T0H, T0H, T0H, T0H, T0H, // G
+        T0H, T0H, T0H, T0H, T0H, T0H, T0H, T0H, // R
+        T1H, T1H, T1H, T1H, T1H, T1H, T1H, T1H, // B
+    ];
+    let reset_seq = [RES; 1];
+
+    let mut config = Config::default();
+    config.sequence_load = SequenceLoad::Common;
+    config.prescaler = Prescaler::Div1;
+    config.max_duty = 20; // 1.25us (1s / 16Mhz * 20)
+    let mut pwm = unwrap!(SequencePwm::new(
+        p.PWM0, p.P1_05, NoPin, NoPin, NoPin, config,
+    ));
+
+    let blue_seq_config = SequenceConfig::default();
+    let mut reset_seq_config = SequenceConfig::default();
+    reset_seq_config.end_delay = 799; // 50us (20 ticks * 40) - 1 tick because we've already got one RES
+    unwrap!(pwm.start(
+        &blue_seq,
+        blue_seq_config,
+        Some(&reset_seq),
+        Some(reset_seq_config),
+        SequenceMode::Times(2)
+    ));
+
+    Timer::after(Duration::from_millis(20000)).await;
+    info!("Program stopped");
+}