UART driver

group nrfx_uart

UART peripheral driver.

Defines

NRFX_UART_INSTANCE(id)

Macro for creating a UART driver instance.

NRFX_UART_DEFAULT_EXTENDED_STOP_CONFIG

UART additional stop bits configuration.

NRFX_UART_DEFAULT_EXTENDED_PARITYTYPE_CONFIG

UART additional parity type configuration.

NRFX_UART_DEFAULT_CONFIG(_pin_tx, _pin_rx)

UART driver default configuration.

This configuration sets up UART with the following options:

  • hardware flow control disabled

  • no parity bit

  • one stop bit

  • baudrate: 115200

Parameters:

  • _pin_tx – [in] TX pin.

  • _pin_rx – [in] RX pin.

NRFX_UART_INST_HANDLER_GET(idx)

Macro returning UART interrupt handler.

param[in] idx UART index.

Returns:

Interrupt handler.

Typedefs

typedef void (*nrfx_uart_event_handler_t)(nrfx_uart_event_t const *p_event, void *p_context)

UART interrupt event handler.

Param p_event:

[in] Pointer to event structure. Event is allocated on the stack so it is available only within the context of the event handler.

Param p_context:

[in] Context passed to the interrupt handler, set on initialization.

Enums

enum nrfx_uart_evt_type_t

Types of UART driver events.

Values:

enumerator NRFX_UART_EVT_TX_DONE

Requested TX transfer completed.

enumerator NRFX_UART_EVT_RX_DONE

Requested RX transfer completed.

enumerator NRFX_UART_EVT_ERROR

Error reported by UART peripheral.

Functions

nrfx_err_t nrfx_uart_init(nrfx_uart_t const *p_instance, nrfx_uart_config_t const *p_config, nrfx_uart_event_handler_t event_handler)

Function for initializing the UART driver.

This function configures and enables UART. After this function GPIO pins are controlled by UART.

Parameters:

  • p_instance – [in] Pointer to the driver instance structure.

  • p_config – [in] Pointer to the structure with the initial configuration.

  • event_handler – [in] Event handler provided by the user. If not provided, the driver works in blocking mode.

Return values:

  • NRFX_SUCCESS – Initialization is successful.

  • NRFX_ERROR_ALREADY – The driver is already initialized.

  • NRFX_ERROR_INVALID_STATE – The driver is already initialized. Deprecated - use NRFX_ERROR_ALREADY instead.

  • NRFX_ERROR_BUSY – Some other peripheral with the same instance ID is already in use. This is possible only if Peripheral Resource Sharing (PRS) module is enabled.

nrfx_err_t nrfx_uart_reconfigure(nrfx_uart_t const *p_instance, nrfx_uart_config_t const *p_config)

Function for reconfiguring the UART driver.

Parameters:

  • p_instance – [in] Pointer to the driver instance structure.

  • p_config – [in] Pointer to the structure with the configuration.

Return values:

  • NRFX_SUCCESS – Reconfiguration was successful.

  • NRFX_ERROR_BUSY – The driver is during transfer.

  • NRFX_ERROR_INVALID_STATE – The driver is uninitialized.

void nrfx_uart_uninit(nrfx_uart_t const *p_instance)

Function for uninitializing the UART driver.

Parameters:

  • p_instance – [in] Pointer to the driver instance structure.

bool nrfx_uart_init_check(nrfx_uart_t const *p_instance)

Function for checking if the UART driver instance is initialized.

Parameters:

  • p_instance – [in] Pointer to the driver instance structure.

Return values:

  • true – Instance is already initialized.

  • false – Instance is not initialized.

NRFX_STATIC_INLINE uint32_t nrfx_uart_task_address_get(nrfx_uart_t const *p_instance, nrf_uart_task_t task)

Function for getting the address of the specified UART task.

Parameters:

  • p_instance – [in] Pointer to the driver instance structure.

  • task – [in] Task.

Returns:

Task address.

NRFX_STATIC_INLINE uint32_t nrfx_uart_event_address_get(nrfx_uart_t const *p_instance, nrf_uart_event_t event)

Function for getting the address of the specified UART event.

Parameters:

  • p_instance – [in] Pointer to the driver instance structure.

  • event – [in] Event.

Returns:

Event address.

nrfx_err_t nrfx_uart_tx(nrfx_uart_t const *p_instance, uint8_t const *p_data, size_t length)

Function for sending data over UART.

If an event handler was provided in nrfx_uart_init() call, this function returns immediately and the handler is called when the transfer is done. Otherwise, the transfer is performed in blocking mode, that is this function returns when the transfer is finished. Blocking mode is not using interrupt so there is no context switching inside the function.

Parameters:

  • p_instance – [in] Pointer to the driver instance structure.

  • p_data – [in] Pointer to data.

  • length – [in] Number of bytes to send.

Return values:

  • NRFX_SUCCESS – Initialization was successful.

  • NRFX_ERROR_BUSY – Driver is already transferring.

  • NRFX_ERROR_FORBIDDEN – The transfer was aborted from a different context (blocking mode only).

bool nrfx_uart_tx_in_progress(nrfx_uart_t const *p_instance)

Function for checking if UART is currently transmitting.

Parameters:

  • p_instance – [in] Pointer to the driver instance structure.

Return values:

  • true – The UART is transmitting.

  • false – The UART is not transmitting.

void nrfx_uart_tx_abort(nrfx_uart_t const *p_instance)

Function for aborting any ongoing transmission.

Note

NRFX_UART_EVT_TX_DONE event will be generated in non-blocking mode. It will contain number of bytes sent until the abort was called. The event handler will be called from the function context.

Parameters:

  • p_instance – [in] Pointer to the driver instance structure.

nrfx_err_t nrfx_uart_rx(nrfx_uart_t const *p_instance, uint8_t *p_data, size_t length)

Function for receiving data over UART.

If an event handler is provided in the nrfx_uart_init() call, this function returns immediately and the handler is called when the transfer is done. Otherwise, the transfer is performed in blocking mode, that is this function returns when the transfer is finished. Blocking mode is not using interrupt so there is no context switching inside the function. The receive buffer pointer is double-buffered in non-blocking mode. The secondary buffer can be set immediately after starting the transfer and will be filled when the primary buffer is full. The double-buffering feature allows receiving data continuously.

If this function is used without a previous call to nrfx_uart_rx_enable, the reception will be stopped on error or when the supplied buffer fills up. In both cases, RX FIFO gets disabled. This means that, in case of error, the bytes that follow are lost. If this nrfx_uart_rx() function is used with the previous call to nrfx_uart_rx_enable, the reception is stopped in case of error, but FIFO is still ongoing. The receiver is still working, so after handling the error, an immediate repeated call to this nrfx_uart_rx() function with fresh data buffer will re-establish reception. To disable the receiver, you must call nrfx_uart_rx_disable explicitly.

Parameters:

  • p_instance – [in] Pointer to the driver instance structure.

  • p_data – [in] Pointer to data.

  • length – [in] Number of bytes to receive.

Return values:

  • NRFX_SUCCESS – Reception is complete (in case of blocking mode) or it is successfully started (in case of non-blocking mode).

  • NRFX_ERROR_BUSY – The driver is already receiving (and the secondary buffer has already been set in non-blocking mode).

  • NRFX_ERROR_FORBIDDEN – The transfer was aborted from a different context (blocking mode only, also see nrfx_uart_rx_disable).

  • NRFX_ERROR_INTERNAL – The UART peripheral reported an error.

bool nrfx_uart_rx_ready(nrfx_uart_t const *p_instance)

Function for testing the receiver state in blocking mode.

Parameters:

  • p_instance – [in] Pointer to the driver instance structure.

Return values:

  • true – The receiver has at least one byte of data to get.

  • false – The receiver is empty.

void nrfx_uart_rx_enable(nrfx_uart_t const *p_instance)

Function for enabling the receiver.

UART has a 6-byte-long RX FIFO and it is used to store incoming data. If a user does not call the UART receive function before the FIFO is filled, an overrun error will appear. The receiver must be explicitly closed by the user

See also

nrfx_uart_rx_disable.

Parameters:

  • p_instance – [in] Pointer to the driver instance structure.

void nrfx_uart_rx_disable(nrfx_uart_t const *p_instance)

Function for disabling the receiver.

This function must be called to close the receiver after it has been explicitly enabled by

See also

nrfx_uart_rx_enable.

Parameters:

  • p_instance – [in] Pointer to the driver instance structure.

void nrfx_uart_rx_abort(nrfx_uart_t const *p_instance)

Function for aborting any ongoing reception.

Note

NRFX_UART_EVT_TX_DONE event will be generated in non-blocking mode. It will contain number of bytes received until the abort was called. The event handler will be called from the UART interrupt context.

Parameters:

  • p_instance – [in] Pointer to the driver instance structure.

uint32_t nrfx_uart_errorsrc_get(nrfx_uart_t const *p_instance)

Function for reading error source mask. Mask contains values from nrf_uart_error_mask_t.

Note

Function must be used in blocking mode only. In case of non-blocking mode, an error event is generated. Function clears error sources after reading.

Parameters:

  • p_instance – [in] Pointer to the driver instance structure.

Returns:

Mask of reported errors.

struct nrfx_uart_t
#include <nrfx_uart.h>

Data structure of the UART driver instance.

Public Members

NRF_UART_Type *p_reg

Pointer to a structure with UART registers.

uint8_t drv_inst_idx

Index of the driver instance. For internal use only.

struct nrfx_uart_config_t
#include <nrfx_uart.h>

Structure for the UART configuration.

Public Members

uint32_t pseltxd

TXD pin number.

uint32_t pselrxd

RXD pin number.

uint32_t pselcts

CTS pin number.

uint32_t pselrts

RTS pin number.

void *p_context

Context passed to interrupt handler.

nrf_uart_baudrate_t baudrate

Baud rate.

uint8_t interrupt_priority

Interrupt priority.

nrf_uart_config_t hal_cfg

Parity, flow control and stop bits settings.

bool skip_gpio_cfg

Skip GPIO configuration of pins.

When set to true, the driver does not modify any GPIO parameters of the used pins. Those parameters are supposed to be configured externally before the driver is initialized.

bool skip_psel_cfg

Skip pin selection configuration.

When set to true, the driver does not modify pin select registers in the peripheral. Those registers are supposed to be set up externally before the driver is initialized.

Note

When both GPIO configuration and pin selection are to be skipped, the structure fields that specify pins can be omitted, as they are ignored anyway.

struct nrfx_uart_xfer_evt_t
#include <nrfx_uart.h>

Structure for the UART transfer completion event.

Public Members

uint8_t *p_data

Pointer to memory used for transfer.

uint32_t bytes

Number of bytes transfered.

struct nrfx_uart_error_evt_t
#include <nrfx_uart.h>

Structure for the UART error event.

Public Members

nrfx_uart_xfer_evt_t rxtx

Transfer details, including number of bytes transferred.

uint32_t error_mask

Mask of error flags that generated the event.

struct nrfx_uart_event_t
#include <nrfx_uart.h>

Structure for the UART event.

Public Members

nrfx_uart_evt_type_t type

Event type.

nrfx_uart_xfer_evt_t rxtx

Data provided for transfer completion events.

nrfx_uart_error_evt_t error

Data provided for error event.

union nrfx_uart_event_t.[anonymous] data

Union to store event data.