Low-level UART peripheral driver. More...

Detailed Description

Low-level UART peripheral driver.

This is a basic UART (Universal Asynchronous Receiver Transmitter) interface to allow platform independent access to the MCU's serial communication abilities. This interface is intentionally designed to be as simple as possible, to allow for easy implementation and maximum portability.

The simple interface provides capabilities to initialize and configure the serial communication module, which automatically enables for receiving data, as well as writing data to the UART port, which means transmitting data. The UART device and the corresponding pins need to be mapped in RIOT/boards/ * /include/periph_conf.h. Furthermore, you need to select the baudrate for initialization which is typically {9600, 19200, 38400, 57600, 115200} baud. Additionally, you should register a callback function that is executed in interrupt context when data is being received. The driver will then read the received data byte, call the registered callback function and pass the received data to it via its argument. The interface enforces the receiving to be implemented in an interrupt driven mode. Thus, you never know how many bytes are going to be received and might want to handle that in your specific callback function. The transmit function can be implemented in any way. You can also configure parity, the number of data and stop bits, i.e. such combinations as 8-E-1, 7-N-2 etc. 8-N-1 mode is set by default.

By default the UART_DEV(0) device of each board is initialized and mapped to STDIO in RIOT which is used for standard input/output functions like printf() or puts().

(Low-) Power Implications

After initialization, the UART peripheral should be powered on and active. The UART can later be explicitly put to sleep and woken up by calling the uart_poweron() and uart_poweroff() functions. Once woken up using uart_poweron(), the UART should transparently continue it's previously configured operation.

While the UART is active, the implementation might need to block certain power states.

Files
file	uart.h
	Low-level UART peripheral driver interface definition.

Data Structures
struct	uart_isr_ctx_t
	Interrupt context for a UART device. More...

Macros
#define	UART_UNDEF (UINT_MAX)
	Default UART undefined value.

#define	UART_DEV(x) (x)
	Default UART device access macro.

Typedefs
typedef unsigned int	uart_t
	Define default UART type identifier.

typedef void(*	uart_rx_cb_t) (void *arg, uint8_t data)
	Signature for receive interrupt callback. More...

Enumerations
enum	{ UART_OK = 0, UART_NODEV = -1, UART_NOBAUD = -2, UART_INTERR = -3, UART_NOMODE = -4 }
	Possible UART return values. More...

enum	uart_parity_t { UART_PARITY_NONE, UART_PARITY_EVEN, UART_PARITY_ODD, UART_PARITY_MARK, UART_PARITY_SPACE }
	Definition of possible parity modes. More...

enum	uart_data_bits_t { UART_DATA_BITS_5, UART_DATA_BITS_6, UART_DATA_BITS_7, UART_DATA_BITS_8 }
	Definition of possible data bits lengths in a UART frame. More...

enum	uart_stop_bits_t { UART_STOP_BITS_1, UART_STOP_BITS_2 }
	Definition of possible stop bits lengths in a UART frame. More...

Functions
int	uart_init (uart_t uart, uint32_t baudrate, uart_rx_cb_t rx_cb, void *arg)
	Initialize a given UART device. More...

void	uart_deinit_pins (uart_t uart)
	Change the pins of the given UART back to plain GPIO functionality. More...

void	uart_init_pins (uart_t uart)
	Initialize the used UART pins, i.e. More...

gpio_t	uart_pin_rx (uart_t uart)
	Get the RX pin of the given UART. More...

gpio_t	uart_pin_tx (uart_t uart)
	Get the TX pin of the given UART. More...

int	uart_mode (uart_t uart, uart_data_bits_t data_bits, uart_parity_t parity, uart_stop_bits_t stop_bits)
	Setup parity, data and stop bits for a given UART device. More...

void	uart_write (uart_t uart, const uint8_t *data, size_t len)
	Write data from the given buffer to the specified UART device. More...

void	uart_poweron (uart_t uart)
	Power on the given UART device. More...

void	uart_poweroff (uart_t uart)
	Power off the given UART device. More...

Typedef Documentation

◆ uart_rx_cb_t

typedef void(* uart_rx_cb_t) (void *arg, uint8_t data)

Signature for receive interrupt callback.

Parameters

[in]	arg	context to the callback (optional)
[in]	data	the byte that was received

Definition at line 99 of file uart.h.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Possible UART return values.

Enumerator
UART_OK	everything in order
UART_NODEV	invalid UART device given
UART_NOBAUD	given baudrate is not applicable
UART_INTERR	all other internal errors
UART_NOMODE	given mode is not applicable

Definition at line 114 of file uart.h.

◆ uart_data_bits_t

enum uart_data_bits_t

Definition of possible data bits lengths in a UART frame.

Enumerator
UART_DATA_BITS_5	5 data bits
UART_DATA_BITS_6	6 data bits
UART_DATA_BITS_7	7 data bits
UART_DATA_BITS_8	8 data bits

Definition at line 139 of file uart.h.

◆ uart_parity_t

enum uart_parity_t

Definition of possible parity modes.

Enumerator
UART_PARITY_NONE	no parity
UART_PARITY_EVEN	even parity
UART_PARITY_ODD	odd parity
UART_PARITY_MARK	mark parity
UART_PARITY_SPACE	space parity

Definition at line 126 of file uart.h.

◆ uart_stop_bits_t

enum uart_stop_bits_t

Definition of possible stop bits lengths in a UART frame.

Enumerator
UART_STOP_BITS_1	1 stop bit
UART_STOP_BITS_2	2 stop bits

Definition at line 151 of file uart.h.

Function Documentation

◆ uart_deinit_pins()

void uart_deinit_pins ( uart_t uart )

Change the pins of the given UART back to plain GPIO functionality.

The pin mux of the RX and TX pins of the bus will be changed back to default (GPIO) mode and the UART is powered off. This allows to use the UART pins for another function and return to UART functionality again by calling uart_init_pins

If you want the pin to be in a defined state, call gpio_init on it.

Note: Until this is implemented on all platforms, this requires the periph_uart_reconfigure feature to be used.

Parameters

[in] uart the device to de-initialize

◆ uart_init()

int uart_init	(	uart_t	uart,
		uint32_t	baudrate,
		uart_rx_cb_t	rx_cb,
		void *	arg
	)

Initialize a given UART device.

The UART device will be initialized with the following configuration:

8 data bits
no parity
1 stop bit
baudrate as given

If no callback parameter is given (rx_cb := NULL), the UART will be initialized in TX only mode.

Parameters

[in]	uart	UART device to initialize
[in]	baudrate	desired baudrate in baud/s
[in]	rx_cb	receive callback, executed in interrupt context once for every byte that is received (RX buffer filled), set to NULL for TX only mode
[in]	arg	optional context passed to the callback functions

Returns: UART_OK on success; UART_NODEV on invalid UART device; UART_NOBAUD on inapplicable baudrate; UART_INTERR on other errors

◆ uart_init_pins()

void uart_init_pins ( uart_t uart )

Initialize the used UART pins, i.e.

RX and TX

After calling uart_init, the pins must be initialized (i.e. uart_init is calling this function internally). In normal cases, this function will not be used. But there are some devices, that use UART bus lines also for other purposes and need the option to dynamically re-configure one or more of the used pins. So they can take control over certain pins and return control back to the UART driver using this function.

The pins used are configured in the board's periph_conf.h.

Parameters

[in] uart UART device the pins are configure for

◆ uart_mode()

int uart_mode	(	uart_t	uart,
		uart_data_bits_t	data_bits,
		uart_parity_t	parity,
		uart_stop_bits_t	stop_bits
	)

Setup parity, data and stop bits for a given UART device.

Parameters

[in]	uart	UART device to configure
[in]	data_bits	number of data bits in a UART frame
[in]	parity	parity mode
[in]	stop_bits	number of stop bits in a UART frame

Returns: UART_OK on success; UART_NOMODE on other errors

◆ uart_pin_rx()

gpio_t uart_pin_rx ( uart_t uart )

Get the RX pin of the given UART.

Parameters

[in] uart The device to query

Note: Until this is implemented on all platforms, this requires the periph_uart_reconfigure feature to be used.

Returns: The GPIO used for the UART RX line.

◆ uart_pin_tx()

gpio_t uart_pin_tx ( uart_t uart )

Get the TX pin of the given UART.

Parameters

[in] uart The device to query

Note: Until this is implemented on all platforms, this requires the periph_uart_reconfigure feature to be used.

Returns: The GPIO used for the UART TX line.

◆ uart_poweroff()

void uart_poweroff ( uart_t uart )

Power off the given UART device.

Parameters

[in] uart the UART device to power off

◆ uart_poweron()

void uart_poweron ( uart_t uart )

Power on the given UART device.

Parameters

[in] uart the UART device to power on

◆ uart_write()

void uart_write	(	uart_t	uart,
		const uint8_t *	data,
		size_t	len
	)

Write data from the given buffer to the specified UART device.

This function is blocking, as it will only return after len bytes from the given buffer have been send. The way this data is send is up to the implementation: active waiting, interrupt driven, DMA, etc.

Parameters

[in]	uart	UART device to use for transmission
[in]	data	data buffer to send
[in]	len	number of bytes to send

Detailed Description

(Low-) Power Implications

Files

Data Structures

Macros

Typedefs

Enumerations

Functions

Typedef Documentation

◆ uart_rx_cb_t

Enumeration Type Documentation

◆ anonymous enum

◆ uart_data_bits_t

◆ uart_parity_t

◆ uart_stop_bits_t

Function Documentation

◆ uart_deinit_pins()

◆ uart_init()

◆ uart_init_pins()

◆ uart_mode()

◆ uart_pin_rx()

◆ uart_pin_tx()

◆ uart_poweroff()

◆ uart_poweron()

◆ uart_write()