mikroSDK Reference Manual

UART Driver API Reference. More...

Functions list

void uart_configure_default (uart_config_t *config)
 Configure UART Driver configuration structure. More...
 
err_t uart_open (uart_t *obj, uart_config_t *config)
 Open the UART Driver object. More...
 
err_t uart_set_baud (uart_t *obj, uint32_t baud)
 Set the UART baud rate. More...
 
err_t uart_set_parity (uart_t *obj, uart_parity_t parity)
 Set the UART parity. More...
 
err_t uart_set_stop_bits (uart_t *obj, uart_stop_bits_t stop)
 Set the number of UART stop bits. More...
 
err_t uart_set_data_bits (uart_t *obj, uart_data_bits_t bits)
 Set the number of UART data bits. More...
 
void uart_set_blocking (uart_t *obj, bool blocking)
 Set UART Driver in blocking/non-blocking mode. More...
 
err_t uart_write (uart_t *obj, uint8_t *buffer, size_t size)
 Write data to UART. More...
 
err_t uart_print (uart_t *obj, char *text)
 Print the string to UART. More...
 
err_t uart_println (uart_t *obj, char *text)
 Print the string to UART and append new line. More...
 
err_t uart_read (uart_t *obj, uint8_t *buffer, size_t size)
 Read data from UART. More...
 
size_t uart_bytes_available (uart_t *obj)
 Check number of bytes available to read from UART. More...
 
void uart_clear (uart_t *obj)
 Discard all characters from UART buffers. More...
 
err_t uart_close (uart_t *obj)
 Close UART Driver object. More...
 

Detailed Description

UART DRV API layer header. Contains all enums, structures and function declarations available for UART module.

Function Documentation

◆ uart_configure_default()

void uart_configure_default ( uart_config_t config)

Configures uart_config_t 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]configconfigure UART driver configuration structure. See uart_config_t structure definition for detailed explanation.

Default values:

Function Default value
Tx pin 0xFFFFFFFF (invalid pin)
Rx pin 0xFFFFFFFF (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 driver configuration structure.
static uart_config_t uart_cfg;
// Fill structure with default values.

◆ uart_open()

err_t uart_open ( uart_t obj,
uart_config_t config 
)

Opens the UART driver object on selected pins. Allocates memory, pins and ring buffers for specified object. Also, initializes interrupts on the global level.

Parameters
[in,out]objUART driver object. See uart_t structure definition for detailed explanation.
[in]configconfigure UART driver configuration settings. See uart_config_t structure definition for detailed explanation.
Returns
The function can return one of the values defined by err_t, which is dependant on the architecture and ported low level layer.
Precondition
Make sure that configuration structure has been adequately populated beforehand. See uart_configure_default definition for detailed explanation.
Note
It is recommended to check return value for error.

Example

// UART driver context structure.
static uart_t uart;
// UART driver configuration structure.
static uart_config_t 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.
// Specify desired UART RX pin.
uart_cfg.rx_pin = MIKROBUS_1_RX;
// Specify desired UART TX pin.
uart_cfg.tx_pin = MIKROBUS_1_TX;
// Declare buffer size.
uart_cfg.tx_ring_size = sizeof( uart_tx_buffer );
// Declare buffer size.
uart_cfg.rx_ring_size = sizeof( uart_rx_buffer );
// Initialize appropriate interrupt and allocate resources for UART module.
if ( uart_open( &uart, &uart_cfg ) == UART_ERROR )
{
// Error handling strategy
}

◆ uart_set_baud()

err_t uart_set_baud ( uart_t obj,
uint32_t  baud 
)

Sets the baud rate to specified baud value.

Parameters
[in]objUART driver object. See uart_t structure definition for detailed explanation.
[in]baudSpecified baud rate value.
Returns
The function can return one of the values defined by err_t, which is dependant on the architecture and ported low level layer.
Precondition
Make sure that adequate memory has been allocated beforehand. See uart_open definition for detailed explanation.
Note
It is recommended to check return value for error.

Example

// UART driver context structure.
static uart_t uart;
// Set baud rate.
if ( uart_set_baud( &uart, 115200 ) == UART_ERROR )
{
// Error handling strategy
}

◆ uart_set_parity()

err_t uart_set_parity ( uart_t obj,
uart_parity_t  parity 
)

Sets parity scheme to be used by the UART driver.

Parameters
[in,out]objUART driver object. See uart_t structure definition for detailed explanation.
[in]parityParity. See uart_parity_t for valid values.
Returns
The function can return one of the values defined by err_t, which is dependant on the architecture and ported low level layer.
Precondition
Make sure that adequate memory has been allocated beforehand. See uart_open definition for detailed explanation.
Note
It is recommended to check return value for error.

Example

// UART driver context structure.
static uart_t uart;
// Set data parity. ( no parity )
{
// Error handling strategy
}

◆ uart_set_stop_bits()

err_t uart_set_stop_bits ( uart_t obj,
uart_stop_bits_t  stop 
)

Sets the number of stop bits to be used by the UART driver.

Parameters
[in,out]objUART driver object. See uart_t structure definition for detailed explanation.
[in]stopStop bits. See uart_stop_bits_t for valid values.
Returns
The function can return one of the values defined by err_t, which is dependant on the architecture and ported low level layer.
Precondition
Make sure that adequate memory has been allocated beforehand. See uart_open definition for detailed explanation.
Note
It is recommended to check return value for error.

Example

// UART driver context structure.
static uart_t uart;
// Set stop bits. ( one stop bit )
{
// Error handling strategy
}

◆ uart_set_data_bits()

err_t uart_set_data_bits ( uart_t obj,
uart_data_bits_t  bits 
)

Sets the number of data bits to be used by the UART driver.

Parameters
[in,out]objUART driver object. See uart_t structure definition for detailed explanation.
[in]bitsData bits. See uart_data_bits_t for valid values.
Returns
The function can return one of the values defined by err_t, which is dependant on the architecture and ported low level layer.
Precondition
Make sure that adequate memory has been allocated beforehand. See uart_open definition for detailed explanation.
Note
It is recommended to check return value for error.

Example

// UART driver context structure.
static uart_t uart;
// Set data bits. ( 8-bit data )
{
// Error handling strategy
}

◆ uart_set_blocking()

void uart_set_blocking ( uart_t obj,
bool  blocking 
)

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

Parameters
[in,out]objUART driver object. See uart_t structure definition for detailed explanation.
[in]blockingtrue for blocking mode, false for non-blocking mode.
Returns
Nothing.

Example

// UART driver context structure.
static uart_t uart;
// Set UART Driver in blocking mode.
uart_set_blocking( &uart, true );

◆ uart_write()

err_t uart_write ( uart_t obj,
uint8_t *  buffer,
size_t  size 
)

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

Parameters
[in]objUART driver object. See 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.
Precondition
Make sure that adequate memory has been allocated beforehand, and the module was configured adequately ( bit-rate... ). See uart_open, uart_set_baud, uart_set_data_bits, uart_set_stop_bits and uart_set_parity definition for detailed explanation.
Note
Take into consideration that the function shall return (-1) if no data was written, and appropriate error handling strategy is recommended.

Example

// UART driver context structure.
static uart_t uart;
// Data transmit buffer.
uint8_t *uart_tx_buffer;
// Number of written bytes.
static size_t size;
// Write size number of data from buffer.
size = uart_write( &uart, uart_tx_buffer, size );

◆ uart_print()

err_t uart_print ( uart_t obj,
char *  text 
)

Print the string pointed to by text.

Parameters
[in]objUART driver object. See 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.
Precondition
Make sure that adequate memory has been allocated beforehand, and the module was configured adequately ( bit-rate... ). See uart_open, uart_set_baud, uart_set_data_bits, uart_set_stop_bits and uart_set_parity definition for detailed explanation.
Note
Take into consideration that the function shall return (-1) if no data was written, and appropriate error handling strategy is recommended.

Example

// UART driver context structure.
static uart_t uart;
// Number of written bytes.
static size_t size;
// Print out "Hello!".
size = uart_print( &uart, "Hello!" );

◆ uart_println()

err_t uart_println ( uart_t obj,
char *  text 
)

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

Parameters
[in]objUART driver object. See 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.
Precondition
Make sure that adequate memory has been allocated beforehand, and the module was configured adequately ( bit-rate... ). See uart_open, uart_set_baud, uart_set_data_bits, uart_set_stop_bits and uart_set_parity definition for detailed explanation.
Note
Take into consideration that the function shall return (-1) if no data was written, and appropriate error handling strategy is recommended.

Example

// UART driver context structure.
static uart_t uart;
// Number of written bytes.
static size_t size;
// Print out "Hello!" and append new line.
size = uart_print_ln( &uart, "Hello!" );

◆ uart_read()

err_t uart_read ( uart_t obj,
uint8_t *  buffer,
size_t  size 
)

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

Parameters
[in]objUART driver object. See 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.
Precondition
Make sure that adequate memory has been allocated beforehand, and the module was configured adequately ( bit-rate... ). See uart_open, uart_set_baud, uart_set_data_bits, uart_set_stop_bits and uart_set_parity definition for detailed explanation.
Note
Take into consideration that the function shall return (-1) if no data was read, and appropriate error handling strategy is recommended.

Example

// UART driver context structure.
static uart_t uart;
// Data receive buffer.
uint8_t *uart_rx_buffer;
// Number of read bytes.
static size_t size;
// Read data.
size = uart_read( &uart, uart_rx_buffer, sizeof( buffer ) );

◆ uart_bytes_available()

size_t uart_bytes_available ( uart_t obj)

Check number of bytes available to read from UART.

Parameters
[in]objUART driver object. See uart_t structure definition for detailed explanation.
Returns
Returns the number of bytes that are available for reading.

Example

// UART driver context structure.
static uart_t uart;
if ( uart_bytes_available( &uart ) )
{
// If it enters here, data is available for reading.
}

◆ uart_clear()

void uart_clear ( uart_t obj)

Discards all characters from the output and input buffer.

Parameters
[in]objUART driver object. See uart_t structure definition for detailed explanation.
Returns
Nothing.

Example

// UART driver context structure.
static uart_t uart;
// Clear rx and tx buffers.
uart_clear( &uart );

◆ uart_close()

err_t uart_close ( uart_t obj)

Closes UART driver 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]objUART driver object. See uart_t structure definition for detailed explanation.
Returns
The function can return one of the values defined by err_t, which is dependant on the architecture and ported low level layer.

Example

// UART driver context structure.
static uart_t uart;
// Close the UART module object handler.
if ( UART_SUCCESS == uart_close( &uart ) {
// no error
} else {
// Handle the error
}
UART_ERROR
Definition: drv_uart.h:60
uart_clear
void uart_clear(uart_t *obj)
Discard all characters from UART buffers.
uart_config_t::rx_ring_size
size_t rx_ring_size
Definition: drv_uart.h:150
uart_set_blocking
void uart_set_blocking(uart_t *obj, bool blocking)
Set UART Driver in blocking/non-blocking mode.
uart_print
err_t uart_print(uart_t *obj, char *text)
Print the string to UART.
uart_config_t::tx_ring_size
size_t tx_ring_size
Definition: drv_uart.h:149
UART_PARITY_DEFAULT
Definition: drv_uart.h:84
uart_open
err_t uart_open(uart_t *obj, uart_config_t *config)
Open the UART Driver object.
UART_STOP_BITS_DEFAULT
Definition: drv_uart.h:97
uart_close
err_t uart_close(uart_t *obj)
Close UART Driver object.
uart_set_stop_bits
err_t uart_set_stop_bits(uart_t *obj, uart_stop_bits_t stop)
Set the number of UART stop bits.
uart_set_parity
err_t uart_set_parity(uart_t *obj, uart_parity_t parity)
Set the UART parity.
uart_t
UART driver context structure, consisted of the following fields :
Definition: drv_uart.h:163
UART_SUCCESS
Definition: drv_uart.h:59
UART_DATA_BITS_DEFAULT
Definition: drv_uart.h:72
uart_set_data_bits
err_t uart_set_data_bits(uart_t *obj, uart_data_bits_t bits)
Set the number of UART data bits.
uart_config_t::rx_pin
pin_name_t rx_pin
Definition: drv_uart.h:139
uart_write
err_t uart_write(uart_t *obj, uint8_t *buffer, size_t size)
Write data to UART.
uart_read
err_t uart_read(uart_t *obj, uint8_t *buffer, size_t size)
Read data from UART.
uart_bytes_available
size_t uart_bytes_available(uart_t *obj)
Check number of bytes available to read from UART.
uart_config_t
UART init configuration structure, consisted of the following fields :
Definition: drv_uart.h:136
uart_set_baud
err_t uart_set_baud(uart_t *obj, uint32_t baud)
Set the UART baud rate.
uart_config_t::tx_pin
pin_name_t tx_pin
Definition: drv_uart.h:138
uart_configure_default
void uart_configure_default(uart_config_t *config)
Configure UART Driver configuration structure.