Merge #537

537: Documents the nRF BufferedUarte problem r=Dirbaio a=huntc

Please see https://github.com/embassy-rs/embassy/issues/536 for the rationale.

Co-authored-by: huntc <[email protected]>

3 files changed, 18 insertions, 7 deletions

diff --git a/embassy-nrf/src/buffered_uarte.rs b/embassy-nrf/src/buffered_uarte.rs
index e3ca74384..45e8afc4b 100644
--- a/embassy-nrf/src/buffered_uarte.rs
+++ b/embassy-nrf/src/buffered_uarte.rs
@@ -1,6 +1,17 @@
 //! Async buffered UART
 //!
-//! Please ee [uarte] to understand when [BufferedUarte] should be used.
+//! WARNING!!! The functionality provided here is intended to be used only
+//! in situations where hardware flow control are available i.e. CTS and RTS.
+//! This is a problem that should be addressed at a later stage and can be
+//! fully explained at https://github.com/embassy-rs/embassy/issues/536.
+//!
+//! Note that discarding a future from a read or write operation may lead to losing
+//! data. For example, when using `futures_util::future::select` and completion occurs
+//! on the "other" future, you should capture the incomplete future and continue to use
+//! it for the next read or write. This pattern is a consideration for all IO, and not
+//! just serial communications.
+//!
+//! Please also see [crate::uarte] to understand when [BufferedUarte] should be used.
 
 use core::cmp::min;
 use core::marker::PhantomData;
diff --git a/embassy-nrf/src/uarte.rs b/embassy-nrf/src/uarte.rs
index 72dcd41b2..ff781cabd 100644
--- a/embassy-nrf/src/uarte.rs
+++ b/embassy-nrf/src/uarte.rs
@@ -2,14 +2,14 @@
 
 //! Async UART
 //!
-//! Async UART is provided in two flavors - this one and also [buffered_uarte::BufferedUarte].
+//! Async UART is provided in two flavors - this one and also [crate::buffered_uarte::BufferedUarte].
 //! The [Uarte] here is useful for those use-cases where reading the UARTE peripheral is
 //! exclusively awaited on. If the [Uarte] is required to be awaited on with some other future,
 //! for example when using `futures_util::future::select`, then you should consider
-//! [buffered_uarte::BufferedUarte] so that reads may continue while processing these
+//! [crate::buffered_uarte::BufferedUarte] so that reads may continue while processing these
 //! other futures. If you do not then you may lose data between reads.
 //!
-//! An advantage of the [Uarte] has over [buffered_uarte::BufferedUarte] is that less
+//! An advantage of the [Uarte] has over [crate::buffered_uarte::BufferedUarte] is that less
 //! memory may be used given that buffers are passed in directly to its read and write
 //! methods.
 
diff --git a/examples/nrf/src/bin/buffered_uart.rs b/examples/nrf/src/bin/buffered_uart.rs
index c3e07e44a..a2602ea6c 100644
--- a/examples/nrf/src/bin/buffered_uart.rs
+++ b/examples/nrf/src/bin/buffered_uart.rs
@@ -8,7 +8,6 @@ mod example_common;
 use embassy::executor::Spawner;
 use embassy::io::{AsyncBufReadExt, AsyncWriteExt};
 use embassy_nrf::buffered_uarte::State;
-use embassy_nrf::gpio::NoPin;
 use embassy_nrf::{buffered_uarte::BufferedUarte, interrupt, uarte, Peripherals};
 use example_common::*;
 use futures::pin_mut;
@@ -24,6 +23,7 @@ async fn main(_spawner: Spawner, p: Peripherals) {
 
     let irq = interrupt::take!(UARTE0_UART0);
     let mut state = State::new();
+    // Please note - important to have hardware flow control (https://github.com/embassy-rs/embassy/issues/536)
     let u = BufferedUarte::new(
         &mut state,
         p.UARTE0,
@@ -33,8 +33,8 @@ async fn main(_spawner: Spawner, p: Peripherals) {
         irq,
         p.P0_08,
         p.P0_06,
-        NoPin,
-        NoPin,
+        p.P0_07,
+        p.P0_05,
         config,
         &mut rx_buffer,
         &mut tx_buffer,