第一节主要介绍 ESP32-IDF 相关 API,在第二节介绍如何在 ESP32 上使用 USART,第三节为实例演示。
一、基本介绍
API 参考路径
esp-idf/components/esp_driver_uart/include/driver/uart.h
。
1、配置结构体
1.1 uart_config_t
typedef struct {
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*/
union {
uart_sclk_t source_clk; /*!< UART source clock selection */
#if (SOC_UART_LP_NUM >= 1)
lp_uart_sclk_t lp_source_clk; /*!< LP_UART source clock selection */
#endif
};
} uart_config_t;
该结构体用于 USART 初始化设置。
baud_rate
:设置波特率data_bits
:数据位长度parity
:设置校验位模式stop_bits
:设置停止位长度flow_ctrl
:硬件流控制rx_flow_ctrl_thresh
:设置 UART 硬件流控制(RTS/CTS)的阈值。当接收到的数据达到这个阈值时,UART 硬件会自动发送 RTS 信号,请求发送方暂停发送数据,直到接收到的数据被处理完毕。这样可以避免数据溢出,提高数据传输的稳定性。source_clk
:时钟源,见下:
typedef enum {
UART_SCLK_APB = SOC_MOD_CLK_APB, /* 使用 APB 时钟 */
UART_SCLK_REF_TICK = SOC_MOD_CLK_REF_TICK, /* 使用外部时钟 */
UART_SCLK_DEFAULT = SOC_MOD_CLK_APB, /* 默认使用 APB 时钟 */
} soc_periph_uart_clk_src_legacy_t;
1.2 uart_intr_config_t
typedef struct {
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.*/
} uart_intr_config_t;
该结构体用于 USART 中断配置。
intr_enable_mask
:中断使能掩码,通过位运算(如按位或)可以连接多个 UART 中断使能标志,例如,对应于UART_TX
、UART_RX
、UART_ERROR
等不同的中断类型。rx_timeout_thresh
:接收超时阈值,单位为发送一个字节的时间。当在此阈值内没有接收到新数据时,将触发超时中断,用于处理接收操作的超时情况。txfifo_empty_intr_thresh
:发送 FIFO 空中断阈值,指定了 UART 发送 FIFO 缓冲区为空时触发的中断阈值。当 FIFO 中的数据量低于此阈值时,将触发与发送操作相关的中断,可以用于确认数据是否成功发送。rxfifo_full_thresh
:接收 FIFO 满中断阈值,在 FIFO 满的情况下,如果再次接收到数据,将触发接收满中断,用于处理接收数据缓冲区可能溢出的情况。
1.3 uart_event_t
typedef struct {
uart_event_type_t type; /*!< UART event type */
size_t size; /*!< UART data size for UART_DATA event*/
bool timeout_flag; /*!< UART data read timeout flag for UART_DATA event (no new data received during configured RX TOUT)*/
/*!< If the event is caused by FIFO-full interrupt, then there will be no event with the timeout flag before the next byte coming.*/
} uart_event_t;
该结构体用于表示 UART 事件的相关信息。
type
:事件类型size
:存放UART_DATA
事件的有效数据大小timeout_flag
:指示 UART 数据读取是否超时。当接收过程中没有在配置的接收超时时间内接收到新的数据时,这个标志会被设置为 true。如果事件是由 FIFO满中断引起的,则在接下来的字节到达之前不会有带超时标志的事件。
2、常用 API
2.1 驱动相关
2.1.1 uart_driver_install
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)
- 参数
uart_num
:UART 端口号,最大为UART_NUM_MAX - 1
rx_buffer_size
:UART 接收环形缓冲区大小tx_buffer_size
:UART 发送环形缓冲区大小。如果设置为零,驱动程序将不使用 TX 缓冲区,TX 函数将阻塞任务直到所有数据都被发送出去。queue_size
:UART 事件队列大小uart_queue
:UART 事件队列句柄(输出参数)。成功后,此处将写入新的队列句柄以提供访问 UART 事件的权限。如果设置为 NULL,则驱动程序将不使用事件队列。intr_alloc_flags
:分配中断时使用的标志。一个或多个(按位或运算)ESP_INTR_FLAG_*
值(见esp_intr_alloc.h
)。
- 作用
- 安装 UART 驱动并设置 UART 为默认配置。UART ISR 处理器将被附加到与该函数正在运行的相同 CPU 内核上。
- 返回值
ESP_OK
成功ESP_FAIL
参数错误
2.1.2 uart_driver_delete
esp_err_t uart_driver_delete(uart_port_t uart_num)
- 参数
uart_num
:UART 端口号,最大为UART_NUM_MAX - 1
- 作用
- 卸载 UART 驱动。
- 返回值
ESP_OK
成功ESP_FAIL
参数错误
2.1.3 uart_is_driver_installed
bool uart_is_driver_installed(uart_port_t uart_num)
- 参数
uart_num
:UART 端口号,最大为UART_NUM_MAX - 1
- 作用
- 检查是否已安装驱动程序。
- 返回值
- true:驱动程序已安装
- false:驱动程序未安装
2.2 中断相关
2.2.1 uart_clear_intr_status
esp_err_t uart_clear_intr_status(uart_port_t uart_num, uint32_t clr_mask)
- 参数
uart_num
:UART 端口号,最大为UART_NUM_MAX - 1
clr_mask
:中断状态要清除的位掩码。
- 作用
- 清除 UART 中断标志位。
- 返回值
ESP_OK
成功ESP_FAIL
参数错误
2.2.2 uart_enable_intr_mask
esp_err_t uart_enable_intr_mask(uart_port_t uart_num, uint32_t enable_mask)
- 参数
uart_num
:UART 端口号,最大为UART_NUM_MAX - 1
enable_mask
:启动位的位掩码。
- 作用
- 设置 UART 中断标志位。
- 返回值
ESP_OK
成功ESP_FAIL
参数错误
同理,禁用为:
esp_err_t uart_disable_intr_mask(uart_port_t uart_num, uint32_t disable_mask)
2.2.3 uart_enable_rx_intr
esp_err_t uart_enable_rx_intr(uart_port_t uart_num)
- 参数
uart_num
:UART 端口号,最大为UART_NUM_MAX - 1
- 作用
- 使能 UART RX 中断(
RX_FULL
、RX_TIMEOUT
)。
- 使能 UART RX 中断(
- 返回值
ESP_OK
成功ESP_FAIL
参数错误
禁用为:
esp_err_t uart_disable_rx_intr(uart_port_t uart_num)
2.2.5 uart_enable_tx_intr
esp_err_t uart_enable_tx_intr(uart_port_t uart_num, int enable, int thresh)
- 参数
uart_num
:UART 端口号,最大为UART_NUM_MAX - 1
enable
:1: 启用; 0: 禁用thresh
:TX 中断的阈值(0 ~UART_HW_FIFO_LEN(uart_num)
)
- 作用
- 使能 UART TX 中断(
TX_FULL
、TX_TIMEOUT
)。
- 使能 UART TX 中断(
- 返回值
ESP_OK
成功ESP_FAIL
参数错误
2.2.6 uart_intr_config
esp_err_t uart_intr_config(uart_port_t uart_num, const uart_intr_config_t *intr_conf)
- 参数
uart_num
:UART 端口号,最大为UART_NUM_MAX - 1
intr_conf
:UART 中断配置
- 作用
- 配置 UART TX 中断。
- 返回值
ESP_OK
成功ESP_FAIL
参数错误
2.3 参数设置
2.3.1 uart_set_word_length
esp_err_t uart_set_word_length(uart_port_t uart_num, uart_word_length_t data_bit)
- 参数
uart_num
:UART 端口号,最大为UART_NUM_MAX - 1
data_bit
:数据位长度
- 作用
- 设置 UART 数据位长度。
- 返回值
ESP_OK
成功ESP_FAIL
参数错误
读取使用函数:
esp_err_t uart_get_word_length(uart_port_t uart_num, uart_word_length_t *data_bit)
2.3.2 uart_set_stop_bits
esp_err_t uart_set_stop_bits(uart_port_t uart_num, uart_stop_bits_t stop_bits)
- 参数
uart_num
:UART 端口号,最大为UART_NUM_MAX - 1
stop_bits
:停止位长度
- 作用
- 设置 UART 停止位长度。
- 返回值
ESP_OK
成功ESP_FAIL
参数错误
读取使用函数:
esp_err_t uart_get_stop_bits(uart_port_t uart_num, uart_stop_bits_t* stop_bits)
2.3.3 uart_set_parity
esp_err_t uart_set_parity(uart_port_t uart_num, uart_parity_t parity_mode)
- 参数
uart_num
:UART 端口号,最大为UART_NUM_MAX - 1
parity_mode
:奇偶校验模式
- 作用
- 设置 UART 奇偶校验模式。
- 返回值
ESP_OK
成功ESP_FAIL
参数错误
读取使用函数:
esp_err_t uart_get_parity, uart_port_t uart_num, uart_parity_t* parity_mode
2.3.4 uart_set_baudrate
esp_err_t uart_set_baudrate(uart_port_t uart_num, uint32_t baudrate)
- 参数
uart_num
:UART 端口号,最大为UART_NUM_MAX - 1
baudrate
:波特率
- 作用
- 设置 UART 波特率。
- 返回值
ESP_OK
成功ESP_FAIL
参数错误
读取使用函数:
esp_err_t uart_get_baudrate(uart_port_t uart_num, uint32_t *baudrate)
2.3.5 uart_set_pin
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)
- 参数
uart_num
:UART 端口号,最大为UART_NUM_MAX - 1
tx_io_num
:tx 引脚号rx_io_num
:rx 引脚号rts_io_num
:rts 引脚号cts_io_num
:cts 引脚号
- 作用
- 将 UART 外设的信号分配给 GPIO 引脚。
- 返回值
ESP_OK
成功ESP_FAIL
参数错误
内部信号可以输出到多个 GPIO 引脚。只能有一个 GPIO 引脚连接输入信号。
2.3.6 uart_set_mode
esp_err_t uart_set_mode(uart_port_t uart_num, uart_mode_t mode)
- 参数
uart_num
:UART 端口号,最大为UART_NUM_MAX - 1
mode
:UART 要设置的模式
- 作用
- 设置 UART 通信模式。
- 返回值
ESP_OK
成功ESP_FAIL
参数错误
2.3.7 uart_param_config
esp_err_t uart_param_config(uart_port_t uart_num, const uart_config_t *uart_config)
- 参数
uart_num
:UART 端口号,最大为UART_NUM_MAX - 1
uart_config
:UART 配置参数
- 作用
- 设置 UART 配置参数。
- 返回值
ESP_OK
成功ESP_FAIL
参数错误
2.4 通信
2.4.1 uart_wait_tx_done
es