UART Controller

Data Structures
struct	uartd_config_t
	UART device configuration structure. More...

Functions
esp_err_t	uartd_init (uartd_config_t *restrict cfg)
	Initialize an UART controller.
esp_err_t	uartd_deinit (uartd_config_t *restrict cfg)
	Deinitialize a UART device.
uartd_config_t	uartd_default_config (void)
	Get a default UART configuration to drive the UART1 controller.
esp_err_t	uartd_wait_event (const uartd_config_t *cfg, uart_event_t *event, TickType_t timeout)
	Wait for an UART event.
esp_err_t	uartd_read (const uartd_config_t *const restrict cfg, void *restrict buf, size_t sz, size_t len, TickType_t timeout, size_t *out_bytes)
	Read raw data from UART.
esp_err_t	uartd_write (const uartd_config_t *const restrict cfg, const void *const restrict buf, size_t sz, size_t len, size_t *out_bytes)
	Write raw data to UART.
esp_err_t	uartd_readline (const uartd_config_t *const restrict cfg, char *restrict line, size_t max_len, TickType_t timeout, size_t *out_len)
	Read up to a newline-terminated string from UART.
esp_err_t	uartd_writeline (const uartd_config_t *const restrict cfg, const char *const restrict line, size_t *out_len)
	Write a null-terminated line to UART.

Default UART1 Controller Configuration
Default parameters for UART communication on the UART1 controller.
#define	DEFAULT_TX   (23)
	Default TX GPIO.
#define	DEFAULT_RX   (22)
	Default RX GPIO.
#define	DEFAULT_CTS   (20)
	Default CTS GPIO.
#define	DEFAULT_RTS   (21)
	Default RTS GPIO.
#define	DEFAULT_BAUDRATE   (115200)
	Default baud rate.
#define	DEFAULT_BUF_SIZE   (2028)
	Default RX/TX buffer size.
#define	DEFAULT_CTRL_TRESH   (122)
	Default flow control threshold.
#define	DEFAULT_EVT_QUEUE_SIZE   (10)
	Default UART event queue size.

Detailed Description

Copyright

Copyright (c) 2026 Adrien Chevrier. Under AGPL-3.0-or-later license.

High-level UART controller driver for ESP-IDF.

---

Data Structure Documentation

uartd_config_t

struct uartd_config_t

UART device configuration structure.

Holds all parameters required to configure and operate an UART controller.

Data Fields
uint32_t	baudrate	UART baud rate.
uint8_t	cts_pin	CTS GPIO pin.
QueueHandle_t	evt_queue	UART event queue handle.
size_t	evt_queue_size	UART event queue size.
bool	flow_ctrl	Enable hardware flow control.
uart_port_t	port	UART port number.
uint8_t	rts_pin	RTS GPIO pin.
size_t	rx_buf_size	RX buffer size.
uint8_t	rx_pin	RX GPIO pin.
const char *const	TAG	Logging tag.
size_t	tx_buf_size	TX buffer size.
uint8_t	tx_pin	TX GPIO pin.

Macro Definition Documentation

DEFAULT_BAUDRATE

#define DEFAULT_BAUDRATE   (115200)

Default baud rate.

DEFAULT_BUF_SIZE

#define DEFAULT_BUF_SIZE   (2028)

Default RX/TX buffer size.

DEFAULT_CTRL_TRESH

#define DEFAULT_CTRL_TRESH   (122)

Default flow control threshold.

DEFAULT_CTS

#define DEFAULT_CTS   (20)

Default CTS GPIO.

DEFAULT_EVT_QUEUE_SIZE

#define DEFAULT_EVT_QUEUE_SIZE   (10)

Default UART event queue size.

DEFAULT_RTS

#define DEFAULT_RTS   (21)

Default RTS GPIO.

DEFAULT_RX

#define DEFAULT_RX   (22)

Default RX GPIO.

DEFAULT_TX

#define DEFAULT_TX   (23)

Default TX GPIO.

Function Documentation

uartd_default_config()

uartd_config_t uartd_default_config

(

void

)

Get a default UART configuration to drive the UART1 controller.

See also

Default UART1 Controller Configuration for details.

Returns

A uartd_config_t structure with default parameters.

uartd_deinit()

esp_err_t uartd_deinit

(

uartd_config_t *restrict

cfg

)

Deinitialize a UART device.

The following steps are performed:

• Flushing the TX buffer.
• Deleting the UART controller.
• Releasing any allocated resources.

Parameters

[in,out]

cfg

UART device configuration structure.

Return values

ESP_OK	On success.
ESP_ERR_INVALID_ARG	If cfg is NULL.
ESP_ERR_TIMEOUT	Timeout while trying to flush the TX buffer.
ESP_FAIL	On failure.

Warning

This function must run inside a critical section.

uartd_init()

esp_err_t uartd_init

(

uartd_config_t *restrict

cfg

)

Initialize an UART controller.

The following steps are performed:

• Initializing the UART controller.
• Installing the UART driver.
• Applying the given UART configuration.

Parameters

[in,out]

cfg

UART device configuration structure.

Return values

ESP_OK	On success.
ESP_ERR_INVALID_ARG	If cfg is NULL.
ESP_FAIL	On failure.

Warning

This function must run inside a critical section.

uartd_read()

esp_err_t uartd_read	(	const uartd_config_t *const restrict	cfg,
		void *restrict	buf,
		size_t	sz,
		size_t	len,
		TickType_t	timeout,
		size_t *	out_bytes )

Read raw data from UART.

Reads up to len elements of size sz into the provided buffer.

See also

uart_read_bytes() from ESP-IDF for detailed behaviour.

Parameters

[in]	cfg	UART device configuration.
[out]	buf	Destination buffer.
[in]	sz	Size of each element in bytes.
[in]	len	Number of elements to read.
[in]	timeout	Read timeout in RTOS ticks.
[out]	out_bytes	Number of bytes actually read.

Return values

ESP_OK	On success.
ESP_ERR_INVALID_ARG	Any parameter is NULL.
ESP_FAIL	Failed to read bytes.

uartd_readline()

esp_err_t uartd_readline	(	const uartd_config_t *const restrict	cfg,
		char *restrict	line,
		size_t	max_len,
		TickType_t	timeout,
		size_t *	out_len )

Read up to a newline-terminated string from UART.

Reads characters until a newline is received or the buffer is full.

See also

uart_read_bytes() from ESP-IDF for detailed behaviour.

Note

Replaces any newline or carriage return character with a null terminator.

Parameters

[in]	cfg	UART device configuration.
[out]	line	Buffer to store the received line.
[in]	max_len	Maximum buffer length.
[in]	timeout	Timeout in RTOS ticks.
[out]	out_len	Number of bytes read.

Return values

ESP_OK	On success.
ESP_ERR_INVALID_ARG	Any parameter is NULL or max_len is < 2.
ESP_FAIL	Failed to read bytes.

uartd_wait_event()

esp_err_t uartd_wait_event	(	const uartd_config_t *	cfg,
		uart_event_t *	event,
		TickType_t	timeout )

Wait for an UART event.

Blocks until an UART event is received or the timeout expires.

Parameters

[in]	cfg	UART device configuration.
[out]	event	Pointer to store the received UART event.
[in]	timeout	Timeout in RTOS ticks.

Return values

ESP_OK	On success.
ESP_ERR_INVALID_ARG	Any parameter is NULL.
ESP_ERR_TIMEOUT	On timeout.

uartd_write()

esp_err_t uartd_write	(	const uartd_config_t *const restrict	cfg,
		const void *const restrict	buf,
		size_t	sz,
		size_t	len,
		size_t *	out_bytes )

Write raw data to UART.

Writes up to len elements of size sz from the provided buffer.

See also

uart_write_bytes() from ESP-IDF for detailed behaviour.

Parameters

[in]	cfg	UART device configuration.
[in]	buf	Source buffer.
[in]	sz	Size of each element in bytes.
[in]	len	Number of elements to write.
[out]	out_bytes	Number of bytes actually written.

Return values

ESP_OK	On success.
ESP_ERR_INVALID_ARG	Any parameter is NULL / equal to 0.
ESP_FAIL	Failed to write bytes.

uartd_writeline()

esp_err_t uartd_writeline	(	const uartd_config_t *const restrict	cfg,
		const char *const restrict	line,
		size_t *	out_len )

Write a null-terminated line to UART.

Writes the provided string.

Note

No newline character is added to the string.

See also

uart_write_bytes() from ESP-IDF for detailed behaviour.

Parameters

[in]	cfg	UART device configuration.
[in]	line	Null-terminated string to write.
[out]	out_len	Number of bytes written.

Return values

ESP_OK	On success.
ESP_ERR_INVALID_ARG	Any parameter is NULL.
ESP_FAIL	Failed to write bytes.