跳到主要内容

ESP-IDF 开发

本节介绍 ESP-IDF 基础示例的编译、烧录、操作方法和运行现象。准备开发板及 USB 数据线,并下载 ESP32-C5-Touch-LCD-2.8 示例程序。

本章节包含以下部分,请按需阅读:

ESP-IDF 入门教程​

初次接触 ESP32 ESP-IDF 开发,想要快速上手?我们为您准备了一套通用的 入门教程。

请注意:该教程使用 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 开发环境​

  1. 前往 ESP-IDF Installation Manager 下载 ESP-IDF 安装管理器。这是乐鑫最新推出的跨平台安装工具,下文将演示如何使用其离线安装功能。

    在页面中点击 Offline Installer 标签,然后在筛选栏中选择 Windows 操作系统和你需要的 ESP-IDF 版本(图示仅为参考,请以实际为准)。

    下载 EIM 和整合包

    确认选择无误后,点击下载按钮。浏览器将自动同时下载两个文件:一个是 ESP-IDF 离线整合包(.zst),另一个是 ESP-IDF 安装器(.exe)。

    下载 EIM 和整合包2

    请耐心等待两个文件下载完成。

  2. 下载完成后,双击运行 ESP-IDF 安装器(eim-gui-windows-x64.exe)。

    启动后,可在右上角将界面语言切换为中文。

    切换 EIM 语言

    安装工具会自动检测同一目录下是否存在离线整合包。点击 从存档安装。

    自动检测整合包

    接下来,选择安装路径。建议使用默认路径;若需自定义,请确保路径中不包含中文或空格。确认无误后,点击 开始安装。

    选择安装路径
  3. 当看到如下界面时,表示 ESP-IDF 已安装成功。

    安装成功
  4. 建议同时安装驱动程序。点击 完成安装,然后点击 安装驱动程序。

    用 ESP-IDF 安装管理器安装驱动

安装 Visual Studio Code 与 ESP-IDF 扩展​

  1. 下载并安装 Visual Studio Code。

  2. 安装时建议勾选 通过 Code 打开操作添加到 Windows 资源管理器文件上下文菜单,以便快速打开项目文件夹。

  3. 在 VS Code 中,点击侧边活动栏中的 扩展图标 扩展图标(或使用快捷键 Ctrl + Shift + X)打开 扩展 视图。

  4. 在搜索框中输入 ESP-IDF,找到 ESP-IDF 扩展并点击安装。

    在 VS Code 中搜索并安装 ESP-IDF 扩展

  5. 当 ESP-IDF 扩展版本 ≥ 2.0 时,扩展会自动检测并识别上述步骤中安装的 ESP-IDF 环境,无需手动配置。

环境或组件版本或配置说明
ESP-IDFv5.5.4使用与工程一致的 SDK 版本
目标芯片esp32c5工程已设置,无需更换目标
LVGL9.5.0由工程依赖配置管理
板级支持包components/esp32_c5_touch_lcd_2_8各示例自带,包含显示、触摸及板载外设适配
串口波特率115200用于基础示例日志

首次构建时会按工程的依赖配置下载所需组件。请保留原有组件配置和依赖锁定文件,不要将 Arduino 的库文件复制到 ESP-IDF 工程中。

编译和烧录​

  1. 在 VS Code 中选择已安装的 ESP-IDF v5.5.4 环境。

  2. 打开要运行的单个示例目录,例如 examples/esp-idf/01_lvgl_demo。目录中应包含 CMakeLists.txt,工程已设置目标芯片为 ESP32-C5。

  3. 通过 USB 连接开发板,在该示例目录打开 ESP-IDF 终端。

  4. 执行以下命令编译、烧录并查看串口日志,将 COM5 替换为实际串口:

    idf.py build
    idf.py -p COM5 flash monitor
  5. 串口监视器使用 115200 波特率。烧录后按下文检查结果,按 Ctrl+] 退出监视器。

每个示例自带板级支持包(BSP,Board Support Package)和本地驱动,可复制完整的单个示例目录使用;保留其 components、配置文件和依赖锁定文件。

基础示例与出厂桌面

烧录基础示例后,开发板会运行该示例。天气、音乐播放器、小智 AI 和 2048 等完整 APP 位于独立的出厂工程 examples/factory。需要恢复桌面时,重新烧录 ESP32-C5-Touch-LCD-2.8 出厂固件。

示例程序​

示例位于源码包的 examples/esp-idf 目录。以下每个示例均为独立工程,打开对应目录后,按 编译和烧录 中的步骤运行。

示例目录功能查看结果
01_lvgl_demoLVGL widgets 显示与触摸LCD
02_sd_card写入、读回并校验 SD 卡测试文件LCD、串口
03_qmi8658三轴加速度和角速度串口
04_pcf85063RTC 设置与读取串口
05_shtc3温湿度读取及 CRC 校验串口
06_exioEXIO6/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、触摸及背光初始化是否报错。

01_lvgl_demo 显示与触摸运行效果

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 重试。写入、读取或校验失败时,结合屏幕提示和串口日志检查对应步骤。

SD 初始化日志

单独出现 cmd=5 ... command not supported 不代表测试失败。该命令用于探测 SDIO 功能,普通存储卡可能不支持,应以后续挂载、写入及读回校验结果为准。

02_sd_card 读写校验成功及文件内容显示

03_qmi8658​

程序说明​

读取板载 QMI8658 六轴传感器,通过串口输出三轴加速度和角速度。

硬件连接​

使用 USB 数据线连接开发板与电脑,无需外接传感器。

代码分析​

  • bsp_imu_init():初始化运动传感器。
  • bsp_imu_get_data():读取三轴加速度和角速度,成功时输出数据,失败时打印错误码。
  • 主循环通过 vTaskDelay() 设置约 500 ms 的读取间隔。

运行效果​

串口约每 500 ms 输出三轴加速度 Accel [g] 和角速度 gyro [deg/s]。轻轻倾斜或转动开发板,数据随之变化;静止时仍会测到重力,各轴不一定为零。

本示例不初始化 LCD,屏幕黑屏属于正常现象。

03_qmi8658 加速度和角速度串口日志

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 后重新编译烧录。

04_pcf85063 日期和时间串口日志

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 错误时,重新上电并查看日志;测量环境温湿度时,不要遮住或弄湿传感器。

05_shtc3 温度和相对湿度串口日志

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 用于板载器件,请勿随意翻转。

06_exio 扩展 IO 电平和背光 PWM 串口日志

07_audio​

程序说明​

使用触摸界面监测麦克风电平,并支持录音、停止和回放。录音保存在内存中,无需 SD 卡或网络。

硬件连接​

上电前接好匹配的喇叭,再使用 USB 数据线连接开发板与电脑。

代码分析​

  • main/main.cpp:初始化显示,调用 MicTest::init() 和 MicTest::run() 创建录音界面并启动后台任务。
  • MicTest::event():响应录音、停止和播放按钮。
  • MicTest::work():采集麦克风 PCM 数据、计算电平,按当前状态录音或回放;录音缓冲区最多保存 10 秒音频。
  • MicTest::refresh():更新音量条、状态和时长显示。

运行效果​

该独立示例沿用出厂 Mic Test 的触摸操作。启动后按以下步骤体验:

  1. 对着板载麦克风说话,观察音量条和电平百分比变化。
  2. 点击 "Record" 开始录音,屏幕显示 REC 和已录时长。
  3. 点击 "Stop" 提前结束,或等待录满 10 秒后自动停止。
  4. 点击 "Play" 回放录音;播放时可点击 "Stop" 中止,结束后可再次回放。

录音参数为 16 kHz、单声道、16 位,默认回放音量为 100/100。录音临时保存在内存中,新录音覆盖上一段,复位或断电后清除,不写入 SD 卡或 Flash。

未录音时 "Play" 按钮不可用。监测电平时喇叭保持静音,不会实时外放麦克风声音。若回放无声,检查喇叭连接、录音时长和屏幕错误提示。

07_audio 麦克风录音与回放界面

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 分压,需要核对精度时可用万用表比较。

08_battery_voltage 电池电压与 ADC 串口日志

08_battery_voltage 电池电压屏幕显示

常见问题​

  • **切换 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。