From 2498fbdf52e1477ffbfcd8fafba1b04edaf8bc8c Mon Sep 17 00:00:00 2001 From: Vasil Nikolov Date: Tue, 9 Jan 2024 00:26:48 +0200 Subject: [PATCH 1/4] add example of pin sharing between tasks --- examples/rp/src/bin/blinky_two_tasks.rs | 61 +++++++++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 examples/rp/src/bin/blinky_two_tasks.rs diff --git a/examples/rp/src/bin/blinky_two_tasks.rs b/examples/rp/src/bin/blinky_two_tasks.rs new file mode 100644 index 000000000..d6c23b546 --- /dev/null +++ b/examples/rp/src/bin/blinky_two_tasks.rs @@ -0,0 +1,61 @@ +#![no_std] +#![no_main] +/// This example demonstrates how to access a given pin from more than one embassy task +/// The on-board LED is toggled by two tasks with slightly different periods, leading to the +/// apparent duty cycle of the LED increasing, then decreasing, linearly. The phenomenon is similar +/// to interference and the 'beats' you can hear if you play two frequencies close to one another +/// [Link explaining it](https://www.physicsclassroom.com/class/sound/Lesson-3/Interference-and-Beats) +use defmt::*; +use embassy_executor::Spawner; +use embassy_rp::{gpio, PeripheralRef}; +use embassy_sync::blocking_mutex::raw::ThreadModeRawMutex; +use embassy_sync::mutex::Mutex; +use embassy_time::Duration; +use embassy_time::{Ticker, Timer}; +use gpio::{AnyPin, Level, Output}; +use {defmt_rtt as _, panic_probe as _}; + +type LedType = Mutex>>>; +static LED: LedType = Mutex::new(None); + +#[embassy_executor::main] +async fn main(spawner: Spawner) { + let p = embassy_rp::init(Default::default()); + // set the content of the global LED reference to the real LED pin + let led = Output::new(AnyPin::from(p.PIN_25), Level::High); + // inner scope is so that once the mutex is written to, the MutexGuard is dropped, thus the + // Mutex is released + { + *(LED.lock().await) = Some(PeripheralRef::new(led)); + } + let dt = 100 * 1_000_000; + let k = 1.003; + + unwrap!(spawner.spawn(toggle(&LED, Duration::from_nanos(dt)))); + unwrap!(spawner.spawn(toggle_slightly_slower( + &LED, + Duration::from_nanos((dt as f64 * k) as u64) + ))); +} + +async fn toggle_led(led: &'static LedType, delay: Duration) { + let mut ticker = Ticker::every(delay); + loop { + { + let mut led_unlocked = led.lock().await; + if let Some(pin_ref) = led_unlocked.as_mut() { + pin_ref.toggle(); + } + } + ticker.next().await; + } +} +#[embassy_executor::task] +async fn toggle(led: &'static LedType, delay: Duration) { + toggle_led(led, delay).await +} + +#[embassy_executor::task] +async fn toggle_slightly_slower(led: &'static LedType, delay: Duration) { + toggle_led(led, delay).await +} From ebf46d37aa7b8fd103c6d6008879f89f01cde70a Mon Sep 17 00:00:00 2001 From: Vasil Nikolov Date: Tue, 9 Jan 2024 00:35:11 +0200 Subject: [PATCH 2/4] remove unused import --- examples/rp/src/bin/blinky_two_tasks.rs | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/examples/rp/src/bin/blinky_two_tasks.rs b/examples/rp/src/bin/blinky_two_tasks.rs index d6c23b546..6b4d35165 100644 --- a/examples/rp/src/bin/blinky_two_tasks.rs +++ b/examples/rp/src/bin/blinky_two_tasks.rs @@ -10,8 +10,7 @@ use embassy_executor::Spawner; use embassy_rp::{gpio, PeripheralRef}; use embassy_sync::blocking_mutex::raw::ThreadModeRawMutex; use embassy_sync::mutex::Mutex; -use embassy_time::Duration; -use embassy_time::{Ticker, Timer}; +use embassy_time::{Duration, Ticker}; use gpio::{AnyPin, Level, Output}; use {defmt_rtt as _, panic_probe as _}; From 4843c060d0fcad11eb639558ccbf18d6362e94c1 Mon Sep 17 00:00:00 2001 From: Vasil Nikolov Date: Wed, 10 Jan 2024 00:47:45 +0200 Subject: [PATCH 3/4] no need for a PeripheralRef --- examples/rp/src/bin/blinky_two_tasks.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/examples/rp/src/bin/blinky_two_tasks.rs b/examples/rp/src/bin/blinky_two_tasks.rs index 6b4d35165..7e0b531e1 100644 --- a/examples/rp/src/bin/blinky_two_tasks.rs +++ b/examples/rp/src/bin/blinky_two_tasks.rs @@ -7,14 +7,14 @@ /// [Link explaining it](https://www.physicsclassroom.com/class/sound/Lesson-3/Interference-and-Beats) use defmt::*; use embassy_executor::Spawner; -use embassy_rp::{gpio, PeripheralRef}; +use embassy_rp::gpio; use embassy_sync::blocking_mutex::raw::ThreadModeRawMutex; use embassy_sync::mutex::Mutex; use embassy_time::{Duration, Ticker}; use gpio::{AnyPin, Level, Output}; use {defmt_rtt as _, panic_probe as _}; -type LedType = Mutex>>>; +type LedType = Mutex>>; static LED: LedType = Mutex::new(None); #[embassy_executor::main] @@ -25,7 +25,7 @@ async fn main(spawner: Spawner) { // inner scope is so that once the mutex is written to, the MutexGuard is dropped, thus the // Mutex is released { - *(LED.lock().await) = Some(PeripheralRef::new(led)); + *(LED.lock().await) = Some(led); } let dt = 100 * 1_000_000; let k = 1.003; From 781e33023e3755bddecba23fb3c2dab10e16ccc6 Mon Sep 17 00:00:00 2001 From: Vasil Nikolov Date: Wed, 10 Jan 2024 00:49:54 +0200 Subject: [PATCH 4/4] add draft doc page for peripheral sharing --- docs/modules/ROOT/nav.adoc | 1 + .../ROOT/pages/sharing_peripherals.adoc | 78 +++++++++++++++++++ 2 files changed, 79 insertions(+) create mode 100644 docs/modules/ROOT/pages/sharing_peripherals.adoc diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index fabb80e31..b692c44e1 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -6,6 +6,7 @@ * xref:layer_by_layer.adoc[Bare metal to async] * xref:runtime.adoc[Executor] * xref:delaying_a_task.adoc[Delaying a Task] +* xref:sharing_peripherals.adoc[Sharing peripherals between tasks] * xref:hal.adoc[HAL] ** xref:nrf.adoc[nRF] ** xref:stm32.adoc[STM32] diff --git a/docs/modules/ROOT/pages/sharing_peripherals.adoc b/docs/modules/ROOT/pages/sharing_peripherals.adoc new file mode 100644 index 000000000..41f467942 --- /dev/null +++ b/docs/modules/ROOT/pages/sharing_peripherals.adoc @@ -0,0 +1,78 @@ += Sharing peripherals between tasks + +Often times, more than one task needs access to the same resource (pin, communication interface, etc.). The following example shows how to use the on-board LED on a Raspberry Pi Pico board by two tasks simultaneously. + +[,rust] +---- +use defmt::*; +use embassy_executor::Spawner; +use embassy_rp::gpio; +use embassy_sync::blocking_mutex::raw::ThreadModeRawMutex; +use embassy_sync::mutex::Mutex; +use embassy_time::{Duration, Ticker}; +use gpio::{AnyPin, Level, Output}; +use {defmt_rtt as _, panic_probe as _}; + +type LedType = Mutex>>; +static LED: LedType = Mutex::new(None); + +#[embassy_executor::main] +async fn main(spawner: Spawner) { + let p = embassy_rp::init(Default::default()); + // set the content of the global LED reference to the real LED pin + let led = Output::new(AnyPin::from(p.PIN_25), Level::High); + // inner scope is so that once the mutex is written to, the MutexGuard is dropped, thus the + // Mutex is released + { + *(LED.lock().await) = Some(led); + } + let dt = 100 * 1_000_000; + let k = 1.003; + + unwrap!(spawner.spawn(toggle(&LED, Duration::from_nanos(dt)))); + unwrap!(spawner.spawn(toggle_slightly_slower( + &LED, + Duration::from_nanos((dt as f64 * k) as u64) + ))); +} + +async fn toggle_led(led: &'static LedType, delay: Duration) { + let mut ticker = Ticker::every(delay); + loop { + { + let mut led_unlocked = led.lock().await; + if let Some(pin_ref) = led_unlocked.as_mut() { + pin_ref.toggle(); + } + } + ticker.next().await; + } +} +#[embassy_executor::task] +async fn toggle(led: &'static LedType, delay: Duration) { + toggle_led(led, delay).await +} + +#[embassy_executor::task] +async fn toggle_slightly_slower(led: &'static LedType, delay: Duration) { + toggle_led(led, delay).await +} +---- + +The structure facilitating access to the resource is the defined `LedType`. + +== Why so complicated + +Unwrapping the layers gives insight into why each one is needed. + +=== `Mutex` + +The mutex is there so if one task gets the resource first and begins modifying it, all other tasks wanting to write will have to wait (the `led.lock().await` will return immediately if no task has locked the mutex, and will block if it is accessed somewhere else). + +=== `Option` + +The `LED` variable needs to be defined outside the main task as references accepted by tasks need to be `'static`. However, if it is outside the main task, it cannot be initialised to point to any pin, as the pins themselves are not initialised. Thus, it is set to `None`. + +=== `Output` + +To indicate that the pin will be set to an Output. The `AnyPin` could have been `embassy_rp::peripherals::PIN_25`, however this option lets the `toggle_led` function be more generic.