Merge #346

346: async: add digital::Wait. r=ryankurte a=Dirbaio

Add `digital::Wait` trait.

This is the previously proposed `WaitForX` traits, unified in a single one supporting both edge-triggered and level-triggered waits.

It is possible to software-emulate edge-triggered out of level-triggered hardware and vice-versa, so requiring support for both shouldn't make it unimplementable for any MCU. It is a good thing to require both: for example, stm32 EXTI is edge-triggered, but drivers usually want level-triggered. It'd be bad if a HAL decided "the hardware only supports edge-triggered, so I'm only going to impl edge-triggered!".

Impl for nRF's GPIOTE here: https://github.com/embassy-rs/embassy/blob/master/embassy-nrf/src/gpiote.rs
Impl for STM32's EXTI here: https://github.com/embassy-rs/embassy/blob/master/embassy-stm32/src/exti.rs

(impls still not unified, but unifying shouldn't be an issue).

Co-authored-by: Dario Nieuwenhuis <[email protected]>

Author: bors[bot]

embedded-hal-async/src/digital.rs

@@ -0,0 +1,76 @@
+//! Asynchronous digital I/O
+//!
+//! # Example
+//!
+//! ```rust
+//! # use embedded_hal_async::digital::Wait;
+//! /// Asynchronously wait until the `ready_pin` becomes high.
+//! async fn wait_until_ready<P>(ready_pin: &mut P)
+//! where
+//!     P: Wait,
+//! {
+//!     ready_pin
+//!         .wait_for_high()
+//!         .await
+//!         .expect("failed to await input pin")
+//! }
+//! ```
+
+use core::future::Future;
+
+/// Asynchronously wait for GPIO pin state.
+pub trait Wait: embedded_hal::digital::ErrorType {
+    /// The future returned by the `wait_for_high` function.
+    type WaitForHighFuture<'a>: Future<Output = Result<(), Self::Error>> + 'a
+    where
+        Self: 'a;
+
+    /// Wait until the pin is high. If it is already high, return immediately.
+    ///
+    /// # Note for implementers
+    /// The pin may have switched back to low before the task was run after
+    /// being woken. The future should still resolve in that case.
+    fn wait_for_high<'a>(&'a mut self) -> Self::WaitForHighFuture<'a>;
+
+    /// The future returned by `wait_for_low`.
+    type WaitForLowFuture<'a>: Future<Output = Result<(), Self::Error>> + 'a
+    where
+        Self: 'a;
+
+    /// Wait until the pin is low. If it is already low, return immediately.
+    ///
+    /// # Note for implementers
+    /// The pin may have switched back to high before the task was run after
+    /// being woken. The future should still resolve in that case.
+    fn wait_for_low<'a>(&'a mut self) -> Self::WaitForLowFuture<'a>;
+
+    /// The future returned from `wait_for_rising_edge`.
+    type WaitForRisingEdgeFuture<'a>: Future<Output = Result<(), Self::Error>> + 'a
+    where
+        Self: 'a;
+
+    /// Wait for the pin to undergo a transition from low to high.
+    ///
+    /// If the pin is already low, this does *not* return immediately, it'll wait for the
+    /// pin to go high and then low again.
+    fn wait_for_rising_edge<'a>(&'a mut self) -> Self::WaitForRisingEdgeFuture<'a>;
+
+    /// The future returned from `wait_for_falling_edge`.
+    type WaitForFallingEdgeFuture<'a>: Future<Output = Result<(), Self::Error>> + 'a
+    where
+        Self: 'a;
+
+    /// Wait for the pin to undergo a transition from high to low.
+    ///
+    /// If the pin is already low, this does *not* return immediately, it'll wait for the
+    /// pin to go high and then low again.
+    fn wait_for_falling_edge<'a>(&'a mut self) -> Self::WaitForFallingEdgeFuture<'a>;
+
+    /// The future returned from `wait_for_any_edge`.
+    type WaitForAnyEdgeFuture<'a>: Future<Output = Result<(), Self::Error>> + 'a
+    where
+        Self: 'a;
+
+    /// Wait for the pin to undergo any transition, i.e low to high OR high to low.
+    fn wait_for_any_edge<'a>(&'a mut self) -> Self::WaitForAnyEdgeFuture<'a>;
+}

embedded-hal-async/src/lib.rs

@@ -12,4 +12,5 @@
 #![feature(generic_associated_types)]
 
 pub mod delay;
+pub mod digital;
 pub mod i2c;