ESP-IDF 开发
本章节包含以下内容：
ESP-IDF 入门教程
初次接触 ESP32 ESP-IDF 开发，想要快速上手？我们为您准备了一套通用的 入门教程。
- 第0节 认识 ESP32
- 第1节 搭建环境
- 第2节 运行实例
- 第3节 创建项目
- 第4节 使用组件
- 第5节 调试程序
- 第6节 FreeRTOS
- 第7节 驱动外设
- 第8节 Wi-Fi 编程
- 第9节 BLE 编程
请注意：该教程使用 ESP32-S3-Zero 作为教学示例，所有硬件代码均基于其引脚布局。在动手实践前，建议您对照手中的开发板引脚图，确认引脚配置无误。
配置开发环境
以下内容以 Windows 系统为例，使用 VS Code + ESP-IDF 扩展 的方式进行开发。Mac/Linux 用户请参考 官方说明。
安装 ESP-IDF 开发环境
-
前往 ESP-IDF Installation Manager 下载 ESP-IDF 安装管理器。这是乐鑫最新推出的跨平台安装工具，下文将演示如何使用其离线安装功能。
在页面中点击 Offline Installer 标签，然后在筛选栏中选择 Windows 操作系统和你要安装的版本。
确认选择无误后，点击下载按钮。浏览器将自动同时下载两个文件：一个是 ESP-IDF 离线整合包(.zst)，另一个是 ESP-IDF 安装器(.exe)。
请耐心等待两个文件下载完成。
-
下载完成后，双击运行 ESP-IDF 安装器(eim-gui-windows-x64.exe)。
启动后，可在右上角将界面语言切换为中文。
安装工具会自动检测同一目录下是否存在离线整合包。点击 从存档安装。
接下来，选择安装路径。建议使用默认路径；若需自定义，请确保路径中不包含中文或空格。确认无误后，点击 开始安装。
-
当看到如下界面时，表示 ESP-IDF 已安装成功。
-
建议同时安装驱动程序。点击 完成安装，然后点击 安装驱动程序。
安装 Visual Studio Code 与 ESP-IDF 扩展
-
下载并安装 Visual Studio Code。
-
安装时建议勾选 通过 Code 打开操作添加到 Windows 资源管理器文件上下文菜单,以便快速打开项目文件夹。
-
在 VS Code 中,点击侧边活动栏中的
扩展图标(或使用快捷键 Ctrl + Shift + X)打开 扩展 视图。 -
在搜索框中输入 ESP-IDF,找到 ESP-IDF 扩展并点击安装。
-
当 ESP-IDF 扩展版本 ≥ 2.0 时,扩展会自动检测并识别上述步骤中安装的 ESP-IDF 环境,无需手动配置。
性能优化配置 (Menuconfig)
为了在 ESP-IDF 下获得最佳的屏幕刷新率和 LVGL 性能（例如在 ESP-IDF v5.3 下达到 41Hz 的接口帧率），建议在编译前通过 idf.py menuconfig 进行以下配置：
- FreeRTOS 滴答频率:
CONFIG_FREERTOS_HZ=1000
- CPU 频率:
CONFIG_ESP_DEFAULT_CPU_FREQ_MHZ_240=y
- Flash 与 PSRAM 优化:
CONFIG_ESPTOOLPY_FLASHMODE_QIO=yCONFIG_ESPTOOLPY_FLASHFREQ_120M=y(需与 PSRAM 保持一致)CONFIG_SPIRAM_MODE_OCT=yCONFIG_SPIRAM_SPEED_120M=y(需启用CONFIG_IDF_EXPERIMENTAL_FEATURES)CONFIG_SPIRAM_FETCH_INSTRUCTIONS=yCONFIG_SPIRAM_RODATA=y
- 缓存行大小:
CONFIG_ESP32S3_DATA_CACHE_LINE_64B=y
- 编译器优化:
CONFIG_COMPILER_OPTIMIZATION_PERF=y
- LVGL 优化 (v8.3+):
CONFIG_LV_MEM_CUSTOM=yCONFIG_LV_MEMCPY_MEMSET_STD=yCONFIG_LV_ATTRIBUTE_FAST_MEM=y
安装失败或需重装，可尝试删除 C:\Users\%Username%\esp 与 C:\Users\%Username%\.espressif 后重试。
烧录程序
-
在安装完 ESP-IDF 的开发环境之后，选择文件夹打开示例
-
在弹出的窗口当中选择示例包解压后的 ESP-IDF 目录下的示例，点击选择文件（这里用 01_I2C_Test 文件夹作为示例）。
-
为了将对应的代码上传到 ESP32-S3，需要用 Type-C 转 Type-A 的线将 ESP32-S3-Touch-LCD-4.3 的 USB 口接到电脑的 USB 口。
-
若是新工程首次烧录程序，需要先选择识别出来的 COM 口，例如我这边识别到的是 COM36。
-
选择下载方式为：UART。
-
接着选择主芯片为 ESP32S3。
选择 openocd 的路径，这里对我们没有影响，所以我们随便选择一个即可，此处可选择第一个。
-
点击下列的小火苗 Build Flash Monitor 一键按钮，用于连续执行 Build-->Flash-->Monitor。
-
板子上板载自动下载电路，无需手动操作即可自动下载。接着等待编译烧录完成就好，首次编译可能需要较长时间才能完成。
示例程序
示例程序位于示例包的 ESP-IDF 目录：
下面给出每个示例的目的、要点说明与运行效果（以便快速上手）。
| 示例程序 | 基础例程说明 | 依赖库 |
|---|---|---|
| 01_I2C_Test | 测试I2C座子 | - |
| 02_RS485_Test | 测试RS485座子 | - |
| 03_SD_Test | 测试SD卡座 | - |
| 04_Sensor_AD | 测试ADC座子 | - |
| 05_UART_Test | 测试UART | - |
| 06_TWAItransmit | 测试CAN卡座 | - |
| 07_TWAIreceive | 测试CAN卡座 | - |
| 08_lvgl_Porting | 测试LVGL移植 | v8.4.0 |
01_I2C_Test
本示例用于测试 I2C 座子：启动控制台命令行，并提供 I2C 扫描/读写工具（如 i2cdetect/i2cget/i2cset）。
硬件连接
- 使用 USB 线把板子接入电脑。
代码分析
app_main()：- 首先定义了与 I2C 相关的常量和变量，如日志标签、I2C 的 SDA 和 SCL 引脚以及端口号。
- 接着，根据不同配置选项安装控制台 REPL 环境，用于用户交互。随后配置 I2C 总线，包括时钟源、端口、引脚和启用内部上拉电阻等，并初始化 I2C 主总线。
- 之后注册一系列 I2C 工具命令，如设备检测、寄存器读写等操作的命令。还打印了使用说明，指导用户如何使用这些命令。
- 最后启动控制台 REPL，允许用户通过命令行与应用程序交互，执行各种 I2C 操作，为用户提供了一种方便的方式通过命令行操作 I2C 总线。
运行效果
-
烧录成功后，打开串口终端，输入命令后按回车即可运行。
使用步骤如下：
- 使用
help检查所有支持的命令 - 使用
i2cconfig配置你的 I2C 总线 - 使用
i2cdetect扫描总线上的设备 - 使用
i2cget获取特定寄存器的内容 - 使用
i2cset设置特定寄存器的值 - 使用
i2cdump转储所有寄存器（实验）
02_RS485_Test
本示例用于测试 RS485 座子：基于 UART 收发回环，收到什么就回传什么。
硬件连接
-
使用 USB 线把板子接入电脑
-
开发板连接 USB 转 RS485 转换器。
代码分析
echo_task()：- 首先配置了 UART 参数，包括波特率、数据位、奇偶校验位、停止位和硬件流控制等。
- 然后安装 UART 驱动，设置 UART 引脚，并分配一个临时缓冲区用于接收数据。
- 在一个无限循环中，从 UART 读取数据，将读取到的数据回写到 UART，并在有数据接收时记录日志信息。
运行效果
-
打开串口调试助手向 ESP32-S3-Touch-LCD-4.3 发送消息，该设备会将收到的消息返回给串口调试助手。
03_SD_Test
本示例用于测试 SD 卡座：初始化 SD 卡并执行基础读写/遍历测试。
硬件连接
- 使用 USB 线把板子接入电脑
代码分析
-
waveshare_sd_card_init()：- 这个函数主要用于初始化 SD 卡。首先初始化 I2C，然后通过 I2C 控制芯片拉低 SD 卡的 CS 引脚。
- 接着配置 SD 卡的挂载选项，包括是否在挂载失败时格式化、最大文件数和分配单元大小等。
- 之后初始化 SPI 总线，并使用配置好的 SPI 总线和挂载选项来挂载 SD 卡文件系统。
- 如果挂载成功则返回
ESP_OK，表示 SD 卡初始化完成。
-
waveshare_sd_card_test()：- 这个函数用于测试 SD 卡的功能。首先打印已初始化的 SD 卡的信息。
- 然后创建一个文件并写入数据，重命名该文件并读取重命名后的文件内容。
- 接着格式化文件系统，检查文件在格式化后是否被删除。
- 最后创建一个新文件并读取其内容，完成测试后卸载 SD 卡并释放 SPI 总线资源。
运行效果
-
烧录成功后，串口会打印有关存储卡的信息，例如名称、类型、容量和支持的最大频率。
-
随后会创建文件、写入文件、重命名文件、读取重命名后的文件。
04_Sensor_AD
本示例用于测试 ADC 座子：读取 ADC 原始值并进行电压校准换算。
硬件连接
- 使用 USB 线把板子接入电脑
- 将 PH2.0 转 2.54mm 杜邦公头配件接入开发板的 Sensor AD 接口
代码分析
app_main()：- 首先定义了用于存储当前 ADC 的一些变量，声明校准函数。
- 接着初始化 ADC，设置 ADC 的分辨率和衰减，然后创建 ADC。
- 在无限循环中，读取当前 ADC 值后打印，循环中还进行了 1 秒钟的延迟。
运行效果
-
开发板会设置 ADC 分辨率，读取当前 AD 值，打印到串口终端。
05_UART_Test
本示例用于测试 UART：收到的数据会原样回传（回环）。
硬件连接
- 使用 USB 线连接板子的 UART 口，接入电脑
代码分析
echo_task()：- 首先配置了 UART 参数，包括波特率、数据位、奇偶校验位、停止位和硬件流控制等。
- 然后安装 UART 驱动，设置 UART 引脚，并分配一个临时缓冲区用于接收数据。
- 在一个无限循环中，从 UART 读取数据，将读取到的数据回写到 UART，并在有数据接收时记录日志信息。
运行效果
-
打开串口调试助手向 ESP32-S3-Touch-LCD-4.3 发送消息，该设备会将收到的消息返回给串口调试助手。
06_TWAItransmit
本示例用于测试 CAN 卡座：初始化 TWAI 并循环发送 CAN 帧。
硬件连接
-
使用 USB 线把板子接入电脑；
-
将 CANH/CANL 接入 CAN 总线，并确保总线端接电阻配置正确。
-
开发板连接 USB-CAN-A。
代码分析
waveshare_twai_transmit()：- 若驱动未安装，等待一段时间后返回失败状态。
- 读取触发的警报并获取 TWAI 状态信息。
- 根据不同警报类型打印相应日志信息，包括错误被动警报、总线错误警报、传输失败警报和传输成功警报，并打印相关状态信息。
- 判断是否到了发送消息的时间，如果是则发送消息并更新上一次发送时间。
运行效果
-
串口打印 CAN 消息发送成功，配置 USB-CAN-A_TOOL 后启动可看到 ESP32-S3-Touch-LCD-4.3 发送的 CAN 消息。
07_TWAIreceive
本示例用于测试 CAN 卡座：初始化 TWAI 并循环接收 CAN 帧。
硬件连接
-
使用 USB 线把板子接入电脑；
-
将 CANH/CANL 接入 CAN 总线，并确保总线端接电阻配置正确。
-
开发板连接 USB-CAN-A。
代码分析
waveshare_twai_receive()：- 如果驱动未安装，则等待一段时间后返回失败状态。
- 读取触发的警报并获取 TWAI 的状态信息。
- 根据触发的不同警报类型打印相应的日志信息，包括错误被动警报、总线错误警报和接收队列满警报，并打印相关的状态信息。
- 如果接收数据警报被触发，则循环接收消息并调用
handle_rx_message函数处理每个接收到的消息。最后返回成功状态。
运行效果
-
ESP32-S3-Touch-LCD-4.3 等待 USB-CAN-A_TOOL 发送消息，如果接收成功，会将其打印到串口上。
08_lvgl_Porting
本示例用于测试 LVGL 移植：初始化 LCD/LVGL 端口并运行 lv_demo_widgets()。
硬件连接
- 使用 USB 线把板子接入电脑；
代码分析
app_main()：- 初始化 Waveshare ESP32-S3 RGB LCD，然后可以选择开启或关闭屏幕背光。
- 接着打印一条信息表示要显示 LVGL 的演示内容，由于 LVGL 的 API 不是线程安全的，所以先锁定互斥锁。
- 然后可以选择运行不同的 LVGL 演示程序，如
lv_demo_stress、lv_demo_benchmark、lv_demo_music、lv_demo_widgets或example_lvgl_demo_ui等。 - 最后释放互斥锁。
代码修改
在 waveshare_rgb_lcd_port.h 中有一宏定义用于选择是否打开触摸功能，值为 0 对应关闭触摸，值为 1 对应打开触摸，可依购买型号选择。
#define CONFIG_EXAMPLE_LCD_TOUCH_CONTROLLER_GT911 0 // 1 initiates the touch, 0 closes the touch.
运行效果
-
烧录成功后，按下复位按键，即可运行示例。
