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 symbol rate 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	CONFIG_UART_DMA_THRESHOLD_BYTES 8
	Threshold under which polling transfers are used instead of DMA TODO: determine at run-time based on baudrate.

#define	UART_UNDEF (UINT_FAST8_MAX)
	Default UART undefined value.

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

Typedefs
typedef uint_fast8_t	uart_t
	Define default UART type identifier.

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

typedef void(*	uart_rxstart_cb_t) (void *arg)
	Signature for receive start condition interrupt callback.

Enumerations
enum	{ UART_OK = 0 , UART_NODEV = -ENODEV , UART_NOBAUD = -ENOTSUP , UART_NOMODE = -ENOTSUP , UART_INTERR = -EIO }
	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 baud, uart_rx_cb_t rx_cb, void *arg)
	Initialize a given UART device.

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

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

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

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

gpio_t	uart_pin_cts (uart_t uart)
	Get the CTS pin of the given UART.

gpio_t	uart_pin_rts (uart_t uart)
	Get the RTS pin of the given UART.

void	uart_rxstart_irq_configure (uart_t uart, uart_rxstart_cb_t cb, void *arg)
	Configure the function that will be called when a start condition is detected.

void	uart_rxstart_irq_enable (uart_t uart)
	Enable the RX start interrupt.

void	uart_rxstart_irq_disable (uart_t uart)
	Disable the RX start interrupt.

void	uart_collision_detect_enable (uart_t uart)
	Enables collision detection check of the UART.

void	uart_collision_detect_disable (uart_t uart)
	Disables collision detection check of the UART.

bool	uart_collision_detected (uart_t uart)
	Disables collision detection check of the UART.

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.

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

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

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

void	uart_enable_tx (uart_t uart)
	Enable the TX line one the given UART.

void	uart_disable_tx (uart_t uart)
	Disable the TX line one the given UART.

Macro Definition Documentation

◆ CONFIG_UART_DMA_THRESHOLD_BYTES

#define CONFIG_UART_DMA_THRESHOLD_BYTES 8

Threshold under which polling transfers are used instead of DMA TODO: determine at run-time based on baudrate.

Definition at line 78 of file uart.h.

◆ UART_DEV

#define UART_DEV ( x ) (x)

Default UART device access macro.

Definition at line 99 of file uart.h.

◆ UART_UNDEF

#define UART_UNDEF (UINT_FAST8_MAX)

Default UART undefined value.

Definition at line 92 of file uart.h.

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 108 of file uart.h.

◆ uart_rxstart_cb_t

typedef void(* uart_rxstart_cb_t) (void *arg)

Signature for receive start condition interrupt callback.

Parameters

[in] arg context to the callback (optional)

Definition at line 115 of file uart.h.

◆ uart_t

typedef uint_fast8_t uart_t

Define default UART type identifier.

Definition at line 85 of file uart.h.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Possible UART return values.

Deprecated:: Use the errno constants directly instead.

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

Definition at line 136 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 161 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 148 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 173 of file uart.h.

Function Documentation

◆ uart_collision_detect_disable()

void uart_collision_detect_disable ( uart_t uart )

Disables collision detection check of the UART.

     If an RX interrupt was configured before, it is enabled again.

Note: You have to add the module periph_uart_rxstart_irq to your project to enable this function

Parameters

[in] uart The device to configure

◆ uart_collision_detect_enable()

void uart_collision_detect_enable ( uart_t uart )

Enables collision detection check of the UART.

This assumes the UART is connected to a bus where RX and TX are connected. After each sent byte it is checked whether the same byte could be received.

This disables the RX interrupt.

Note: You have to add the module periph_uart_rxstart_irq to your project to enable this function

Parameters

[in] uart The device to configure

◆ uart_collision_detected()

bool uart_collision_detected ( uart_t uart )

Disables collision detection check of the UART.

     If an RX interrupt was configured before, it is enabled again.

Note: You have to add the module periph_uart_rxstart_irq to your project to enable this function

Parameters

[in] uart The device to probe

Returns: true if a collision occurred during the last transder

◆ 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_disable_tx()

void uart_disable_tx ( uart_t uart )

Disable the TX line one the given UART.

Note: requires the periph_uart_tx_ondemand feature

Parameters

[in] uart the UART device to stop TX on

◆ uart_enable_tx()

void uart_enable_tx ( uart_t uart )

Enable the TX line one the given UART.

Note: requires the periph_uart_tx_ondemand feature

Parameters

[in] uart the UART device start TX on

◆ uart_init()

int uart_init	(	uart_t	uart,
		uint32_t	baud,
		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
symbol rate 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]	baud	desired symbol rate in baud
[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

Return values

0	Success
-ENODEV	Invalid UART device
-ENOTSUP	Unsupported symbol rate
<0	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

Return values

0	Success
-ENOTSUP	Given configuration not supported
<0	Other error

◆ uart_pin_cts()

gpio_t uart_pin_cts ( uart_t uart )

Get the CTS 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 CTS line.

◆ uart_pin_rts()

gpio_t uart_pin_rts ( uart_t uart )

Get the RTS 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 RTS line.

◆ 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_rxstart_irq_configure()

void uart_rxstart_irq_configure	(	uart_t	uart,
		uart_rxstart_cb_t	cb,
		void *	arg
	)

Configure the function that will be called when a start condition is detected.

This will not enable / disable the generation of the RX start interrupt.

Note: You have to add the module periph_uart_rxstart_irq to your project to enable this function

Parameters

[in]	uart	The device to configure
[in]	cb	The function called when a start condition is detected
[in]	arg	Optional function argument

◆ uart_rxstart_irq_disable()

void uart_rxstart_irq_disable ( uart_t uart )

Disable the RX start interrupt.

Note: You have to add the module periph_uart_rxstart_irq to your project to enable this function

Parameters

[in] uart The device to configure

◆ uart_rxstart_irq_enable()

void uart_rxstart_irq_enable ( uart_t uart )

Enable the RX start interrupt.

Note: You have to add the module periph_uart_rxstart_irq to your project to enable this function

Parameters

[in] uart The device to configure

◆ 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

Macro Definition Documentation

◆ CONFIG_UART_DMA_THRESHOLD_BYTES

◆ UART_DEV

◆ UART_UNDEF

Typedef Documentation

◆ uart_rx_cb_t

◆ uart_rxstart_cb_t

◆ uart_t

Enumeration Type Documentation

◆ anonymous enum

◆ uart_data_bits_t

◆ uart_parity_t

◆ uart_stop_bits_t

Function Documentation

◆ uart_collision_detect_disable()

◆ uart_collision_detect_enable()

◆ uart_collision_detected()

◆ uart_deinit_pins()

◆ uart_disable_tx()

◆ uart_enable_tx()

◆ uart_init()

◆ uart_init_pins()

◆ uart_mode()

◆ uart_pin_cts()

◆ uart_pin_rts()

◆ uart_pin_rx()

◆ uart_pin_tx()

◆ uart_poweroff()

◆ uart_poweron()

◆ uart_rxstart_irq_configure()

◆ uart_rxstart_irq_disable()

◆ uart_rxstart_irq_enable()

◆ uart_write()