UART: Universal Asynchronous Receive/Transmit

Custom asynchronous driver.

enum smg_uart_bits_t

Number of UART data bits.

Values:

enumerator UART_NB_BIT_5

enumerator UART_NB_BIT_6

enumerator UART_NB_BIT_7

enumerator UART_NB_BIT_8

enum smg_uart_parity_t

UART parity setting.

Actually combines two bits: bit 1 is set for parity enable, clear if disabled bit 0 is set for even parity, clear for odd parity

Values:

enumerator UART_PARITY_NONE

enumerator UART_PARITY_EVEN

enumerator UART_PARITY_ODD

enum smg_uart_stop_bits_t

Number of UART stop bits.

Values:

enumerator UART_NB_STOP_BIT_0

enumerator UART_NB_STOP_BIT_1

enumerator UART_NB_STOP_BIT_15

enumerator UART_NB_STOP_BIT_2

enum smg_uart_format_settings_t

Values:

enumerator UART_PARITY_MASK

enumerator UART_PARITY_SHIFT

enumerator UART_NB_BIT_MASK

enumerator UART_NB_BIT_SHIFT

enumerator UART_NB_STOP_BIT_MASK

enumerator UART_NB_STOP_BIT_SHIFT

enum smg_uart_format_t

Options for config argument of uart_init.

Values:

enumerator UART_5N1

enumerator UART_6N1

enumerator UART_7N1

enumerator UART_8N1

enumerator UART_5N2

enumerator UART_6N2

enumerator UART_7N2

enumerator UART_8N2

enumerator UART_5E1

enumerator UART_6E1

enumerator UART_7E1

enumerator UART_8E1

enumerator UART_5E2

enumerator UART_6E2

enumerator UART_7E2

enumerator UART_8E2

enumerator UART_5O1

enumerator UART_6O1

enumerator UART_7O1

enumerator UART_8O1

enumerator UART_5O2

enumerator UART_6O2

enumerator UART_7O2

enumerator UART_8O2

enum smg_uart_status_t

Values:

enumerator UART_STATUS_TX_DONE

All data transmitted (ESP32 only)

enumerator UART_STATUS_RXFIFO_TOUT

enumerator UART_STATUS_BRK_DET

enumerator UART_STATUS_CTS_CHG

enumerator UART_STATUS_DSR_CHG

enumerator UART_STATUS_RXFIFO_OVF

enumerator UART_STATUS_FRM_ERR

enumerator UART_STATUS_PARITY_ERR

enumerator UART_STATUS_TXFIFO_EMPTY

enumerator UART_STATUS_RXFIFO_FULL

enum smg_uart_mode_t

values for mode argument of uart_init

Values:

enumerator UART_FULL

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

enumerator UART_RX_ONLY

Receive only.

enumerator UART_TX_ONLY

Transmit only.

enum smg_uart_option_bits_t

bit values for options argument of uart_init

Note

use _BV(opt) to specify values

Values:

enumerator UART_OPT_TXWAIT

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

enumerator UART_OPT_CALLBACK_RAW

ISR invokes user callback function with no pre-processing.

enum smg_uart_notify_code_t

Indicates notification, parameters refer to uart_notify_info_t structure.

Values:

enumerator UART_NOTIFY_AFTER_OPEN

Called when uart has been initialised successfully.

enumerator UART_NOTIFY_BEFORE_CLOSE

Called immediately before uart is closed and destroyed.

enumerator UART_NOTIFY_AFTER_WRITE

Called after data has been written into tx buffer.

enumerator UART_NOTIFY_BEFORE_READ

Called before data is read from rx buffer.

enumerator UART_NOTIFY_WAIT_TX

Called to ensure all buffered data is output.

using uart_options_t = uint8_t

typedef void (*smg_uart_callback_t)(smg_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

Param arg:

the UART object

Param status:

UART USIS STATUS flag bits indicating cause of interrupt

using smg_uart_notify_callback_t = void (*)(smg_uart_t *uart, smg_uart_notify_code_t code)

Port notification callback function type.

Param info:

Retval bool:

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

static inline constexpr uint8_t SMG_UART_FORMAT(smg_uart_bits_t databits, smg_uart_stop_bits_t stopbits, smg_uart_parity_t parity)

bool smg_uart_set_notify(unsigned uart_nr, smg_uart_notify_callback_t callback)

Set the notification callback function.

Parameters:

• uart_nr – Which uart to register notifications for

• callback –

Return values:

bool – true on success

smg_uart_t *smg_uart_init(uint8_t uart_nr, uint32_t baudrate, smg_uart_format_t format, smg_uart_mode_t mode, uint8_t tx_pin, size_t rx_size, size_t tx_size = 0)

smg_uart_t *smg_uart_init_ex(const smg_uart_config_t &cfg)

void smg_uart_uninit(smg_uart_t *uart)

void smg_uart_set_format(smg_uart_t *uart, smg_uart_format_t format)

Set the UART data format.

Parameters:

• uart –

• format – UART CONF0 register bits

bool smg_uart_intr_config(smg_uart_t *uart, const smg_uart_intr_config_t *config)

Configure interrupt thresholds.

Parameters:

• uart –

• config –

Return values:

bool – true on success, false on error (bad parameter or unsupported)

int smg_uart_get_nr(smg_uart_t *uart)

smg_uart_t *smg_uart_get_uart(uint8_t uart_nr)

Get the uart structure for the given number.

Parameters:

uart_nr –

Return values:

uart_t* – Returns nullptr if uart isn’t initialised

void smg_uart_set_callback(smg_uart_t *uart, smg_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 *smg_uart_get_callback_param(smg_uart_t *uart)

Get the callback parameter specified by uart_set_callback()

Parameters:

uart –

Return values:

void* – the callback parameter

static inline void smg_uart_set_options(smg_uart_t *uart, uart_options_t options)

Set option flags.

Parameters:

• uart –

• options – The option(s) to set

uint8_t smg_uart_get_status(smg_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 values:

Status – error bits:

static inline uart_options_t smg_uart_get_options(smg_uart_t *uart)

void smg_uart_swap(smg_uart_t *uart, int tx_pin)

bool smg_uart_set_tx(smg_uart_t *uart, int tx_pin)

bool smg_uart_set_pins(smg_uart_t *uart, int tx_pin, int rx_pin)

bool smg_uart_tx_enabled(smg_uart_t *uart)

bool smg_uart_rx_enabled(smg_uart_t *uart)

uint32_t smg_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 values:

uint32_t – actual baudrate used, 0 on failure

uint32_t smg_uart_set_baudrate(smg_uart_t *uart, uint32_t baud_rate)

set UART baud rate

Parameters:

• uart –

• baud_rate – requested baud rate

Return values:

uint32_t – actual baudrate used, 0 on failure

uint32_t smg_uart_get_baudrate(smg_uart_t *uart)

get the actual baud rate in use

Parameters:

uart –

Return values:

uint32_t – the baud rate, 0 on failure

size_t smg_uart_resize_rx_buffer(smg_uart_t *uart, size_t new_size)

size_t smg_uart_rx_buffer_size(smg_uart_t *uart)

size_t smg_uart_resize_tx_buffer(smg_uart_t *uart, size_t new_size)

size_t smg_uart_tx_buffer_size(smg_uart_t *uart)

size_t smg_uart_write(smg_uart_t *uart, const void *buffer, size_t size)

write a block of data

Parameters:

• uart –

• buffer –

• size –

Return values:

size_t – number of bytes buffered for transmission

static inline size_t smg_uart_write_char(smg_uart_t *uart, char c)

queue a single character for output

Parameters:

• uart –

• c –

Return values:

size_t – 1 if character was written, 0 on failure

size_t smg_uart_read(smg_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 values:

size_t – number of bytes read

static inline int smg_uart_read_char(smg_uart_t *uart)

read a received character

Parameters:

uart –

Return values:

the – character, -1 on failure

int smg_uart_peek_char(smg_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 values:

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

int smg_uart_peek_last_char(smg_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 values:

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

int smg_uart_rx_find(smg_uart_t *uart, char c)

size_t smg_uart_rx_available(smg_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 values:

size_t –

size_t smg_uart_tx_free(smg_uart_t *uart)

return free space in transmit buffer

void smg_uart_wait_tx_empty(smg_uart_t *uart)

Deprecated:

don’t use this - causes extended delays - use callback notification

void smg_uart_set_break(smg_uart_t *uart, bool state)

Set or clear a break condition on the TX line.

Parameters:

• uart –

• state –

void smg_uart_flush(smg_uart_t *uart, smg_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 smg_uart_set_debug(int uart_nr)

int smg_uart_get_debug()

void smg_uart_start_isr(smg_uart_t *uart)

enable interrupts for a UART

Parameters:

uart –

void smg_uart_stop_isr(smg_uart_t *uart)

disable interrupts for a UART

Parameters:

uart –

void smg_uart_detach(int uart_nr)

detach a UART interrupt service routine

Parameters:

uart_nr –

void smg_uart_detach_all()

detach all UART interrupt service routines

Note

call at startup to put all UARTs into a known state

uint8_t smg_uart_disable_interrupts()

disable interrupts and return current interrupt state

Return values:

state – non-zero if any UART interrupts were active

void smg_uart_restore_interrupts()

re-enable interrupts after calling uart_disable_interrupts()

UART_NO

No UART specified.

UART_PIN_DEFAULT

Use default pin assignments.

UART_PIN_NO_CHANGE

Use default pin assignments.

UART_RX_FIFO_SIZE

UART_TX_FIFO_SIZE

union smg_uart_config_format_t

#include <uart.h>

Structure for easier decomposing of format value.

Used by drivers to read format values

Public Members

smg_uart_parity_t parity

smg_uart_bits_t bits

smg_uart_stop_bits_t stop_bits

struct smg_uart_config_format_t::[anonymous] [anonymous]

uint8_t val

struct smg_uart_t

#include <uart.h>

Public Members

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.

smg_uart_callback_t callback

Optional User callback routine.

void *param

User-supplied callback parameter.

struct smg_uart_config_t

#include <uart.h>

Public Members

uint8_t tx_pin

Specify 2 for alternate pin, otherwise defaults to pin 1.

smg_uart_mode_t mode

Whether to enable receive, transmit or both.

uint32_t baudrate

Requested baudrate; actual baudrate may differ.

smg_uart_format_t format

UART CONF0 register bits.

struct smg_uart_intr_config_t

#include <uart.h>

UART interrupt configuration parameters for smg_uart_intr_config function.

Threshold values are expressed in character times

Public Members

uint8_t rxfifo_full_thresh

Ignored if additional buffers are allocated.

uint32_t intr_mask

Mask of smg_uart_status_t indicating which interrupt bits to change.

uint32_t intr_enable

State of interrupt bits.