nRF5 SDK  v15.2.0
Choose documentation:
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Serial port library

This module allows to create and handle serial port instances. It is designed as a more sophisticated replacement for the app_uart module. The following are the advantages of this module over app_uart:

  • API is more generic and robust: you can read or write any amount of bytes.
  • Multi-instance capability.
  • The module can work in three modes: POLLING, IRQ, and DMA.
  • Calls can be asynchronous and synchronus (with timeouts).
  • Independent RX/TX FIFOs with configurable sizes.
  • Configurable RX/TX transfer buffers (smallest transfer slice).
  • Event handler (not mandatory).
  • Sleep handler (not mandatory).

You can initialize this module in one of the three available modes:

  • NRF_SERIAL_MODE_POLLING - Simple polling operation without any interrupts.
    • Functional timeouts.
    • Only 6-byte size hardware FIFO.
  • NRF_SERIAL_MODE_IRQ - Interrupt mode.
    • Software FIFOs with configured size.
    • User-defined transfer slice size.
    • Funtional timeouts.
    • User-defined event and sleep handlers.
  • NRF_SERIAL_MODE_DMA - Same functionality as in IRQ mode but uses EasyDMA.

The following code snippet shows how to create a configuration structure for each of these modes:

NULL, NULL, NULL, NULL);
&queues, &buffers, NULL, NULL);
&queues, &buffers, NULL, NULL);

Such configuration structure can be passed directly to the nrf_serial_init method. The table below shows the configuration dependencies:

  • R - Required
  • O - Optional
  • U - Unused
Mode/Configuration QUEUES BUFFERS EVENT_HANDLER SLEEP_HANDLER
NRF_SERIAL_MODE_POLLING U U U U
NRF_SERIAL_MODE_IRQ R R O O
NRF_SERIAL_MODE_DMA R R O O

In Interrupt and DMA modes, you must create the RX/TX queues. The following code snippet shows how to create an instance of the RX/TX queue:

#define SERIAL_FIFO_TX_SIZE 32
#define SERIAL_FIFO_RX_SIZE 32
NRF_SERIAL_QUEUES_DEF(serial_queues, SERIAL_FIFO_TX_SIZE, SERIAL_FIFO_RX_SIZE);

Interrupt and DMA modes require a definition of the transfer buffers. They are the smallest slices of data that can be transfered in a single UART driver - legacy layer driver request. The following code snippet shows how to declare transfer buffers:

#define SERIAL_BUFF_TX_SIZE 1
#define SERIAL_BUFF_RX_SIZE 1
NRF_SERIAL_BUFFERS_DEF(serial_buffs, SERIAL_BUFF_TX_SIZE, SERIAL_BUFF_RX_SIZE);

For API documentation of this library, refer to Serial port abstraction layer.

For a usage example, refer to Serial Port Library Example.