ESP-IDF教程4 UART 异步通信

1、前提

1.1、基础知识

1.1.1、参数

串口是一种异步通信协议，需要收发双方保持相同的协议才可以正确解析数据，这里不会过多介绍串口协议的相关知识，仅从应用角度来说，一般需要配置如下几个参数：

• 波特率
  
• 数据位
  
• 校验位
  
• 停止位
  
• 流控
  

在 ESP-IDF 下，每一个参数都都有对应的 API 单独设置或获取该参数，如下所示：

• uart_set_baudrate() / uart_get_baudrate()
  
• uart_set_word_length() / uart_get_word_length()
  
• uart_set_parity() / uart_get_parity()
  
• uart_set_stop_bits() / uart_get_stop_bits()
  
• uart_set_hw_flow_ctrl() / uart_set_sw_flow_ctrl() / uart_get_hw_flow_ctrl()
  

但开发者一般在初始化时不会一个一个单独的设置 UART 的参数，而是使用结构体 uart_config_t 配置参数，最后通过 uart_param_config() 函数执行 UART 的参数配置，如下所示：

1. void uart_parameter_init(void) {
2.     const uart_config_t uart_cfg = {
3.         .baud_rate = 115200,
4.         .data_bits = UART_DATA_8_BITS,
5.         .parity = UART_PARITY_DISABLE,
6.         .stop_bits = UART_STOP_BITS_1,
7.         .flow_ctrl = UART_HW_FLOWCTRL_DISABLE,
8.         .source_clk = UART_SCLK_APB,
9.     };
11.     // Initialize UART peripheral with the given configuration
12.     uart_param_config(UART_PORT_NUM, & uart_cfg);
13. }

复制代码

1.1.2、输出函数

ESP-IDF 下有多种与串口输出相关的函数，如下所示：

• uart_write_bytes
  
• printf
  
• ESP_LOGx
  
• ets_printf
  

其中 uart_write_bytes 是 #include "driver/uart.h" 驱动库中的函数，其必须在串口显示初始化后才能使用，否则将出现 E (x) uart: uart_write_bytes(1485): uart driver error 的错误。
printf 为标准的 C 函数，ESP_LOGx 系列函数是 ESP-IDF 的日志框架，这两种输出方式通常会使用默认的 UART0 进行输出。由于 ESP32 在上电时 UART0 已经被默认初始化，因此即使不显示初始化 UART0 也可以正常输出。
ESP_LOGx 系列函数默认带回车换行，无需手动添加回车换行，使用时需要包含 #include "esp_log.h" 头文件，主要有如下几种：

• ESP_LOGI，信息 Info
  
• ESP_LOGE，错误 Error
  
• ESP_LOGW，警告 Warning
  
• ...
  

ets_printf 是 ESP-ROM 提供的轻量级输出函数，使用时需要包含 #include  头文件，该函数不依赖 FreeRTOS，可以直接输出到 UART0，读者可以将其类比于 STM32 HAL 库开发中的 HAL_UART_Transmit 函数，因此在中断中使用也不会卡死，而 printf 则不能在中断中使用。
1.1.3、接收函数

uart_read_bytes() 是 ESP-IDF 中主要的串口接收函数，它的四个参数含义如下：

• uart_num，串口号
  
• buf，接收缓存区
  
• length，接收数据长度
  
• ticks_to_wait，阻塞等待时间
  

上述函数将在以下两种情况下返回：

• 接收缓存区满
  
• 阻塞时间到期
  

1.1.4、事件

使用 uart_driver_install() 函数安装串口驱动程序时，会涉及到 queue_size 和 uart_queue 两个参数，这两个参数分别设置了队列深度和关联了一个串口队列。
串口驱动安装函数不是用于初始化串口的吗？为什么要创建一个队列？
主要是为了方便管理串口发生的事件，当上述两个参数非空时，串口便可以将驱动层发出的与串口相关的事件自动传递至队列中，用户可以通过 xQueueReceive() 函数来接收事件，方便根据不同的事件分别处理。
串口相关的事件有哪些？

1. typedef enum {
2.     UART_DATA,              /* 有数据接收 */
3.     UART_BREAK,             /* 检测到 Break 信号 */
4.     UART_BUFFER_FULL,       /* RX 环形缓冲区满 */
5.     UART_FIFO_OVF,          /* FIFO 溢出 */
6.     UART_FRAME_ERR,         /* 帧格式错误 */
7.     UART_PARITY_ERR,        /* 校验错误 */
8.     UART_DATA_BREAK,
9.     UART_PATTERN_DET,
10. #if SOC_UART_SUPPORT_WAKEUP_INT
11.     UART_WAKEUP,
12. #endif
13.     UART_EVENT_MAX,
14. } uart_event_type_t;

复制代码

当有设备向 ESP32 发送数据时，ESP32 会产生 UART_DATA 事件
ESP32 驱动安装时会设置 TX/RX 缓存区大小，如果设备不断地向 ESP32 发送数据，而 ESP32 没有从其中读出数据，在 RX 缓冲区满的那一刻会产生 UART_BUFFER_FULL 事件
产生 UART_BUFFER_FULL 事件后，如果设备仍然向 ESP32 发送数据，将会不断触发 UART_FIFO_OVF 事件
串口事件使用 uart_event_t 结构体管理，除了包含上述事件类型外还有参数，如下为其具体定义：

1. typedef struct {
2.     uart_event_type_t type; /* 串口事件类型 */
3.     size_t size;            /* UART_DATA 事件的数据大小 */
4.     bool timeout_flag;      /* UART_DATA 事件数据读超时标志 */
5. } uart_event_t;

复制代码

串口事件队列一般如何使用？

1. // 1. 新建串口队列
2. QueueHandle_t uart_queue;
3. // 2. 安装驱动时关联串口队列
4. uart_driver_install(UART_NUM_x, 1024, 0, 10, & uart_queue, 0);
6. void uart_event_task(void * pvParameters) {
7.         uart_event_t event;
8.         while (1) {
9.                 // 3. 接收事件，根据不同的事件做处理
10.                 if (xQueueReceive(uart_queue, (void * ) & event, portMAX_DELAY)) {
11.                         switch (event.type) {
12.                                 case UART_DATA:
13.                                         ...
14.                                         break;
15.                       case ...:
16.                               break;
17.                                 ...
18.             }
19.         }
20.     }
21. }

复制代码

这里为避免混淆，简单说一下串口接收时阻塞、非阻塞、同步和异步的区别，具体如下表所示：
视角类型含义程序视角阻塞函数调用，程序停止，直到返回结果-非阻塞函数调用，立即返回结果用户视角同步函数调用，用户等结果出来，然后做其他事情-异步函数调用，用户不等，有了结果别人通知用户上述两种视角相互结合可以看到如下几种常见组合：

• 同步阻塞，uart_read_bytes(x, x, portMAX_DELAY)
  
• 同步非阻塞，uart_read_bytes(x, x, 0)
  
• 异步阻塞，xQueueReceive(x, x, portMAX_DELAY)
  
• 异步非阻塞，xQueueReceive(x, x, 0)
  

可能描述的不那么直观，举个烧水切菜做饭的例子：
模式说明同步阻塞你烧水的时候一直盯着水壶，水开了才去炒菜同步非阻塞你烧水，但一直轮询看有没有水开，同时开始切菜异步阻塞你烧水后坐着等老婆提醒你水开了异步非阻塞你烧水，装个智能水壶，水开了会响铃，你继续安心炒菜1.2、数据结构

ESP-IDF 驱动头文件

1. #include "driver/uart.h"

复制代码

UART 参数配置结构体

1. typedef struct {
2.     int baud_rate;                                                 /* 波特率 */
3.     uart_word_length_t data_bits;                 /* 数据位 */
4.     uart_parity_t parity;                                 /* 校验位 */
5.     uart_stop_bits_t stop_bits;                 /* 停止位 */
6.     uart_hw_flowcontrol_t flow_ctrl;         /* 硬件流控模式 */
7.     uint8_t rx_flow_ctrl_thresh;                 /* 硬件 RTS 阈值 */
8.     union {
9.         uart_sclk_t source_clk;                 /* 时钟源 */
10. #if(SOC_UART_LP_NUM >= 1)
11.         lp_uart_sclk_t lp_source_clk;         /* 低功耗模式下的时钟源 */
12. #endif
13.     };
14.     struct {
15.         uint32_t allow_pd: 1;                                /* 允许进入低功耗模式  */
16.         uint32_t backup_before_sleep: 1;         /* 进入低功耗模式前保存状态 */
17.     }flags;                                                                 /* 配置标志 */
18. }uart_config_t;

复制代码

1.3、硬件原理图

ESP32 系列芯片在硬件设计时，一般均选择将 UART0 作为默认的输出串口，同时也做控制台输出，本文有关 UART 的硬件原理图如下图所示：

根据 esp32_datasheet_cn.pdf 第 “2.2 管脚概述” 节中 “表 2-1. 管脚概述” 内容可知，U0RXD 默认连接至 GPIO3，U0TXD 默认连接至 GPIO1，如下所示：

其他 ESP32 系列芯片同理，比如 ESP32-C3 ，根据 esp32-c3_datasheet_cn.pdf 第 ”2.3.4 外设管脚分配“ 节中 “表 2-7. 外设管脚分配” 内容可知，U0RXD 默认连接至 GPIO20，U0TXD 默认连接至 GPIO21，如下图所示，因此后续初始化 UART0 时便知道 TX/RX 两个引脚对应的 GPIO 号。

2、示例程序

2.1、UART Transmitter

功能：

• 通过串口 UART_PORT_NUM 输出数据到串口助手
  

程序流程：

• 调用 uart_param_config() 函数初始化串口配置参数
  
• 调用 uart_set_pin() 函数绑定串口引脚
  
• 调用 uart_driver_install() 函数安装串口驱动，此后即可使用该串口输出/输入数据
  
• 调用 uart_write_bytes() / printf() / ESP_LOGI() 等函数通过串口输出数据
  

示例程序：

1. #include "freertos/FreeRTOS.h"
2. #include "driver/uart.h"
3. #include "string.h"
4. #include "esp_log.h"
6. // UART configuration
7. #define UART_PORT_NUM           UART_NUM_0
8. #define UART_RX_PIN             3
9. #define UART_TX_PIN             1
10. #define UART_RX_BUFFER_SIZE     1024
11. #define UART_TX_BUFFER_SIZE     1024
13. // UART parameter configuration
14. #define UART_BAUD_RATE          115200
15. #define UART_DATA_BITS          UART_DATA_8_BITS
16. #define UART_PARITY             UART_PARITY_DISABLE
17. #define UART_STOP_BITS          UART_STOP_BITS_1
18. #define UART_FLOW_CTRL          UART_HW_FLOWCTRL_DISABLE
20. /* The following does not need to be modified */
21. static const char *TAG = "UART_Transmitter_Example";
23. void uart_init(void) {
24.     const uart_config_t uart_cfg = {
25.         .baud_rate = UART_BAUD_RATE,
26.         .data_bits = UART_DATA_BITS,
27.         .parity = UART_PARITY,
28.         .stop_bits = UART_STOP_BITS,
29.         .flow_ctrl = UART_FLOW_CTRL,
30.         .source_clk = UART_SCLK_APB,
31.     };
33.     // Initialize UART peripheral with the given configuration
34.     uart_param_config(UART_PORT_NUM, & uart_cfg);
36.     // Set UART pins
37.     uart_set_pin(UART_PORT_NUM, UART_TX_PIN, UART_RX_PIN, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE);
39.     // Install UART driver and get the queue handle
40.     uart_driver_install(UART_PORT_NUM, UART_RX_BUFFER_SIZE, UART_TX_BUFFER_SIZE, 0, NULL, 0);
41. }
43. void app_main(void) {
45.     uart_init();
47.     while(1) {
48.         const char *data_1 = "method_1: uart_write_bytes()\r\n";
49.         uart_write_bytes(UART_PORT_NUM, data_1, strlen(data_1));
50.         vTaskDelay(500);
51.         
52.         printf("method_2: printf()\r\n");
53.         vTaskDelay(500);
55.         ESP_LOGI(TAG, "method_3: ESP_LOGx()\r\n");
56.         vTaskDelay(500);
57.     }
58.         // Will not execute
59.         uart_driver_delete(UART_PORT_NUM);
60. }

复制代码

2.2、UART Receiver

功能：

• 通过串口 UART_PORT_NUM 阻塞的接收数据，并将接收到的数据回显
  

程序流程：

• 同 "2.1、UART Transmitter" 初始化 UART 流程
  
• 调用 uart_read_bytes() 函数阻塞的接收串口数据
  
• 如果接收到数据，调用 uart_write_bytes() 函数将数据回显给发送方
  

示例程序：

1. #include "freertos/FreeRTOS.h"
2. #include "driver/uart.h"
4. // UART configuration
5. #define UART_PORT_NUM           UART_NUM_0
6. #define UART_RX_PIN             3
7. #define UART_TX_PIN             1
8. #define UART_RX_BUFFER_SIZE     1024
9. #define UART_TX_BUFFER_SIZE     1024
11. // UART parameter configuration
12. #define UART_BAUD_RATE          115200
13. #define UART_DATA_BITS          UART_DATA_8_BITS
14. #define UART_PARITY             UART_PARITY_DISABLE
15. #define UART_STOP_BITS          UART_STOP_BITS_1
16. #define UART_FLOW_CTRL          UART_HW_FLOWCTRL_DISABLE
18. /* The following does not need to be modified */
19. void uart_init(void) {
20.     const uart_config_t uart_cfg = {
21.         .baud_rate = UART_BAUD_RATE,
22.         .data_bits = UART_DATA_BITS,
23.         .parity = UART_PARITY,
24.         .stop_bits = UART_STOP_BITS,
25.         .flow_ctrl = UART_FLOW_CTRL,
26.         .source_clk = UART_SCLK_APB,
27.     };
28.    
29.     // Initialize UART peripheral with the given configuration
30.     uart_param_config(UART_PORT_NUM, & uart_cfg);
32.     // Set UART pins
33.     uart_set_pin(UART_PORT_NUM, UART_TX_PIN, UART_RX_PIN, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE);
35.     // Install UART driver and get the queue handle
36.     uart_driver_install(UART_PORT_NUM, UART_RX_BUFFER_SIZE, UART_TX_BUFFER_SIZE, 0, NULL, 0);
37. }
40. void app_main(void) {
42.     uart_init();
44.     uint8_t data[UART_RX_BUFFER_SIZE];
45.     while (1) {
46.         int len = uart_read_bytes(UART_PORT_NUM, data, sizeof(data) - 1, 0);
47.         if (len > 0) {
48.             data[len] = '\r';
49.             data[len + 1] = '\n';
50.             data[len + 2] = '\0';
51.             uart_write_bytes(UART_PORT_NUM, (char * ) data, len + 2);
52.         }
53.         vTaskDelay(10);
54.     }
55.     // Will not execute
56.         uart_driver_delete(UART_PORT_NUM);
57. }

复制代码

2.3、UART Receiver Using Event Queue

功能：

• 通过串口 UART_PORT_NUM 接收数据，并将接收到的数据回显
  

程序流程：

• 同 "2.1、UART Transmitter" 初始化 UART 流程，但要额外注意 uart_driver_install() 函数的 uart_queue 参数
  
• 调用 xQueueReceive() 函数处理 UART 事件
  
• 如果是 UART_DATA 事件，调用 uart_write_bytes() 函数将数据回显给发送方，同时对比接收到的数据，如果为 “on” 则打开 LED 灯，否则为 “off” 则关闭 LED 灯
  

示例程序：

1. #include "freertos/FreeRTOS.h"
2. #include "driver/uart.h"
3. #include "driver/gpio.h"
4. #include "string.h"
6. #define LED_GPIO_PIN            GPIO_NUM_13
8. // UART configuration
9. #define UART_PORT_NUM           UART_NUM_0
10. #define UART_RX_PIN             3
11. #define UART_TX_PIN             1
12. #define UART_RX_BUFFER_SIZE     1024
13. #define UART_TX_BUFFER_SIZE     1024
14. #define UART_QUEUE_DEPTH        20
16. // UART parameter configuration
17. #define UART_BAUD_RATE          115200
18. #define UART_DATA_BITS          UART_DATA_8_BITS
19. #define UART_PARITY             UART_PARITY_DISABLE
20. #define UART_STOP_BITS          UART_STOP_BITS_1
21. #define UART_FLOW_CTRL          UART_HW_FLOWCTRL_DISABLE
23. /* The following does not need to be modified */
24. static QueueHandle_t uart_queue;
26. void led_init(void) {
28.     gpio_config_t io_cfg = {
29.         .pin_bit_mask = 1 << LED_GPIO_PIN,
30.         .mode = GPIO_MODE_OUTPUT,
31.         .pull_up_en = 0,
32.         .pull_down_en = 0,
33.         .intr_type = GPIO_INTR_DISABLE,
34.     };
36.     gpio_config( & io_cfg);
37.     // defaut output high level
38.         gpio_set_level(LED_GPIO_PIN, 1);
39. }
42. void uart_init(void) {
43.     const uart_config_t uart_cfg = {
44.         .baud_rate = UART_BAUD_RATE,
45.         .data_bits = UART_DATA_BITS,
46.         .parity = UART_PARITY,
47.         .stop_bits = UART_STOP_BITS,
48.         .flow_ctrl = UART_FLOW_CTRL,
49.         .source_clk = UART_SCLK_APB,
50.     };
51.    
52.     // Initialize UART peripheral with the given configuration
53.     uart_param_config(UART_PORT_NUM, & uart_cfg);
55.     // Set UART pins
56.     uart_set_pin(UART_PORT_NUM, UART_TX_PIN, UART_RX_PIN, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE);
58.     // Install UART driver and get the queue handle
59.     uart_driver_install(UART_PORT_NUM, UART_RX_BUFFER_SIZE, UART_TX_BUFFER_SIZE, UART_QUEUE_DEPTH, & uart_queue, 0);
61. }
63. static void uart_event_task(void * pvParameters) {
64.     uart_event_t event;
65.     uint8_t data[UART_RX_BUFFER_SIZE];
67.     while (1) {
68.         if (xQueueReceive(uart_queue, & event, portMAX_DELAY)) {
69.             switch (event.type) {
70.                 case UART_DATA:
71.                     int len = uart_read_bytes(UART_PORT_NUM, data, sizeof(data) - 1, 0);
72.                     if (len > 0) {
73.                         // add end
74.                         data[len] = '\r';
75.                         data[len + 1] = '\n';
76.                         data[len + 2] = '\0';
77.                         uart_write_bytes(UART_PORT_NUM, (char * ) data, len + 2);
78.                         
79.                         // control logic
80.                         if(strcmp((const char *)data, "on\r\n") == 0) {
81.                             gpio_set_level(LED_GPIO_PIN, 1);
82.                         } else if(strcmp((const char *)data, "off\r\n") == 0) {
83.                             gpio_set_level(LED_GPIO_PIN, 0);
84.                         }
85.                     }
86.                     break;
87.                 default:
88.                     printf("Unhandled UART event type: %d\r\n", event.type);
89.                     break;
90.             }
91.         } else {
92.                         vTaskDelay(10);
93.         }
94.     }
95. }
98. void app_main(void) {
99.     led_init();
100.         uart_init();
101.     xTaskCreate(uart_event_task, "uart_event_task", 4096, NULL, 12, NULL);
102. }

复制代码

3、常用函数

1. // 串口参数配置
2. esp_err_t uart_param_config(uart_port_t uart_num, const uart_config_t *uart_config);
3. // 串口引脚配置
4. 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);
5. // 串口驱动注册
6. esp_err_t uart_driver_install(uart_port_t uart_num, int rx_buffer_size, int tx_buffer_size, int event_queue_size, QueueHandle_t *uart_queue, int intr_alloc_flags);
7. // 串口阻塞接收数据
8. int uart_read_bytes(uart_port_t uart_num, void *buf, uint32_t length, TickType_t ticks_to_wait);
9. // 串口发送数据
10. int uart_write_bytes(uart_port_t uart_num, const void *src, size_t size);
11. // 串口驱动注销
12. esp_err_t uart_driver_delete(uart_port_t uart_num);
14. // 串口参数配置/获取函数
15. esp_err_t uart_set_baudrate(uart_port_t uart_num, uint32_t baud_rate);
16. esp_err_t uart_get_baudrate(uart_port_t uart_num, uint32_t *baudrate);
17. esp_err_t uart_set_word_length(uart_port_t uart_num, uart_word_length_t data_bit);
18. esp_err_t uart_get_word_length(uart_port_t uart_num, uart_word_length_t *data_bit);
19. esp_err_t uart_set_parity(uart_port_t uart_num, uart_parity_t parity_mode);
20. esp_err_t uart_get_parity(uart_port_t uart_num, uart_parity_t *parity_mode);
21. esp_err_t uart_set_stop_bits(uart_port_t uart_num, uart_stop_bits_t stop_bit);
22. esp_err_t uart_get_stop_bits(uart_port_t uart_num, uart_stop_bits_t *stop_bit);

复制代码

4、烧录验证

第 "2.1、UART Transmitter" 节实验现象如下所示，通过三种方式循环从串口发送数据。

第 "2.2、UART Receiver" 节实验现象如下所示，利用串口助手通过串口向 ESP32 发送数据，ESP32 接收到数据后回显给串口助手。

第 "2.3、UART Receiver Using Event Queue" 节实验现象如下所示，通过串口助手发送 “on” 或者 “off” 来控制 LED_GPIO_PIN 的引脚电平状态，并将串口助手发送的数据回显。

来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！