| nRF5 SDK v12.0.0 |

Choose documentation: | nRF5 SDK | S130 SoftDevice API | S132 SoftDevice API | S212 SoftDevice API | S332 SoftDevice API

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Modules | Data Structures | Macros | Typedefs | Enumerations | Functions
UART driver
UART driver and HAL

UART driver. More...

## Modules
| UART/UARTE peripheral driver configuration

## Data Structures
struct | nrf_drv_uart_t
| Structure for the UART driver instance. More...
struct | nrf_drv_uart_config_t
| Structure for UART configuration. More...
struct | nrf_drv_uart_xfer_evt_t
| Structure for UART transfer completion event. More...
struct | nrf_drv_uart_error_evt_t
| Structure for UART error event. More...
struct | nrf_drv_uart_event_t
| Structure for UART event. More...

## Macros
#define | UART0_INSTANCE_INDEX 0
#define | UART_COUNT 1
#define | NRF_DRV_UART_PERIPHERAL(id) (void *)CONCAT_2(NRF_UART, id)
#define | NRF_DRV_UART_INSTANCE(id)
| Macro for creating an UART driver instance. More...
#define | NRF_DRV_UART_DEFAULT_CONFIG
| UART default configuration. More...

## Typedefs
typedef void(* | nrf_uart_event_handler_t )(nrf_drv_uart_event_t *p_event, void *p_context)
| UART interrupt event handler. More...

## Enumerations
enum | nrf_drv_uart_evt_type_t { NRF_DRV_UART_EVT_TX_DONE, NRF_DRV_UART_EVT_RX_DONE, NRF_DRV_UART_EVT_ERROR }
| Types of UART driver events. More...

## Functions
ret_code_t | nrf_drv_uart_init (nrf_drv_uart_t const *p_instance, nrf_drv_uart_config_t const *p_config, nrf_uart_event_handler_t event_handler)
| Function for initializing the UART driver. More...
void | nrf_drv_uart_uninit (nrf_drv_uart_t const *p_instance)
| Function for uninitializing the UART driver. More...
__STATIC_INLINE uint32_t | nrf_drv_uart_task_address_get (nrf_drv_uart_t const *p_instance, nrf_uart_task_t task)
| Function for getting the address of a specific UART task. More...
__STATIC_INLINE uint32_t | nrf_drv_uart_event_address_get (nrf_drv_uart_t const *p_instance, nrf_uart_event_t event)
| Function for getting the address of a specific UART event. More...
ret_code_t | nrf_drv_uart_tx (nrf_drv_uart_t const *p_instance, uint8_t const *const p_data, uint8_t length)
| Function for sending data over UART. More...
bool | nrf_drv_uart_tx_in_progress (nrf_drv_uart_t const *p_instance)
| Function for checking if UART is currently transmitting. More...
void | nrf_drv_uart_tx_abort (nrf_drv_uart_t const *p_instance)
| Function for aborting any ongoing transmission. More...
ret_code_t | nrf_drv_uart_rx (nrf_drv_uart_t const *p_instance, uint8_t *p_data, uint8_t length)
| Function for receiving data over UART. More...
void | nrf_drv_uart_rx_enable (nrf_drv_uart_t const *p_instance)
| Function for enabling receiver. More...
void | nrf_drv_uart_rx_disable (nrf_drv_uart_t const *p_instance)
| Function for disabling receiver. More...
void | nrf_drv_uart_rx_abort (nrf_drv_uart_t const *p_instance)
| Function for aborting any ongoing reception. More...
uint32_t | nrf_drv_uart_errorsrc_get (nrf_drv_uart_t const *p_instance)
| Function for reading error source mask. Mask contains values from nrf_uart_error_mask_t. More...

## Detailed Description

UART driver.

## Macro Definition Documentation

#define NRF_DRV_UART_DEFAULT_CONFIG

Value:
{ \
.pseltxd = NRF_UART_PSEL_DISCONNECTED, \
.pselrxd = NRF_UART_PSEL_DISCONNECTED, \
.pselcts = NRF_UART_PSEL_DISCONNECTED, \
.pselrts = NRF_UART_PSEL_DISCONNECTED, \
.p_context = NULL, \
.hwfc = (nrf_uart_hwfc_t)UART_DEFAULT_CONFIG_HWFC, \
.parity = (nrf_uart_parity_t)UART_DEFAULT_CONFIG_PARITY, \
.baudrate = (nrf_uart_baudrate_t)UART_DEFAULT_CONFIG_BAUDRATE, \
.interrupt_priority = UART_DEFAULT_CONFIG_IRQ_PRIORITY, \
}

UART default configuration.

#define NRF_DRV_UART_INSTANCE | ( |  | id | ) |

Value:
{ \
.reg = {NRF_DRV_UART_PERIPHERAL(id)}, \
.drv_inst_idx = CONCAT_3(UART, id, _INSTANCE_INDEX),\
}

Macro for creating an UART driver instance.

## Typedef Documentation

typedef void(* nrf_uart_event_handler_t)(nrf_drv_uart_event_t *p_event, void *p_context)

UART interrupt event handler.

Parameters

  [in] | p_event | Pointer to event structure. Event is allocated on the stack so it is available only within the context of the event handler.
  [in] | p_context | Context passed to interrupt handler, set on initialization.

## Enumeration Type Documentation

enum nrf_drv_uart_evt_type_t

Types of UART driver events.

Enumerator
NRF_DRV_UART_EVT_TX_DONE | Requested TX transfer completed.
NRF_DRV_UART_EVT_RX_DONE | Requested RX transfer completed.
NRF_DRV_UART_EVT_ERROR | Error reported by UART peripheral.

## Function Documentation

uint32_t nrf_drv_uart_errorsrc_get | ( | nrf_drv_uart_t const * | p_instance | ) |

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

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

Parameters

  [in] | p_instance | Pointer to the driver instance structure.

Return values

  Mask | of reported errors.

__STATIC_INLINE uint32_t nrf_drv_uart_event_address_get | ( | nrf_drv_uart_t const * | p_instance,
|  | nrf_uart_event_t | event
| ) |  |

Function for getting the address of a specific UART event.

Parameters

  [in] | p_instance | Pointer to the driver instance structure.
  [in] | event | Event.

Returns
  Event address.

ret_code_t nrf_drv_uart_init | ( | nrf_drv_uart_t const * | p_instance,
|  | nrf_drv_uart_config_t const * | p_config,
|  | nrf_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

  [in] | p_instance | Pointer to the driver instance structure.
  [in] | p_config | Initial configuration. Default configuration used if NULL.
  [in] | event_handler | Event handler provided by the user. If not provided driver works in blocking mode.

Return values

  NRF_SUCCESS | If initialization was successful.
  NRF_ERROR_INVALID_STATE | If driver is already initialized.

ret_code_t nrf_drv_uart_rx | ( | nrf_drv_uart_t const * | p_instance,
|  | uint8_t * | p_data,
|  | uint8_t | length
| ) |  |

Function for receiving data over UART.

If an event handler was provided in the nrf_drv_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, i.e. 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.

Note
  Peripherals using EasyDMA (i.e. UARTE) require that the transfer buffers are placed in the Data RAM region. If they are not and UARTE driver instance is used, this function will fail with error code NRF_ERROR_INVALID_ADDR.

Parameters

  [in] | p_instance | Pointer to the driver instance structure.
  [in] | p_data | Pointer to data.
  [in] | length | Number of bytes to receive.

Return values

  NRF_SUCCESS | If initialization was successful.
  NRF_ERROR_BUSY | If the driver is already receiving (and the secondary buffer has already been set in non-blocking mode).
  NRF_ERROR_FORBIDDEN | If the transfer was aborted from a different context (blocking mode only, also see nrf_drv_uart_rx_disable).
  NRF_ERROR_INTERNAL | If UART peripheral reported an error.
  NRF_ERROR_INVALID_ADDR | If p_data does not point to RAM buffer (UARTE only).

void nrf_drv_uart_rx_abort | ( | nrf_drv_uart_t const * | p_instance | ) |

Function for aborting any ongoing reception.

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

Parameters

  [in] | p_instance | Pointer to the driver instance structure.

void nrf_drv_uart_rx_disable | ( | nrf_drv_uart_t const * | p_instance | ) |

Function for disabling receiver.

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

See Also
  nrf_drv_uart_rx_enable. Feature is supported only in UART mode (without Easy DMA). Function asserts if mode is wrong.

Parameters

  [in] | p_instance | Pointer to the driver instance structure.

void nrf_drv_uart_rx_enable | ( | nrf_drv_uart_t const * | p_instance | ) |

Function for enabling receiver.

UART has 6 byte long RX FIFO and it will be used to store incoming data. If user will not call UART receive function before FIFO is filled, overrun error will encounter. Enabling receiver without specifying RX buffer is supported only in UART mode (without Easy DMA). Receiver must be explicitly closed by the user

See Also
  nrf_drv_uart_rx_disable. Function asserts if mode is wrong.

Parameters

  [in] | p_instance | Pointer to the driver instance structure.

__STATIC_INLINE uint32_t nrf_drv_uart_task_address_get | ( | nrf_drv_uart_t const * | p_instance,
|  | nrf_uart_task_t | task
| ) |  |

Function for getting the address of a specific UART task.

Parameters

  [in] | p_instance | Pointer to the driver instance structure.
  [in] | task | Task.

Returns
  Task address.

ret_code_t nrf_drv_uart_tx | ( | nrf_drv_uart_t const * | p_instance,
|  | uint8_t const *const | p_data,
|  | uint8_t | length
| ) |  |

Function for sending data over UART.

If an event handler was provided in nrf_drv_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, i.e. this function returns when the transfer is finished. Blocking mode is not using interrupt so there is no context switching inside the function.

Note
  Peripherals using EasyDMA (i.e. UARTE) require that the transfer buffers are placed in the Data RAM region. If they are not and UARTE instance is used, this function will fail with error code NRF_ERROR_INVALID_ADDR.

Parameters

  [in] | p_instance | Pointer to the driver instance structure.
  [in] | p_data | Pointer to data.
  [in] | length | Number of bytes to send.

Return values

  NRF_SUCCESS | If initialization was successful.
  NRF_ERROR_BUSY | If driver is already transferring.
  NRF_ERROR_FORBIDDEN | If the transfer was aborted from a different context (blocking mode only, also see nrf_drv_uart_rx_disable).
  NRF_ERROR_INVALID_ADDR | If p_data does not point to RAM buffer (UARTE only).

void nrf_drv_uart_tx_abort | ( | nrf_drv_uart_t const * | p_instance | ) |

Function for aborting any ongoing transmission.

Note
  NRF_DRV_UART_EVT_TX_DONE event will be generated in non-blocking mode. Event will contain number of bytes sent until abort was called. If Easy DMA is not used event will be called from the function context. If Easy DMA is used it will be called from UART interrupt context.

Parameters

  [in] | p_instance | Pointer to the driver instance structure.

bool nrf_drv_uart_tx_in_progress | ( | nrf_drv_uart_t const * | p_instance | ) |

Function for checking if UART is currently transmitting.

Parameters

  [in] | p_instance | Pointer to the driver instance structure.

Return values

  true | If UART is transmitting.
  false | If UART is not transmitting.

void nrf_drv_uart_uninit | ( | nrf_drv_uart_t const * | p_instance | ) |

Function for uninitializing the UART driver.

Parameters

  [in] | p_instance | Pointer to the driver instance structure.