UART¶

API Reference¶

Header File¶

esp8266/include/driver/uart.h

Functions¶

esp_err_t uart_set_word_length(uart_port_t uart_num, uart_word_length_t data_bit)¶

Set UART data bits.

Return

ESP_OK success
ESP_ERR_INVALID_ARG Parameter error

Parameters

uart_num: Uart port number.
data_bit: Uart data bits.

esp_err_t uart_get_word_length(uart_port_t uart_num, uart_word_length_t *data_bit)¶

Get UART data bits.

Return

ESP_OK success
ESP_ERR_INVALID_ARG Parameter error

Parameters

uart_num: Uart port number.
data_bit: Pointer to accept value of UART data bits.

esp_err_t uart_set_stop_bits(uart_port_t uart_num, uart_stop_bits_t stop_bits)¶

Set UART stop bits.

Return

ESP_OK success
ESP_ERR_INVALID_ARG Parameter error

Parameters

uart_num: Uart port number
stop_bits: Uart stop bits

esp_err_t uart_get_stop_bits(uart_port_t uart_num, uart_stop_bits_t *stop_bits)¶

Get UART stop bits.

Return

ESP_OK success
ESP_ERR_INVALID_ARG Parameter error

Parameters

uart_num: Uart port number.
stop_bits: Pointer to accept value of UART stop bits.

esp_err_t uart_set_parity(uart_port_t uart_num, uart_parity_t parity_mode)¶

Set UART parity mode.

Return

ESP_OK success
ESP_ERR_INVALID_ARG Parameter error

Parameters

uart_num: Uart port number.
parity_mode: The enum of uart parity configuration.

esp_err_t uart_get_parity(uart_port_t uart_num, uart_parity_t *parity_mode)¶

Get UART parity mode.

Return

ESP_OK success
ESP_ERR_INVALID_ARG Parameter error

Parameters

uart_num: Uart port number
parity_mode: Pointer to accept value of UART parity mode.

esp_err_t uart_set_baudrate(uart_port_t uart_num, uint32_t baudrate)¶

Set UART baud rate.

Return

ESP_OK success
ESP_ERR_INVALID_ARG Parameter error

Parameters

uart_num: Uart port number
baudrate: UART baud rate.

esp_err_t uart_get_baudrate(uart_port_t uart_num, uint32_t *baudrate)¶

Get UART baud rate.

Return

ESP_OK success
ESP_ERR_INVALID_ARG Parameter error

Parameters

uart_num: Uart port number.
baudrate: Pointer to accept value of Uart baud rate.

esp_err_t uart_set_line_inverse(uart_port_t uart_num, uint32_t inverse_mask)¶

Set UART line inverse mode.

Return

ESP_OK success
ESP_ERR_INVALID_ARG Parameter error

Parameters

uart_num: UART_NUM_0
inverse_mask: Choose the wires that need to be inverted. Inverse_mask should be chosen from UART_INVERSE_RXD / UART_INVERSE_TXD / UART_INVERSE_RTS / UART_INVERSE_CTS, combined with OR operation.

esp_err_t uart_set_hw_flow_ctrl(uart_port_t uart_num, uart_hw_flowcontrol_t flow_ctrl, uint8_t rx_thresh)¶

Configure Hardware flow control.

Return

ESP_OK success
ESP_ERR_INVALID_ARG Parameter error

Parameters

uart_num: Uart port number.
flow_ctrl: Hardware flow control mode.
rx_thresh: Threshold of Hardware flow control.

esp_err_t uart_get_hw_flow_ctrl(uart_port_t uart_num, uart_hw_flowcontrol_t *flow_ctrl)¶

Get hardware flow control mode.

Return

ESP_OK Success, result will be put in (*flow_ctrl)
ESP_ERR_INVALID_ARG Parameter error

Parameters

uart_num: Uart port number.
flow_ctrl: Option for different flow control mode.

esp_err_t uart_enable_swap(void)¶

UART0 swap. Use MTCK as UART0 RX, MTDO as UART0 TX, so ROM log will not output from this new UART0. We also need to use MTDO (U0RTS) and MTCK (U0CTS) as UART0 in hardware.

Return

ESP_OK Success

esp_err_t uart_disable_swap(void)¶

Disable UART0 swap. Use the original UART0, not MTCK and MTDO.

Return

ESP_OK Success

esp_err_t uart_clear_intr_status(uart_port_t uart_num, uint32_t mask)¶

Clear uart interrupts status.

Return

ESP_OK success
ESP_ERR_INVALID_ARG Parameter error

Parameters

uart_num: Uart port number.
mask: Uart interrupt bits mask.

esp_err_t uart_enable_intr_mask(uart_port_t uart_num, uint32_t enable_mask)¶

Set UART interrupt enable.

Return

ESP_OK Success
ESP_ERR_INVALID_ARG Parameter error

Parameters

uart_num: Uart port number
enable_mask: Bit mask of the enable bits. The bit mask should be composed from the fields of register UART_INT_ENA_REG.

esp_err_t uart_disable_intr_mask(uart_port_t uart_num, uint32_t disable_mask)¶

Clear UART interrupt enable bits.

Return

ESP_OK Success
ESP_ERR_INVALID_ARG Parameter error

Parameters

uart_num: Uart port number
disable_mask: Bit mask of the disable bits. The bit mask should be composed from the fields of register UART_INT_ENA_REG.

esp_err_t uart_enable_rx_intr(uart_port_t uart_num)¶

Enable UART RX interrupt (RX_FULL & RX_TIMEOUT INTERRUPT)

Return

ESP_OK Success
ESP_ERR_INVALID_ARG Parameter error

Parameters

uart_num: UART_NUM_0

esp_err_t uart_disable_rx_intr(uart_port_t uart_num)¶

Disable UART RX interrupt (RX_FULL & RX_TIMEOUT INTERRUPT)

Return

ESP_OK Success
ESP_ERR_INVALID_ARG Parameter error

Parameters

uart_num: UART_NUM_0

esp_err_t uart_disable_tx_intr(uart_port_t uart_num)¶

Disable UART TX interrupt (TX_FULL & TX_TIMEOUT INTERRUPT)

Return

ESP_OK Success
ESP_ERR_INVALID_ARG Parameter error

Parameters

uart_num: UART_NUM_0

esp_err_t uart_enable_tx_intr(uart_port_t uart_num, int enable, int thresh)¶

Enable UART TX interrupt (TX_FULL & TX_TIMEOUT INTERRUPT)

Return

ESP_OK Success
ESP_ERR_INVALID_ARG Parameter error

Parameters

uart_num: UART_NUM_0
enable: 1: enable; 0: disable
thresh: Threshold of TX interrupt, 0 ~ UART_FIFO_LEN

esp_err_t uart_isr_register(uart_port_t uart_num, void (*fn)(void *), void *arg, )¶

Register UART interrupt handler (ISR).

Return

ESP_OK Success
ESP_ERR_INVALID_ARG Parameter error

Parameters

uart_num: UART_NUM_0
fn: Interrupt handler function.
arg: parameter for handler function

esp_err_t uart_param_config(uart_port_t uart_num, uart_config_t *uart_conf)¶

Config Common parameters of serial ports.

Return

ESP_OK success
ESP_ERR_INVALID_ARG Parameter error

Parameters

uart_num: Uart port number.
uart_conf: Uart config parameters.

esp_err_t uart_intr_config(uart_port_t uart_num, uart_intr_config_t *uart_intr_conf)¶

Config types of uarts.

Return

ESP_OK success
ESP_ERR_INVALID_ARG Parameter error

Parameters

uart_num: Uart port number.
uart_intr_conf: Uart interrupt config parameters.

esp_err_t uart_driver_install(uart_port_t uart_num, int rx_buffer_size, int tx_buffer_size, int queue_size, QueueHandle_t *uart_queue, int no_use)¶

Install UART driver.

Note

Rx_buffer_size should be greater than UART_FIFO_LEN. Tx_buffer_size should be either zero or greater than UART_FIFO_LEN.

Return

ESP_OK Success
ESP_ERR_INVALID_ARG Parameter error

Parameters

uart_num: Uart port number.
rx_buffer_size: UART RX ring buffer size.
tx_buffer_size: UART TX ring buffer size. If set to zero, driver will not use TX buffer, TX function will block task until all data have been sent out.
queue_size: UART event queue size/depth.
uart_queue: UART event queue handle (out param). On success, a new queue handle is written here to provide access to UART events. If set to NULL, driver will not use an event queue.
no_use: Invalid parameters, just to fit some modules.

esp_err_t uart_driver_delete(uart_port_t uart_num)¶

Uninstall UART driver.

Return

ESP_OK Success
ESP_ERR_INVALID_ARG Parameter error

Parameters

uart_num: Uart port number.

esp_err_t uart_wait_tx_done(uart_port_t uart_num, TickType_t ticks_to_wait)¶

Waiting for the last byte of data to be sent.

Return

ESP_OK Success
ESP_ERR_INVALID_ARG Parameter error

Parameters

uart_num: Uart port number.
ticks_to_wait: Timeout, count in RTOS ticks

int uart_tx_chars(uart_port_t uart_num, const char *buffer, uint32_t len)¶

Send data to the UART port from a given buffer and length.

This function will not wait for enough space in TX FIFO. It will just fill the available TX FIFO and return when the FIFO is full.

Note

This function should only be used when UART TX buffer is not enabled.

Return

(-1) Parameter error
OTHERS (>=0) The number of bytes pushed to the TX FIFO

Parameters

uart_num: Uart port number.
buffer: data buffer address
len: data length to send

int uart_write_bytes(uart_port_t uart_num, const char *src, size_t size)¶

Send data to the UART port from a given buffer and length,.

If the UART driver’s parameter ‘tx_buffer_size’ is set to zero: This function will not return until all the data have been sent out, or at least pushed into TX FIFO.

Otherwise, if the ‘tx_buffer_size’ > 0, this function will return after copying all the data to tx ring buffer, UART ISR will then move data from the ring buffer to TX FIFO gradually.

Return

(-1) Parameter error
OTHERS (>=0) The number of bytes pushed to the TX FIFO

Parameters

uart_num: Uart port number.
src: data buffer address
size: data length to send

int uart_read_bytes(uart_port_t uart_num, uint8_t *buf, uint32_t length, TickType_t ticks_to_wait)¶

UART read bytes from UART buffer.

Return

(-1) Error
OTHERS (>=0) The number of bytes read from UART FIFO

Parameters

uart_num: Uart port number.
buf: pointer to the buffer.
length: data length
ticks_to_wait: sTimeout, count in RTOS ticks

esp_err_t uart_flush(uart_port_t uart_num)¶

Alias of uart_flush_input. UART ring buffer flush. This will discard all data in the UART RX buffer.

Note

Instead of waiting the data sent out, this function will clear UART rx buffer. In order to send all the data in tx FIFO, we can use uart_wait_tx_done function.

Return

ESP_OK Success
ESP_ERR_INVALID_ARG Parameter error

Parameters

uart_num: UART port number.

esp_err_t uart_flush_input(uart_port_t uart_num)¶

Clear input buffer, discard all the data is in the ring-buffer.

Note

In order to send all the data in tx FIFO, we can use uart_wait_tx_done function.

Return

ESP_OK Success
ESP_ERR_INVALID_ARG Parameter error

Parameters

uart_num: UART port number.

esp_err_t uart_get_buffered_data_len(uart_port_t uart_num, size_t *size)¶

UART get RX ring buffer cached data length.

Return

ESP_OK Success
ESP_ERR_INVALID_ARG Parameter error

Parameters

uart_num: UART port number.
size: Pointer of size_t to accept cached data length

esp_err_t uart_set_rx_timeout(uart_port_t uart_num, const uint8_t tout_thresh)¶

UART set threshold timeout for TOUT feature.

Return

ESP_OK Success
ESP_ERR_INVALID_ARG Parameter error

Parameters

uart_num: Uart number to configure
tout_thresh: This parameter defines timeout threshold in uart symbol periods. The maximum value of threshold is 126. tout_thresh = 1, defines TOUT interrupt timeout equal to transmission time of one symbol (~11 bit) on current baudrate. If the time is expired the UART_RXFIFO_TOUT_INT interrupt is triggered. If tout_thresh == 0, the TOUT feature is disabled.

bool uart_is_driver_installed(uart_port_t uart_num)¶

Checks whether the driver is installed or not.

Return

true driver is installed
false driver is not installed

Parameters

uart_num: UART port number, the max port number is (UART_NUM_MAX -1).

Structures¶

struct uart_config_t¶

UART configuration parameters for uart_param_config function.

Public Members

int baud_rate¶: UART baud rate

uart_word_length_t data_bits¶: UART byte size

uart_parity_t parity¶: UART parity mode

uart_stop_bits_t stop_bits¶: UART stop bits

uart_hw_flowcontrol_t flow_ctrl¶: UART HW flow control mode (cts/rts)

uint8_t rx_flow_ctrl_thresh¶: UART HW RTS threshold

struct uart_intr_config_t¶

UART interrupt configuration parameters for uart_intr_config function.

Public Members

uint32_t intr_enable_mask¶: UART interrupt enable mask, choose from UART_XXXX_INT_ENA_M under UART_INT_ENA_REG(i), connect with bit-or operator

uint8_t rx_timeout_thresh¶: UART timeout interrupt threshold (unit: time of sending one byte)

uint8_t txfifo_empty_intr_thresh¶: UART TX empty interrupt threshold.

uint8_t rxfifo_full_thresh¶: UART RX full interrupt threshold.

struct uart_event_t¶

Event structure used in UART event queue.

Public Members

uart_event_type_t type¶: UART event type

size_t size¶: UART data size for UART_DATA event

Macros¶

UART_FIFO_LEN¶: Length of the hardware FIFO buffers

UART_INTR_MASK¶: Mask of all UART interrupts

UART_LINE_INV_MASK¶: TBD

UART_INVERSE_DISABLE¶: Disable UART signal inverse

UART_INVERSE_RXD¶: UART RXD input inverse

UART_INVERSE_CTS¶: UART CTS input inverse

UART_INVERSE_TXD¶: UART TXD output inverse

UART_INVERSE_RTS¶: UART RTS output inverse

Enumerations¶

enum uart_mode_t¶

UART mode selection.

Values:

UART_MODE_UART = 0x00¶: mode: regular UART mode

enum uart_word_length_t¶

UART word length constants.

Values:

UART_DATA_5_BITS = 0x0¶: word length: 5bits

UART_DATA_6_BITS = 0x1¶: word length: 6bits

UART_DATA_7_BITS = 0x2¶: word length: 7bits

UART_DATA_8_BITS = 0x3¶: word length: 8bits

UART_DATA_BITS_MAX = 0x4¶

enum uart_stop_bits_t¶

UART stop bits number.

Values:

UART_STOP_BITS_1 = 0x1¶: stop bit: 1bit

UART_STOP_BITS_1_5 = 0x2¶: stop bit: 1.5bits

UART_STOP_BITS_2 = 0x3¶: stop bit: 2bits

UART_STOP_BITS_MAX = 0x4¶

enum uart_port_t¶

UART peripheral number.

Values:

UART_NUM_0 = 0x0¶

UART_NUM_1 = 0x1¶

UART_NUM_MAX¶

enum uart_parity_t¶

UART parity constants.

Values:

UART_PARITY_DISABLE = 0x0¶: Disable UART parity

UART_PARITY_EVEN = 0x2¶: Enable UART even parity

UART_PARITY_ODD = 0x3¶: Enable UART odd parity

enum uart_hw_flowcontrol_t¶

UART hardware flow control modes.

Values:

UART_HW_FLOWCTRL_DISABLE = 0x0¶: disable hardware flow control

UART_HW_FLOWCTRL_RTS = 0x1¶: enable RX hardware flow control (rts)

UART_HW_FLOWCTRL_CTS = 0x2¶: enable TX hardware flow control (cts)

UART_HW_FLOWCTRL_CTS_RTS = 0x3¶: enable hardware flow control

UART_HW_FLOWCTRL_MAX = 0x4¶

enum uart_event_type_t¶

UART event types used in the ring buffer.

Values:

UART_DATA¶: UART data event

UART_BUFFER_FULL¶: UART RX buffer full event

UART_FIFO_OVF¶: UART FIFO overflow event

UART_FRAME_ERR¶: UART RX frame error event

UART_PARITY_ERR¶: UART RX parity event

UART_EVENT_MAX¶: UART event max index