mikroSDK Reference Manual

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

Function Documentation

◆ 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_objUART 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.
}
size_t hal_uart_bytes_available(hal_uart_t *hal_obj)
Check number of data available to read.

◆ hal_uart_clear()

void hal_uart_clear ( hal_uart_t * hal_obj)

Discards all characters from the output and input buffer.

Parameters
[in]hal_objUART HAL object. See hal_uart_t structure definition for detailed explanation.
Returns
Nothing.

Example

// Clear rx and tx buffers.
hal_uart_clear( &hal_uart );
void hal_uart_clear(hal_uart_t *hal_obj)
Discard all characters from UART 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]handleUART 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 );
err_t hal_uart_close(handle_t *handle)
Close UART HAL layer object.

◆ 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]configUART 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 );
void hal_uart_configure_default(hal_uart_config_t *config)
Configure UART configuration structure with default values.
UART HAL init configuration structure, consisted of the following fields :
Definition hal_uart.h:159

◆ 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]handleUART handle. See hal_uart_t structure definition for detailed explanation.
[in]hal_obj_open_stateUART 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 hal_uart_rx_buffer[128];
// Be careful to have large enough buffers.
static uint8_t hal_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( hal_uart_tx_buffer );
// Declare buffer size.
hal_uart_cfg.rx_ring_size = sizeof( hal_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
}
void uart_configure_default(uart_config_t *config)
Configure UART Driver configuration structure.
err_t hal_uart_open(handle_t *handle, bool hal_obj_open_state)
Open the UART HAL layer object on selected pins.
@ HAL_UART_ERROR
Definition hal_uart.h:77
size_t rx_ring_size
Definition hal_uart.h:172
size_t tx_ring_size
Definition hal_uart.h:171
hal_pin_name_t rx_pin
Definition hal_uart.h:161
hal_pin_name_t tx_pin
Definition hal_uart.h:160
UART HAL context structure, consisted of the following fields :
Definition hal_uart.h:186
handle_t handle
Definition hal_uart.h:187

◆ hal_uart_print()

size_t hal_uart_print ( handle_t * handle,
char * text )

Print the string pointed to by text.

Parameters
[in]handleUART handle. See hal_uart_t structure definition for detailed explanation.
[in]textPointer 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!".
size = hal_uart_print( &hal_uart->handle, "Hello!" ); // Print out "Hello!".
size_t hal_uart_print(handle_t *handle, char *text)
Print the string to UART.

◆ 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]handleUART handle. See hal_uart_t structure definition for detailed explanation.
[in]textPointer 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]handleUART handle. See hal_uart_t structure definition for detailed explanation.
[out]bufferArray to place read data in.
[in]sizeNumber 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, hal_uart_rx_buffer, sizeof( buffer ) );
size_t hal_uart_read(handle_t *handle, uint8_t *buffer, size_t size)
Read data from UART.

◆ 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]handleUART handle. See hal_uart_t structure definition for detailed explanation.
[in]configUART 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

// Set baud rate.
hal_uart_set_baud( &hal_uart->handle, &hal_uart->config );
err_t hal_uart_set_baud(handle_t *handle, hal_uart_config_t *config)
Set the UART baud rate.

◆ 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]handleUART handle. See hal_uart_t structure definition for detailed explanation.
[in]blockingtrue for blocking mode, false for non-blocking mode.
Returns
Nothing.

Example

// Set transmit/receive mode to be blocking/non-blocking.
hal_uart_set_blocking( &hal_uart->handle, true );
void hal_uart_set_blocking(handle_t *handle, bool blocking)
Set UART HAL in blocking/non-blocking mode.

◆ 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]handleUART handle. See hal_uart_t structure definition for detailed explanation.
[in]configUART 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

// Set data bits.
hal_uart_set_data_bits( &hal_uart->handle, &hal_uart->data_bits );
err_t hal_uart_set_data_bits(handle_t *handle, hal_uart_config_t *config)
Set the number of UART data bits.

◆ 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]handleUART handle. See hal_uart_t structure definition for detailed explanation.
[in]configUART 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

// Set data parity.
hal_uart_set_parity( &hal_uart->handle, &hal_uart->parity );
err_t hal_uart_set_parity(handle_t *handle, hal_uart_config_t *config)
Set the UART 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]handleUART handle. See hal_uart_t structure definition for detailed explanation.
[in]configUART 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

// Set stop bits.
hal_uart_set_stop_bits( &hal_uart->handle, &hal_uart->stop_bits );
err_t hal_uart_set_stop_bits(handle_t *handle, hal_uart_config_t *config)
Set the number of UART stop bits.

◆ 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]handleUART handle. See hal_uart_t structure definition for detailed explanation.
[in]bufferArray containing data to be written.
[in]sizeNumber 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, hal_uart_tx_buffer, size );
size_t hal_uart_write(handle_t *handle, uint8_t *buffer, size_t size)
Write data to UART.