跳到主要内容

ESP-IDF 开发

本章节包含以下内容，请按需阅读：

ESP-IDF 入门教程​

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

请注意：该教程使用 ESP32-S3-Zero 作为教学示例，所有硬件代码均基于其引脚布局。在动手实践前，建议您对照手中的开发板引脚图，确认引脚配置无误。

配置 ESP-IDF 开发环境​

请参考 安装 ESP-IDF 开发环境。

版本说明

ESP32-C5-LCD-2.73 示例使用 ESP-IDF v5.5.3，工程目标芯片为 esp32c5。如使用其它 ESP-IDF 版本，请以示例工程中的 dependencies.lock 和 sdkconfig 为准。

备注

以下内容以 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-IDF 示例程序位于示例程序包的 code/idf 目录。各示例工程已经按照 ESP32-C5-LCD-2.73 的板载硬件资源进行适配，可用于验证 LCD、LVGL、Micro SD、QMI8658、PCF85063、SHTC3 和 CH32V003 IO 扩展等功能。

编译和烧录​

进入任意 ESP-IDF 示例目录后执行：

cd code/idf/02_lvgl_demo
idf.py build flash monitor

如果需要指定串口，请将 COMx 替换为实际串口号，例如 COM5：

idf.py -p COMx build flash monitor

板载资源​

功能器件或接口引脚或说明
LCDILI9488，SPI，320 x 320，RGB666SCLK GPIO6，MOSI GPIO7，MISO GPIO5，DC GPIO4，CS GPIO8
LCD 复位CH32V003 IO 扩展IO0
LCD 背光CH32V003 PWMIO 扩展 PWM
IO 扩展CH32V003，I2C 地址 0x24SDA GPIO27，SCL GPIO26
六轴传感器QMI8658，I2C 地址 0x6BSDA GPIO27，SCL GPIO26
RTCPCF85063，I2C 地址 0x51SDA GPIO27，SCL GPIO26
温湿度传感器SHTC3，I2C 地址 0x70SDA GPIO27，SCL GPIO26
Micro SDSDSPISCLK GPIO6，MOSI GPIO7，MISO GPIO5，CS GPIO9
BOOT 按键用户按键GPIO28

示例列表​

示例目录功能
01_factory工厂示例，包含主菜单、设置、传感器、相册和天气页面。
02_lvgl_demo初始化 LCD 和 LVGL，运行 LVGL benchmark 示例。
03_sd_card挂载 Micro SD 卡，写入并读回测试文件。
04_qmi8658读取 QMI8658 加速度和陀螺仪数据，并通过串口输出。
05_pcf85063读取 PCF85063 RTC 时间，并通过串口周期输出。
06_shtc3读取 SHTC3 温湿度数据，并通过串口周期输出。
07_exio测试 CH32V003 IO 扩展，循环翻转 IO4~IO14 输出电平。

使用说明​

  • 二次开发时，建议优先修改应用层或 UI 逻辑。BSP 已完成开发板基础硬件资源和底层接口的定义与初始化；仅在更换硬件连接、调整底层驱动或适配新外设时，再修改 BSP 相关代码。
  • 01_factory、02_lvgl_demo 使用 LVGL v9.5.0 和 esp_lvgl_adapter。
  • 01_factory 和 03_sd_card 运行前建议插入 FAT 或 FAT32 格式的 Micro SD 卡。
  • 01_factory 的相册页面默认读取 /sdcard/photo 目录下的 .jpg 或 .jpeg 图片。
  • 本产品共用一组 I2C：SDA GPIO27、SCL GPIO26，CH32V003、QMI8658、PCF85063 和 SHTC3 都在该 I2C 总线上。
  • 07 示例是 EXIO 扩展 IO 测试，主要观察 IO 输出或串口运行状态，不配置运行效果图片。

01_factory​

程序说明​

  • 本示例为出厂应用示例，启动后初始化 NVS、Micro SD、CH32V003 IO 扩展、PCF85063 RTC、LCD、LVGL 和应用菜单。
  • 程序会从 RTC 同步系统时间，并在状态栏中显示时间和 Wi-Fi 状态。
  • 菜单中注册 Settings、Sensor、Photo 和 Weather 应用。
  • Settings 页面包含 Wi-Fi、背光、TF 卡容量、电池信息和 About 等项目。
  • Sensor 页面显示 QMI8658 加速度、陀螺仪数据，以及 SHTC3 温湿度数据。
  • Photo 页面读取 /sdcard/photo 目录下的 JPG 图片，并提供上一张、下一张和返回控制。
  • Weather 页面用于显示天气信息，需先通过设置页面配置 Wi-Fi。

硬件连接​

  • 将开发板通过 USB 连接到电脑。
  • 如需使用相册页面，请插入 FAT 或 FAT32 格式的 Micro SD 卡，并在 SD 卡中创建 photo 目录后放入 .jpg 或 .jpeg 图片。
  • 如需使用天气页面，请配置可联网的 Wi-Fi。

代码入口​

01_factory/main/main.c
01_factory/components/app_settings
01_factory/components/app_sensor
01_factory/components/app_photo
01_factory/components/app_weather
01_factory/components/waveshare__esp32_c5_lcd_2_73

建议优先查看：

代码作用
system_manage_service_init()初始化系统管理服务
bsp_sdcard_mount()挂载 Micro SD 卡
bsp_io_expander_init()初始化 CH32V003 IO 扩展
bsp_pcf85063a_drv_init()初始化 PCF85063 RTC
bsp_display_start()初始化 LCD 和 LVGL
butmenu_register_app()注册 Settings、Sensor、Photo、Weather 应用

运行效果​

  • LCD 显示工厂菜单主界面。
  • 可通过按键进入设置、传感器、相册和天气页面。
  • 状态栏每秒更新时间，Wi-Fi 连接后状态图标会变化。
主界面设置页面
ESP32-C5-LCD-2.73 ESP-IDF factory main page
ESP32-C5-LCD-2.73 ESP-IDF factory settings page
传感器页面天气页面
ESP32-C5-LCD-2.73 ESP-IDF factory sensor page
ESP32-C5-LCD-2.73 ESP-IDF factory weather page
相册页面
ESP32-C5-LCD-2.73 ESP-IDF factory photo page

常见排查​

现象可能原因处理方法
相册页面提示无图片SD 卡未挂载、目录不存在或图片格式不匹配确认 SD 卡中存在 /photo 目录，并放入 .jpg 或 .jpeg 图片
天气页面无数据Wi-Fi 未连接或网络不可用在设置页面配置 Wi-Fi，并确认热点可以访问互联网
传感器页面无数据I2C 外设初始化失败先分别运行 04_qmi8658、05_pcf85063、06_shtc3 和 07_exio

02_lvgl_demo​

程序说明​

  • 本示例用于验证 LCD、背光和 LVGL 图形刷新。
  • 程序初始化 NVS、CH32V003 IO 扩展、ILI9488 LCD、LVGL 和背光。
  • 初始化完成后调用 lv_demo_benchmark()，运行 LVGL benchmark 示例。

硬件连接​

  • 将开发板通过 USB 连接到电脑即可。
  • 示例使用板载 LCD 和背光，无需外接模块。

代码入口​

02_lvgl_demo/main/main.c
02_lvgl_demo/components/waveshare__esp32_c5_lcd_2_73

建议优先查看：

代码作用
bsp_io_expander_init()初始化 CH32V003 IO 扩展
IO_EXTENSION_Output(IO_EXTENSION_IO_0, ...)控制 LCD 复位
bsp_display_start()初始化 LCD 和 LVGL
bsp_display_backlight_on()打开背光
lv_demo_benchmark()运行 LVGL benchmark

运行效果​

  • LCD 显示 LVGL benchmark 画面。
  • 串口会输出 LCD、LVGL 和 benchmark 相关日志。
ESP32-C5-LCD-2.73 ESP-IDF LVGL demo

常见排查​

现象可能原因处理方法
屏幕不亮CH32V003、LCD 复位、背光或 SPI 初始化异常先运行 07_exio，再恢复 BSP 中 LCD 相关引脚定义
显示异常LCD 色彩格式或分辨率配置被修改确认 BSP_LCD_H_RES、BSP_LCD_V_RES 为 320，BSP_LCD_BITS_PER_PIXEL 为 18

03_sd_card​

程序说明​

  • 本示例用于验证 Micro SD 卡读写。
  • 程序先将 LCD CS GPIO8 设置为高电平，避免 LCD 与 SD 卡共用 SPI 总线时发生片选冲突。
  • 然后调用 bsp_sdcard_mount() 挂载 SD 卡，挂载点为 /sdcard。
  • 挂载成功后，程序写入 /sdcard/test.txt，再读回并校验内容。

硬件连接​

  • 将开发板通过 USB 连接到电脑。
  • 插入 FAT 或 FAT32 格式的 Micro SD 卡。

代码入口​

03_sd_card/main/main.c
03_sd_card/components/waveshare__esp32_c5_lcd_2_73

建议优先查看：

代码作用
BSP_LCD_CSLCD CS，GPIO8，测试前拉高
bsp_sdcard_mount()挂载 Micro SD 卡
BSP_SD_MOUNT_POINTSD 卡挂载点，默认 /sdcard
tf_card_read_write_test()写入、读回和校验测试文件
sdmmc_card_print_info()打印 SD 卡信息

运行效果​

  • 串口打印 SD 卡信息。
  • 测试通过后输出 TF CARD TEST PASS。
ESP32-C5-LCD-2.73 ESP-IDF SD card test

常见排查​

现象可能原因处理方法
SD 卡挂载失败未插卡、卡格式异常或接触不良使用 FAT/FAT32 格式 Micro SD 卡，重新插拔后再测试
文件写入或读回失败文件系统异常或卡不可写更换 SD 卡或重新格式化后测试
与 LCD 示例切换后异常SPI 总线或片选状态残留重新上电后单独运行 03_sd_card

04_qmi8658​

程序说明​

  • 本示例用于验证板载 QMI8658 六轴传感器。
  • 程序调用 bsp_qmi8658_drv_init() 初始化 QMI8658。
  • 数据单位配置为加速度 m/s^2、陀螺仪 dps。
  • 主循环每 200 ms 检查一次数据就绪状态，读取后通过串口输出。

硬件连接​

  • 将开发板通过 USB 连接到电脑即可。
  • 示例使用板载 QMI8658，无需外接模块。

代码入口​

04_qmi8658/main/main.c
04_qmi8658/components/waveshare__esp32_c5_lcd_2_73

建议优先查看：

代码作用
bsp_qmi8658_drv_init()初始化 QMI8658
qmi8658_set_accel_unit_mps2()将加速度单位设置为 m/s^2
qmi8658_set_gyro_unit_dps()将陀螺仪单位设置为 dps
qmi8658_is_data_ready()检查数据是否就绪
qmi8658_read_sensor_data()读取加速度和陀螺仪数据

运行效果​

  • 串口周期输出加速度和陀螺仪数据。
  • 轻微转动开发板时，输出数据会随姿态变化。
ESP32-C5-LCD-2.73 ESP-IDF QMI8658 test

常见排查​

现象可能原因处理方法
初始化失败I2C 通信异常确认 I2C 使用 SDA GPIO27、SCL GPIO26，并先运行 07_exio 或 06_shtc3
数据无变化开发板静止或数据未更新轻微转动开发板，并确认串口监视器仍在运行

05_pcf85063​

程序说明​

  • 本示例用于验证板载 PCF85063 RTC。
  • 程序调用 bsp_pcf85063a_drv_init() 初始化 RTC。
  • 主循环每秒调用 pcf85063a_get_time_date() 读取日期、时间和星期，并通过串口输出。

硬件连接​

  • 将开发板通过 USB 连接到电脑即可。
  • 示例使用板载 PCF85063，无需外接模块。

代码入口​

05_pcf85063/main/main.c
05_pcf85063/components/waveshare__esp32_c5_lcd_2_73

建议优先查看：

代码作用
bsp_pcf85063a_drv_init()初始化 PCF85063 RTC
pcf85063a_get_time_date()读取 RTC 日期和时间
pcf85063a_datetime_tRTC 日期时间结构体

运行效果​

  • 串口每秒输出一次 RTC 时间。
ESP32-C5-LCD-2.73 ESP-IDF PCF85063 test

常见排查​

现象可能原因处理方法
RTC 读取失败PCF85063 I2C 通信异常确认 I2C 使用 SDA GPIO27、SCL GPIO26，并测试其它 I2C 示例
时间不符合预期RTC 未设置或电池供电状态异常先运行 01_factory 同步系统时间，或在代码中增加设置 RTC 时间的逻辑

06_shtc3​

程序说明​

  • 本示例用于验证板载 SHTC3 温湿度传感器。
  • 程序延时 1 秒后调用 bsp_shtc3_drv_init() 初始化 SHTC3。
  • 主循环每秒调用 shtc3_get_th() 读取温度和湿度，并通过串口输出。

硬件连接​

  • 将开发板通过 USB 连接到电脑即可。
  • 示例使用板载 SHTC3，无需外接模块。

代码入口​

06_shtc3/main/main.c
06_shtc3/components/waveshare__esp32_c5_lcd_2_73

建议优先查看：

代码作用
bsp_shtc3_drv_init()初始化 SHTC3
shtc3_get_th()读取温度和湿度
SHTC3_REG_T_CSD_NM温度优先、正常模式测量命令

运行效果​

  • 串口每秒输出一次温度和湿度。
ESP32-C5-LCD-2.73 ESP-IDF SHTC3 test

常见排查​

现象可能原因处理方法
初始化失败SHTC3 I2C 通信异常确认 I2C 使用 SDA GPIO27、SCL GPIO26，确认开发板供电正常
温湿度读取失败传感器未正确响应或 I2C 数据异常重新上电后再测试，并对照 04_qmi8658 或 05_pcf85063 判断 I2C 是否正常

07_exio​

程序说明​

  • 本示例用于验证 CH32V003 IO 扩展输出控制。
  • 程序调用 bsp_io_expander_init() 初始化 CH32V003。
  • 示例将 IO 扩展引脚模式配置为 0xFFF7，然后每秒翻转 IO4~IO14 的输出电平。
  • CH32V003 出厂时已经烧录好固件，无需单独烧录 CH32 固件。

硬件连接​

  • 将开发板通过 USB 连接到电脑即可。
  • 示例使用板载 CH32V003 IO 扩展芯片，无需外接模块。

代码入口​

07_exio/main/main.c
07_exio/components/waveshare__esp32_c5_lcd_2_73

建议优先查看：

代码作用
bsp_io_expander_init()初始化 CH32V003 IO 扩展
IO_EXTENSION_IO_Mode(0xFFF7)配置 IO 扩展引脚模式
IO_EXTENSION_Output()设置指定 IO 扩展引脚输出电平
IO_EXTENSION_IO_4 / IO_EXTENSION_IO_14输出翻转范围

运行效果​

  • IO4~IO14 每秒翻转一次输出电平。
  • 该示例不配置运行效果图片。

常见排查​

现象可能原因处理方法
后续 LCD 或背光示例异常CH32V003 未正常通信先确认 07_exio 可以运行，再排查 LCD 复位和背光控制
IO 输出无变化IO 扩展初始化失败或输出范围被修改保留示例中的 IO_EXTENSION_IO_Mode(0xFFF7) 和 IO4~IO14 输出范围