Loading...
Searching...
No Matches

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]argcontext to the callback (optional)
[in]datathe 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]argcontext 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

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

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

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]uartThe 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]uartThe 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]uartThe 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]uartthe 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]uartthe 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]uartthe 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]uartUART device to initialize
[in]bauddesired symbol rate in baud
[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
Return values
0Success
-ENODEVInvalid UART device
-ENOTSUPUnsupported symbol rate
<0On 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]uartUART 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]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
Return values
0Success
-ENOTSUPGiven configuration not supported
<0Other error

◆ uart_pin_cts()

gpio_t uart_pin_cts ( uart_t  uart)

Get the CTS pin of the given UART.

Parameters
[in]uartThe 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]uartThe 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]uartThe 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]uartThe 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]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_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]uartThe device to configure
[in]cbThe function called when a start condition is detected
[in]argOptional 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]uartThe 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]uartThe 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]uartUART device to use for transmission
[in]datadata buffer to send
[in]lennumber of bytes to send