UART: Universal Asynchronous Receive/Transmit¶

Custom asynchronous driver.

enum uart_driver::uart_mode_¶

values for mode argument of uart_init

Values:

UART_FULL¶: Both receive and transmit - will revert to TX only if RX not supported.

UART_RX_ONLY¶: Receive only.

UART_TX_ONLY¶: Transmit only.

enum uart_driver::uart_option_bits_t¶

bit values for options argument of uart_init

Note: use _BV(opt) to specify values

Values:

UART_OPT_TXWAIT¶: If buffers are full then uart_write() will wait for free space.

UART_OPT_CALLBACK_RAW¶: ISR invokes user callback function with no pre-processing.

enum uart_driver::uart_notify_code_t¶

Indicates notification, parameters refer to uart_notify_info_t structure.

Values:

UART_NOTIFY_AFTER_OPEN¶: Called when uart has been iniitialised successfully.

UART_NOTIFY_BEFORE_CLOSE¶: Called immediately before uart is closed and destroyed.

UART_NOTIFY_AFTER_WRITE¶: Called after data has been written into tx buffer.

UART_NOTIFY_BEFORE_READ¶: Called before data is read from rx buffer.

UART_NOTIFY_WAIT_TX¶: Called to ensure all buffered data is output.

typedef enum uart_mode_ uart_mode_t¶

typedef uint8_t uart_options_t¶

typedef struct uart_ uart_t¶

typedef void (*uart_callback_t)(uart_t *uart, uint32_t status)¶

callback invoked directly from ISR

Errors can be detected via

uart_get_status().

Note

Values can be: UIFE: TX FIFO Empty UIFF: RX FIFO Full UITO: RX FIFO Timeout UIBD: Break Detected

Parameters

arg: the UART object
status: UART USIS STATUS flag bits indicating cause of interrupt

typedef void (*uart_notify_callback_t)(uart_t *uart, uart_notify_code_t code)¶

Port notification callback function type.

Parameters

info:

Return Value

bool: true if callback handled operation, false to default to normal operation

bool uart_set_notify(unsigned uart_nr, uart_notify_callback_t callback)¶

Set the notification callback function.

Parameters

uart_nr: Which uart to register notifications for
callback:

Return Value

bool: true on success

uart_t *uart_init(uint8_t uart_nr, uint32_t baudrate, uint32_t config, uart_mode_t mode, uint8_t tx_pin, size_t rx_size, size_t tx_size = 0)¶

uart_t *uart_init_ex(const uart_config &cfg)¶

void uart_uninit(uart_t *uart)¶

int uart_get_nr(uart_t *uart)¶

uart_t *uart_get_uart(uint8_t uart_nr)¶

Get the uart structure for the given number.

Parameters

uart_nr:

Return Value

uart_t*: Returns nullptr if uart isn’t initialised

void uart_set_callback(uart_t *uart, uart_callback_t callback, void *param)¶

Set callback handler for serial port.

Parameters

uart:
callback: specify nullptr to disable callbacks
param: user parameter passed to callback

void *uart_get_callback_param(uart_t *uart)¶

Get the callback parameter specified by uart_set_callback()

Parameters

uart:

Return Value

void*: the callback parameter

static void uart_set_options(uart_t *uart, uart_options_t options)¶

Set option flags.

Parameters

uart:
options: The option(s) to set

uint8_t uart_get_status(uart_t *uart)¶

Get error flags and clear them.

Note

To detect errors during a transaction, call at the start to clear the flags, then check the value at the end. Only these values are cleared/returned: UIBD: Break Detected UIOF: RX FIFO OverFlow UIFR: Frame Error UIPE: Parity Error

Parameters

uart:

Return Value

Status: error bits:

static uart_options_t uart_get_options(uart_t *uart)¶

void uart_swap(uart_t *uart, int tx_pin)¶

void uart_set_tx(uart_t *uart, int tx_pin)¶

void uart_set_pins(uart_t *uart, int tx, int rx)¶

bool uart_tx_enabled(uart_t *uart)¶

bool uart_rx_enabled(uart_t *uart)¶

uint32_t uart_set_baudrate_reg(int uart_nr, uint32_t baud_rate)¶

set UART baud rate, given the UART number

Parameters

uart_nr:
baud_rate: requested baud rate

Return Value

uint32_t: actual baudrate used, 0 on failure

uint32_t uart_set_baudrate(uart_t *uart, uint32_t baud_rate)¶

set UART baud rate

Parameters

uart:
baud_rate: requested baud rate

Return Value

uint32_t: actual baudrate used, 0 on failure

uint32_t uart_get_baudrate(uart_t *uart)¶

get the actual baud rate in use

Parameters

uart:

Return Value

uint32_t: the baud rate, 0 on failure

size_t uart_resize_rx_buffer(uart_t *uart, size_t new_size)¶

size_t uart_rx_buffer_size(uart_t *uart)¶

size_t uart_resize_tx_buffer(uart_t *uart, size_t new_size)¶

size_t uart_tx_buffer_size(uart_t *uart)¶

size_t uart_write(uart_t *uart, const void *buffer, size_t size)¶

write a block of data

Parameters

uart:
buffer:
size:

Return Value

size_t: number of bytes buffered for transmission

static size_t uart_write_char(uart_t *uart, char c)¶

queue a single character for output

Parameters

uart:
c:

Return Value

size_t: 1 if character was written, 0 on failure

size_t uart_read(uart_t *uart, void *buffer, size_t size)¶

read a block of data

Parameters

uart:
buffer: where to write the data
size: requested quantity of bytes to read

Return Value

size_t: number of bytes read

static int uart_read_char(uart_t *uart)¶

read a received character

Parameters

uart:

Return Value

the: character, -1 on failure

int uart_peek_char(uart_t *uart)¶

see what the next character in the rx buffer is

Note

if buffer isn’t allocated data may be in the hardware FIFO, which must be read out using uart_read()

Parameters

uart:

Return Value

int: returns -1 if buffer is empty or not allocated

int uart_peek_last_char(uart_t *uart)¶

fetch last character read out of FIFO

Note

this is only useful if an rx buffer has been allocated of sufficient size to contain a message. This function then indicates the terminating character.

Parameters

uart:

Return Value

int: the character, or -1 if rx buffer is empty or unallocated

int uart_rx_find(uart_t *uart, char c)¶

size_t uart_rx_available(uart_t *uart)¶

determine available data which can be read

Note

this obtains a count of data both in the memory buffer and hardware FIFO

Parameters

uart:

Return Value

size_t:

size_t uart_tx_free(uart_t *uart)¶: return free space in transmit buffer

void uart_wait_tx_empty(uart_t *uart)¶

void uart_set_break(uart_t *uart, bool state)¶

Set or clear a break condition on the TX line.

Parameters

uart:
state:

void uart_flush(uart_t *uart, uart_mode_t mode = UART_FULL)¶

discard any buffered data and reset hardware FIFOs

Note

this function does not wait for any transmissions to complete

Parameters

uart:
mode: Whether to flush TX, RX or both (the default)

void uart_set_debug(int uart_nr)¶

int uart_get_debug()¶

void uart_start_isr(uart_t *uart)¶

enable interrupts for a UART

Parameters

uart:

void uart_stop_isr(uart_t *uart)¶

disable interrupts for a UART

Parameters

uart:

void uart_detach(int uart_nr)¶

detach a UART interrupt service routine

Parameters

uart_nr:

void uart_detach_all()¶

detach all UART interrupt service routines

Note: call at startup to put all UARTs into a known state

uint8_t uart_disable_interrupts()¶

disable interrupts and return current interrupt state

Return Value

state: non-zero if any UART interrupts were active

void uart_restore_interrupts()¶: re-enable interrupts after calling uart_disable_interrupts()

UART0¶

UART1¶

UART2¶: Virtualised UART0.

UART_NO¶: No UART specified.

UART_PHYSICAL_COUNT¶: Number of physical UARTs on the system.

UART_COUNT¶: Number of UARTs on the system, virtual or otherwise.

UART_NB_BIT_MASK¶

UART_NB_BIT_5¶

UART_NB_BIT_6¶

UART_NB_BIT_7¶

UART_NB_BIT_8¶

UART_PARITY_MASK¶

UART_PARITY_NONE¶

UART_PARITY_EVEN¶

UART_PARITY_ODD¶

UART_NB_STOP_BIT_MASK¶

UART_NB_STOP_BIT_0¶

UART_NB_STOP_BIT_1¶

UART_NB_STOP_BIT_15¶

UART_NB_STOP_BIT_2¶

UART_5N1¶

UART_6N1¶

UART_7N1¶

UART_8N1¶

UART_5N2¶

UART_6N2¶

UART_7N2¶

UART_8N2¶

UART_5E1¶

UART_6E1¶

UART_7E1¶

UART_8E1¶

UART_5E2¶

UART_6E2¶

UART_7E2¶

UART_8E2¶

UART_5O1¶

UART_6O1¶

UART_7O1¶

UART_8O1¶

UART_5O2¶

UART_6O2¶

UART_7O2¶

UART_8O2¶

UART_RX_FIFO_SIZE¶

UART_TX_FIFO_SIZE¶

struct uart_¶

#include <uart.h>

Public Members

uint8_t uart_nr¶

uint32_t baud_rate¶

uart_mode_t mode¶

uint8_t options¶

uint8_t rx_pin¶

uint8_t tx_pin¶

uint8_t rx_headroom¶: Callback when rx_buffer free space <= headroom.

uint16_t status¶: All status flags reported to callback since last uart_get_status() call.

struct SerialBuffer *rx_buffer¶: Optional receive buffer.

struct SerialBuffer *tx_buffer¶: Optional transmit buffer.

uart_callback_t callback¶: Optional User callback routine.

void *param¶: User-supplied callback parameter.

struct uart_config¶

#include <uart.h>

Public Members

uint8_t uart_nr¶

uint8_t tx_pin¶: Specify 2 for alternate pin, otherwise defaults to pin 1.

uart_mode_t mode¶: Whether to enable receive, transmit or both.

uart_options_t options¶

uint32_t baudrate¶: Requested baudrate; actual baudrate may differ.

uint32_t config¶: UART CONF0 register bits.

size_t rx_size¶

size_t tx_size¶