Fork me on GitHub

UART

This library provides UART hardware access interface.

C API Reference mgos_uart.h

#include "mgos_uart.h"

See on GitHub: mgos_uart.h, mgos_uart.c


struct mgos_uart_dev_config {};

enum mgos_uart_fc_type {
  MGOS_UART_FC_NONE = 0,
  MGOS_UART_FC_HW = 1, /* CTS/RTS */
  MGOS_UART_FC_SW = 2, /* XON/XOFF */
};

enum mgos_uart_parity {
  MGOS_UART_PARITY_NONE = 0,
  MGOS_UART_PARITY_EVEN = 1,
  MGOS_UART_PARITY_ODD = 2,
};

enum mgos_uart_stop_bits {
  MGOS_UART_STOP_BITS_1 = 1, /* So that 1 means 1 bit and 2 means 2. */
  MGOS_UART_STOP_BITS_2 = 2,
  MGOS_UART_STOP_BITS_1_5 = 3,
};

struct mgos_uart_config {
  int baud_rate;                      /* Baud rate. Default: 115200 */
  int num_data_bits;                  /* Number of data bits, 5-8. Default: 8 */
  enum mgos_uart_parity parity;       /* Parity. Default: none */
  enum mgos_uart_stop_bits stop_bits; /* Number of stop bits. Default: 1 */

  /* Size of the Rx buffer, default: 256 */
  int rx_buf_size;
  /* Enable flow control for Rx (RTS pin), default: off */
  enum mgos_uart_fc_type rx_fc_type;
  /*
   * Lingers for this many microseconds after RX fifo is empty in case more
   * data arrives. Default: 15.
   */
  int rx_linger_micros;

  /* Size of the Tx buffer, default: 256 */
  int tx_buf_size;
  /* Enable flow control for Tx (CTS pin), default: off */
  enum mgos_uart_fc_type tx_fc_type;

  /* Platform-specific configuration options. */
  struct mgos_uart_dev_config dev;
};

bool mgos_uart_configure(int uart_no, const struct mgos_uart_config *cfg);

Apply given UART configuration.

void mgos_uart_config_set_defaults(int uart_no, struct mgos_uart_config *cfg);

Fill provided cfg structure with the default values.

bool mgos_uart_config_get(int uart_no, struct mgos_uart_config *cfg);

Fill provided cfg structure with the current UART config. Returns false if the specified UART has not bee configured yet.

typedef void (*mgos_uart_dispatcher_t)(int uart_no, void *arg);

UART dispatcher gets when there is data in the input buffer or space available in the output buffer.

void mgos_uart_set_dispatcher(int uart_no, mgos_uart_dispatcher_t cb,
                              void *arg);

size_t mgos_uart_write(int uart_no, const void *buf, size_t len);

Write data to the UART. Note: if there is enough space in the output buffer, the call will return immediately, otherwise it will wait for buffer to drain. If you want the call to not block, check mgos_uart_write_avail() first.

size_t mgos_uart_write_avail(int uart_no);

Returns amount of space availabe in the output buffer.

int mgos_uart_printf(int uart_no, const char *fmt, ...);

Write data to UART, printf style. Note: currently this requires that data is fully rendered in memory before sending. There is no fixed limit as heap allocation is used, but be careful when printing longer strings.

size_t mgos_uart_read(int uart_no, void *buf, size_t len);

Read data from UART input buffer. The _mbuf variant is a convenice function that reads into an mbuf. Note: unlike write, read will not block if there are not enough bytes in the input buffer.

size_t mgos_uart_read_mbuf(int uart_no, struct mbuf *mb, size_t len);

size_t mgos_uart_read_avail(int uart_no);

Returns the number of bytes available for reading.

void mgos_uart_set_rx_enabled(int uart_no, bool enabled);

Controls whether UART receiver is enabled.

bool mgos_uart_is_rx_enabled(int uart_no);

void mgos_uart_flush(int uart_no);

Flush the UART output buffer - waits for data to be sent.

void mgos_uart_schedule_dispatcher(int uart_no, bool from_isr);

struct mgos_uart_stats {
  uint32_t ints;

  uint32_t rx_ints;
  uint32_t rx_bytes;
  uint32_t rx_overflows;
  uint32_t rx_linger_conts;

  uint32_t tx_ints;
  uint32_t tx_bytes;
  uint32_t tx_throttles;

  void *dev_data;
};

const struct mgos_uart_stats *mgos_uart_get_stats(int uart_no);

enum mgos_init_result mgos_uart_init(void);

struct mgos_uart_config *mgos_uart_config_get_default(int uart_no);

Allocate and return new config structure filled with the default values. Primarily useful for ffi.

void mgos_uart_config_set_basic_params(struct mgos_uart_config *cfg,
                                       int baud_rate, int num_data_bits,
                                       int parity, int num_stop_bits);

Set baud rate in the provided config structure.

void mgos_uart_config_set_rx_params(struct mgos_uart_config *cfg,
                                    int rx_buf_size, bool rx_fc_ena,
                                    int rx_linger_micros);

Set Rx params in the provided config structure: buffer size rx_buf_size, whether Rx flow control is enabled (rx_fc_ena), and the number of microseconds to linger after Rx fifo is empty (default: 15).

void mgos_uart_config_set_tx_params(struct mgos_uart_config *cfg,
                                    int tx_buf_size, bool tx_fc_ena);

Set Tx params in the provided config structure: buffer size tx_buf_size and whether Tx flow control is enabled (tx_fc_ena).

JAVASCRIPT API Reference api_uart.js

load("api_uart.js");

UART API. Source C API is defined at: mgos_uart.h


UART.setConfig(uartNo, param)

Set UART config. param is an object with the following optional fields:

  • baudRate: baud rate, integer, default: 115200;
  • numDataBits: Number of data bits, default: 8;
  • parity: Parity: 0 - none, 1 - even, 2 - odd; default: none;
  • numStopBits: Number of stop bits: 1 - 1 bit, 2 - 2 bits, 3 - 1.5; default: 1;
  • rxBufSize: size of the Rx buffer, integer, default: 256;
  • rxFlowControl: whether Rx flow control (RTS pin) is enabled, boolean, default: false;
  • rxLingerMicros: how many microseconds to linger after Rx fifo is empty, in case more data arrives. Integer, default: 15;
  • txBufSize: size of the Tx buffer, integer, default: 256;
  • txFlowControl: whether Tx flow control (CTS pin) is enabled, boolean, default: false;

Other than that, there are architecture-dependent settings, grouped in the objects named with the architecture name: "esp32", "esp8266", etc.

Settings for esp32:

  esp32: {
     /
       GPIO pin numbers, default values depend on UART.
      
       UART 0: Rx: 3, Tx: 1, CTS: 19, RTS: 22
       UART 1: Rx: 13, Tx: 14, CTS: 15, RTS: 16
       UART 2: Rx: 17, Tx: 25, CTS: 26, RTS: 27
      /
     gpio: {
       rx: number,
       tx: number,
       cts: number,
       rts: number,
     },

     / Hardware FIFO tweaks /
     fifo: {
       /
         A number of bytes in the hardware Rx fifo, should be between 1 and 127.
         How full hardware Rx fifo should be before "rx fifo full" interrupt is
         fired.
        /
       rxFullThresh: number,

       /
         A number of bytes in the hardware Rx fifo, should be more than
         rx_fifo_full_thresh.
        
         How full hardware Rx fifo should be before CTS is deasserted, telling
         the other side to stop sending data.
        /
       rxFcThresh: number,

       /
         Time in uart bit intervals when "rx fifo full" interrupt fires even if
         it's not full enough
        /
       rxAlarm: number,

       /
         A number of bytes in the hardware Tx fifo, should be between 1 and 127.
         When the number of bytes in Tx buffer becomes less than
         tx_fifo_empty_thresh, "tx fifo empty" interrupt fires.
        /
       txEmptyThresh: number,
     },
   }

UART.setDispatcher(uartNo, callback, userdata)

Set UART dispatcher callback which gets invoked when there is a new data in the input buffer or when the space becomes available on the output buffer.

Callback receives the following arguments: (uartNo, userdata).

UART.write(uartNo, data)

Write data to the buffer. Returns number of bytes written.

Example usage: UART.write(1, "foobar"), in this case, 6 bytes will be written.

UART.writeAvail(uartNo)

Return amount of space available in the output buffer.

UART.read(uartNo)

It never blocks, and returns a string containing read data (which will be empty if there's no data available).

UART.readAvail(uartNo)

Return amount of data available in the input buffer.

UART.setRxEnabled(uartNo)

Set whether Rx is enabled.

UART.isRxEnabled(uartNo)

Returns whether Rx is enabled.

UART.flush(uartNo)

Flush the UART output buffer, wait for the data to be sent.