Struct Uart

pub struct Uart<'d, Dm: DriverMode> { /* private fields */ }

UART (Full-duplex)

let mut uart = Uart::new(
    peripherals.UART0,
    Config::default())?
.with_rx(peripherals.GPIO1)
.with_tx(peripherals.GPIO2);

uart.write(b"Hello world!")?;

Implementations

impl<'d> Uart<'d, Blocking>

pub fn new( uart: impl Peripheral<P = impl Instance> + 'd, config: Config, ) -> Result<Self, ConfigError>

Create a new UART instance in Blocking mode.

Errors

This function returns a ConfigError if the configuration is not supported by the hardware.

Example

let mut uart1 = Uart::new(
    peripherals.UART1,
    Config::default())?
.with_rx(peripherals.GPIO1)
.with_tx(peripherals.GPIO2);

pub fn into_async(self) -> Uart<'d, Async>

Reconfigures the driver to operate in Async mode.

pub fn with_rx(self, rx: impl Peripheral<P = impl PeripheralInput> + 'd) -> Self

Assign the RX pin for UART instance.

Sets the specified pin to input and connects it to the UART RX signal.

Note: when you listen for the output of the UART peripheral, you should configure the driver side (i.e. the TX pin), or ensure that the line is initially high, to avoid receiving a non-data byte caused by an initial low signal level.

pub fn with_tx( self, tx: impl Peripheral<P = impl PeripheralOutput> + 'd, ) -> Self

Assign the TX pin for UART instance.

Sets the specified pin to push-pull output and connects it to the UART TX signal.

impl<'d> Uart<'d, Async>

pub fn into_blocking(self) -> Uart<'d, Blocking>

Reconfigures the driver to operate in Blocking mode.

impl<'d, Dm> Uart<'d, Dm>

where Dm: DriverMode,

pub fn with_cts( self, cts: impl Peripheral<P = impl PeripheralInput> + 'd, ) -> Self

Configure CTS pin

pub fn with_rts( self, rts: impl Peripheral<P = impl PeripheralOutput> + 'd, ) -> Self

Configure RTS pin

pub fn split(self) -> (UartRx<'d, Dm>, UartTx<'d, Dm>)

Available on crate feature unstable only.

Split the UART into a transmitter and receiver

This is particularly useful when having two tasks correlating to transmitting and receiving.

Example

// The UART can be split into separate Transmit and Receive components:
let (mut rx, mut tx) = uart1.split();

// Each component can be used individually to interact with the UART:
tx.write(&[42u8])?;
let mut byte = [0u8; 1];
rx.read(&mut byte);

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn write(&mut self, data: &[u8]) -> Result<usize, TxError>

Writes bytes.

This function writes data to the internal TX FIFO of the UART peripheral. The data is then transmitted over the UART TX line.

The function returns the number of bytes written to the FIFO. This may be less than the length of the provided data. The function may only return 0 if the provided data is empty.

Errors

This function returns a TxError if an error occurred during the write operation.

Example

// Write bytes out over the UART:
uart1.write(b"Hello, world!")?;

pub fn check_for_rx_errors(&mut self) -> Result<(), RxError>

Available on crate feature unstable only.

Reads and clears errors set by received data.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn read(&mut self, buf: &mut [u8]) -> Result<usize, RxError>

Read received bytes.

The UART hardware continuously receives bytes and stores them in the RX FIFO. This function reads the bytes from the RX FIFO and returns them in the provided buffer, without blocking.

The function returns the number of bytes read into the buffer. This may be less than the length of the buffer. This function only returns 0 if the provided buffer is empty.

Errors

This function returns an RxError if an error occurred since the last check for errors.

If the error occurred before this function was called, the contents of the FIFO are not modified.

pub fn read_buffered(&mut self, buf: &mut [u8]) -> Result<usize, RxError>

Available on crate feature unstable only.

Read already received bytes.

This function reads the already received bytes from the FIFO into the provided buffer. The function does not wait for the FIFO to actually contain any bytes.

The function returns the number of bytes read into the buffer. This may be less than the length of the buffer, and it may also be 0.

Errors

This function returns an RxError if an error occurred since the last check for errors.

If the error occurred before this function was called, the contents of the FIFO are not modified.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn set_at_cmd(&mut self, config: AtCmdConfig)

Available on crate feature unstable only.

Configures the AT-CMD detection settings

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn flush(&mut self) -> Result<(), TxError>

Flush the transmit buffer of the UART

pub fn apply_config(&mut self, config: &Config) -> Result<(), ConfigError>

Change the configuration.

Errors

This function returns a ConfigError if the configuration is not supported by the hardware.

impl Uart<'_, Blocking>

pub fn set_interrupt_handler(&mut self, handler: InterruptHandler)

Available on crate feature unstable only.

Registers an interrupt handler for the peripheral.

Note that this will replace any previously registered interrupt handlers.

You can restore the default/unhandled interrupt handler by using crate::interrupt::DEFAULT_INTERRUPT_HANDLER

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn listen(&mut self, interrupts: impl Into<EnumSet<UartInterrupt>>)

Available on crate feature unstable only.

Listen for the given interrupts

Example

Note: In practice a proper serial terminal should be used to connect to the board (espflash won’t work)

uart0.set_interrupt_handler(interrupt_handler);

critical_section::with(|cs| {
    uart0.set_at_cmd(AtCmdConfig::default().with_cmd_char(b'#'));
    uart0.listen(UartInterrupt::AtCmd | UartInterrupt::RxFifoFull);

    SERIAL.borrow_ref_mut(cs).replace(uart0);
});

loop {
    println!("Send `#` character or >=30 characters");
    delay.delay(Duration::from_secs(1));
}

static SERIAL: Mutex<RefCell<Option<Uart<esp_hal::Blocking>>>> =
    Mutex::new(RefCell::new(None));

#[handler]
fn interrupt_handler() {
    critical_section::with(|cs| {
        let mut serial = SERIAL.borrow_ref_mut(cs);
        if let Some(serial) = serial.as_mut() {
            let mut buf = [0u8; 64];
            if let Ok(cnt) = serial.read_buffered(&mut buf) {
                println!("Read {} bytes", cnt);
            }

            let pending_interrupts = serial.interrupts();
            println!(
                "Interrupt AT-CMD: {} RX-FIFO-FULL: {}",
                pending_interrupts.contains(UartInterrupt::AtCmd),
                pending_interrupts.contains(UartInterrupt::RxFifoFull),
            );

            serial.clear_interrupts(
                UartInterrupt::AtCmd | UartInterrupt::RxFifoFull
            );
        }
    });
}

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn unlisten(&mut self, interrupts: impl Into<EnumSet<UartInterrupt>>)

Available on crate feature unstable only.

Unlisten the given interrupts

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn interrupts(&mut self) -> EnumSet<UartInterrupt>

Available on crate feature unstable only.

Gets asserted interrupts

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn clear_interrupts(&mut self, interrupts: EnumSet<UartInterrupt>)

Available on crate feature unstable only.

Resets asserted interrupts

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

impl Uart<'_, Async>

pub async fn read_async(&mut self, buf: &mut [u8]) -> Result<usize, RxError>

Read data asynchronously.

This function reads data from the UART receive buffer into the provided buffer. If the buffer is empty, the function waits asynchronously for data to become available, or for an error to occur.

The function returns the number of bytes read into the buffer. This may be less than the length of the buffer.

Note that this function may ignore the rx_fifo_full_threshold setting to ensure that it does not wait for more data than the buffer can hold.

Upon an error, the function returns immediately and the contents of the internal FIFO are not modified.

Cancellation

This function is cancellation safe.

pub async fn read_exact_async(&mut self, buf: &mut [u8]) -> Result<(), RxError>

Available on crate feature unstable only.

Fill buffer asynchronously.

This function reads data from the UART receive buffer into the provided buffer. If the buffer is empty, the function waits asynchronously for data to become available, or for an error to occur.

Note that this function may ignore the rx_fifo_full_threshold setting to ensure that it does not wait for more data than the buffer can hold.

Cancellation

This function is not cancellation safe. If the future is dropped before it resolves, or if an error occurs during the read operation, previously read data may be lost.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub async fn write_async(&mut self, words: &[u8]) -> Result<usize, TxError>

Write data into the TX buffer.

This function writes the provided buffer bytes into the UART transmit buffer. If the buffer is full, the function waits asynchronously for space in the buffer to become available.

The function returns the number of bytes written into the buffer. This may be less than the length of the buffer.

Upon an error, the function returns immediately and the contents of the internal FIFO are not modified.

Cancellation

This function is cancellation safe.

pub async fn flush_async(&mut self) -> Result<(), TxError>

Asynchronously flushes the UART transmit buffer.

This function ensures that all pending data in the transmit FIFO has been sent over the UART. If the FIFO contains data, it waits for the transmission to complete before returning.

Cancellation

This function is cancellation safe.

Trait Implementations

impl<Dm: DriverMode> ErrorType for Uart<'_, Dm>

Available on crate feature unstable only.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

type Error = IoError

Error type of all the IO operations on this type.

impl InterruptConfigurable for Uart<'_, Blocking>

Available on crate feature unstable only.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

fn set_interrupt_handler(&mut self, handler: InterruptHandler)

Registers an interrupt handler for the peripheral.

impl Read for Uart<'_, Async>

Available on crate feature unstable only.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

async fn read(&mut self, buf: &mut [u8]) -> Result<usize, Self::Error>

Read some bytes from this source into the specified buffer, returning how many bytes were read.

async fn read_exact( &mut self, buf: &mut [u8], ) -> Result<(), ReadExactError<Self::Error>>

Read the exact number of bytes required to fill buf.

impl<Dm> Read for Uart<'_, Dm>

where Dm: DriverMode,

Available on crate feature unstable only.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

fn read(&mut self, buf: &mut [u8]) -> Result<usize, Self::Error>

Read some bytes from this source into the specified buffer, returning how many bytes were read.

fn read_exact( &mut self, buf: &mut [u8], ) -> Result<(), ReadExactError<Self::Error>>

Read the exact number of bytes required to fill buf.

impl<Dm> ReadReady for Uart<'_, Dm>

where Dm: DriverMode,

Available on crate feature unstable only.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

fn read_ready(&mut self) -> Result<bool, Self::Error>

Get whether the reader is ready for immediately reading.

impl<Dm> SetConfig for Uart<'_, Dm>

where Dm: DriverMode,

Available on crate feature unstable only.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

type Config = Config

The configuration type used by this driver.

type ConfigError = ConfigError

The error type that can occur if set_config fails.

fn set_config(&mut self, config: &Self::Config) -> Result<(), Self::ConfigError>

Set the configuration of the driver.

impl Write for Uart<'_, Async>

Available on crate feature unstable only.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

async fn write(&mut self, buf: &[u8]) -> Result<usize, Self::Error>

Write a buffer into this writer, returning how many bytes were written.

async fn flush(&mut self) -> Result<(), Self::Error>

Flush this output stream, ensuring that all intermediately buffered contents reach their destination.

async fn write_all(&mut self, buf: &[u8]) -> Result<(), Self::Error>

Write an entire buffer into this writer.

impl<Dm> Write for Uart<'_, Dm>

where Dm: DriverMode,

fn write_str(&mut self, s: &str) -> Result

Writes a string slice into this writer, returning whether the write succeeded.

fn write_char(&mut self, c: char) -> Result<(), Error>

Writes a [char] into this writer, returning whether the write succeeded.

fn write_fmt(&mut self, args: Arguments<'_>) -> Result<(), Error>

Glue for usage of the [write!] macro with implementors of this trait.

impl<Dm> Write for Uart<'_, Dm>

where Dm: DriverMode,

Available on crate feature unstable only.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

fn write(&mut self, buf: &[u8]) -> Result<usize, Self::Error>

Write a buffer into this writer, returning how many bytes were written.

fn flush(&mut self) -> Result<(), Self::Error>

Flush this output stream, blocking until all intermediately buffered contents reach their destination.

fn write_all(&mut self, buf: &[u8]) -> Result<(), Self::Error>

Write an entire buffer into this writer.

fn write_fmt( &mut self, fmt: Arguments<'_>, ) -> Result<(), WriteFmtError<Self::Error>>

Write a formatted string into this writer, returning any error encountered.

impl<Dm> uWrite for Uart<'_, Dm>

where Dm: DriverMode,

Available on crate feature unstable only.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

type Error = TxError

The error associated to this writer

fn write_str(&mut self, s: &str) -> Result<(), Self::Error>

Writes a string slice into this writer, returning whether the write succeeded.

fn write_char(&mut self, ch: char) -> Result<(), Self::Error>

Writes a [char] into this writer, returning whether the write succeeded.