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 作为教学示例，所有硬件代码均基于其引脚布局。在动手实践前，建议您对照手中的开发板引脚图，确认引脚配置无误。
配置 ESP-IDF 开发环境
请参考 安装 ESP-IDF 开发环境。
ESP32-C5-Touch-LCD-2.8 示例需要 ESP-IDF v5.5.4 版本。
以下内容以 Windows 系统为例，使用 VS Code + ESP-IDF 扩展 的方式进行开发。Mac/Linux 用户请参考 官方说明。
此部分图示以安装 ESP-IDF V5.5.2 为例示范，安装时请选用与您开发板示例匹配的 ESP-IDF 版本。
安装 ESP-IDF 开发环境
-
前往 ESP-IDF Installation Manager 下载 ESP-IDF 安装管理器。这是乐鑫最新推出的跨平台安装工具，下文将演示如何使用其离线安装功能。
在页面中点击 Offline Installer 标签，然后在筛选栏中选择 Windows 操作系统和你需要的 ESP-IDF 版本（图示仅为参考，请以实际为准）。
确认选择无误后，点击下载按钮。浏览器将自动同时下载两个文件：一个是 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 环境,无需手动配置。
示例程序
ESP-IDF 示例程序位于示例程序包的 example/ESP-IDF-V554 目录。各示例工程已经按照 ESP32-C5-Touch-LCD-2.8 的板载硬件资源进行适配，可用于验证显示、触摸、音频、SD 卡、Wi-Fi、传感器和图形界面等功能。
编译和烧录
进入任意 ESP-IDF 示例目录后执行：
cd example/ESP-IDF-V554/02_2048
idf.py build flash monitor
如果需要指定串口，请将 COMx 替换为实际串口号，例如 COM5：
idf.py -p COMx build flash monitor
示例列表
| 示例目录 | 功能 |
|---|---|
01_ch32_test | CH32V003 IO 扩展芯片测试，验证 IO 输出翻转和输入读取功能。 |
02_2048 | 基于 LVGL v9 的 2048 小游戏，支持触摸交互、分数统计和游戏结果提示。 |
03_sd_lvgl | 挂载 Micro SD 卡，读取根目录 Test.txt 文件，并将文本内容显示到 LCD。 |
04_sd_music | 从 SD 卡 /sdcard/music 目录扫描 MP3 文件，并自动播放第一首音乐。 |
05_spiff_music | 从 SPIFFS /music 目录读取 MP3 文件，实现带 LVGL 界面的音乐播放器。 |
06_wifi_weather | 连接指定 Wi-Fi，获取深圳实时天气数据，并在屏幕上显示天气信息。 |
07_Ball_qmi | 读取 QMI8658 加速度数据，实现随开发板倾斜移动的重力小球。 |
08_bookesia | 基于 ESP-Brookesia 框架实现触摸画板应用，并显示状态栏和内存信息。 |
使用说明
- 二次开发时，建议优先修改应用层或 UI 逻辑。BSP 已完成开发板基础硬件资源和底层接口的定义与初始化，常规界面、交互和业务功能修改通常不需要改动 BSP；仅在更换硬件连接、调整底层驱动或适配新外设时，再修改 BSP 相关代码。
01_ch32_test用于测试板载 CH32V003 IO 扩展芯片。CH32V003 出厂时已经烧录好固件，无需单独烧录 CH32 固件，运行 ESP32-C5 示例即可验证 IO 扩展通信和控制功能。02_2048的 UI 基于 GUI Guider 生成，界面布局主要位于components/generated/setup_scr_Game2048.c，事件函数主要位于components/generated/events_init.c，自定义初始化和扩展逻辑位于components/custom/custom.c。03_sd_lvgl运行前，请在 SD 卡根目录放置Test.txt文件。04_sd_music运行前，请在 SD 卡根目录创建music文件夹，并放入.mp3文件。05_spiff_music使用 SPIFFS 中的 MP3 文件，适合配合 LVGL 界面实现音乐播放器效果。06_wifi_weather默认连接weather-wifi热点，密码为12345678，热点支持 2.4GHz 或 5GHz 频段；如需修改热点或城市，请在示例源码中调整对应配置。07_Ball_qmi校准时需要保持开发板水平静止，否则小球可能出现明显偏移。08_bookesia使用 ESP-Brookesia 框架，适合作为触摸 GUI、多应用界面和画板功能的二次开发参考。
01_ch32_test
程序说明
- 本示例用于验证板载 CH32V003 IO 扩展芯片。
- 程序会初始化 I2C 总线和 CH32V003 IO 扩展设备，然后依次测试 IO 输出和输入读取功能。
- 示例先将
IO_EXP_PIN_0到IO_EXP_PIN_7配置为输出模式，并循环输出高低电平；随后切换为输入模式并读取输入状态。
硬件连接
- 将开发板通过 USB 连接到电脑即可。
- 示例仅使用板载 CH32V003 IO 扩展芯片，无需外接模块。
运行效果
- 串口会打印 I2C 初始化、IO 扩展初始化、输出电平切换和输入电平读取结果。
- 若 IO 扩展通信正常，可看到
IO_EXP_PIN_0~7配置、输出和读取成功的日志。
02_2048
程序说明
- 本示例基于 LVGL v9 实现 2048 小游戏。
- UI 界面基于 GUI Guider 生成，工程中的
main.c会依次调用setup_ui()、custom_init()和events_init()完成界面创建、自定义初始化和事件绑定。 - 屏幕显示 4 x 4 数字方块、当前分数、历史最高分以及重新开始按钮。
- 支持通过触摸滑动控制方块移动，程序会自动合并相同数字并更新分数。
- 当合成 2048 时显示胜利提示；无可移动方块时显示游戏结束提示。
- 二次开发时，可参考
components/generated/setup_scr_Game2048.c查看 2048 页面控件布局，参考components/generated/events_init.c查看触摸和按钮事件逻辑，参考components/custom/custom.c查看自定义初始化和业务扩展逻辑。
硬件连接
- 将开发板通过 USB 连接到电脑即可。
- 示例使用板载 LCD 和电容触摸屏，无需外接模块。
运行效果
- LCD 显示 2048 游戏界面。
- 可在触摸屏上滑动操作，实时查看分数变化和游戏结果。
03_sd_lvgl
程序说明
- 本示例用于演示 SD 卡文件读取和 LVGL 屏幕显示。
- 程序启动后会初始化 LCD 和 LVGL 页面，然后挂载 Micro SD 卡。
- 示例会读取 SD 卡根目录下的
Test.txt文件，并将文件内容显示在 LCD 中央。 - 若未检测到 SD 卡或文件读取失败，屏幕会显示对应错误提示。
硬件连接
- 将开发板通过 USB 连接到电脑。
- 将 FAT32 格式的 Micro SD 卡插入卡槽。
- 在 SD 卡根目录放置
Test.txt文件。
运行效果
- LCD 先显示
Waiting for SD card...。 - 成功读取后，屏幕显示
Test.txt中的文本内容。 - 如果没有检测到 SD 卡，则显示
SD card not detected!。
04_sd_music
程序说明
- 本示例用于验证 SD 卡 MP3 音频播放功能。
- 程序会初始化板载 IO 扩展、挂载 SD 卡，并扫描
/sdcard/music目录下的.mp3文件。 - 扫描到音乐文件后，示例会初始化音频驱动和功放，并自动播放第一首 MP3。
- 该示例主要用于验证 SD 卡读取、音频 Codec、功放和喇叭播放链路。
硬件连接
- 将开发板通过 USB 连接到电脑。
- 将 FAT32 格式的 Micro SD 卡插入卡槽。
- 在 SD 卡根目录创建
music文件夹，并放入.mp3音频文件。 - 将喇叭连接到板载 Speaker 接口。
运行效果
- 串口打印扫描到的 MP3 文件列表。
- 程序自动播放扫描到的第一首 MP3 音乐。
- 若 SD 卡挂载失败或未找到 MP3 文件，串口会输出错误提示。
05_spiff_music
程序说明
- 本示例基于 SPIFFS 和 LVGL v9 实现音乐播放器界面。
- 程序会挂载 SPIFFS 文件系统，并扫描
/spiffs/music目录下的.mp3文件。 - 屏幕显示音乐封面和播放控制按钮。
- 点击播放按钮后，程序播放第一首 MP3，同时音乐封面持续旋转。
- 再次点击按钮可暂停播放，封面旋转会停止；继续播放时会从暂停角度恢复旋转。
- 播放完成后，程序会自动停止动画并恢复播放按钮状态。
硬件连接
- 将开发板通过 USB 连接到电脑。
- 将喇叭连接到板载 Speaker 接口。
- 需要提前将 MP3 文件打包到 SPIFFS 的
music目录中。
运行效果
- LCD 显示音乐播放器界面。
- 点击播放按钮后开始播放音乐，并显示旋转的音乐封面动画。
- 支持播放、暂停和播放结束状态恢复。
06_wifi_weather
程序说明
- 本示例用于演示 Wi-Fi 联网和天气数据显示。
- 程序会连接固定 Wi-Fi 热点，并通过 HTTP 请求获取深圳实时天气数据。
- 屏幕显示城市、日期、天气状态、温度、湿度、风速和风向等信息。
- 程序支持 Wi-Fi 断线自动重连。
- 天气数据会定时刷新，成功获取后约每 5 分钟更新一次。
默认 Wi-Fi 配置
| 项目 | 默认值 |
|---|---|
| Wi-Fi 名称 | weather-wifi |
| Wi-Fi 密码 | 12345678 |
| Wi-Fi 频段 | 2.4GHz 或 5GHz 均可 |
| 天气城市 | 深圳 |
| 请求服务器 | cn.apihz.cn |
硬件连接
- 上电前请先开启与示例一致的 Wi-Fi 热点。
- 将开发板通过 USB 连接到电脑并上电。
- 热点可使用 2.4GHz 或 5GHz 频段，但热点名称和密码需要与示例配置保持一致，并确保热点可以正常访问互联网。
- 示例使用板载 LCD 和 Wi-Fi 功能，无需外接模块。
运行效果
- 连接 Wi-Fi 后，屏幕会显示深圳天气信息。
- 若热点未开启或网络异常，程序会持续重试连接和请求。
07_Ball_qmi
程序说明
- 本示例用于演示 QMI8658 加速度传感器和 LVGL 图形交互。
- 程序会初始化 QMI8658，并配置加速度量程为 8G、输出数据率为 500Hz。
- 启动后会进行水平校准，用于消除静止状态下的偏移。
- 校准完成后，屏幕中央生成一个小球，小球会根据开发板倾斜方向实时移动。
- 程序会限制小球移动范围，避免超出屏幕边界和圆角区域。
硬件连接
- 将开发板通过 USB 连接到电脑。
- 示例使用板载 LCD 和 QMI8658 六轴传感器，无需外接模块。
- 校准时请将开发板水平放置在稳定桌面上。
运行效果
- 屏幕显示一个绿色小球。
- 倾斜开发板时，小球会随重力方向移动。
- 串口会打印校准状态和传感器相关日志。
08_bookesia
程序说明
- 本示例基于 ESP-Brookesia 框架实现类似手机系统的图形界面。
- 程序使用 240 x 320 深色主题，支持状态栏、应用管理和触摸交互。
- 示例会安装系统默认应用，并额外安装 Drawing Board 画板应用。
- 画板应用支持通过电容触摸屏进行自由绘图和涂鸦。
- 状态栏时钟会每秒刷新。
- 最近任务界面会周期性显示 SRAM 和 PSRAM 使用情况。
硬件连接
- 将开发板通过 USB 连接到电脑。
- 示例使用板载 LCD 和电容触摸屏，无需外接模块。
运行效果
- LCD 显示 ESP-Brookesia 风格的界面。
- 可通过触摸进入画板应用并进行绘图。
- 系统界面支持状态栏、最近任务和内存信息显示。
