UART module implementation. 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, APP_UART_FLOW_CONTROL_LOW_POWER }
	UART Flow Control modes for the peripheral. More...

enum	app_uart_connection_state_t { APP_UART_DISCONNECTED, APP_UART_CONNECTED }
	Enumeration describing current state of the UART. 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, uint16_t *p_uart_uid)
	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_get_connection_state (app_uart_connection_state_t *p_connection_state)
	Function for getting the current state of 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 (uint16_t app_uart_id)
	Function for closing the UART module. More...

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...

Detailed Description

The UART module can be used for control of the UART. The UART module has three modes:

UART without Hardware Flow Control
UART with Hardware Flow Control
UART with Low Power mode, will use Hardware Flow Control and GPIOTE on the CTS line to power off the UART module in the nRF chip, allowing the nRF to save power.

The low power mode will be use RTS/CTS flow control while also use the CTS line as to enter low power mode. The UART peripheral will be turned off whenever the CTS signal from the remote side is high, and when CTS becomes low (active) the UART peripheral will be enabled.

Asynchronous nature

The UART module will receive bytes from the RXD register when an EVENT_RXDRDY interrupt has occurred. The byte will be put into the RX FIFO and can be fetched by the application using app_uart_get. First byte received and placed in the RX FIFO will trigger an APP_UART_DATA_READY event.

The app_uart_put will place the provided byte in the TX FIFO. Bytes in the TX FIFO will be written to the TXD register by the app_uart module. When a byte is successfully transfered an EVENT_TXDRDY interrupt is triggered. The interrupt handler in the app_uart module will fetch the next byte from the FIFO and write it to the TXD register. The application can call app_uart_put to request transmission of bytes.

Error handling

An error flag is set in the UART peripheral in event of an error during data reception. The error will be propagated to the application event handler as an app_uart_evt_t containing APP_UART_ERROR_SOURCE in the evt_type field. The data.error_source field will contain the original error source information from the UART peripheral register.

In case the RX FIFO is full when data are received an app_uart_evt_t containing APP_UART_NRF_ERROR in the evt_type field will be generated and sent to the application. The event will contain the original error code from the FIFO in the data.error_code field.

UART Low Power mode with flow control

When UART is configured to use Low Power mode with flow control it will use low power mode when possible. The UART peripheral will be de-activated when the CTS signal from the remote side is set to inactive state. When CTS is set active by the remote side, the UART peripheral will be activated.

The STARTTX register will be enabled when data are available in the TX FIFO and CTS is active.

The application should use app_uart_get_connection_state to ensure that the nRF51 chip only power off when the UART peripheral is disconnected. When the nRF51 chip is in power off mode the remote side can wake up the nRF51 chip by setting the CTS to active state.

UART with flow control enabled state machine diagram.

Note: When using RTS/CTS flow control the CTS pin will be monitored by the GPIOTE. To register the UART module as a user of app_gpiote run the GPIOTE_INIT(X) macro to initialize the module with the X number of users. X will be the number of all app_gpiote users of the whole application.

UART without flow control

     When using the app_uart module without flow control the UART will not use GPIOTE. CTS will
     not work as a signal for the UART to stop the RX peripheral. Thus the UART RX will
     always be on.

UART without flow control state machine diagram.

Macro Definition Documentation

#define UART_PIN_DISCONNECTED 0xFFFFFFFF

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

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

Value:

do \
 { \
 uint16_t APP_UART_UID = 0; \
 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, &APP_UART_UID); \
 } while (0)

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]	EVENT_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 \
 { \
 uint16_t APP_UART_UID = 0; \
 ERR_CODE = app_uart_init(P_COMM_PARAMS, NULL, EVT_HANDLER, IRQ_PRIO, &APP_UART_UID); \
 } while (0)

Parameters

[in]	P_COMM_PARAMS	Pointer to a UART communication structure: app_uart_comm_params_t
[in]	EVENT_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.

Typedef Documentation

typedef void(* app_uart_event_handler_t)(app_uart_evt_t *p_app_uart_event)

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

Parameters

[in] p_app_uart_event Pointer to UART event.

Enumeration Type Documentation

enum app_uart_flow_control_t

Enumerator
APP_UART_FLOW_CONTROL_DISABLED	UART Hw Flow Control is disabled.
APP_UART_FLOW_CONTROL_ENABLED	Standard UART Hw Flow Control is enabled.
APP_UART_FLOW_CONTROL_LOW_POWER	Specialized UART Hw Flow Control is used. The Low Power setting allows the nRF51 to Power Off the UART module when CTS is in-active, and re-enabling the UART when the CTS signal becomes active. This allows the nRF51 to safe power by only using the UART module when it is needed by the remote site.

enum app_uart_connection_state_t

The connection state can be fetched by the application using the function call app_uart_get_connection_state. When hardware flow control is used

APP_UART_CONNECTED: Communication is ongoing.
APP_UART_DISCONNECTED: No communication is ongoing.

When no hardware flow control is used

APP_UART_CONNECTED: Always returned as bytes can always be received/transmitted.

Enumerator
APP_UART_DISCONNECTED	State indicating that the UART is disconnected and cannot receive or transmit bytes.
APP_UART_CONNECTED	State indicating that the UART is connected and ready to receive or transmit bytes. If flow control is disabled, the state will always be connected.

enum app_uart_evt_type_t

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.

Function Documentation

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,
		uint16_t *	p_uart_uid
	)

This initialization will return a UART user id for the caller. The UART user id must be used upon re-initialization of the UART or closing of the module for the user. If single instance usage is needed, the APP_UART_INIT() macro should be used instead.

Note: Normally single instance 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]	app_irq_priority	Interrupt priority level.
[in,out]	p_uart_uid	User id for the UART module. The p_uart_uid must be used if re-initialization and/or closing of the UART module is needed. If the value pointed to by p_uart_uid is zero, this is considdered a first time initialization. Otherwise this is considered a re-initialization for the user with id *p_uart_uid.

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.

Those 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, those 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_get ( uint8_t * p_byte )

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_put ( uint8_t byte )

This call is non-blocking.

Parameters

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

Return values

NRF_SUCCESS	If the byte was succesfully 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.

uint32_t app_uart_get_connection_state ( app_uart_connection_state_t * p_connection_state )

If flow control is disabled, the state is assumed to always be APP_UART_CONNECTED.

     When using flow control the state will be controlled by the CTS. If CTS is set active 
     by the remote side, or the app_uart module is in the process of transmitting a byte,
     app_uart is in APP_UART_CONNECTED state. If CTS is set inactive by remote side app_uart
     will not get into APP_UART_DISCONNECTED state until the last byte in the TXD register 
     is fully transmitted.

     Internal states in the state machine are mapped to the general connected/disconnected
     states in the following ways:

     - UART_ON    = CONNECTED
     - UART_READY = CONNECTED
     - UART_WAIT  = CONNECTED
     - UART_OFF   = DISCONNECTED.

Parameters

[out] p_connection_state Current connection state of the UART.

Return values

NRF_SUCCESS The connection state was succesfully retrieved.

uint32_t app_uart_flush ( void )

Return values

NRF_SUCCESS Flushing completed (Current implementation will always succeed).

uint32_t app_uart_close ( uint16_t app_uart_id )

This function will close any on-going UART transmissions and disable itself in the GPTIO module.

Parameters

[in] app_uart_uid User id for the UART module. The app_uart_uid must be identical to the UART id returned on initialization and which is currently in use.

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.

Macros

Typedefs

Enumerations

Functions

Data Structures

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation