Description

Driver for the UART peripheral for serial communication.

File(s):

The driver must be configured by supplying a project specific "px_uart_cfg.h". "px_uart_cfg_template.h" can be copied, renamed and modified to supply compile time options.

#include "px_board.h"
#include "px_compiler.h"
#include "px_uart.h"
 
// Create UART handle object
static px_uart_handle_t px_uart_handle;
 
int main(void)
{
    uint8_t data;
 
    // Initialise board
    px_board_init();
    // Initialise module
    px_uart_init();
    // Enable interrupts
    px_interrupts_enable();
    // Open UART0 @ 115200 BAUD, 8 data bits, no parity, 1 stop bit
    px_uart_open2(&px_uart_handle,
                  PX_UART_NR_0, 
                  115200, 
                  PX_UART_DATA_BITS_8, 
                  PX_UART_PARITY_NONE, 
                  PX_UART_STOP_BITS_1);
 
    // Loop forever
    while(true)
    {
        // Wait until a byte is received
        if(px_uart_rd_u8(&px_uart_handle, &data))
        {
            // Send back received byte (loopback/echo mode)
            px_uart_wr_u8(&px_uart_handle, data);
        }
    }
}

Data Structures
struct	px_uart_handle_t
	Define UART handle. More...

Macros
#define	PX_UART_CFG_PER_COUNT
	Number of enabled peripherals. More...

#define	PX_UART_CFG_UART0_EN 1
	Enable/disable support for UART0 peripheral. More...

#define	PX_UART_CFG_UART1_EN 0
	Enable/disable support for UART1 peripheral. More...

#define	PX_UART_CFG_DEFAULT_BAUD 115200ul
	Default BAUD rate. More...

#define	PX_UART_CFG_DEFAULT_UCSRC ((1 << UCSZ01) \| (1 << UCSZ00))
	Default UART configuration (8 data bits, no parity, 1 stop bit) More...

#define	PX_UART_CFG_TX_BUF_SIZE 32
	Size of transmit buffer (must be a power of two, e.g. 2,4,8,..., 256) More...

#define	PX_UART_CFG_RX_BUF_SIZE 64
	Size of receive buffer (must be a power of two, e.g. 2,4,8,..., 256) More...

#define	PX_UART_CFG_USE_2X_BAUD_RATE 1
	Use double rate UART Transmission speed (0 = no; 1 = yes) More...

Enumerations
enum	px_uart_nr_t
	Specify UART peripheral. More...

enum	px_uart_parity_t
	Specify UART parity (none, odd or even) More...

enum	px_uart_stop_bits_t
	Specify number of stop bits (1/2) More...

Functions
void	px_uart_init (void)
	Initialise UART driver. More...

bool	px_uart_open (px_uart_handle_t *handle, px_uart_nr_t uart_nr)
	Open UART peripheral using predefined (default) parameters. More...

bool	px_uart_open2 (px_uart_handle_t *handle, px_uart_nr_t uart_nr, uint32_t baud, px_uart_data_bits_t data_bits, px_uart_parity_t parity, px_uart_stop_bits_t stop_bits)
	Open UART peripheral using specified parameters. More...

bool	px_uart_close (px_uart_handle_t *handle)
	Close specified peripheral. More...

void	px_uart_putchar (px_uart_handle_t *handle, char data)
	Write one byte. More...

bool	px_uart_wr_u8 (px_uart_handle_t *handle, uint8_t data)
	Buffer one byte for transmission. More...

size_t	px_uart_wr (px_uart_handle_t handle, const void data, size_t nr_of_bytes)
	Buffer byte(s) for transmission. More...

char	px_uart_getchar (px_uart_handle_t *handle)
	Read one byte. More...

bool	px_uart_rd_u8 (px_uart_handle_t handle, uint8_t data)
	See if a received byte is available and store it in the specified location. More...

size_t	px_uart_rd (px_uart_handle_t handle, void buf, size_t nr_of_bytes)
	Copy received data from receive buffer into specified buffer. More...

bool	px_uart_wr_buf_is_full (px_uart_handle_t *handle)
	See if transmit buffer can accept more data. More...

bool	px_uart_wr_buf_is_empty (px_uart_handle_t *handle)
	See if transmit buffer is empty. More...

bool	px_uart_wr_is_done (px_uart_handle_t *handle)
	See if all transmission has finished, including last byte. More...

bool	px_uart_rd_buf_is_empty (px_uart_handle_t *handle)
	See if there is received data in the receive buffer. More...

bool	px_uart_change_baud (px_uart_handle_t *handle, uint32_t baud)
	Change UART peripheral baud rate. More...

Data Structure Documentation

◆ px_uart_handle_t

struct px_uart_handle_t

Define UART handle.

Definition at line 140 of file px_uart.h.

Data Fields
struct px_uart_per_s *	uart_per	USART peripheral data.

Macro Definition Documentation

◆ PX_UART_CFG_PER_COUNT

#define PX_UART_CFG_PER_COUNT

Value:

( PX_UART_CFG_UART0_EN \

+ PX_UART_CFG_UART1_EN )

PX_UART_CFG_UART0_EN

#define PX_UART_CFG_UART0_EN

Enable/disable support for UART0 peripheral.

Definition: px_uart_cfg_template.h:34

PX_UART_CFG_UART1_EN

#define PX_UART_CFG_UART1_EN

Enable/disable support for UART1 peripheral.

Definition: px_uart_cfg_template.h:35

Number of enabled peripherals.

Definition at line 64 of file px_uart.h.

◆ PX_UART_CFG_UART0_EN

#define PX_UART_CFG_UART0_EN 1

Enable/disable support for UART0 peripheral.

Definition at line 34 of file px_uart_cfg_template.h.

◆ PX_UART_CFG_UART1_EN

#define PX_UART_CFG_UART1_EN 0

Enable/disable support for UART1 peripheral.

Definition at line 37 of file px_uart_cfg_template.h.

◆ PX_UART_CFG_DEFAULT_BAUD

#define PX_UART_CFG_DEFAULT_BAUD 115200ul

Default BAUD rate.

Definition at line 40 of file px_uart_cfg_template.h.

◆ PX_UART_CFG_DEFAULT_UCSRC

#define PX_UART_CFG_DEFAULT_UCSRC ((1 << UCSZ01) | (1 << UCSZ00))

Default UART configuration (8 data bits, no parity, 1 stop bit)

Definition at line 43 of file px_uart_cfg_template.h.

◆ PX_UART_CFG_TX_BUF_SIZE

#define PX_UART_CFG_TX_BUF_SIZE 32

Size of transmit buffer (must be a power of two, e.g. 2,4,8,..., 256)

Definition at line 46 of file px_uart_cfg_template.h.

◆ PX_UART_CFG_RX_BUF_SIZE

#define PX_UART_CFG_RX_BUF_SIZE 64

Size of receive buffer (must be a power of two, e.g. 2,4,8,..., 256)

Definition at line 49 of file px_uart_cfg_template.h.

◆ PX_UART_CFG_USE_2X_BAUD_RATE

#define PX_UART_CFG_USE_2X_BAUD_RATE 1

Use double rate UART Transmission speed (0 = no; 1 = yes)

If enabled, it results in a smaller BAUD rate error when using imprecise clock inputs, e.g. for F_CPU = 16 MHz and desired Baud Rate = 115200:

U2Xn = 0 : UBBRn = 8 (-3.5% error)
U2Xn = 1 : UBBRn = 16 (+2.1% error)

Definition at line 59 of file px_uart_cfg_template.h.

Enumeration Type Documentation

◆ px_uart_nr_t

enum px_uart_nr_t

Specify UART peripheral.

Definition at line 77 of file px_uart.h.

◆ px_uart_parity_t

enum px_uart_parity_t

Specify UART parity (none, odd or even)

Definition at line 84 of file px_uart.h.

◆ px_uart_stop_bits_t

enum px_uart_stop_bits_t

Specify number of stop bits (1/2)

Definition at line 101 of file px_uart.h.

Function Documentation

◆ px_uart_init()

void px_uart_init ( void )

Initialise UART driver.

Definition at line 452 of file px_uart.c.

◆ px_uart_open()

bool px_uart_open	(	px_uart_handle_t *	handle,
		px_uart_nr_t	uart_nr
	)

Open UART peripheral using predefined (default) parameters.

Parameters

handle	Pointer to handle data structure
uart_nr	UART peripheral number.

See also: px_uart_nr_t

Return values

false	Error: peripheral was not opened
true	Success: peripheral was opened

Definition at line 472 of file px_uart.c.

◆ px_uart_open2()

bool px_uart_open2	(	px_uart_handle_t *	handle,
		px_uart_nr_t	uart_nr,
		uint32_t	baud,
		px_uart_data_bits_t	data_bits,
		px_uart_parity_t	parity,
		px_uart_stop_bits_t	stop_bits
	)

Open UART peripheral using specified parameters.

Parameters

handle	Pointer to handle data structure
uart_nr	UART peripheral number.

See also: px_uart_nr_t

Parameters

baud	Baud rate in bits/s
data_bits	Data bits.

See also: px_uart_data_bits_t

Parameters

parity Parity.

See also: px_uart_parity_t

Parameters

stop_bits Stop bits.

See also: px_uart_stop_bits_t

Return values

false	Error: peripheral was not opened
true	Success: peripheral was opened

Definition at line 483 of file px_uart.c.

◆ px_uart_close()

bool px_uart_close ( px_uart_handle_t * handle )

Close specified peripheral.

Parameters

handle Pointer to handle data structure

Return values

true	Success
false	Specified peripheral was already closed (or not opened)

Definition at line 544 of file px_uart.c.

◆ px_uart_putchar()

void px_uart_putchar	(	px_uart_handle_t *	handle,
		char	data
	)

Write one byte.

This function blocks until space is available in the write buffer.

Parameters

	handle	Pointer to handle data structure
[in]	data	Byte to be written

Definition at line 632 of file px_uart.c.

◆ px_uart_wr_u8()

bool px_uart_wr_u8	(	px_uart_handle_t *	handle,
		uint8_t	data
	)

Buffer one byte for transmission.

Parameters

	handle	Pointer to handle data structure
[in]	data	Byte to be written

Return values

true	Byte has been buffered
false	Byte has not been buffered, because write buffer is full

Definition at line 651 of file px_uart.c.

◆ px_uart_wr()

size_t px_uart_wr	(	px_uart_handle_t *	handle,
		const void *	data,
		size_t	nr_of_bytes
	)

Buffer byte(s) for transmission.

Note: The write buffer may not be able to hold all of the specified data.

Parameters

	handle	Pointer to handle data structure
[in]	data	Buffer containing data for transmission
[in]	nr_of_bytes	Number of bytes in buffer to be written

Returns: size_t The actual number of bytes buffered for transmission.

Definition at line 677 of file px_uart.c.

◆ px_uart_getchar()

char px_uart_getchar ( px_uart_handle_t * handle )

Read one byte.

This function blocks until a byte is received.

Parameters

handle Pointer to handle data structure

Returns: Received byte

Definition at line 706 of file px_uart.c.

◆ px_uart_rd_u8()

bool px_uart_rd_u8	(	px_uart_handle_t *	handle,
		uint8_t *	data
	)

See if a received byte is available and store it in the specified location.

Parameters

	handle	Pointer to handle data structure
[out]	data	Pointer to location where data byte must be stored

Return values

true	Received byte is stored in specified location
false	No received data available (receive buffer empty)

Definition at line 726 of file px_uart.c.

◆ px_uart_rd()

size_t px_uart_rd	(	px_uart_handle_t *	handle,
		void *	buf,
		size_t	nr_of_bytes
	)

Copy received data from receive buffer into specified buffer.

Parameters

	handle	Pointer to handle data structure
[out]	buf	Buffer to copy received data into
[in]	nr_of_bytes	Maximum number of received bytes to copy into buffer

Returns: size_t Number of received bytes copied into buffer

Definition at line 743 of file px_uart.c.

◆ px_uart_wr_buf_is_full()

bool px_uart_wr_buf_is_full ( px_uart_handle_t * handle )

See if transmit buffer can accept more data.

Parameters

handle Pointer to handle data structure

Return values

true	Transmit buffer is full
false	Transmit buffer has space for at least one byte

Definition at line 762 of file px_uart.c.

◆ px_uart_wr_buf_is_empty()

bool px_uart_wr_buf_is_empty ( px_uart_handle_t * handle )

See if transmit buffer is empty.

Note: Buffer may be empty, but UART peripheral may still be busy with the transmission of the last byte in the buffer.

See also: px_uart_tx_finished.

Parameters

handle Pointer to handle data structure

Return values

true	Transmit buffer is empty
false	Transmit buffer has space for at least one byte

Definition at line 778 of file px_uart.c.

◆ px_uart_wr_is_done()

bool px_uart_wr_is_done ( px_uart_handle_t * handle )

See if all transmission has finished, including last byte.

This functions is usefull for communication standards like RS-485 where the mode must be changed manually from TX to RX after transmission.

Parameters

handle Pointer to handle data structure

Return values

true	Transmision completely finished
false	Busy with transmission

Definition at line 794 of file px_uart.c.

◆ px_uart_rd_buf_is_empty()

bool px_uart_rd_buf_is_empty ( px_uart_handle_t * handle )

See if there is received data in the receive buffer.

Parameters

handle Pointer to handle data structure

Return values

true	There is received data in the receive buffer
false	The receive buffer is empty

Definition at line 817 of file px_uart.c.

◆ px_uart_change_baud()

bool px_uart_change_baud	(	px_uart_handle_t *	handle,
		uint32_t	baud
	)

Change UART peripheral baud rate.

Parameters

handle	Pointer to handle data structure
baud	Baud rate in bits/s

Return values

true	Success. Baud was changed
false	Error. Requested baud invalid

Definition at line 833 of file px_uart.c.

Description

Data Structures

Macros

Enumerations

Functions

Data Structure Documentation

◆ px_uart_handle_t

Macro Definition Documentation

◆ PX_UART_CFG_PER_COUNT

◆ PX_UART_CFG_UART0_EN

◆ PX_UART_CFG_UART1_EN

◆ PX_UART_CFG_DEFAULT_BAUD

◆ PX_UART_CFG_DEFAULT_UCSRC

◆ PX_UART_CFG_TX_BUF_SIZE

◆ PX_UART_CFG_RX_BUF_SIZE

◆ PX_UART_CFG_USE_2X_BAUD_RATE

Enumeration Type Documentation

◆ px_uart_nr_t

◆ px_uart_parity_t

◆ px_uart_stop_bits_t

Function Documentation

◆ px_uart_init()

◆ px_uart_open()

◆ px_uart_open2()

◆ px_uart_close()

◆ px_uart_putchar()

◆ px_uart_wr_u8()

◆ px_uart_wr()

◆ px_uart_getchar()

◆ px_uart_rd_u8()

◆ px_uart_rd()

◆ px_uart_wr_buf_is_full()

◆ px_uart_wr_buf_is_empty()

◆ px_uart_wr_is_done()

◆ px_uart_rd_buf_is_empty()

◆ px_uart_change_baud()