ESP-IDF 开发
本节介绍 ESP-IDF 基础示例的编译、烧录、操作方法和运行现象。准备开发板及 USB 数据线,并下载 ESP32-C5-Touch-LCD-2.8 示例程序。
本章节包含以下部分,请按需阅读:
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 开发环境安装教程 安装环境。
本文使用 ESP-IDF v5.5.4,基础示例共 8 个,位于 examples/esp-idf。图形界面使用 LVGL 9.5.0,与 Arduino 示例使用的 LVGL 8.4.0 不同。
以下内容以 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 | v5.5.4 | 使用与工程一致的 SDK 版本 |
| 目标芯片 | esp32c5 | 工程已设置,无需更换目标 |
| LVGL | 9.5.0 | 由工程依赖配置管理 |
| 板级支持包 | components/esp32_c5_touch_lcd_2_8 | 各示例自带,包含显示、触摸及板载外设适配 |
| 串口波特率 | 115200 | 用于基础示例日志 |
首次构建时会按工程的依赖配置下载所需组件。请保留原有组件配置和依赖锁定文件,不要将 Arduino 的库文件复制到 ESP-IDF 工程中。
编译和烧录
-
在 VS Code 中选择已安装的 ESP-IDF v5.5.4 环境。
-
打开要运行的单个示例目录,例如
examples/esp-idf/01_lvgl_demo。目录中应包含CMakeLists.txt,工程已设置目标芯片为 ESP32-C5。 -
通过 USB 连接开发板,在该示例目录打开 ESP-IDF 终端。
-
执行以下命令编译、烧录并查看串口日志,将
COM5替换为实际串口:idf.py buildidf.py -p COM5 flash monitor -
串口监视器使用 115200 波特率。烧录后按下文检查结果,按
Ctrl+]退出监视器。
每个示例自带板级支持包(BSP,Board Support Package)和本地驱动,可复制完整的单个示例目录使用;保留其 components、配置文件和依赖锁定文件。
烧录基础示例后,开发板会运行该示例。天气、音乐播放器、小智 AI 和 2048 等完整 APP 位于独立的出厂工程 examples/factory。需要恢复桌面时,重新烧录 ESP32-C5-Touch-LCD-2.8 出厂固件。
示例程序
示例位于源码包的 examples/esp-idf 目录。以下每个示例均为独立工程,打开对应目录后,按 编译和烧录 中的步骤运行。
| 示例目录 | 功能 | 查看结果 |
|---|---|---|
| 01_lvgl_demo | LVGL widgets 显示与触摸 | LCD |
| 02_sd_card | 写入、读回并校验 SD 卡测试文件 | LCD、串口 |
| 03_qmi8658 | 三轴加速度和角速度 | 串口 |
| 04_pcf85063 | RTC 设置与读取 | 串口 |
| 05_shtc3 | 温湿度读取及 CRC 校验 | 串口 |
| 06_exio | EXIO6/7 电平及背光 PWM 切换 | 串口、电平及背光变化 |
| 07_audio | 触摸录音、电平监测和回放 | LCD、喇叭 |
| 08_battery_voltage | 电池电压与 ADC 原始值 | LCD、串口 |
01_lvgl_demo
程序说明
使用板级支持包初始化屏幕和触摸,运行 LVGL 9 的 widgets 控件演示。
硬件连接
使用 USB 数据线连接开发板与电脑,无需 SD 卡或喇叭。
代码分析
bsp_display_start():初始化显示、触摸和 LVGL 运行环境。bsp_display_lock()与bsp_display_unlock():在创建控件时保护 LVGL 操作。lv_demo_widgets():创建控件演示界面;随后调用bsp_display_show(),在首帧完成后点亮屏幕。
运行效果
编译烧录后,屏幕在首帧完成后点亮,并显示 LVGL widgets 演示页面。点击控件、拖动滑块,检查触摸交互是否正常;按 RESET 可重新启动演示。
若屏幕持续不亮,查看串口中 LCD、触摸及背光初始化是否报错。

02_sd_card
程序说明
向 SD 卡写入测试文件,读回并比较内容,在串口和 LCD 上显示测试结果。
硬件连接
每次运行会覆盖 SD 卡根目录下的 test.txt。请先备份同名文件,使用 FAT32 格式测试卡。本 IDF 示例不会格式化 SD 卡。
上电前插入 SD 卡,再使用 USB 数据线连接开发板与电脑,无需预先创建测试文件。
代码分析
run_sd_test():通过bsp_sdcard_acquire()挂载 SD 卡,以覆盖方式写入test.txt,再读取文件、比较长度和内容。- 测试完成后释放并卸载 SD 卡,保留文件供电脑查看。
show_result():创建 LVGL 结果界面,显示状态、文件路径和读回内容。SD 卡访问在 LCD 初始化之前完成,避免同时占用两者共用的 SPI 总线。
运行效果
程序先向 SD 卡写入测试内容,再读回并校验,完成后点亮屏幕显示结果。成功时:
-
串口依次输出
SD card mounted、Write successful、Read successful和Write/read verification: ESP_OK。 -
屏幕显示
Write / read passed、文件路径/sdcard/test.txt和以下读回内容:ESP32-C5-Touch-LCD-2.8 SD test
校验完成并成功卸载 SD 卡后,屏幕保留结果,可取卡在电脑中查看根目录的 test.txt。按 RESET 可重新测试。
未插卡或挂载失败时,屏幕显示 SD card not mounted,插入 FAT32 卡后按 RESET 重试。写入、读取或校验失败时,结合屏幕提示和串口日志检查对应步骤。
单独出现 cmd=5 ... command not supported 不代表测试失败。该命令用于探测 SDIO 功能,普通存储卡可能不支持,应以后续挂载、写入及读回校验结果为准。

03_qmi8658
程序说明
读取板载 QMI8658 六轴传感器,通过串口输出三轴加速度和角速度。
硬件连接
使用 USB 数据线连接开发板与电脑,无需外接传感器。
代码分析
bsp_imu_init():初始化运动传感器。bsp_imu_get_data():读取三轴加速度和角速度,成功时输出数据,失败时打印错误码。- 主循环通过
vTaskDelay()设置约 500 ms 的读取间隔。
运行效果
串口约每 500 ms 输出三轴加速度 Accel [g] 和角速度 gyro [deg/s]。轻轻倾斜或转动开发板,数据随之变化;静止时仍会测到重力,各轴不一定为零。
本示例不初始化 LCD,屏幕黑屏属于正常现象。

04_pcf85063
程序说明
设置板载 PCF85063 实时时钟(RTC,Real-Time Clock),并通过串口定时读取日期和时间。
硬件连接
使用 USB 数据线连接开发板与电脑,无需外接时钟模块。
代码分析
bsp_rtc_init():初始化 RTC。initial:保存启动时的演示时间;bsp_rtc_set_datetime()将其写入 RTC。bsp_rtc_get_datetime():在循环中读取日期和时间,约每秒输出一次。
运行效果
启动时将板载 RTC 设置为 2026 年 10 月 24 日 12:00:00,串口每秒输出一次日期和时间,秒数持续递增。本示例不点亮屏幕。
每次复位都会重新写入演示时间,不进行联网校时。如需修改起始日期,调整 main/main.c 中的 initial 后重新编译烧录。

05_shtc3
程序说明
读取板载 SHTC3 的环境温度和相对湿度,校验数据后通过串口输出。
硬件连接
使用 USB 数据线连接开发板与电脑,无需 SD 卡或外接传感器。
代码分析
bsp_environment_init():初始化温湿度传感器。bsp_environment_get_data():读取温度和湿度,底层驱动执行循环冗余校验(CRC,Cyclic Redundancy Check)。- 主循环每秒读取一次,成功时输出摄氏温度和相对湿度,失败时输出错误码。
运行效果
串口约每秒输出一次环境温度和相对湿度,例如 25.00 C; 50.00 %RH。读取时校验传感器返回数据的 CRC。本示例不点亮屏幕。
出现 I2C 或 CRC 错误时,重新上电并查看日志;测量环境温湿度时,不要遮住或弄湿传感器。

06_exio
程序说明
通过板载 CH32V003 控制 EXIO6/7 输出电平,以及背光的脉宽调制(PWM,Pulse Width Modulation)值。
硬件连接
使用 USB 数据线连接开发板与电脑;可用万用表测量 EXIO6/7 排针相对 GND 的电平。
代码分析
bsp_io_expander_init():初始化 IO 扩展器,再获取控制句柄。esp_io_expander_set_dir():只将 EXIO6/7 配置为输出。esp_io_expander_set_level()与custom_io_expander_set_pwm():每秒切换输出电平和背光 PWM,并通过串口打印状态。
运行效果
运行后每秒翻转 EXIO6/7 输出,并在 PWM 0 与 255 之间切换背光。串口交替显示:
EXIO6/7=0; backlight PWM=0
EXIO6/7=1; backlight PWM=255
背光明暗切换属于预期现象,LCD 不显示应用界面。CH32V003 已预装控制固件,无需另行烧录;本示例仅使用 EXIO6/7 测试,其他扩展 IO 用于板载器件,请勿随意翻转。

07_audio
程序说明
使用触摸界面监测麦克风电平,并支持录音、停止和回放。录音保存在内存中,无需 SD 卡或网络。
硬件连接
上电前接好匹配的喇叭,再使用 USB 数据线连接开发板与电脑。
代码分析
main/main.cpp:初始化显示,调用MicTest::init()和MicTest::run()创建录音界面并启动后台任务。MicTest::event():响应录音、停止和播放按钮。MicTest::work():采集麦克风 PCM 数据、计算电平,按当前状态录音或回放;录音缓冲区最多保存 10 秒音频。MicTest::refresh():更新音量条、状态和时长显示。
运行效果
该独立示例沿用出厂 Mic Test 的触摸操作。启动后按以下步骤体验:
- 对着板载麦克风说话,观察音量条和电平百分比变化。
- 点击 "Record" 开始录音,屏幕显示
REC和已录时长。 - 点击 "Stop" 提前结束,或等待录满 10 秒后自动停止。
- 点击 "Play" 回放录音;播放时可点击 "Stop" 中止,结束后可再次回放。
录音参数为 16 kHz、单声道、16 位,默认回放音量为 100/100。录音临时保存在内存中,新录音覆盖上一段,复位或断电后清除,不写入 SD 卡或 Flash。
未录音时 "Play" 按钮不可用。监测电平时喇叭保持静音,不会实时外放麦克风声音。若回放无声,检查喇叭连接、录音时长和屏幕错误提示。

08_battery_voltage
程序说明
通过 CH32V003 获取电池 ADC 采样值,换算电压,并在 LCD 和串口中显示。
硬件连接
将匹配的电池接到电池座,接入前核对正负极,再使用 USB 数据线连接电脑。
代码分析
app_main():初始化 IO 扩展器和显示,创建电压标签,随后循环读取数据。bsp_battery_get_voltage():读取八次 ADC 数据并取平均,使用标称 3.3 V 参考电压和 3:1 分压计算电池电压。- 每秒更新 LCD 和串口输出;更新标签时使用显示锁,读取失败时显示
ADC read failed。
运行效果
LCD 和串口约每秒更新一次估算电池电压及 ADC 原始值。屏幕显示 Battery voltage、电压及 ADC: ... / 1023;显示的是电压,不是剩余电量百分比。
未接电池或接触不良时,读数可能为零或异常。程序对八次 ADC 采样取平均,使用标称 3.3 V 参考电压和 3:1 分压,需要核对精度时可用万用表比较。


常见问题
- **切换 IDF 后编译报错:**确认当前终端使用 v5.5.4,执行
idf.py fullclean后重新编译,不沿用其他 IDF 版本生成的构建缓存。 - **出现
esp_timer_stop_blocking错误:**检查 IDF 与显示适配组件版本是否匹配,使用指定的 v5.5.4 和随工程提供的依赖配置重新构建。 - **无串口输出:**检查 USB 数据线、串口选择及 115200 波特率,关闭其他占用串口的软件,再按 RESET。
- **屏幕不亮:**先对照示例列表确认是否有显示界面;传感器串口示例不会点亮屏幕。
更多问题参见 ESP32-C5-Touch-LCD-2.8 产品 FAQ。