feat: uart break send + detect (#4284)

* feat: uart break send + detect

* fix: example configs

* fix: not needed directives

* fix: instability::unstable; one line doc comment

* Update esp-hal/CHANGELOG.md

Co-authored-by: Dániel Buga <[email protected]>

* fix: fold in hil test

* chore: remove old test from toml

* feat: add missing `wait_for_break` fn

* fix: self.regs

* feat: wait_for_break with timeout + async

* chore: fmt

* fix: pins now match embassy_serial example

* test: increase break length

* test: uses wait_for_break method

* test: with timeout

* fix: extend break on other test

* fix: missing assert

* test: explicit enable before first break

* test: delay after enable

* test: sync_regs on c6/h2

* test: interleaved

* test: sync and delay

* test: c6/h2 sync on send

* test: sync only without additional delay

* test: break detection amongst transmission

* fix: data tests should flush to allow full tx

* fix: delete unneeded example

* feat: added break sending to uart example

* fix: use time::Duration

* fix: TRMs dictate c3 and s3 need sync_regs after write to conf0

* fix: use Duration in HIL tests

* fix: save unoptimizable register read

* fix: remove cancellation safe (they're not)

* fix: reg assignment bits()

* test: no sync after enable_listen_rx (just after conf0 writes)

* chore: retrigger ci

* chore: retrigger ci again

* chore: update example payload to be something more relevant

* test: put back sync for c6/h2

* docs: update changelog

* docs: clarify changelog entry

* fix: missing byte in example

* fix: changelog version

* Update esp-hal/src/uart/mod.rs

Co-authored-by: Juraj Sadel <[email protected]>

---------

Co-authored-by: Dániel Buga <[email protected]>
Co-authored-by: Juraj Sadel <[email protected]>

Author: 3 people

esp-hal/CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Added blocking `send_break`, `wait_for_break` and `wait_for_break_with_timeout` for sending and detecting software breaks with the UART driver (#4284)
+- Added support for `RxBreakDetected` interrupt and `wait_for_break_async` for detecting software breaks asynchronously to the UART driver (#4284)
 
 ### Changed
 

esp-hal/src/uart/mod.rs

@@ -486,6 +486,7 @@ where
                 mem_guard,
                 rts_pin,
                 tx_pin,
+                baudrate: config.baudrate,
             },
         };
         serial.init(config)?;
@@ -523,6 +524,7 @@ pub struct UartTx<'d, Dm: DriverMode> {
     mem_guard: MemoryGuard<'d>,
     rts_pin: PinGuard,
     tx_pin: PinGuard,
+    baudrate: u32,
 }
 
 /// UART (Receive)
@@ -623,6 +625,7 @@ where
     type ConfigError = ConfigError;
 
     fn set_config(&mut self, config: &Self::Config) -> Result<(), Self::ConfigError> {
+        self.baudrate = config.baudrate;
         self.apply_config(config)
     }
 }
@@ -667,6 +670,7 @@ impl<'d> UartTx<'d, Blocking> {
             mem_guard: self.mem_guard,
             rts_pin: self.rts_pin,
             tx_pin: self.tx_pin,
+            baudrate: self.baudrate,
         }
     }
 }
@@ -690,6 +694,7 @@ impl<'d> UartTx<'d, Async> {
             mem_guard: self.mem_guard,
             rts_pin: self.rts_pin,
             tx_pin: self.tx_pin,
+            baudrate: self.baudrate,
         }
     }
 
@@ -863,6 +868,44 @@ where
         while !self.is_tx_idle() {}
     }
 
+    /// Sends a break signal for a specified duration in bit time.
+    ///
+    /// Duration is in bits, the time it takes to transfer one bit at the
+    /// current baud rate. The delay during the break is just busy-waiting.
+    #[instability::unstable]
+    pub fn send_break(&mut self, bits: u32) {
+        // Read the current TX inversion state
+        let original_conf0 = self.uart.info().regs().conf0().read();
+        let original_txd_inv = original_conf0.txd_inv().bit();
+
+        // Invert the TX line (toggle the current state)
+        self.uart
+            .info()
+            .regs()
+            .conf0()
+            .modify(|_, w| w.txd_inv().bit(!original_txd_inv));
+
+        #[cfg(any(esp32c3, esp32c6, esp32h2, esp32s3))]
+        sync_regs(self.uart.info().regs());
+
+        // Calculate total delay in microseconds: (bits * 1_000_000) / baudrate_bps
+        // Use u64 to avoid overflow, then convert back to u32
+        let total_delay_us = (bits as u64 * 1_000_000) / self.baudrate as u64;
+        let delay_us = (total_delay_us as u32).max(1);
+
+        crate::rom::ets_delay_us(delay_us);
+
+        // Restore the original register state
+        self.uart
+            .info()
+            .regs()
+            .conf0()
+            .write(|w| unsafe { w.bits(original_conf0.bits()) });
+
+        #[cfg(any(esp32c3, esp32c6, esp32h2, esp32s3))]
+        sync_regs(self.uart.info().regs());
+    }
+
     /// Checks if the TX line is idle for this UART instance.
     ///
     /// Returns `true` if the transmit line is idle, meaning no data is
@@ -944,6 +987,50 @@ impl<'d> UartRx<'d, Blocking> {
         Ok(uart_rx)
     }
 
+    /// Waits for a break condition to be detected.
+    ///
+    /// This is a blocking function that will continuously check for a break condition.
+    /// After detection, the break interrupt flag is automatically cleared.
+    #[instability::unstable]
+    pub fn wait_for_break(&mut self) {
+        self.enable_break_detection();
+
+        while !self.regs().int_raw().read().brk_det().bit_is_set() {
+            // wait
+        }
+
+        self.regs()
+            .int_clr()
+            .write(|w| w.brk_det().clear_bit_by_one());
+    }
+
+    /// Waits for a break condition to be detected with a timeout.
+    ///
+    /// This is a blocking function that will check for a break condition up to
+    /// the specified timeout. Returns `true` if a break was detected, `false` if
+    /// the timeout elapsed. After successful detection, the break interrupt flag
+    /// is automatically cleared.
+    ///
+    /// ## Arguments
+    /// * `timeout` - Maximum time to wait for a break condition
+    #[instability::unstable]
+    pub fn wait_for_break_with_timeout(&mut self, timeout: crate::time::Duration) -> bool {
+        self.enable_break_detection();
+
+        let start = crate::time::Instant::now();
+
+        while !self.regs().int_raw().read().brk_det().bit_is_set() {
+            if crate::time::Instant::now() - start >= timeout {
+                return false;
+            }
+        }
+
+        self.regs()
+            .int_clr()
+            .write(|w| w.brk_det().clear_bit_by_one());
+        true
+    }
+
     /// Reconfigures the driver to operate in [`Async`] mode.
     #[instability::unstable]
     pub fn into_async(self) -> UartRx<'d, Async> {
@@ -1099,6 +1186,19 @@ impl<'d> UartRx<'d, Async> {
 
         Ok(())
     }
+
+    /// Waits for a break condition to be detected asynchronously.
+    ///
+    /// This is an async function that will await until a break condition is
+    /// detected on the RX line. After detection, the break interrupt flag is
+    /// automatically cleared.
+    #[instability::unstable]
+    pub async fn wait_for_break_async(&mut self) {
+        UartRxFuture::new(self.uart.reborrow(), RxEvent::BreakDetected).await;
+        self.regs()
+            .int_clr()
+            .write(|w| w.brk_det().clear_bit_by_one());
+    }
 }
 
 impl<'d, Dm> UartRx<'d, Dm>
@@ -1144,6 +1244,23 @@ where
         self
     }
 
+    /// Enable break detection.
+    ///
+    /// This must be called before any breaks are expected to be received.
+    /// Break detection is enabled automatically by [`Self::wait_for_break`]
+    /// and [`Self::wait_for_break_with_timeout`], but calling this method
+    /// explicitly ensures that breaks occurring before the first wait call
+    /// will be reliably detected.
+    #[instability::unstable]
+    pub fn enable_break_detection(&mut self) {
+        self.uart
+            .info()
+            .enable_listen_rx(RxEvent::BreakDetected.into(), true);
+
+        #[cfg(any(esp32c6, esp32h2))]
+        sync_regs(self.regs());
+    }
+
     /// Change the configuration.
     ///
     /// ## Errors
@@ -1389,6 +1506,29 @@ impl<'d> Uart<'d, Blocking> {
     pub fn clear_interrupts(&mut self, interrupts: EnumSet<UartInterrupt>) {
         self.tx.uart.info().clear_interrupts(interrupts)
     }
+
+    /// Waits for a break condition to be detected.
+    ///
+    /// This is a blocking function that will continuously check for a break condition.
+    /// After detection, the break interrupt flag is automatically cleared.
+    #[instability::unstable]
+    pub fn wait_for_break(&mut self) {
+        self.rx.wait_for_break()
+    }
+
+    /// Waits for a break condition to be detected with a timeout.
+    ///
+    /// This is a blocking function that will check for a break condition up to
+    /// the specified timeout. Returns `true` if a break was detected, `false` if
+    /// the timeout elapsed. After successful detection, the break interrupt flag
+    /// is automatically cleared.
+    ///
+    /// ## Arguments
+    /// * `timeout` - Maximum time to wait for a break condition
+    #[instability::unstable]
+    pub fn wait_for_break_with_timeout(&mut self, timeout: crate::time::Duration) -> bool {
+        self.rx.wait_for_break_with_timeout(timeout)
+    }
 }
 
 impl<'d> Uart<'d, Async> {
@@ -1528,6 +1668,16 @@ impl<'d> Uart<'d, Async> {
     pub async fn read_exact_async(&mut self, buf: &mut [u8]) -> Result<(), RxError> {
         self.rx.read_exact_async(buf).await
     }
+
+    /// Waits for a break condition to be detected asynchronously.
+    ///
+    /// This is an async function that will await until a break condition is
+    /// detected on the RX line. After detection, the break interrupt flag is
+    /// automatically cleared.
+    #[instability::unstable]
+    pub async fn wait_for_break_async(&mut self) {
+        self.rx.wait_for_break_async().await
+    }
 }
 
 /// List of exposed UART events.
@@ -1543,6 +1693,11 @@ pub enum UartInterrupt {
     /// The transmitter has finished sending out all data from the FIFO.
     TxDone,
 
+    /// Break condition has been detected.
+    /// Triggered when the receiver detects a NULL character (i.e. logic 0 for
+    /// one NULL character transmission) after stop bits.
+    RxBreakDetected,
+
     /// The receiver has received more data than what
     /// [`RxConfig::fifo_full_threshold`] specifies.
     RxFifoFull,
@@ -1700,6 +1855,12 @@ where
         self.tx.flush()
     }
 
+    /// Sends a break signal for a specified duration
+    #[instability::unstable]
+    pub fn send_break(&mut self, bits: u32) {
+        self.tx.send_break(bits)
+    }
+
     /// Returns whether the UART buffer has data.
     ///
     /// If this function returns `true`, [`Self::read`] will not block.
@@ -2233,6 +2394,7 @@ pub(crate) enum RxEvent {
     GlitchDetected,
     FrameError,
     ParityError,
+    BreakDetected,
 }
 
 fn rx_event_check_for_error(events: EnumSet<RxEvent>) -> Result<(), RxError> {
@@ -2242,7 +2404,10 @@ fn rx_event_check_for_error(events: EnumSet<RxEvent>) -> Result<(), RxError> {
             RxEvent::GlitchDetected => return Err(RxError::GlitchOccurred),
             RxEvent::FrameError => return Err(RxError::FrameFormatViolated),
             RxEvent::ParityError => return Err(RxError::ParityMismatch),
-            RxEvent::FifoFull | RxEvent::CmdCharDetected | RxEvent::FifoTout => continue,
+            RxEvent::FifoFull
+            | RxEvent::CmdCharDetected
+            | RxEvent::FifoTout
+            | RxEvent::BreakDetected => continue,
         }
     }
 
@@ -2804,6 +2969,7 @@ impl Info {
                 match interrupt {
                     UartInterrupt::AtCmd => w.at_cmd_char_det().bit(enable),
                     UartInterrupt::TxDone => w.tx_done().bit(enable),
+                    UartInterrupt::RxBreakDetected => w.brk_det().bit(enable),
                     UartInterrupt::RxFifoFull => w.rxfifo_full().bit(enable),
                     UartInterrupt::RxTimeout => w.rxfifo_tout().bit(enable),
                 };
@@ -2824,6 +2990,9 @@ impl Info {
         if ints.tx_done().bit_is_set() {
             res.insert(UartInterrupt::TxDone);
         }
+        if ints.brk_det().bit_is_set() {
+            res.insert(UartInterrupt::RxBreakDetected);
+        }
         if ints.rxfifo_full().bit_is_set() {
             res.insert(UartInterrupt::RxFifoFull);
         }
@@ -2842,6 +3011,7 @@ impl Info {
                 match interrupt {
                     UartInterrupt::AtCmd => w.at_cmd_char_det().clear_bit_by_one(),
                     UartInterrupt::TxDone => w.tx_done().clear_bit_by_one(),
+                    UartInterrupt::RxBreakDetected => w.brk_det().clear_bit_by_one(),
                     UartInterrupt::RxFifoFull => w.rxfifo_full().clear_bit_by_one(),
                     UartInterrupt::RxTimeout => w.rxfifo_tout().clear_bit_by_one(),
                 };
@@ -2905,6 +3075,7 @@ impl Info {
             for event in events {
                 match event {
                     RxEvent::FifoFull => w.rxfifo_full().bit(enable),
+                    RxEvent::BreakDetected => w.brk_det().bit(enable),
                     RxEvent::CmdCharDetected => w.at_cmd_char_det().bit(enable),
 
                     RxEvent::FifoOvf => w.rxfifo_ovf().bit(enable),
@@ -2925,6 +3096,9 @@ impl Info {
         if pending_interrupts.rxfifo_full().bit_is_set() {
             active_events |= RxEvent::FifoFull;
         }
+        if pending_interrupts.brk_det().bit_is_set() {
+            active_events |= RxEvent::BreakDetected;
+        }
         if pending_interrupts.at_cmd_char_det().bit_is_set() {
             active_events |= RxEvent::CmdCharDetected;
         }
@@ -2953,6 +3127,7 @@ impl Info {
             for event in events {
                 match event {
                     RxEvent::FifoFull => w.rxfifo_full().clear_bit_by_one(),
+                    RxEvent::BreakDetected => w.brk_det().clear_bit_by_one(),
                     RxEvent::CmdCharDetected => w.at_cmd_char_det().clear_bit_by_one(),
 
                     RxEvent::FifoOvf => w.rxfifo_ovf().clear_bit_by_one(),

examples/interrupt/uart/.cargo/config.toml

@@ -0,0 +1,24 @@
+[target.'cfg(target_arch = "riscv32")']
+runner    = "espflash flash --monitor"
+rustflags = [
+  "-C", "link-arg=-Tlinkall.x",
+  "-C", "force-frame-pointers",
+]
+
+[target.'cfg(target_arch = "xtensa")']
+runner    = "espflash flash --monitor"
+rustflags = [
+  # GNU LD
+  "-C", "link-arg=-Wl,-Tlinkall.x",
+  "-C", "link-arg=-nostartfiles",
+
+  # LLD
+  # "-C", "link-arg=-Tlinkall.x",
+  # "-C", "linker=rust-lld",
+]
+
+[env]
+ESP_LOG = "info"
+
+[unstable]
+build-std = ["core", "alloc"]