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, andclear_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_hzthat comes closest tobaud, 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
neworset_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; withrts, 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;flushwaits until it is sent. TimedOut, with the bytes queued before it intransferred, 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
bytesas 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
flushwithout 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 forread: 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
bytesfor 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