SOFT-UART library for Mongoose OS

Overview

SOFT-UART library for Mongoose OS.

💡 This library is strongly optimized and it uses interrupts and hardware timers to do not block CPU while receiving data.

Use this library to add new (software) UART ports, in addition to the hardware ones, on the MCUs listed in the table below.

MCU	SOFT-UART0 (Rx/Tx pins)	SOFT-UART1	Notes
ESP8266	13/15	--
ESP32	--	--	Not yet tested.

Configuration

The library adds the soft_uart section to the device configuration:

{
  "port":                       // SOFT-UART0 port settings
  {
    "rx_gpio_pin": ,            // Default Rx pin
    "rx_gpio_pull_up": true,    // True if Rx GPIO is pulled up
    "tx_gpio_pin": ,            // Default Tx pin
  }
}

C/C++ APIs Reference

mgos_soft_uart_config

struct mgos_soft_uart_config {
  int baud_rate;
  int num_data_bits;
  enum mgos_uart_parity parity;
  enum mgos_uart_stop_bits stop_bits;
  int rx_buf_size;
  int tx_buf_size;
};

UART configuration parameters.

Field
baud_rate	Baud rate. Default: 9600.
num_data_bits	Number of data bits, 5-8. Default: 8.
parity	Parity. Default: MGOS_UART_PARITY_NONE.
stop_bits	Number of stop bits. Default: MGOS_UART_STOP_BITS_1. Value MGOS_UART_STOP_BITS_1_5 is not supported.
rx_buf_size	Size of the Rx buffer. Default: 256.
tx_buf_size	Size of the Tx buffer. Default: 256.

mgos_soft_uart_configure

bool mgos_soft_uart_configure(int uart_no, const struct mgos_soft_uart_config *cfg);

Apply given SOFT-UART configuration. Returns true if success, otherwise false.

Parameter
uart_no	SOFT-UART number.
cfg	Config structure.

⚠️ Stop bit value 1.5 is not supported.

Example:

#include "mgos_soft_uart.h"

int uart_no = 0;
struct mgos_soft_uart_config ucfg;
mgos_soft_uart_config_set_defaults(uart_no, &ucfg);

ucfg.baud_rate = 9600;
ucfg.rx_buf_size = 1500;
ucfg.tx_buf_size = 1500;

if (!mgos_soft_uart_configure(uart_no, &ucfg)) {
  LOG(LL_ERROR, ("Failed to configure SOFT-UART%d", uart_no));
}

mgos_soft_uart_config_set_defaults

void mgos_soft_uart_config_set_defaults(int uart_no, struct mgos_soft_uart_config *cfg);

Fill provided cfg structure with the default values. See example above.

Parameter
uart_no	SOFT-UART number.
cfg	Config structure.

mgos_soft_uart_config_get

bool mgos_soft_uart_config_get(int uart_no, struct mgos_soft_uart_config *cfg);

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

Parameter
uart_no	SOFT-UART number.
cfg	Config structure.

mgos_soft_uart_set_dispatcher

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

Set SOFT-UART dispatcher: a callback which gets called when there is data in the input buffer or space available in the output buffer.

Parameter
uart_no	SOFT-UART number.
cb	Dispatcher's callback.
arg	Callback arguments or NULL.

mgos_soft_uart_read

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

Read data from SOFT-UART input buffer. Note: unlike write, read will not block if there are not enough bytes in the input buffer.

Parameter
uart_no	SOFT-UART number.
buf	Buffer.
len	Len of the buffer.

mgos_soft_uart_read_mbuf

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

Like mgos_soft_uart_read(), but reads into an mbuf.

Parameter
uart_no	SOFT-UART number.
buf	mbuf pointer.
len	Len of the buffer.

mgos_soft_uart_read_avail

size_t mgos_soft_uart_read_avail(int uart_no);

Returns the number of bytes available for reading.

Parameter
uart_no	SOFT-UART number.

mgos_soft_uart_set_rx_enabled

bool mgos_soft_uart_set_rx_enabled(int uart_no, bool enabled);

Controls whether SOFT-UART receiver is enabled. Returns false if error.

Parameter
uart_no	SOFT-UART number.
enabled	true to enable Rx.

mgos_soft_uart_is_rx_enabled

bool mgos_soft_uart_is_rx_enabled(int uart_no);

Returns whether SOFT-UART receiver is enabled.

Parameter
uart_no	SOFT-UART number.

mgos_soft_uart_write

size_t mgos_soft_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_soft_uart_write_avail() first.

Parameter
uart_no	SOFT-UART number.
buf	Buffer.
len	Len of the buffer.

mgos_soft_uart_write_avail

size_t mgos_soft_uart_write_avail(int uart_no);

Returns amount of space availabe in the output buffer.

Parameter
uart_no	SOFT-UART number.

mgos_soft_uart_printf

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

Parameter
uart_no	SOFT-UART number.
fmt	String format.
...	String format args.

mgos_soft_uart_flush

void mgos_soft_uart_flush(int uart_no);

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

Parameter
uart_no	SOFT-UART number.

To Do

• Implement javascript APIs for Mongoose OS MJS.
• Test the library on ESP32 and other MCUs.