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 = 0x5, UART_DATA_BITS_6 = 0x6, UART_DATA_BITS_7 = 0x7, UART_DATA_BITS_8 = 0x0,
  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...
 
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]argcontext to the callback (optional)
[in]datathe byte that was received

Definition at line 101 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 116 of file uart.h.

◆ 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

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

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

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

Function Documentation

◆ 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]uartUART device to initialize
[in]baudratedesired baudrate in baud/s
[in]rx_cbreceive callback, executed in interrupt context once for every byte that is received (RX buffer filled), set to NULL for TX only mode
[in]argoptional 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_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]uartUART device to configure
[in]data_bitsnumber of data bits in a UART frame
[in]parityparity mode
[in]stop_bitsnumber of stop bits in a UART frame
Returns
UART_OK on success
UART_NOMODE on other errors

◆ uart_poweroff()

void uart_poweroff ( uart_t  uart)

Power off the given UART device.

Parameters
[in]uartthe UART device to power off

◆ uart_poweron()

void uart_poweron ( uart_t  uart)

Power on the given UART device.

Parameters
[in]uartthe 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]uartUART device to use for transmission
[in]datadata buffer to send
[in]lennumber of bytes to send