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
-
int
-
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.
-
uint32_t
-
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_event_type_t
宏¶
-
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_2data_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_2data_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_2stop_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_2stop_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_2parity_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_2parity_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_2baudrate
: 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_2baudrate
: 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_2inverse_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_2flow_ctrl
: Hardware flow control moderx_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_2flow_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_2clr_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_2enable_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_2disable_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_2enable
: 1: enable; 0: disablethresh
: 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_2fn
: Interrupt handler function.arg
: parameter for handler functionintr_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_2tx_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_2level
: 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_2level
: 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_2uart_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_2intr_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_2rx_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_2ticks_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_2buffer
: data buffer addresslen
: 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_2src
: data buffer addresssize
: 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_2src
: data buffer addresssize
: data length to sendbrk_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_2buf
: pointer to the buffer.length
: data lengthticks_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 patternchr_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.