UART Driver¶

UART driver provides functionality for asynchronous serial communication to access serial ports.

To use this library

Header: #include "drv_uart.h"

memake: MikroSDK.Driver

Communication may be simplex, full duplex or half duplex. Microcontrollers usually have one or more UART integrated modules.
The driver has two modes of operation, blocking and non-blocking:

In the blocking mode, functions for reading and writing block program execution until all data is transmitted, any data is received over serial port or if an error occurred.
In the non-blocking mode, function calls return immediately.

Default mode is non-blocking.

Initialization¶

Example initialization of UART driver instance:

uart_t uart;
uart_config_t uart_cfg;

uint8_t uart_rx_buffer[256];
uint8_t uart_tx_buffer[256];

uart_configure_default( &uart_cfg );

uart.tx_ring_buffer = uart_tx_buffer;
uart.rx_ring_buffer = uart_rx_buffer;

uart_cfg.rx_pin = PC7;
uart_cfg.tx_pin = PC6;
uart_cfg.tx_ring_size = sizeof( uart_tx_buffer );
uart_cfg.rx_ring_size = sizeof( uart_rx_buffer );

uart_open( &uart, &uart_cfg );

Before using any other function, UART driver context must be initialized by calling uart_open() function. After that, you can call functions for setting communication parameters such as baud rate or parity. Buffers uart_rx_buffer and uart_tx_buffer provided in open function are internal circular buffers used by the driver, to store received data and pending transmit data. User must ensure that they are large enough to store all received data in order to prevent any data loss. Whether data loss will occur depends on how fast the new data arrives, as well as how often the data is read from the buffer.

Default parameters

If not specified, the communication parameters are set to:

Baud rate: 115200
Data bits: 8
Stop bits: 1
Parity: none

To set operation mode, use uart_set_blocking() function as shown bellow:

uart_set_blocking(&uart, true);

The driver tries to find corresponding UART module for configured pins. If target MCU does not have UART hardware module connected on selected GPIO pins, uart_open() returns error.

Reading¶

Reading from serial port can be done with uart_read() function. It reads up to size of bytes and copies them to buffer array. Function returns the number of bytes actually read or an error.

Example usage is shown below:

int result = 0;
uint8_t buffer[16];

result = uart_read( &uart, buffer, sizeof( buffer ) );

Be sure that the parameter size is not larger than buffer array length in bytes to ensure that memory outside of array buffer is not overwritten.

In the non-blocking mode it returns immediately and returns the actual number of bytes copied to buffer.
In the blocking mode, this function waits until at least one byte is received over serial port.

Writing¶

Writing to serial port can be done with uart_write() function. It writes size of bytes to serial port from buffer array.
In non-blocking mode this function copies data from buffer to internal circular buffer and returns immediately.
In blocking mode, the function call blocks code execution until all bytes are written to serial port. It returns the number of bytes that were actually written.

Example usage is shown below:

int result = 0;
uint8_t buffer[] = {'A', 'T'};

result = uart_write( &uart, buffer, sizeof( buffer ) );

The library also provides two utility functions for writing cstrings: uart_print() and uart_println(). Example for writing a single line on serial port:

uart_print( &uart, "Hello!" );
uart_println( &uart, "This is a simple UART example!" );