UART Event 示例

[English]

示例说明

本示例展示如何初始化、配置、校准 ADC 以及如何使用 ADC 单次采样模式采集模拟输入信号并进行处理。学习该示例前，建议先掌握 FreeRTOS 队列的相关内容，其基础说明及 API 使用示例可参考 队列管理。

运行方法

示例完整代码见 UART Event 示例。运行前的配置说明、构建与烧录流程详见示例目录下的 README.md 文件。

如需自定义配置项及查看默认值，可参考 全局变量/宏定义说明 部分。

头文件说明

本示例所使用的头文件涵盖了 FreeRTOS 任务管理、常用系统工具以及 UART 驱动等基础模块，为任务创建、UART 配置、数据传输等功能提供支持。

各头文件按功能分类如下：

  1. FreeRTOS 任务调度 ：任务创建、调度及队列操作功能

#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "freertos/queue.h"

  1. 系统工具 ：提供系统日志、标准输入输出以及字符串处理等功能。

#include <stdio.h>
#include <string.h>
#include "esp_log.h"

  1. UART 驱动 ：提供配置和管理 UART 外设的通信，包括外设初始化、数据发送、接收等操作。

#include "driver/uart.h"

全局变量/宏定义说明

本示例中涉及的宏定义主要用于定义 UART 外设的相关配置参数，以及缓冲区大小。

宏定义按功能分类如下：

  1. UART 配置

  • 定义所使用的 UART 单元。本示例使用 UART_NUM_0，即 UART0 外设。

#define EX_UART_NUM UART_NUM_0

  • 配置 UART 模式匹配功能，用于触发特定操作或事件。本示例中，当接收到 3 个连续相同的字符时，表示检测到一个模式。

#define PATTERN_CHR_NUM    (3)

  1. 缓冲区大小 ：

  • 设置数据缓冲区和读取缓冲区的大小，分别用于存放待发送的以及接收到的 UART 数据。示例中均设置为 1024 字节。

#define BUF_SIZE (1024)
#define RD_BUF_SIZE (BUF_SIZE)

  1. 定义全局变量：

  • 定义队列句柄变量 uart0_queue，用于 FreeRTOS 的任务间通信，将接收到的数据从 UART 接收任务传递到其他任务进行处理。

任务函数说明

在本示例中，为了处理从 UART 接口接收到的数据、处理错误情况（如溢出、帧错误等），并根据需要将数据回写或清理缓冲区，提供了一个任务函数 uart_event_task()。该函数通过事件队列接收 UART 相关的事件，并根据不同的事件类型执行相应的操作。

该函数的执行逻辑为：

  1. 定义变量：

  • 定义 UART 事件句柄 event，用于存储从 UART 队列接收到的事件信息。该变量在每次处理 UART 事件时都会更新，确保任务能够根据不同的事件类型执行相应的操作。

  • 定义 buffered_size，用于存储当前 UART 接收缓冲区中的数据长度，帮助确定缓冲区中可用的数据大小，或者用于清理缓冲区并确保后续数据传输的正常进行。

  • 定义变量 dtmp 并动态分配内存，用作接收缓冲区，存储接收到的数据。大小为 RD_BUF_SIZE。

  1. 调用 xQueueReceive() 阻塞等待 UART 事件。进一步说明及使用示例可参考 队列数据接收。

  2. 接收到事件后，进入事件处理流程，根据事件类型执行相应的操作，其中部分事件说明可参考 使用中断说明：

  • 将接收缓冲区 dtmp 中的数据全部清零，确保在处理新的 UART 数据前，缓冲区内容不会受到之前残留数据的干扰。

  • UART 数据接收：UART_DATA，当 UART 接收到有效数据并写入驱动层的接收缓冲区后触发。

    • 打印日志输出数据大小。

    • 调用 uart_read_bytes() 读取接收到的数据并将其存储在 dtmp 缓冲区。进一步介绍及参数说明可参考 UART API。

    • 调用 uart_write_bytes() 将接收到的数据再写回 UART 发送端，用于回显测试。进一步介绍及参数说明可参考 UART API。

    备注

    回显测试并不是应用逻辑的必需步骤，而是 UART 示例代码中常用的调试手段。其作用在于验证通信链路是否正常、便于调试以及检查数据传输的完整性。

  • 硬件 FIFO 溢出：UART_FIFO_OVF，当硬件 FIFO 接收数据过多，缓冲区溢出时触发。

    • 调用 uart_flush_input() 清空接收缓冲区。进一步介绍及参数说明可参考 UART API。

    • 调用 xQueueReset() 重置事件队列。

  • 环形缓冲区满：UART_BUFFER_FULL，当驱动层配置的环形缓冲区存满，无法继续写入新的接收数据时触发。

    • 调用 uart_flush_input() 清空接收缓冲区。进一步介绍及参数说明可参考 UART API。

    • 调用 xQueueReset() 重置事件队列。

  • UART 接收中断：UART_BREAK，当接收端检测到总线上的低电平持续时间超过 1 个帧周期时触发。

    • 打印日志提示。

  • UART 奇偶校验错误：UART_PARITY_ERR，当接收到的数据帧在校验位检查中发现错误时触发。

    • 打印日志提示。

  • UART 帧错误：UART_FRAME_ERR，当接收到的数据帧格式异常（如停止位错误）时触发。

    • 打印日志提示。

  • UART 模式匹配：UART_PATTERN_DET，当接收的数据流中出现预先配置的连续特定字符模式（由 PATTERN_CHR_NUM 定义）时触发。

    • 调用 uart_get_buffered_data_len() 查看 FIFO 缓冲区中可用的字节数。，并保存至变量 buffered_size。进一步介绍及参数说明可参考 UART API。

    • 调用 uart_pattern_pop_pos() 获取模式匹配的位置，并保存至变量 pos。进一步介绍及参数说明可参考 UART API。

    • 判断位置：

      备注

      如果 pos == -1 说明模式队列已满，无法记录匹配位置。

      • 如果检测到模式但模式队列已满，调用 uart_flush_input() 清空缓冲区。进一步介绍及参数说明可参考 UART API。

      • 模式队列未满：

        • 调用 uart_read_bytes() 读取模式匹配位置前的数据，并将其保存至缓冲区 dtmp 中。进一步介绍及参数说明可参考 UART API。

        • 定义临时数组 pat 并初始化为 0，用于存放匹配到的模式字符。数组长度为 PATTERN_CHR_NUM + 1，其中额外的 1 个字节用于存放字符串结束符 '\0'，确保在后续处理和日志输出时可以作为有效字符串使用。

        • 调用 uart_read_bytes() 读取模式字符并保存至数组 pat。进一步介绍及参数说明可参考 UART API。

        • 打印日志，输出已接收到的数据和匹配到的模式内容。

  • 其他事件：

    • 打印日志输出事件类型。

  1. 释放内存并删除任务：

  • 任务结束时，释放动态分配的内存 dtmp，并将 dtmp 指针设为 NULL。

  • 调用 vTaskDelete() 删除当前任务。进一步说明及使用示例可参考 删除任务。

主函数说明

本函数展示了 UART 外设在 ESP-IDF 中的基本使用流程。主要功能包括：配置 UART 参数、安装并初始化驱动、设置通信引脚和模式检测功能，最后创建事件处理任务，实现串口数据的接收与管理。

  1. 调用 esp_log_level_set() 设置日志级别，便于后续调试和信息输出。

  2. 安装 UART 驱动程序。

  3. 配置并应用 UART 参数。

  4. 设置通信引脚。

  5. 启用模式检测功能：

  • 调用 uart_enable_pattern_det_baud_intr() 启用基于 UART 波特率的模式检测功能，可用于快速识别数据帧边界、命令分隔符或特定协议标记，便于任务对接收数据进行解析和处理。进一步介绍及参数说明可参考 UART API。

  • 调用 uart_pattern_queue_reset() 重置模式匹配队列，并设置最大可记录的模式位置数量。确保队列中只保留最新的匹配信息，避免队列溢出或记录过多历史位置影响性能。进一步介绍及参数说明可参考 UART API。

  1. 调用 xTaskCreate() 创建事件处理任务。进一步说明及使用示例可参考 动态创建任务。