API referencestd/embedded

std/embedded/peripheral/esp_uart

Public declarations, types, methods, and source contracts for std/embedded/peripheral/esp_uart.

On this page

Library guide · API index and notation

This page is generated from the bundled library in this checkout. Signatures and adjacent source comments are reproduced below; the linked guide explains usage, storage, failures, and platform support.

import "std/embedded/peripheral/esp_uart"

Names used in signatures

Unqualified names denote this package’s types (including other source files in the same package), language built-ins, or generic parameters such as T. Qualified names use the import aliases below. These aliases belong to the library source; import a dependency yourself to use its alias in your program.

Alias Package Source file
hal std/embedded/hal esp_uart.dodo
io std/io esp_uart.dodo
serial std/embedded/hal/serial esp_uart.dodo

RX_INTERRUPT

Constant · Source

Interrupt sources, as bits of listen, ignore, pending_interrupts, and clear_interrupts. The controller raises its one interrupt line, UART0 or UART1 on the ESP32-C6, while any listened-to source is pending.

RX_INTERRUPT: the receive FIFO holds 96 bytes or more. RX_TIMEOUT_INTERRUPT: received bytes have waited for 30 bit times with no more arriving, so a handler also hears about a short message. Reads that drain the FIFO end both; clear them too, as they are latched.

pub const RX_INTERRUPT: u32 = 1 << 0

TX_INTERRUPT

Constant · Source

The transmit FIFO has drained below 64 bytes: room to write more.

pub const TX_INTERRUPT: u32 = 1 << 1

RX_TIMEOUT_INTERRUPT

Constant · Source

pub const RX_TIMEOUT_INTERRUPT: u32 = 1 << 8

ERROR_INTERRUPTS

Constant · Source

A received frame had a parity or framing error, was a break, or found the receive FIFO full.

pub const ERROR_INTERRUPTS: u32 = PARITY_INTERRUPT | FRAMING_INTERRUPT | OVERFLOW_INTERRUPT | BREAK_INTERRUPT

DEFAULT_POLL_LIMIT

Constant · Source

Status polls without progress before a wait for output gives up.

pub const DEFAULT_POLL_LIMIT: u32 = 10_000_000

NO_POLL_LIMIT

Constant · Source

A poll limit of zero waits as long as it takes.

pub const NO_POLL_LIMIT: u32 = 0

FIFO_DEPTH

Constant · Source

Bytes in each FIFO.

pub const FIFO_DEPTH: usize = 128

FRAMING_ERROR

Constant · Source

Receive errors, as in pl011: a failed read’s io.Error has kind Other and these bits in its code. The controller drops a byte with a framing or parity error, or a break. An overrun means bytes were lost because the receive FIFO was full.

pub const FRAMING_ERROR: i32 = 1

PARITY_ERROR

Constant · Source

pub const PARITY_ERROR: i32 = 2

BREAK

Constant · Source

pub const BREAK: i32 = 4

OVERRUN

Constant · Source

pub const OVERRUN: i32 = 8

Parity

Enum · Source

The parity bit after each frame’s data bits.

pub enum Parity {
    None,
    Even,
    Odd
}

Divisor

Struct · Source

The divisor for one baud rate, from divisor.

pub struct Divisor {
    // The function clock it divides.
    pub clock_hz: u32
    // The divisor in sixteenths: clock_hz * 16 / sixteenths is the rate.
    pub sixteenths: u32
    // The resulting baud rate.
    pub baud: u32
}

divisor

Function · Source

The divisor from a function clock of clock_hz that comes closest to baud, exact to 1/16. InvalidInput above clock_hz / 2 (20 Mbaud from a 40 MHz crystal), or below clock_hz / 4096, where the divisor no longer fits; a chip package divides the clock first for slower rates.

pub fn divisor(clock_hz: u32, baud: u32) -> Divisor!hal.Error

Controller

Struct · Source

A serial port on one controller with registers R, any hal.Registers. Implements the std/io Reader and Writer interfaces and the serial port protocols of std/embedded/hal/serial.

pub struct Controller<R: hal.Registers>: serial.Port + serial.PollPort {
    // Private implementation fields omitted.
}

Controller.new

Function · Source

Configure a controller fresh out of reset for 8N1 frames at the baud rate of divisor, with both FIFOs emptied.

pub fn new(registers: R, divisor: Divisor) -> Controller<R>

Controller.baud

Function · Source

The baud rate, in bits per second: the closest the controller can make to the requested one.

pub fn baud(&self) -> u32

Controller.clock_hz

Function · Source

The function clock, as given to new or set_divisor.

pub fn clock_hz(&self) -> u32

Controller.dma_settings

Function · Source

Whether newlines are translated, and the poll limit and read poll limit, for a DMA session that takes the port over (esp_uhci).

pub fn dma_settings(&self) -> (bool, u32, u32)

Controller.set_poll_limit

Function · Source

pub fn set_poll_limit(&mut self, polls: u32)

Controller.set_read_poll_limit

Function · Source

pub fn set_read_poll_limit(&mut self, polls: u32)

Controller.set_baud

Function · Source

Change the baud rate, from the same function clock. Waits until everything written is out first. InvalidInput or Timeout leaves it unchanged.

pub fn set_baud(&mut self, baud: u32) -> void!hal.Error

Controller.set_divisor

Function · Source

Change the divisor, for a chip package that changes the function clock too: waits as set_baud does, then latches settings.

pub fn set_divisor(&mut self, settings: Divisor) -> void!hal.Error

Controller.set_format

Function · Source

Change the frame format: 5 to 8 data bits, the parity bit, and 1 or 2 stop bits. Waits like set_baud; InvalidInput or Timeout leaves the format unchanged.

pub fn set_format(&mut self, data_bits: u32, parity: Parity, stop_bits: u32) -> void!hal.Error

Controller.set_crlf

Function · Source

Translate newlines for a serial terminal: write each “\n” as “\r\n”, and read the carriage return that a terminal’s Enter key sends, alone or followed by “\n”, as one “\n”. Off at first.

pub fn set_crlf(&mut self, on: bool)

Controller.set_flow_control

Function · Source

Turn hardware flow control on or off, once everything written is out: with cts, the transmitter sends only while the other end holds CTS low; with rts, the controller holds RTS low while its receive FIFO has room and raises it from 100 bytes on. Both need the pins routed, which chip packages do for ports claimed with flow control.

pub fn set_flow_control(&mut self, cts: bool, rts: bool) -> void!hal.Error

Controller.listen

Function · Source

Raise the controller’s interrupt for these sources, in addition to those already listened to. Ports start with none.

pub fn listen(&mut self, sources: u32)

Controller.ignore

Function · Source

pub fn ignore(&mut self, sources: u32)

Controller.pending_interrupts

Function · Source

The listened-to sources that are pending now.

pub fn pending_interrupts(&mut self) -> u32

Controller.clear_interrupts

Function · Source

Acknowledge sources. The receive and transmit levels come back at once while their condition lasts.

pub fn clear_interrupts(&mut self, sources: u32)

Controller.set_break

Function · Source

Hold the transmit line low, a break, from once everything written is out until set_break(false).

pub fn set_break(&mut self, on: bool) -> void!hal.Error

Controller.set_loopback

Function · Source

Connect the transmitter to the receiver inside the controller, so reads return what was written. Meant for self-tests. Timeout if what was written does not get out.

pub fn set_loopback(&mut self, on: bool) -> void!hal.Error

Controller.write

Function · Source

Send bytes, waiting while the transmit FIFO is full. Returns once the last byte is queued; flush waits until it is sent. TimedOut, with the bytes queued before it in transferred, if the FIFO stays full for the poll limit.

pub fn write(&mut self, bytes: &[u8]) -> usize!io.Error

Controller.poll_write

Function · Source

Queue as much of bytes as the transmit FIFO has room for, without waiting; Pending, with what was queued, once it is full.

pub fn poll_write(&mut self, bytes: &[u8]) -> io.Poll!io.Error

Controller.flush

Function · Source

Wait until every byte written has left, stop bits included. TimedOut after the poll limit.

pub fn flush(&mut self) -> void!io.Error

Controller.poll_flush

Function · Source

flush without waiting: true once every byte written has left, stop bits included (the transmit FIFO is empty and the transmitter idle, TXFIFO_CNT and the FSM_STATUS transmit state both 0), false while some are still queued or being sent.

pub fn poll_flush(&mut self) -> bool!io.Error

Controller.read

Function · Source

Wait for the first byte, then return what has arrived, up to buffer.len. A serial port has no end of input, so a read never returns 0 bytes for a nonempty buffer. On a receive error, the bytes before it are in buffer[..transferred] and io.Error.code holds its bits; see FRAMING_ERROR. The next read continues after it.

pub fn read(&mut self, buffer: &mut[u8]) -> usize!io.Error

Controller.poll_read

Function · Source

Return what the receive FIFO holds, up to buffer.len, without waiting: Pending, with nothing, while it is empty. Errors as for read: the errors latched since the last read, after the bytes read now.

pub fn poll_read(&mut self, buffer: &mut[u8]) -> io.Poll!io.Error

Controller.send_report

Function · Source

Write bytes for a panic report: with newlines as given, waiting for room as long as the poll limit allows, then for the line to go idle.

pub fn send_report(&mut self, bytes: &[u8])

Controller.release

Function · Source

Wait until everything written is out, within the poll limit, stop listening, and give back the registers. Output still stuck after the poll limit is dropped.

pub fn release(self) -> R

Search every guide, reference page, and API declaration.