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