| 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 module
SDK common libraries

UART module interface. More...

## Modules
| UART driver configuration

## Data Structures
struct | app_uart_comm_params_t
| UART communication structure holding configuration settings for the peripheral. More...
struct | app_uart_buffers_t
| UART buffer for transmitting/receiving data. More...
struct | app_uart_evt_t
| Struct containing events from the UART module. More...

## Macros
#define | UART_PIN_DISCONNECTED 0xFFFFFFFF
#define | APP_UART_FIFO_INIT(P_COMM_PARAMS, RX_BUF_SIZE, TX_BUF_SIZE, EVT_HANDLER, IRQ_PRIO, ERR_CODE)
| Macro for safe initialization of the UART module in a single user instance when using a FIFO together with UART. More...
#define | APP_UART_INIT(P_COMM_PARAMS, EVT_HANDLER, IRQ_PRIO, ERR_CODE)
| Macro for safe initialization of the UART module in a single user instance. More...

## Typedefs
typedef void(* | app_uart_event_handler_t )(app_uart_evt_t *p_app_uart_event)
| Function for handling app_uart event callback. More...

## Enumerations
enum | app_uart_flow_control_t { APP_UART_FLOW_CONTROL_DISABLED, APP_UART_FLOW_CONTROL_ENABLED }
| UART Flow Control modes for the peripheral. More...
enum | app_uart_evt_type_t { APP_UART_DATA_READY, APP_UART_FIFO_ERROR, APP_UART_COMMUNICATION_ERROR, APP_UART_TX_EMPTY, APP_UART_DATA }
| Enumeration which defines events used by the UART module upon data reception or error. More...

## Functions
uint32_t | app_uart_init (const app_uart_comm_params_t *p_comm_params, app_uart_buffers_t *p_buffers, app_uart_event_handler_t error_handler, app_irq_priority_t irq_priority)
| Function for initializing the UART module. Use this initialization when several instances of the UART module are needed. More...
uint32_t | app_uart_get (uint8_t *p_byte)
| Function for getting a byte from the UART. More...
uint32_t | app_uart_put (uint8_t byte)
| Function for putting a byte on the UART. More...
uint32_t | app_uart_flush (void)
| Function for flushing the RX and TX buffers (Only valid if FIFO is used). This function does nothing if FIFO is not used. More...
uint32_t | app_uart_close (void)
| Function for closing the UART module. More...

## Detailed Description

UART module interface.

## Macro Definition Documentation

#define APP_UART_FIFO_INIT | ( |  | P_COMM_PARAMS,
|  |  | RX_BUF_SIZE,
|  |  | TX_BUF_SIZE,
|  |  | EVT_HANDLER,
|  |  | IRQ_PRIO,
|  |  | ERR_CODE
| ) |  |

Value:
do \
{ \
app_uart_buffers_t buffers; \
static uint8_t rx_buf[RX_BUF_SIZE]; \
static uint8_t tx_buf[TX_BUF_SIZE]; \
\
buffers.rx_buf = rx_buf; \
buffers.rx_buf_size = sizeof (rx_buf); \
buffers.tx_buf = tx_buf; \
buffers.tx_buf_size = sizeof (tx_buf); \
ERR_CODE = app_uart_init(P_COMM_PARAMS, &buffers, EVT_HANDLER, IRQ_PRIO); \
} while (0)

Macro for safe initialization of the UART module in a single user instance when using a FIFO together with UART.

Parameters

  [in] | P_COMM_PARAMS | Pointer to a UART communication structure: app_uart_comm_params_t
  [in] | RX_BUF_SIZE | Size of desired RX buffer, must be a power of 2 or ZERO (No FIFO).
  [in] | TX_BUF_SIZE | Size of desired TX buffer, must be a power of 2 or ZERO (No FIFO).
  [in] | EVT_HANDLER | Event handler function to be called when an event occurs in the UART module.
  [in] | IRQ_PRIO | IRQ priority, app_irq_priority_t, for the UART module irq handler.
  [out] | ERR_CODE | The return value of the UART initialization function will be written to this parameter.

Note
  Since this macro allocates a buffer and registers the module as a GPIOTE user when flow control is enabled, it must only be called once.

#define APP_UART_INIT | ( |  | P_COMM_PARAMS,
|  |  | EVT_HANDLER,
|  |  | IRQ_PRIO,
|  |  | ERR_CODE
| ) |  |

Value:
do \
{ \
ERR_CODE = app_uart_init(P_COMM_PARAMS, NULL, EVT_HANDLER, IRQ_PRIO); \
} while (0)

Macro for safe initialization of the UART module in a single user instance.

Parameters

  [in] | P_COMM_PARAMS | Pointer to a UART communication structure: app_uart_comm_params_t
  [in] | EVT_HANDLER | Event handler function to be called when an event occurs in the UART module.
  [in] | IRQ_PRIO | IRQ priority, app_irq_priority_t, for the UART module irq handler.
  [out] | ERR_CODE | The return value of the UART initialization function will be written to this parameter.

Note
  Since this macro allocates registers the module as a GPIOTE user when flow control is enabled, it must only be called once.

#define UART_PIN_DISCONNECTED 0xFFFFFFFF

Value indicating that no pin is connected to this UART register.

## Typedef Documentation

typedef void(* app_uart_event_handler_t)(app_uart_evt_t *p_app_uart_event)

Function for handling app_uart event callback.

Upon an event in the app_uart module this callback function will be called to notify the application about the event.

Parameters

  [in] | p_app_uart_event | Pointer to UART event.

## Enumeration Type Documentation

enum app_uart_evt_type_t

Enumeration which defines events used by the UART module upon data reception or error.

The event type is used to indicate the type of additional information in the event app_uart_evt_t.

Enumerator
APP_UART_DATA_READY | An event indicating that UART data has been received. The data is available in the FIFO and can be fetched using app_uart_get.
APP_UART_FIFO_ERROR | An error in the FIFO module used by the app_uart module has occured. The FIFO error code is stored in app_uart_evt_t.data.error_code field.
APP_UART_COMMUNICATION_ERROR | An communication error has occured during reception. The error is stored in app_uart_evt_t.data.error_communication field.
APP_UART_TX_EMPTY | An event indicating that UART has completed transmission of all available data in the TX FIFO.
APP_UART_DATA | An event indicating that UART data has been received, and data is present in data field. This event is only used when no FIFO is configured.

enum app_uart_flow_control_t

UART Flow Control modes for the peripheral.

Enumerator
APP_UART_FLOW_CONTROL_DISABLED | UART Hw Flow Control is disabled.
APP_UART_FLOW_CONTROL_ENABLED | Standard UART Hw Flow Control is enabled.

## Function Documentation

uint32_t app_uart_close | ( | void |  | ) |

Function for closing the UART module.

Return values

  NRF_SUCCESS | If successfully closed.
  NRF_ERROR_INVALID_PARAM | If an invalid user id is provided or the user id differs from the current active user.

uint32_t app_uart_flush | ( | void |  | ) |

Function for flushing the RX and TX buffers (Only valid if FIFO is used). This function does nothing if FIFO is not used.

Return values

  NRF_SUCCESS | Flushing completed (Current implementation will always succeed).

uint32_t app_uart_get | ( | uint8_t * | p_byte | ) |

Function for getting a byte from the UART.

This function will get the next byte from the RX buffer. If the RX buffer is empty an error code will be returned and the app_uart module will generate an event upon reception of the first byte which is added to the RX buffer.

Parameters

  [out] | p_byte | Pointer to an address where next byte received on the UART will be copied.

Return values

  NRF_SUCCESS | If a byte has been received and pushed to the pointer provided.
  NRF_ERROR_NOT_FOUND | If no byte is available in the RX buffer of the app_uart module.

uint32_t app_uart_init | ( | const app_uart_comm_params_t * | p_comm_params,
|  | app_uart_buffers_t * | p_buffers,
|  | app_uart_event_handler_t | error_handler,
|  | app_irq_priority_t | irq_priority
| ) |  |

Function for initializing the UART module. Use this initialization when several instances of the UART module are needed.

Note
  Normally single initialization should be done using the APP_UART_INIT() or APP_UART_INIT_FIFO() macro depending on whether the FIFO should be used by the UART, as that will allocate the buffers needed by the UART module (including aligning the buffer correctly).

Parameters

  [in] | p_comm_params | Pin and communication parameters.
  [in] | p_buffers | RX and TX buffers, NULL is FIFO is not used.
  [in] | error_handler | Function to be called in case of an error.
  [in] | irq_priority | Interrupt priority level.

Return values

  NRF_SUCCESS | If successful initialization.
  NRF_ERROR_INVALID_LENGTH | If a provided buffer is not a power of two.
  NRF_ERROR_NULL | If one of the provided buffers is a NULL pointer.

The below errors are propagated by the UART module to the caller upon registration when Hardware Flow Control is enabled. When Hardware Flow Control is not used, these errors cannot occur.

Return values

  NRF_ERROR_INVALID_STATE | The GPIOTE module is not in a valid state when registering the UART module as a user.
  NRF_ERROR_INVALID_PARAM | The UART module provides an invalid callback function when registering the UART module as a user. Or the value pointed to by *p_uart_uid is not a valid GPIOTE number.
  NRF_ERROR_NO_MEM | GPIOTE module has reached the maximum number of users.

uint32_t app_uart_put | ( | uint8_t | byte | ) |

Function for putting a byte on the UART.

This call is non-blocking.

Parameters

  [in] | byte | Byte to be transmitted on the UART.

Return values

  NRF_SUCCESS | If the byte was successfully put on the TX buffer for transmission.
  NRF_ERROR_NO_MEM | If no more space is available in the TX buffer. NRF_ERROR_NO_MEM may occur if flow control is enabled and CTS signal is high for a long period and the buffer fills up.
  NRF_ERROR_INTERNAL | If UART driver reported error.