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_MSG
         
         ((_tx_size) <= UINT8_MAX, NRF_SERIAL_TX_SIZE); \
        
         STATIC_ASSERT_MSG((_rx_size) <= UINT8_MAX, NRF_SERIAL_RX_SIZE); \
        
         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.

Serial port abstraction layer

nRF5 SDK v13.0.0

Modules

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation