Serial module interface. More...

Modules
	Serial port interface configuration

Data Structures
struct	nrf_serial_queues_t
	Serial port RX and TX queues. More...

struct	nrf_serial_buffers_t
	Serial buffers. Data slices used by nrf_drv_uart_tx and nrf_drv_uart_rx. More...

struct	nrf_serial_config_t
	Configuration of UART serial interface. More...

struct	nrf_serial_ctx_t
	Serial port context. Contains all data structures that need to be stored in RAM memory. More...

struct	nrf_serial_s
	Serial port instance declaration. More...

Macros
#define	NRF_SERIAL_DRV_UART_CONFIG_DEF(_name,_rx_pin,_tx_pin,_rts_pin,_cts_pin,_flow_control,_parity,_baud_rate,_irq_prio)
	Creates an instance of nrf_drv_uart_config_t. More...

#define	NRF_SERIAL_QUEUES_DEF(_name, _tx_size, _rx_size)
	Creates an instance of serial port queues. More...

#define	NRF_SERIAL_BUFFERS_DEF(_name, _tx_size, _rx_size)
	Creates an instance of serial port buffers. More...

#define	NRF_SERIAL_CONFIG_DEF(_name, _mode, _queues, _buffers, _ev_handler, _sleep)
	Creates an instance of serial port configuration. More...

#define	NRF_SERIAL_RX_ENABLED_FLAG (1u << 0)
	Receiver enable flag.

#define	NRF_SERIAL_TX_ENABLED_FLAG (1u << 1)
	Transmitter enable flag.

#define	NRF_SERIAL_UART_DEF(_name, _instance_number)
	Creates an instance of a serial port. More...

#define	NRF_SERIAL_MAX_TIMEOUT UINT32_MAX
	Maximum value of timeout. API might be blocked indefinitely if this value is not set.

Typedefs
typedef struct nrf_serial_s	nrf_serial_t

typedef void(*	nrf_serial_evt_handler_t )(struct nrf_serial_s const *p_serial, nrf_serial_event_t event)
	Event handler type.

typedef void(*	nrf_serial_sleep_handler_t )(void)
	Sleep handler type.

Enumerations
enum	nrf_serial_mode_t { NRF_SERIAL_MODE_POLLING, NRF_SERIAL_MODE_IRQ, NRF_SERIAL_MODE_DMA }
	Serial port mode. More...

enum	nrf_serial_event_t { NRF_SERIAL_EVENT_TX_DONE, NRF_SERIAL_EVENT_RX_DATA, NRF_SERIAL_EVENT_DRV_ERR, NRF_SERIAL_EVENT_FIFO_ERR }
	Events generated by this module. More...

Functions
ret_code_t	nrf_serial_init (nrf_serial_t const p_serial, nrf_drv_uart_config_t const p_drv_uart_config, nrf_serial_config_t const *p_config)
	Function for initializing a serial port. Serial port can be initialized in various modes that are defined by nrf_serial_mode_t. More...

ret_code_t	nrf_serial_uninit (nrf_serial_t const *p_serial)
	Function for uninitializing a serial port. More...

ret_code_t	nrf_serial_write (nrf_serial_t const p_serial, void const p_data, size_t size, size_t *p_written, uint32_t timeout_ms)
	Function for writing to a serial port. More...

ret_code_t	nrf_serial_read (nrf_serial_t const p_serial, void p_data, size_t size, size_t *p_read, uint32_t timeout_ms)
	Function for reading from a serial port. More...

ret_code_t	nrf_serial_flush (nrf_serial_t const *p_serial, uint32_t timeout_ms)
	Function for flushing a serial port TX queue. More...

ret_code_t	nrf_serial_tx_abort (nrf_serial_t const *p_serial)
	Function for aborting a serial port transmission. Aborts the current ongoing transmission and resets TX FIFO. More...

ret_code_t	nrf_serial_rx_drain (nrf_serial_t const *p_serial)
	Function for draining the serial port receive RX FIFO. Drains HW FIFO and resets RX FIFO. More...

Detailed Description

Serial module interface.

This module is more sophisticated than UART driver - legacy layer. It internally uses mutex, queues, and app_timer. You can configure it to work in three different modes (polling, interrupt, DMA). API can be configured to work in synchronous mode. Both read and write methods have a timeout parameter. Asynchronous mode is available by passing 0 as the timeout parameter.

Warning: Do not use synchronous API (timeout_ms parameter > 0) in IRQ context. It may lead to a deadlock because the timeout interrupt cannot preempt the current IRQ context.

Macro Definition Documentation

#define NRF_SERIAL_BUFFERS_DEF	(	_name,
		_tx_size,
		_rx_size
	)

Value:

STATIC_ASSERT((_tx_size) <= UINT8_MAX); \
 STATIC_ASSERT((_rx_size) <= UINT8_MAX); \
 static uint8_t _name##_txb[_tx_size]; \
 static uint8_t _name##_rxb[_rx_size]; \
 static const nrf_serial_buffers_t _name = { \
 .p_txb = _name##_txb, \
 .p_rxb = _name##_rxb, \
 .tx_size = sizeof(_name##_txb), \
 .rx_size = sizeof(_name##_rxb), \
 }

Creates an instance of serial port buffers.

Parameters

_name	Instance name.
_tx_size	TX buffer size.
_rx_size	RX buffer size.

#define NRF_SERIAL_CONFIG_DEF	(	_name,
		_mode,
		_queues,
		_buffers,
		_ev_handler,
		_sleep
	)

Value:

static const nrf_serial_config_t _name = { \
 .mode = _mode, \
 .p_queues = _queues, \
 .p_buffers = _buffers, \
 .ev_handler = _ev_handler, \
 .sleep_handler = _sleep, \
 }

Creates an instance of serial port configuration.

Parameters

_name	Instance name.
_mode	Serial port mode.
_queues	Serial port queues. NULL can be passed in NRF_SERIAL_MODE_POLLING mode.
_buffers	Serial port buffers. NULL can be passed in NRF_SERIAL_MODE_POLLING mode.
_ev_handler	Serial port event handler. NULL can be passed in any mode.
_sleep	Serial port sleep handler. NULL can be passed in any mode.

#define NRF_SERIAL_DRV_UART_CONFIG_DEF	(	_name,
		_rx_pin,
		_tx_pin,
		_rts_pin,
		_cts_pin,
		_flow_control,
		_parity,
		_baud_rate,
		_irq_prio
	)

Value:

static const nrf_drv_uart_config_t _name = { \
 .pselrxd = _rx_pin, \
 .pseltxd = _tx_pin, \
 .pselrts = _rts_pin, \
 .pselcts = _cts_pin, \
 .hwfc = _flow_control, \
 .parity = _parity, \
 .baudrate = _baud_rate, \
 .interrupt_priority = _irq_prio, \
 }

Creates an instance of nrf_drv_uart_config_t.

Parameters

_name	Instance name.
_rx_pin	RX pin number.
_tx_pin	TX pin number.
_rts_pin	RTS pin number.
_cts_pin	CTS pin number.
_flow_control	Flow control enable/disable (nrf_uart_hwfc_t).
_parity	Parity enable/disable (nrf_uart_parity_t).
_baud_rate	Baud rate (nrf_uart_baudrate_t).
_irq_prio	Interrupt priority.

#define NRF_SERIAL_QUEUES_DEF	(	_name,
		_tx_size,
		_rx_size
	)

Value:

NRF_QUEUE_DEF(uint8_t, _name##_rxq, _rx_size, NRF_QUEUE_MODE_NO_OVERFLOW); \
 NRF_QUEUE_DEF(uint8_t, _name##_txq, _tx_size, NRF_QUEUE_MODE_NO_OVERFLOW); \
 static const nrf_serial_queues_t _name = { \
 .p_rxq = &_name##_rxq, \
 .p_txq = &_name##_txq, \
 }

Creates an instance of serial port queues.

Parameters

_name	Instance name.
_tx_size	TX queue size.
_rx_size	RX queue size.

#define NRF_SERIAL_UART_DEF	(	_name,
		_instance_number
	)

Value:

APP_TIMER_DEF(_name##_rx_timer); \
 APP_TIMER_DEF(_name##_tx_timer); \
 static nrf_serial_ctx_t _name##_ctx; \
 static const nrf_serial_t _name = { \
 .instance = NRF_DRV_UART_INSTANCE(_instance_number), \
 .p_ctx = &_name##_ctx, \
 .p_tx_timer = &_name##_tx_timer, \
 .p_rx_timer = &_name##_rx_timer, \
 }

Creates an instance of a serial port.

Parameters

_name	Instance name.
_instance_number	Driver instance number (NRF_DRV_UART_INSTANCE).

Enumeration Type Documentation

enum nrf_serial_event_t

Events generated by this module.

Enumerator
NRF_SERIAL_EVENT_TX_DONE	Chunk of data has been sent.
NRF_SERIAL_EVENT_RX_DATA	New chunk of data has been received.
NRF_SERIAL_EVENT_DRV_ERR	Internal driver error.
NRF_SERIAL_EVENT_FIFO_ERR	RX FIFO overrun.

enum nrf_serial_mode_t

Serial port mode.

Enumerator
NRF_SERIAL_MODE_POLLING	Polling mode.
NRF_SERIAL_MODE_IRQ	Interrupt mode.
NRF_SERIAL_MODE_DMA	DMA mode.

Function Documentation

ret_code_t nrf_serial_flush	(	nrf_serial_t const *	p_serial,
		uint32_t	timeout_ms
	)

Function for flushing a serial port TX queue.

Parameters

p_serial	Serial port instance.
timeout_ms	Operation timeout, in milliseconds. Pass 0 to operate in non blocking mode.

Returns: Standard error code.

ret_code_t nrf_serial_init	(	nrf_serial_t const *	p_serial,
		nrf_drv_uart_config_t const *	p_drv_uart_config,
		nrf_serial_config_t const *	p_config
	)

Function for initializing a serial port. Serial port can be initialized in various modes that are defined by nrf_serial_mode_t.

NRF_SERIAL_MODE_POLLING - Simple polling mode. API calls will be synchronous. There is no need to define queues or buffers. No events will be generated.
NRF_SERIAL_MODE_IRQ - Interrupt mode. API can be set to work in synchronous or asynchronous mode. Queues and buffers must be passed during initialization. Events will be generated if a non NULL handler is passed as the ev_handler parameter.
NRF_SERIAL_MODE_DMA - Similar to NRF_SERIAL_MODE_IRQ. Uses EasyDMA.

Parameters

p_serial	Serial port instance.
p_drv_uart_config	UART driver configuration. Cannot be NULL.
p_config	Serial port configuration. Cannot be NULL. This object must be created using the NRF_SERIAL_CONFIG_DEF macro.

Returns: Standard error code.

ret_code_t nrf_serial_read	(	nrf_serial_t const *	p_serial,
		void *	p_data,
		size_t	size,
		size_t *	p_read,
		uint32_t	timeout_ms
	)

Function for reading from a serial port.

Parameters

p_serial	Serial port instance.
p_data	Receive buffer pointer.
size	Receive buffer size.
p_read	Amount of data actually read from the serial port. NULL pointer can be passed.
timeout_ms	Operation timeout, in milliseconds. Pass 0 to operate in non blocking mode.

Returns: Standard error code.

ret_code_t nrf_serial_rx_drain ( nrf_serial_t const * p_serial )

Function for draining the serial port receive RX FIFO. Drains HW FIFO and resets RX FIFO.

Parameters

p_serial Serial port instance.

Returns: Standard error code.

ret_code_t nrf_serial_tx_abort ( nrf_serial_t const * p_serial )

Function for aborting a serial port transmission. Aborts the current ongoing transmission and resets TX FIFO.

Parameters

p_serial Serial port instance.

Returns: Standard error code.

ret_code_t nrf_serial_uninit ( nrf_serial_t const * p_serial )

Function for uninitializing a serial port.

Parameters

p_serial Serial port instance.

Returns: Standard error code.

ret_code_t nrf_serial_write	(	nrf_serial_t const *	p_serial,
		void const *	p_data,
		size_t	size,
		size_t *	p_written,
		uint32_t	timeout_ms
	)

Function for writing to a serial port.

Parameters

p_serial	Serial port instance.
p_data	Transmit buffer pointer.
size	Transmit buffer size.
p_written	Amount of data actually written to the serial port. NULL pointer can be passed.
timeout_ms	Operation timeout, in milliseconds. Pass 0 to operate in non blocking mode.

Returns: Standard error code.

Modules

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation