| 资源 | 说明 |
|---|---|
| 主控模组 | ESP32-C5-WROOM-1-N32R8 |
| 显示屏 | 2.73 英寸 LCD,ILI9488,320 x 320 |
| 存储扩展 | Micro SD 卡槽 |
| 姿态传感器 | QMI8658 六轴传感器 |
| 实时时钟 | PCF85063 RTC |
| 温湿度传感器 | SHTC3 |
| IO 扩展 | CH32V003,I2C 地址 0x24 |
| 电源 | USB Type-C 供电,预留 3.7 V 锂电池接口 |

ESP32-C5-LCD-2.73 支持 Arduino IDE 和 ESP-IDF 两种开发框架,可根据工程需求选择开发工具。
Arduino IDE 是开源电子原型开发平台,适合验证 LCD、Micro SD、I2C 传感器、RTC、温湿度传感器和 EXIO 等基础示例。
ESP-IDF 全称 Espressif IoT Development Framework,是乐鑫科技为 ESP 系列芯片推出的开发框架,包含编译器、调试器、烧录工具等,支持命令行或配合 Visual Studio Code 插件进行开发。
本章节包含以下内容,请按需阅读:
运行示例前,请确认以下条件已经满足:
01_lvgl_demo 或 07_example,请安装示例包内置的 libraries/lvgl。04_I2C_pcf85063 或 07_example,请安装 SensorLib,用于提供 SensorPCF85063.hpp。初次接触 Arduino ESP32 开发,想要快速上手?我们为您准备了一套通用的 入门教程。
请注意:该教程使用 ESP32-S3-Zero 作为教学示例,所有硬件代码均基于其引脚布局。在动手实践前,建议您对照手中的开发板引脚图,确认引脚配置无误。
请参考 安装和配置 Arduino IDE 教程 下载并安装 Arduino IDE。
请在 Arduino IDE 的开发板管理器中安装 esp32 by Espressif Systems 开发板支持包。
ESP32-C5-LCD-2.73 板载 MCU 模组为 ESP32-C5-WROOM-1-N32R8,芯片版本属于 v1.2,请使用 esp32 by Espressif Systems 的 v3.3.10 版本。
如果使用较旧版本的 ESP32 Arduino Core,可能无法正确识别该开发板,导致串口下载失败或无法烧录程序。
ESP32-C5-LCD-2.73 所需开发板安装说明:
| 板名称 | 板安装要求 | 版本号要求 |
|---|---|---|
| ESP32 by Espressif Systems | "离线"安装 / "在线"安装 | v3.3.10 |
安装完成后,在 Arduino IDE 中选择 ESP32-C5 对应开发板,并选择当前连接的 USB 串口。
ESP32-C5-LCD-2.73 Arduino 工程参数设置中,开发板需要选择 ESP32C5 Dev Module。

本产品 Arduino 示例主要使用 Arduino ESP32 Core 自带能力、示例目录内提供的源码,以及资料包中的库文件。
| 库或文件 | 作用 | 推荐版本或来源 | 使用示例 | 安装方式 |
|---|---|---|---|---|
| Arduino ESP32 Core | ESP32-C5 开发板支持、下载和基础外设接口 | v3.3.10 | 全部示例 | Arduino IDE 开发板管理器 |
lvgl | LVGL 图形界面框架 | 示例包 libraries/lvgl,LVGL v8.4.0 | 01_lvgl_demo、07_example | 离线手动复制到 Arduino 库目录 |
SensorLib / SensorPCF85063.hpp | PCF85063 RTC 驱动 | SensorLib | 04_I2C_pcf85063、07_example | Arduino Library Manager 或离线库目录 |
01_lvgl_demo 和 07_example 基于 LVGL v8.4.0。请勿替换为 LVGL v9,否则 lv_disp_drv_t、lv_disp_draw_buf_t、lv_disp_drv_register() 等接口会不兼容。
离线/手动安装方式:
下载并解压产品示例程序包。
找到示例包中的 LVGL 库目录:
code/arduino/libraries/lvgl
将 lvgl 文件夹完整复制到 Arduino 的库目录。
Windows 默认库目录通常是:
C:\Users\<用户名>\Documents\Arduino\libraries
也可以在 Arduino IDE 中通过 File > Preferences 查看 Sketchbook location,其下的 libraries 文件夹就是库目录。
安装完成后重启 Arduino IDE,再打开示例进行编译。
安装检查方法:
Documents\Arduino\libraries 下可以看到 lvgl 目录。Documents\Arduino\libraries\lvgl\library.properties 中可以看到 version=8.4.0。01_lvgl_demo 和 07_example 目录中的 lv_conf.h 需要保留在当前示例目录内,不要移动到 Arduino 全局库目录,也不要删除。lvgl,避免头文件冲突。04_I2C_pcf85063 或 07_example 提示找不到 SensorPCF85063.hpp,请确认已经安装 SensorLib。esp32 by Espressif Systems v3.3.10 开发板支持包。Tools > Board 中选择 ESP32C5 Dev Module。code/arduino/examples 下的对应示例 .ino 文件进行编译和烧录。使用 arduino-cli 时,可参考以下命令:
arduino-cli core install esp32:esp32@3.3.10
arduino-cli compile --fqbn esp32:esp32:esp32c5 code/arduino/examples/01_lvgl_demo
Arduino 示例程序位于示例程序包的 code/arduino/examples 目录。各示例已经按照 ESP32-C5-LCD-2.73 的板载硬件连接进行适配。
| 功能 | 器件或接口 | 引脚或说明 |
|---|---|---|
| LCD | ILI9488,SPI,320 x 320 | SCLK GPIO6,MOSI GPIO7,MISO GPIO5,DC GPIO4,CS GPIO8 |
| LCD 复位 | CH32V003 IO 扩展 | IO0 |
| LCD 背光 | CH32V003 PWM | PWM 寄存器 0x05 |
| IO 扩展 | CH32V003,I2C 地址 0x24 | SDA GPIO27,SCL GPIO26 |
| 六轴传感器 | QMI8658,I2C 地址 0x6B | SDA GPIO27,SCL GPIO26 |
| RTC | PCF85063,I2C 地址 0x51 | SDA GPIO27,SCL GPIO26 |
| 温湿度传感器 | SHTC3,I2C 地址 0x70 | SDA GPIO27,SCL GPIO26 |
| Micro SD | SDSPI | SCLK GPIO6,MOSI GPIO7,MISO GPIO5,CS GPIO9 |
| BOOT 按键 | 用户按键 | GPIO28 |
显示、背光、复位、SD 卡和传感器引脚已经在示例中按产品硬件连接适配。常规二次开发建议优先修改应用层和 UI 逻辑;仅在更换硬件连接或移植到其他板卡时,再修改底层引脚定义。
| 示例目录 | 基础例程说明 | 主要验证内容 |
|---|---|---|
| 01_lvgl_demo | 基于 ILI9488 和 LVGL v8.4.0 运行 LVGL 压力测试界面 | LCD、背光、LVGL |
| 02_SD_Card | 通过 SDSPI 挂载 Micro SD 卡,并执行文件写入和读回检查 | Micro SD、SDSPI、文件读写 |
| 03_I2C_qmi8658 | 读取 QMI8658 六轴传感器数据,并通过串口输出加速度和陀螺仪数据 | IMU、I2C 总线 |
| 04_I2C_pcf85063 | 初始化 PCF85063 RTC,设置测试时间,并通过串口周期打印 RTC 时间 | RTC、I2C 总线 |
| 05_shtc3 | 读取 SHTC3 温湿度传感器 ID、温度和湿度,并通过串口输出 | 温湿度传感器、CRC 校验 |
| 06_exio | 测试板载 CH32V003 IO 扩展芯片,循环翻转 IO4~IO14 输出电平 | IO 扩展、I2C 总线 |
| 07_example | 综合显示 RTC、SHTC3、QMI8658 和 SD 卡状态,并通过 BOOT 按键切换页面 | LCD、背光、传感器、RTC、SD 卡 |
当前 Arduino 示例目录包含以下工程:
code/arduino
|-- examples
| |-- 01_lvgl_demo
| |-- 02_SD_Card
| |-- 03_I2C_qmi8658
| |-- 04_I2C_pcf85063
| |-- 05_shtc3
| |-- 06_exio
| `-- 07_example
`-- libraries
`-- lvgl
每个子目录都是一个独立 Arduino 示例。打开示例时,应打开对应目录下的 .ino 文件,例如:
code/arduino/examples/01_lvgl_demo/01_lvgl_demo.ino
libraries/lvgl 是 01_lvgl_demo 和 07_example 使用的 LVGL v8.4.0 库文件。编译这两个示例前,需要将 lvgl 复制到 Arduino 库目录。
建议按以下顺序运行:
06_exio
-> 05_shtc3
-> 03_I2C_qmi8658
-> 04_I2C_pcf85063
-> 02_SD_Card
-> 01_lvgl_demo
-> 07_example
06_exio 验证 CH32V003 IO 扩展和 I2C 总线。LCD 复位和背光控制都与 CH32V003 有关,建议先确认该示例正常。05_shtc3、03_I2C_qmi8658 和 04_I2C_pcf85063 验证 I2C 外设。02_SD_Card 验证 Micro SD 卡和 SDSPI。01_lvgl_demo 和 07_example,验证 LCD、背光、LVGL 和综合页面。code/arduino/examples,请不要与 ESP-IDF 示例目录混用。SDA GPIO27、SCL GPIO26,CH32V003、QMI8658、PCF85063 和 SHTC3 都在该 I2C 总线上。02_SD_Card 和 07_example 运行前需要插入 FAT 或 FAT32 格式的 Micro SD 卡。04_I2C_pcf85063 默认每次上电都会写入固定测试时间,若需要 RTC 持续计时,请注释 i2c_rtc_setTime()。01_lvgl_demo 和 07_example 已经适配 ILI9488 显示,不需要额外引入 GFX 显示库。【功能说明】
该示例用于验证 LCD 显示、背光和 LVGL 基础运行。程序通过 SPI 初始化 ILI9488 LCD,使用 CH32V003 控制 LCD 复位和背光,然后启动 LVGL 压力测试界面。
【代码入口】
01_lvgl_demo/01_lvgl_demo.ino
01_lvgl_demo/esp_lcd_ili9488.c
01_lvgl_demo/esp_lcd_ili9488.h
01_lvgl_demo/lv_conf.h
建议优先查看:
| 代码 | 作用 |
|---|---|
LCD_H_RES / LCD_V_RES | LCD 分辨率,320 x 320 |
LCD_SPI_SCLK / LCD_SPI_MOSI / LCD_SPI_MISO | LCD SPI 引脚,GPIO6/GPIO7/GPIO5 |
LCD_SPI_DC / LCD_SPI_CS | LCD DC/CS 引脚,GPIO4/GPIO8 |
IO_EXT_LCD_RST | LCD 复位,CH32V003 IO0 |
io_ext_pwm() | 通过 CH32V003 PWM 设置背光 |
esp_lcd_new_panel_ili9488() | 创建 ILI9488 面板驱动 |
lv_demo_stress() | 启动 LVGL 压力测试界面 |
【正常运行现象】
ESP32-C5-LCD-2.73 Arduino LVGL demo 和 LVGL stress demo started。
【常见排查】
| 现象 | 可能原因 | 处理方法 |
|---|---|---|
编译找不到 lvgl.h | 未安装示例包内 LVGL | 将 code/arduino/libraries/lvgl 复制到 Arduino libraries 目录 |
编译出现大量 lv_disp_drv_t 相关错误 | 使用了 LVGL v9 | 删除错误版本 LVGL,使用示例包内 LVGL v8.4.0 |
| 屏幕不亮 | CH32V003、LCD 复位、背光或 ILI9488 初始化异常 | 先运行 06_exio,确认 CH32V003 正常;再恢复 01_lvgl_demo 原始引脚配置 |
| 显示颜色异常 | 像素格式或颜色顺序配置被修改 | 保持示例中的 bits_per_pixel = 18、LCD_RGB_ELEMENT_ORDER_BGR 和颜色反转配置 |
【功能说明】
该示例用于验证 Micro SD 卡接口。程序通过 SDSPI 挂载 SD 卡,挂载路径为 /sd_card,随后写入 sd_rw_test.txt 并读回校验。
【代码入口】
02_SD_Card/02_SD_Card.ino
02_SD_Card/sd_card_bsp.cpp
02_SD_Card/sd_card_bsp.h
建议优先查看:
| 代码 | 作用 |
|---|---|
PIN_NUM_CLK | SD SCLK,GPIO6 |
PIN_NUM_MOSI | SD MOSI,GPIO7 |
PIN_NUM_MISO | SD MISO,GPIO5 |
PIN_NUM_CS | SD CS,GPIO9 |
SD_card_Init() | 初始化 SPI 总线并挂载 Micro SD 卡 |
s_example_write_file() / s_example_read_file() | 示例中的文件写入和读取接口 |
【正常运行现象】
PASS 结果。
【常见排查】
| 现象 | 可能原因 | 处理方法 |
|---|---|---|
| SD 卡挂载失败 | 未插卡、卡格式异常或接触不良 | 使用 FAT/FAT32 格式 Micro SD 卡,重新插拔后再测试 |
| 文件读写失败 | 挂载失败或路径错误 | 先确认 SD_card_Init() 已成功打印卡信息 |
| 与 LCD 示例切换后 SD 卡异常 | SPI 总线状态或 CS 电平未恢复 | 重新上电后单独运行 02_SD_Card |
【功能说明】
该示例用于读取板载 QMI8658 六轴传感器。程序初始化 I2C 后创建 qmi8658c_example 任务,周期读取加速度和陀螺仪数据,并通过串口输出。
【代码入口】
03_I2C_qmi8658/03_I2C_qmi8658.ino
03_I2C_qmi8658/i2c_bsp.cpp
03_I2C_qmi8658/qmi8658c.cpp
03_I2C_qmi8658/qmi8658c.h
建议优先查看:
| 代码 | 作用 |
|---|---|
I2C_master_Init() | 初始化 I2C,总线引脚为 SDA GPIO27、SCL GPIO26,频率 400 kHz |
QMI8658_SLAVE_ADDR_H | QMI8658 I2C 地址,默认 0x6B |
qmi8658_init() | 初始化 QMI8658 |
qmi8658_read_xyz() | 读取加速度和陀螺仪数据 |
【正常运行现象】

【常见排查】
| 现象 | 可能原因 | 处理方法 |
|---|---|---|
| 串口提示 QMI8658 初始化失败 | QMI8658 I2C 通信失败 | 确认 I2C 引脚为 GPIO27/GPIO26,先运行 05_shtc3 或 06_exio 验证 I2C |
| 数据一直不变化 | 开发板静止或任务未运行 | 轻微转动开发板,并确认串口波特率为 115200 |
| 编译报 I2C 相关接口错误 | Arduino ESP32 Core 版本不匹配 | 使用包含 ESP32-C5 支持的开发板支持包 |
【功能说明】
该示例用于验证板载 PCF85063 RTC。程序会初始化 RTC,并在 setup() 中调用:
i2c_rtc_setTime(2025, 9, 9, 14, 51, 30);
随后创建 i2c_rtc_loop_task 任务,每秒读取并打印一次 RTC 时间。
【代码入口】
04_I2C_pcf85063/04_I2C_pcf85063.ino
04_I2C_pcf85063/rtc_bsp.cpp
04_I2C_pcf85063/rtc_bsp.h
建议优先查看:
| 代码 | 作用 |
|---|---|
rtc.begin(Wire, SENSOR_SDA, SENSOR_SCL) | 初始化 PCF85063,默认 SDA GPIO27、SCL GPIO26 |
i2c_rtc_setTime() | 设置 RTC 时间 |
i2c_rtc_get() | 读取 RTC 时间结构体 |
i2c_rtc_loop_task() | 周期读取并串口打印 RTC 时间 |
【正常运行现象】

由于示例在 setup() 中每次上电都会重新写入固定测试时间,如需验证 RTC 持续计时,请注释或删除 i2c_rtc_setTime()。
【常见排查】
| 现象 | 可能原因 | 处理方法 |
|---|---|---|
编译提示找不到 SensorPCF85063.hpp | 缺少 SensorLib 依赖 | 安装 SensorLib 后重新编译 |
串口提示 Failed to find PCF85063 | RTC I2C 通信失败 | 确认 I2C 引脚为 GPIO27/GPIO26,并先测试其它 I2C 示例 |
| 每次上电时间都回到固定时间 | 示例主动写入测试时间 | 注释或删除 i2c_rtc_setTime() 后再测试 RTC 走时 |
【功能说明】
该示例用于读取板载 SHTC3 温湿度传感器。程序使用 Wire 发送 SHTC3 命令,启动后唤醒传感器、读取 ID、执行软复位,并在 loop() 中每秒读取一次温度和湿度。
示例读取数据时会校验 SHTC3 CRC,避免无效数据被当成正常温湿度输出。
【代码入口】
05_shtc3/05_shtc3.ino
建议优先查看:
| 代码 | 作用 |
|---|---|
I2C_SDA / I2C_SCL | I2C 引脚,SDA GPIO27、SCL GPIO26 |
SHTC3_ADDR | SHTC3 I2C 地址,默认 0x70 |
SHTC3_CMD_READ_ID | 读取传感器 ID |
SHTC3_CMD_MEASURE_T_RH | 触发温湿度测量 |
shtc3Crc() | 校验 SHTC3 返回数据 |
readShtc3() | 读取并换算温度、湿度 |
【正常运行现象】

【常见排查】
| 现象 | 可能原因 | 处理方法 |
|---|---|---|
串口提示 SHTC3 not found | I2C 通信失败 | 确认 I2C 引脚为 GPIO27/GPIO26,确认开发板供电正常 |
串口提示 Failed to read SHTC3 | CRC 校验失败或传感器未正确响应 | 保持开发板稳定供电,重新上电后再测试 |
| 温湿度数值偶发异常 | I2C 数据无效 | 示例已做 CRC 校验,建议以通过校验的数据为准 |
【功能说明】
该示例用于验证板载 CH32V003 IO 扩展芯片通信是否正常。CH32V003 通过 I2C 与 ESP32-C5 通信,地址为 0x24,示例会将 IO4~IO14 配置为输出,并每秒翻转一次电平。
CH32V003 出厂时已经烧录好固件,无需单独烧录 CH32 固件。
【代码入口】
06_exio/06_exio.ino
06_exio/io_extension.cpp
06_exio/io_extension.h
建议优先查看:
| 代码 | 作用 |
|---|---|
Wire.begin(I2C_SDA, I2C_SCL) | 初始化 I2C,总线引脚为 SDA GPIO27、SCL GPIO26 |
IO_EXTENSION_ADDR | CH32V003 I2C 地址,默认 0x24 |
IO_EXTENSION_Init(Wire) | 初始化 IO 扩展芯片 |
IO_EXTENSION_IO_Mode(0xFFF7) | 配置 IO 扩展引脚模式 |
IO_EXTENSION_Output() | 设置指定 IO 扩展引脚输出电平 |
【正常运行现象】
IO4~IO14 will toggle every second.。
【常见排查】
| 现象 | 可能原因 | 处理方法 |
|---|---|---|
串口提示 IO extension not found at 0x24 | I2C 通信失败 | 确认使用 SDA GPIO27、SCL GPIO26,确认开发板供电正常 |
| 后续 LCD 不正常 | CH32V003 未正常通信 | 先确保 06_exio 正常,再排查显示和背光 |
| 想重新烧录 CH32V003 固件 | 不需要 | CH32V003 出厂已烧录固件,正常使用无需操作 |
【功能说明】
该示例用于综合验证 LCD、背光、RTC、SHTC3、QMI8658 和 Micro SD 卡。程序启动后初始化 I2C、CH32V003、ILI9488、LVGL 和板载外设,LCD 页面显示系统状态、RTC、温湿度、IMU 和 SD 卡信息。
按下 BOOT 按键可切换页面。
【代码入口】
07_example/07_example.ino
07_example/esp_lcd_ili9488.c
07_example/esp_lcd_ili9488.h
07_example/i2c_bsp.cpp
07_example/qmi8658c.cpp
07_example/rtc_bsp.cpp
07_example/sd_card_bsp.cpp
07_example/lv_conf.h
建议优先查看:
| 代码 | 作用 |
|---|---|
init_lcd_panel() | 初始化 SPI 总线和 ILI9488 面板 |
init_lvgl() | 初始化 LVGL 显示缓冲区和刷新回调 |
init_peripherals() | 依次检查 RTC、SHTC3、QMI8658 和 SD 卡 |
refresh_sensors() | 周期读取传感器和 RTC 数据 |
refresh_screen() | 按当前页面刷新 LCD 显示内容 |
handle_button() | 读取 GPIO28 BOOT 按键并切换页面 |
【正常运行现象】
System Status 页面。
【常见排查】
| 现象 | 可能原因 | 处理方法 |
|---|---|---|
编译找不到 lvgl.h | 未安装示例包内 LVGL | 将 code/arduino/libraries/lvgl 复制到 Arduino libraries 目录 |
编译找不到 SensorPCF85063.hpp | 缺少 SensorLib 依赖 | 安装 SensorLib 后重新编译 |
页面显示某外设为 NO | 对应外设初始化或通信失败 | 先单独运行该外设对应的基础示例 |
| BOOT 按键无法切换页面 | 按键 GPIO 配置异常 | 确认示例保留 BOOT_BUTTON = GPIO_NUM_28 和 INPUT_PULLUP 配置 |
| SD 页面显示未挂载 | 未插入 SD 卡或格式异常 | 插入 FAT/FAT32 格式 Micro SD 卡后重新上电测试 |
本节介绍 ESP32-C5-LCD-2.73 出厂固件的使用方式。实际出厂固件对应 ESP-IDF 示例程序 01_factory,包含主界面、Settings、Sensor、Photo 和 Weather 页面。
Firmware 目录中。code/idf/01_factory 目录中。如果出现无法识别端口的情况,请进入 Boot 模式:
下载完成后,重新上电运行程序。
启动后,LCD 显示出厂固件主界面。通过板载按键选择并进入各个页面。





Settings 页面用于查看和配置板载功能:
Weather 页面需要先在 Settings 页面配置 Wi-Fi。
Sensor 页面显示板载传感器数据:
轻微转动开发板时,加速度和陀螺仪数据会随姿态变化。
Photo 页面读取 Micro SD 卡中的图片文件:
/sdcard/photo 目录下的 .jpg 和 .jpeg 图片。photo 目录。Weather 页面用于显示天气信息。使用前请在 Settings 页面配置可访问互联网的 Wi-Fi。
| 现象 | 可能原因 | 处理方法 |
|---|---|---|
| 屏幕不亮 | 供电异常、LCD 复位异常或背光未打开 | 重新连接 USB 后再启动;如需排查程序,参考 ESP-IDF 02_lvgl_demo 和 07_exio 示例 |
| Weather 页面无数据 | Wi-Fi 未连接或网络不可用 | 在 Settings 页面配置 Wi-Fi,并确认热点可以访问互联网 |
| Photo 页面无图片 | SD 卡未挂载、目录不存在或图片格式不匹配 | 确认 SD 卡中存在 /photo 目录,并放入 .jpg 或 .jpeg 图片 |
| Sensor 页面无数据 | I2C 外设初始化异常 | 参考 ESP-IDF 04_qmi8658、06_shtc3 和 07_exio 示例排查 |
本章节包含以下内容,请按需阅读:
初次接触 ESP32 ESP-IDF 开发,想要快速上手?我们为您准备了一套通用的 入门教程。
请注意:该教程使用 ESP32-S3-Zero 作为教学示例,所有硬件代码均基于其引脚布局。在动手实践前,建议您对照手中的开发板引脚图,确认引脚配置无误。
请参考 安装 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 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。
安装时建议勾选 通过 Code 打开操作添加到 Windows 资源管理器文件上下文菜单,以便快速打开项目文件夹。
在 VS Code 中,点击侧边活动栏中的 扩展图标(或使用快捷键 Ctrl + Shift + X)打开 扩展 视图。
在搜索框中输入 ESP-IDF,找到 ESP-IDF 扩展并点击安装。

当 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
| 功能 | 器件或接口 | 引脚或说明 |
|---|---|---|
| LCD | ILI9488,SPI,320 x 320,RGB666 | SCLK GPIO6,MOSI GPIO7,MISO GPIO5,DC GPIO4,CS GPIO8 |
| LCD 复位 | CH32V003 IO 扩展 | IO0 |
| LCD 背光 | CH32V003 PWM | IO 扩展 PWM |
| IO 扩展 | CH32V003,I2C 地址 0x24 | SDA GPIO27,SCL GPIO26 |
| 六轴传感器 | QMI8658,I2C 地址 0x6B | SDA GPIO27,SCL GPIO26 |
| RTC | PCF85063,I2C 地址 0x51 | SDA GPIO27,SCL GPIO26 |
| 温湿度传感器 | SHTC3,I2C 地址 0x70 | SDA GPIO27,SCL GPIO26 |
| Micro SD | SDSPI | SCLK 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 输出电平。 |
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 图片。SDA GPIO27、SCL GPIO26,CH32V003、QMI8658、PCF85063 和 SHTC3 都在该 I2C 总线上。/sdcard/photo 目录下的 JPG 图片,并提供上一张、下一张和返回控制。photo 目录后放入 .jpg 或 .jpeg 图片。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 应用 |





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

| 现象 | 可能原因 | 处理方法 |
|---|---|---|
| 屏幕不亮 | CH32V003、LCD 复位、背光或 SPI 初始化异常 | 先运行 07_exio,再恢复 BSP 中 LCD 相关引脚定义 |
| 显示异常 | LCD 色彩格式或分辨率配置被修改 | 确认 BSP_LCD_H_RES、BSP_LCD_V_RES 为 320,BSP_LCD_BITS_PER_PIXEL 为 18 |
bsp_sdcard_mount() 挂载 SD 卡,挂载点为 /sdcard。/sdcard/test.txt,再读回并校验内容。03_sd_card/main/main.c
03_sd_card/components/waveshare__esp32_c5_lcd_2_73
建议优先查看:
| 代码 | 作用 |
|---|---|
BSP_LCD_CS | LCD CS,GPIO8,测试前拉高 |
bsp_sdcard_mount() | 挂载 Micro SD 卡 |
BSP_SD_MOUNT_POINT | SD 卡挂载点,默认 /sdcard |
tf_card_read_write_test() | 写入、读回和校验测试文件 |
sdmmc_card_print_info() | 打印 SD 卡信息 |
TF CARD TEST PASS。
| 现象 | 可能原因 | 处理方法 |
|---|---|---|
| SD 卡挂载失败 | 未插卡、卡格式异常或接触不良 | 使用 FAT/FAT32 格式 Micro SD 卡,重新插拔后再测试 |
| 文件写入或读回失败 | 文件系统异常或卡不可写 | 更换 SD 卡或重新格式化后测试 |
| 与 LCD 示例切换后异常 | SPI 总线或片选状态残留 | 重新上电后单独运行 03_sd_card |
bsp_qmi8658_drv_init() 初始化 QMI8658。m/s^2、陀螺仪 dps。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() | 读取加速度和陀螺仪数据 |

| 现象 | 可能原因 | 处理方法 |
|---|---|---|
| 初始化失败 | I2C 通信异常 | 确认 I2C 使用 SDA GPIO27、SCL GPIO26,并先运行 07_exio 或 06_shtc3 |
| 数据无变化 | 开发板静止或数据未更新 | 轻微转动开发板,并确认串口监视器仍在运行 |
bsp_pcf85063a_drv_init() 初始化 RTC。pcf85063a_get_time_date() 读取日期、时间和星期,并通过串口输出。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_t | RTC 日期时间结构体 |

| 现象 | 可能原因 | 处理方法 |
|---|---|---|
| RTC 读取失败 | PCF85063 I2C 通信异常 | 确认 I2C 使用 SDA GPIO27、SCL GPIO26,并测试其它 I2C 示例 |
| 时间不符合预期 | RTC 未设置或电池供电状态异常 | 先运行 01_factory 同步系统时间,或在代码中增加设置 RTC 时间的逻辑 |
bsp_shtc3_drv_init() 初始化 SHTC3。shtc3_get_th() 读取温度和湿度,并通过串口输出。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 | 温度优先、正常模式测量命令 |

| 现象 | 可能原因 | 处理方法 |
|---|---|---|
| 初始化失败 | SHTC3 I2C 通信异常 | 确认 I2C 使用 SDA GPIO27、SCL GPIO26,确认开发板供电正常 |
| 温湿度读取失败 | 传感器未正确响应或 I2C 数据异常 | 重新上电后再测试,并对照 04_qmi8658 或 05_pcf85063 判断 I2C 是否正常 |
bsp_io_expander_init() 初始化 CH32V003。0xFFF7,然后每秒翻转 IO4~IO14 的输出电平。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 | 输出翻转范围 |
| 现象 | 可能原因 | 处理方法 |
|---|---|---|
| 后续 LCD 或背光示例异常 | CH32V003 未正常通信 | 先确认 07_exio 可以运行,再排查 LCD 复位和背光控制 |
| IO 输出无变化 | IO 扩展初始化失败或输出范围被修改 | 保留示例中的 IO_EXTENSION_IO_Mode(0xFFF7) 和 IO4~IO14 输出范围 |
当前产品提供了测试固件,可通过直接烧录测试固件来验证板载设备功能是否正常。
Firmware 目录下0x00下文以烧录 ESP32-S3-Touch-LCD-2.8 出厂固件 为例,若烧录其他固件,操作步骤类推。
下载并解压乐鑫官方烧录工具 Flash Download Tool(下载地址)
运行解压得到的 flash_download_tool_3.9.7.exe,根据开发板的主控芯片与下载接口选择,例如 ESP32-S3 与 USB(大部分设备选择 USB,具体以产品硬件设计为准)

参数设置
0x00),同时勾选该行最左侧的复选框
等待烧录完成(烧录过程需要一定时间,请耐心等待)
按下复位键,观察运行现象

开发板设计文件
ESP32-C5 芯片官方手册
板载器件数据手册
周一-周五(9:30-6:30)周六(9:30-5:30)
手机:13434470212
邮箱:services04@spotpear.cn
QQ:202004841
