UART

应用程序示例

Configure uart settings and install uart driver to read/write using UART0 and UART1 interfaces: peripherals/uart.

API 参考手册

Data 结构体

struct uart_config_t

UART configuration parameters for uart_param_config function.

Public Members

int baud_rate

UART baudrate

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

宏

UART_FIFO_LEN

Length of the hardware FIFO buffers

UART_INTR_MASK

mask of all UART interrupts

UART_LINE_INV_MASK

TBD

UART_BITRATE_MAX

Max bit rate supported by UART

UART_PIN_NO_CHANGE

Constant for uart_set_pin function which indicates that UART pin should not be changed

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

枚举

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 base address 0x3ff40000

UART_NUM_1 = 0x1

UART base address 0x3ff50000

UART_NUM_2 = 0x2

UART base address 0x3ff6E000

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 ringbuffer.

Values:

UART_DATA

UART data event

UART_BREAK

UART break 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_DATA_BREAK

UART TX data and break event

UART_EVENT_MAX

UART event max index

UART_PATTERN_DET

UART pattern detected

函数

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_FAIL Parameter error
Parameters
  • uart_num: UART_NUM_0, UART_NUM_1 or UART_NUM_2
  • 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_FAIL Parameter error
  • ESP_OK Success, result will be put in (*data_bit)
Parameters
  • uart_num: UART_NUM_0, UART_NUM_1 or UART_NUM_2
  • 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_FAIL Fail
Parameters
  • uart_num: UART_NUM_0, UART_NUM_1 or UART_NUM_2
  • stop_bits: UART stop bits

esp_err_t uart_get_stop_bits(uart_port_t uart_num, uart_stop_bits_t *stop_bits)

Set UART stop bits.

Return
  • ESP_FAIL Parameter error
  • ESP_OK Success, result will be put in (*stop_bit)
Parameters
  • uart_num: UART_NUM_0, UART_NUM_1 or UART_NUM_2
  • 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.

Return
  • ESP_FAIL Parameter error
  • ESP_OK Success
Parameters
  • uart_num: UART_NUM_0, UART_NUM_1 or UART_NUM_2
  • 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_FAIL Parameter error
  • ESP_OK Success, result will be put in (*parity_mode)
Parameters
  • uart_num: UART_NUM_0, UART_NUM_1 or UART_NUM_2
  • 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_FAIL Parameter error
  • ESP_OK Success
Parameters
  • uart_num: UART_NUM_0, UART_NUM_1 or UART_NUM_2
  • baudrate: UART baud rate.

esp_err_t uart_get_baudrate(uart_port_t uart_num, uint32_t *baudrate)

Get UART bit-rate.

Return
  • ESP_FAIL Parameter error
  • ESP_OK Success, result will be put in (*baudrate)
Parameters
  • uart_num: UART_NUM_0, UART_NUM_1 or UART_NUM_2
  • 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_FAIL Parameter error
Parameters
  • uart_num: UART_NUM_0, UART_NUM_1 or UART_NUM_2
  • 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, combine 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)

Set hardware flow control.

Return
  • ESP_OK Success
  • ESP_FAIL Parameter error
Parameters
  • uart_num: UART_NUM_0, UART_NUM_1 or UART_NUM_2
  • flow_ctrl: Hardware flow control mode
  • rx_thresh: Threshold of Hardware RX flow control(0 ~ UART_FIFO_LEN). Only when UART_HW_FLOWCTRL_RTS is set, will the rx_thresh value be set.

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_FAIL Parameter error
  • ESP_OK Success, result will be put in (*flow_ctrl)
Parameters
  • uart_num: UART_NUM_0, UART_NUM_1 or UART_NUM_2
  • flow_ctrl: Option for different flow control mode.

esp_err_t uart_clear_intr_status(uart_port_t uart_num, uint32_t clr_mask)

Clear UART interrupt status.

Return
  • ESP_OK Success
  • ESP_FAIL Parameter error
Parameters
  • uart_num: UART_NUM_0, UART_NUM_1 or UART_NUM_2
  • clr_mask: Bit mask of the status that to be cleared. enable_mask should be chosen from the fields of register UART_INT_CLR_REG.

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_FAIL Parameter error
Parameters
  • uart_num: UART_NUM_0, UART_NUM_1 or UART_NUM_2
  • enable_mask: Bit mask of the enable bits. enable_mask should be chosen 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_FAIL Parameter error
Parameters
  • uart_num: UART_NUM_0, UART_NUM_1 or UART_NUM_2
  • disable_mask: Bit mask of the disable bits. disable_mask should be chosen 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_FAIL Parameter error
Parameters
  • uart_num: UART_NUM_0, UART_NUM_1 or UART_NUM_2

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_FAIL Parameter error
Parameters
  • uart_num: UART_NUM_0, UART_NUM_1 or UART_NUM_2

esp_err_t uart_disable_tx_intr(uart_port_t uart_num)

Disable UART TX interrupt(RX_FULL & RX_TIMEOUT INTERRUPT)

Return
  • ESP_OK Success
  • ESP_FAIL Parameter error
Parameters
  • uart_num: UART_NUM_0, UART_NUM_1 or UART_NUM_2

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

Enable UART TX interrupt(RX_FULL & RX_TIMEOUT INTERRUPT)

Return
  • ESP_OK Success
  • ESP_FAIL Parameter error
Parameters
  • uart_num: UART_NUM_0, UART_NUM_1 or UART_NUM_2
  • 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, int intr_alloc_flags, uart_isr_handle_t *handle, )

register UART interrupt handler(ISR).

Note
UART ISR handler will be attached to the same CPU core that this function is running on.
Return
  • ESP_OK Success
  • ESP_FAIL Parameter error
Parameters
  • uart_num: UART_NUM_0, UART_NUM_1 or UART_NUM_2
  • fn: Interrupt handler function.
  • arg: parameter for handler function
  • intr_alloc_flags: Flags used to allocate the interrupt. One or multiple (ORred) ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info.
  • handle: Pointer to return handle. If non-NULL, a handle for the interrupt will be returned here.

esp_err_t uart_set_pin(uart_port_t uart_num, int tx_io_num, int rx_io_num, int rts_io_num, int cts_io_num)

Set UART pin number.

Note
Internal signal can be output to multiple GPIO pads. Only one GPIO pad can connect with input signal.
Return
  • ESP_OK Success
  • ESP_FAIL Parameter error
Parameters
  • uart_num: UART_NUM_0, UART_NUM_1 or UART_NUM_2
  • tx_io_num: UART TX pin GPIO number, if set to UART_PIN_NO_CHANGE, use the current pin.
  • rx_io_num: UART RX pin GPIO number, if set to UART_PIN_NO_CHANGE, use the current pin.
  • rts_io_num: UART RTS pin GPIO number, if set to UART_PIN_NO_CHANGE, use the current pin.
  • cts_io_num: UART CTS pin GPIO number, if set to UART_PIN_NO_CHANGE, use the current pin.

esp_err_t uart_set_rts(uart_port_t uart_num, int level)

UART set RTS level (before inverse) UART rx hardware flow control should not be set.

Return
  • ESP_OK Success
  • ESP_FAIL Parameter error
Parameters
  • uart_num: UART_NUM_0, UART_NUM_1 or UART_NUM_2
  • level: 1: RTS output low(active); 0: RTS output high(block)

esp_err_t uart_set_dtr(uart_port_t uart_num, int level)

UART set DTR level (before inverse)

Return
  • ESP_OK Success
  • ESP_FAIL Parameter error
Parameters
  • uart_num: UART_NUM_0, UART_NUM_1 or UART_NUM_2
  • level: 1: DTR output low; 0: DTR output high

esp_err_t uart_param_config(uart_port_t uart_num, const uart_config_t *uart_config)

UART parameter configure.

Return
  • ESP_OK Success
  • ESP_FAIL Parameter error
Parameters
  • uart_num: UART_NUM_0, UART_NUM_1 or UART_NUM_2
  • uart_config: UART parameter settings

esp_err_t uart_intr_config(uart_port_t uart_num, const uart_intr_config_t *intr_conf)

UART interrupt configure.

Return
  • ESP_OK Success
  • ESP_FAIL Parameter error
Parameters
  • uart_num: UART_NUM_0, UART_NUM_1 or UART_NUM_2
  • intr_conf: UART interrupt settings

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 intr_alloc_flags)

Install UART driver.

UART ISR handler will be attached to the same CPU core that this function is running on.

Return
  • ESP_OK Success
  • ESP_FAIL Parameter error
Parameters
  • uart_num: UART_NUM_0, UART_NUM_1 or UART_NUM_2
  • rx_buffer_size: UART RX ring buffer size, rx_buffer_size should be greater than UART_FIFO_LEN.
  • 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.
  • intr_alloc_flags: Flags used to allocate the interrupt. One or multiple (ORred) ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info. Do not set ESP_INTR_FLAG_IRAM here (the driver’s ISR handler is not located in IRAM)

esp_err_t uart_driver_delete(uart_port_t uart_num)

Uninstall UART driver.

Return
  • ESP_OK Success
  • ESP_FAIL Parameter error
Parameters
  • uart_num: UART_NUM_0, UART_NUM_1 or UART_NUM_2

esp_err_t uart_wait_tx_done(uart_port_t uart_num, TickType_t ticks_to_wait)

Wait UART TX FIFO empty.

Return
  • ESP_OK Success
  • ESP_FAIL Parameter error
  • ESP_ERR_TIMEOUT Timeout
Parameters
  • uart_num: UART_NUM_0, UART_NUM_1 or UART_NUM_2
  • 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 the space in TX FIFO, just fill the 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 data that pushed to the TX FIFO
Parameters
  • uart_num: UART_NUM_0, UART_NUM_1 or UART_NUM_2
  • 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 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 tx_buffer_size > 0, this function will return after copying all the data to tx ringbuffer, then, UART ISR will move data from ring buffer to TX FIFO gradually.

Return
  • (-1) Parameter error
  • OTHERS(>=0) The number of data that pushed to the TX FIFO
Parameters
  • uart_num: UART_NUM_0, UART_NUM_1 or UART_NUM_2
  • src: data buffer address
  • size: data length to send

int uart_write_bytes_with_break(uart_port_t uart_num, const char *src, size_t size, int brk_len)

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

If parameter tx_buffer_size is set to zero: This function will not return until all the data and the break signal have been sent out. After all data send out, send a break signal.

Otherwise, if tx_buffer_size > 0, this function will return after copying all the data to tx ringbuffer, then, UART ISR will move data from ring buffer to TX FIFO gradually. After all data send out, send a break signal.

Return
  • (-1) Parameter error
  • OTHERS(>=0) The number of data that pushed to the TX FIFO
Parameters
  • uart_num: UART_NUM_0, UART_NUM_1 or UART_NUM_2
  • src: data buffer address
  • size: data length to send
  • brk_len: break signal length (unit: time of one data bit at current_baudrate)

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 return a char data from uart fifo.
Parameters
  • uart_num: UART_NUM_0, UART_NUM_1 or UART_NUM_2
  • 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)

UART ring buffer flush.

Return
  • ESP_OK Success
  • ESP_FAIL Parameter error
Parameters
  • uart_num: UART_NUM_0, UART_NUM_1 or UART_NUM_2

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_FAIL Parameter error
Parameters
  • uart_num: UART port number.
  • size: Pointer of size_t to accept cached data length

esp_err_t uart_disable_pattern_det_intr(uart_port_t uart_num)

UART disable pattern detect function. Designed for applications like ‘AT commands’. When the hardware detect a series of one same character, the interrupt will be triggered.

Return
  • ESP_OK Success
  • ESP_FAIL Parameter error
Parameters
  • uart_num: UART port number.

esp_err_t uart_enable_pattern_det_intr(uart_port_t uart_num, char pattern_chr, uint8_t chr_num, int chr_tout, int post_idle, int pre_idle)

UART enable pattern detect function. Designed for applications like ‘AT commands’. When the hardware detect a series of one same character, the interrupt will be triggered.

Return
  • ESP_OK Success
  • ESP_FAIL Parameter error
Parameters
  • uart_num: UART port number.
  • pattern_chr: character of the pattern
  • chr_num: number of the character, 8bit value.
  • chr_tout: timeout of the interval between each pattern characters, 24bit value, unit is APB(80Mhz) clock cycle.
  • post_idle: idle time after the last pattern character, 24bit value, unit is APB(80Mhz) clock cycle.
  • pre_idle: idle time before the first pattern character, 24bit value, unit is APB(80Mhz) clock cycle.