UART: Universal Asynchronous Receive/Transmit

Custom asynchronous driver.

enum uart_driver::smg_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.

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::smg_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.

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::smg_uart_notify_code_t

Indicates notification, parameters refer to uart_notify_info_t structure.

Values:

UART_NOTIFY_AFTER_OPEN

Called when uart has been initialised 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.

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.

enum uart_driver::smg_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.

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::smg_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.

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::smg_uart_notify_code_t

Indicates notification, parameters refer to uart_notify_info_t structure.

Values:

UART_NOTIFY_AFTER_OPEN

Called when uart has been initialised 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.

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 smg_uart_mode_ smg_uart_mode_t

typedef uint8_t uart_options_t

typedef struct smg_uart_ smg_uart_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

Parameters

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

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

typedef enum smg_uart_mode_ smg_uart_mode_t

typedef uint8_t uart_options_t

typedef struct smg_uart_ smg_uart_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

Parameters

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

typedef void (*smg_uart_notify_callback_t)(smg_uart_t *uart, smg_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 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 Value

• bool: true on success

smg_uart_t *smg_uart_init(uint8_t uart_nr, uint32_t baudrate, uint32_t config, 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 &cfg)

void smg_uart_uninit(smg_uart_t *uart)

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 Value

• 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 Value

• void*: the callback parameter

static 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 Value

• Status: error bits:

static uart_options_t smg_uart_get_options(smg_uart_t *uart)

void smg_uart_swap(smg_uart_t *uart, int tx_pin)

void smg_uart_set_tx(smg_uart_t *uart, int tx_pin)

void smg_uart_set_pins(smg_uart_t *uart, int tx, int rx)

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 Value

• 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 Value

• 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 Value

• 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 Value

• size_t: number of bytes buffered for transmission

static size_t smg_uart_write_char(smg_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 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 Value

• size_t: number of bytes read

static int smg_uart_read_char(smg_uart_t *uart)

read a received character

Parameters

• uart:

Return Value

• 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 Value

• 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 Value

• 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 Value

• 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)

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 Value

• state: non-zero if any UART interrupts were active

void smg_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

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 smg_uart_

#include <uart.h>

Public Members

uint8_t uart_nr

uint32_t baud_rate

smg_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.

smg_uart_callback_t callback

Optional User callback routine.

void *param

User-supplied callback parameter.

uart_port_t uart_nr

struct smg_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.

smg_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

uint8_t rx_pin