UART HAL

UART Hardware Abstraction Layer API Reference. More...

Functions list
void	hal_uart_configure_default (hal_uart_config_t *config)
	Configure UART configuration structure with default values. More...
err_t	hal_uart_open (handle_t *handle, bool hal_obj_open_state)
	Open the UART HAL layer object on selected pins. More...
err_t	hal_uart_set_baud (handle_t *handle, hal_uart_config_t *config)
	Set the UART baud rate. More...
err_t	hal_uart_set_parity (handle_t *handle, hal_uart_config_t *config)
	Set the UART parity. More...
err_t	hal_uart_set_stop_bits (handle_t *handle, hal_uart_config_t *config)
	Set the number of UART stop bits. More...
err_t	hal_uart_set_data_bits (handle_t *handle, hal_uart_config_t *config)
	Set the number of UART data bits. More...
void	hal_uart_set_blocking (handle_t *handle, bool blocking)
	Set UART HAL in blocking/non-blocking mode. More...
size_t	hal_uart_write (handle_t *handle, uint8_t *buffer, size_t size)
	Write data to UART. More...
size_t	hal_uart_print (handle_t *handle, char *text)
	Print the string to UART. More...
size_t	hal_uart_println (handle_t *handle, char *text)
	Print the string to UART and append new line. More...
size_t	hal_uart_read (handle_t *handle, uint8_t *buffer, size_t size)
	Read data from UART. More...
size_t	hal_uart_bytes_available (hal_uart_t *hal_obj)
	Check number of data available to read. More...
void	hal_uart_clear (hal_uart_t *hal_obj)
	Discard all characters from UART buffers. More...
err_t	hal_uart_close (handle_t *handle)
	Close UART HAL layer object. More...

Detailed Description

API for configuring and manipulating UART HAL module.

Function Documentation

hal_uart_configure_default()

void hal_uart_configure_default

(

hal_uart_config_t *

config

)

Configures structure to default initialization values. Take into consideration that this is just structure variable initial values setting. Values need to be redefined by user.

Parameters

[in,out]

config

UART HAL layer configuration structure. See hal_uart_config_t structure definition for detailed explanation.

Default values:

Function	Default value
Tx pin	HAL_PIN_NC (invalid pin)
Rx pin	HAL_PIN_NC (invalid pin)
Baud rate	115200
Data bits	8 data bits
Parity	no parity
Stop bits	1 stop bit
Tx buffer	cleared
Rx buffer	cleared
Tx ring buffer size	zero
Rx ring buffer size	zero

Returns

Nothing.

Example

// UART HAL config structure
static hal_uart_config_t hal_uart_cfg;
 
// Fill structure with default values
hal_uart_configure_default( &hal_uart_cfg );

hal_uart_open()

err_t hal_uart_open	(	handle_t *	handle,
		bool	hal_obj_open_state
	)

Function opens the UART HAL layer object on selected pins and allocates memory needed for UART module, pins and ring buffers for specified object. Also, initializes interrupts on the global level.

Parameters

[in,out]	handle	UART handle. See hal_uart_t structure definition for detailed explanation.
[in]	hal_obj_open_state	UART state, is it open or not.

Returns

The function can return one of the values defined in the hal_uart_err_t enum list.

Note

It is recommended to check return value for error.

Example

// UART HAL context structure
static hal_uart_t hal_uart;
 
// UART HAL config structure
static hal_uart_config_t hal_uart_cfg;
 
// Be careful to have large enough buffers
static uint8_t uart_rx_buffer[128];
 
// Be careful to have large enough buffers
static uint8_t uart_tx_buffer[128];
 
// Fill structure with default values
uart_configure_default(&hal_uart_cfg);
 
// Specify desired UART RX pin
hal_uart_cfg.rx_pin = MIKROBUS_1_RX;
 
// Specify desired UART TX pin
hal_uart_cfg.tx_pin = MIKROBUS_1_TX;
 
// Declare buffer size
hal_uart_cfg.tx_ring_size = sizeof(uart_tx_buffer);
 
// Declare buffer size
hal_uart_cfg.rx_ring_size = sizeof(uart_rx_buffer);
 
// Initialize appropriate interrupt and allocate resources for UART module.
if ( hal_uart_open( &hal_uart->handle, true ) == HAL_UART_ERROR )
{
 // Error handling strategy
};

hal_uart_set_baud()

err_t hal_uart_set_baud	(	handle_t *	handle,
		hal_uart_config_t *	config
	)

Initializes module on the hardware level and sets the baud rate to specified config->baud value.

Parameters

[in]	handle	UART handle. See hal_uart_t structure definition for detailed explanation.
[in]	config	UART HAL config structure. See hal_uart_config_t structure definition for detailed explanation.

Returns

The function can return one of the values defined by hal_uart_err_t, which is size dependant on the architecture.

Precondition

Make sure that adequate memory has been allocated beforehand. See hal_uart_open definition for detailed explanation.

Warning

Take into consideration that if the difference between desired baud rate and actual baud rate the hw was initialized to is greater than 1%, baud rate shall not be set.

Example

hal_uart_set_baud( &hal_uart->handle, &hal_uart->config ); // Set baud rate.

hal_uart_set_parity()

err_t hal_uart_set_parity	(	handle_t *	handle,
		hal_uart_config_t *	config
	)

Sets parity on hardware level based on config->parity value.

Parameters

[in]	handle	UART handle. See hal_uart_t structure definition for detailed explanation.
[in]	config	UART HAL config structure.

Returns

The function can return one of the values defined by hal_uart_err_t, which is size dependant on the architecture.

Precondition

Make sure that adequate memory has been allocated beforehand. See hal_uart_open definition for detailed explanation.

Example

hal_uart_set_parity( &hal_uart->handle, &hal_uart->parity ); // Set data parity.

hal_uart_set_stop_bits()

err_t hal_uart_set_stop_bits	(	handle_t *	handle,
		hal_uart_config_t *	config
	)

Sets stop bits on hardware level based on config->stop_bits value.

Parameters

[in]	handle	UART handle. See hal_uart_t structure definition for detailed explanation.
[in]	config	UART HAL config structure.

Returns

The function can return one of the values defined by hal_uart_err_t, which is size dependant on the architecture.

Precondition

Make sure that adequate memory has been allocated beforehand. See hal_uart_open definition for detailed explanation.

Example

hal_uart_set_stop_bits( &hal_uart->handle, &hal_uart->stop_bits ); // Set stop bits.

hal_uart_set_data_bits()

err_t hal_uart_set_data_bits	(	handle_t *	handle,
		hal_uart_config_t *	config
	)

Sets data bits on hardware level based on config->data_bits value.

Parameters

[in]	handle	UART handle. See hal_uart_t structure definition for detailed explanation.
[in]	config	UART HAL config structure.

Returns

The function can return one of the values defined by hal_uart_err_t, which is size dependant on the architecture.

Precondition

Make sure that adequate memory has been allocated beforehand. See hal_uart_open definition for detailed explanation.

Example

hal_uart_set_data_bits( &hal_uart->handle, &hal_uart->data_bits ); // Set data bits.

hal_uart_set_blocking()

void hal_uart_set_blocking	(	handle_t *	handle,
		bool	blocking
	)

Sets the UART HAL to work in blocking/non-blocking mode.

Parameters

[in]	handle	UART handle. See hal_uart_t structure definition for detailed explanation.
[in]	blocking	true for blocking mode, false for non-blocking mode.

Returns

Nothing.

Example

hal_uart_set_blocking( &hal_uart->handle, true );

hal_uart_write()

size_t hal_uart_write	(	handle_t *	handle,
		uint8_t *	buffer,
		size_t	size
	)

Writes at most size bytes of data from buffer to the device.

Parameters

[in]	handle	UART handle. See hal_uart_t structure definition for detailed explanation.
[in]	buffer	Array containing data to be written.
[in]	size	Number of bytes to be written.

Returns

Returns the number of bytes that were actually written, or -1 if an error occurred or no data written.

Precondition

Make sure that adequate memory has been allocated beforehand. See hal_uart_open definition for detailed explanation.

Example

static size_t size;
 
// Write size number of data from buffer.
size = hal_uart_write( &hal_uart->handle, buffer, size );

hal_uart_print()

size_t hal_uart_print	(	handle_t *	handle,
		char *	text
	)

Print the string pointed to by text.

Parameters

[in]	handle	UART handle. See hal_uart_t structure definition for detailed explanation.
[in]	text	Pointer to text array.

Returns

Returns the number of bytes that were actually written, or -1 if an error occurred or no data written.

Precondition

Make sure that adequate memory has been allocated beforehand. See hal_uart_open definition for detailed explanation.

Example :

static size_t size;
 
size = hal_uart_print( &hal_uart->handle, "Hello!" ); // Print out "Hello!".

hal_uart_println()

size_t hal_uart_println	(	handle_t *	handle,
		char *	text
	)

Print the string pointed to by text and append new line at the end.

Parameters

[in]	handle	UART handle. See hal_uart_t structure definition for detailed explanation.
[in]	text	Pointer to text array.

Returns

Returns the number of bytes that were actually written, or -1 if an error occurred or no data written.

Precondition

Make sure that adequate memory has been allocated beforehand. See hal_uart_open definition for detailed explanation.

Example

static size_t size;
 
// Print out "Hello!" and append new line.
size = hal_uart_print_ln( &hal_uart, "Hello!" );

hal_uart_read()

size_t hal_uart_read	(	handle_t *	handle,
		uint8_t *	buffer,
		size_t	size
	)

Reads at most size bytes of data from the device into buffer.

Parameters

[in]	handle	UART handle. See hal_uart_t structure definition for detailed explanation.
[out]	buffer	Array to place read data in.
[in]	size	Number of bytes to be written.

Returns

Returns the number of bytes that were actually read, or -1 if an error occurred or no data read.

Precondition

Make sure that adequate memory has been allocated beforehand. See hal_uart_open definition for detailed explanation.

Example

static size_t size;
 
// Read data.
size = hal_uart_read( &hal_uart->handle, buffer, sizeof( buffer ) );

hal_uart_bytes_available()

size_t hal_uart_bytes_available

(

hal_uart_t *

hal_obj

)

Check number of data available to read.

Parameters

[in]

hal_obj

UART HAL object. See hal_uart_t structure definition for detailed explanation.

Returns

Returns the number of bytes that are available for reading.

Example

if ( hal_uart_bytes_available( &hal_uart ) )
{
 // If it enters here, data is available for reading.
}

hal_uart_clear()

void hal_uart_clear

(

hal_uart_t *

hal_obj

)

Discards all characters from the output and input buffer.

Parameters

[in]

hal_obj

UART HAL object. See hal_uart_t structure definition for detailed explanation.

Returns

Nothing.

Example

hal_uart_clear( &hal_uart ); // Clear rx and tx buffers.

hal_uart_close()

err_t hal_uart_close

(

handle_t *

handle

)

Closes UART HAL layer object, disables all interrupts, resets pin AF to default values, clears all buffers used by object and disables module clock for lower power consumption.

Parameters

[in,out]

handle

UART handle. See hal_uart_t structure definition for detailed explanation.

Returns

Nothing.

Example

// Close the UART HAL module object handler.
hal_uart_close( &hal_uart->handle );