ESP32-C5-LCD-2.73 使用教程

产品特性

  • 采用 ESP32-C5-WROOM-1-N32R8 模组,板载 MCU 为 ESP32-C5
  • 搭载 RISC-V 32 位处理器,主频 240 MHz
  • 集成 384 KB SRAM、320 KB ROM、8 MB PSRAM 和 32 MB Flash
  • 支持 2.4 GHz / 5 GHz 双频 Wi-Fi、Bluetooth 5 (LE) 和 IEEE 802.15.4,可用于 Zigbee 3.0 和 Thread 相关开发
  • 采用 USB Type-C 接口,用于供电、下载和串口调试
  • 板载 2.73 英寸 LCD,显示驱动芯片为 ILI9488,分辨率为 320 x 320,RGB666 色彩格式
  • 板载 QMI8658 六轴传感器、PCF85063 RTC、SHTC3 温湿度传感器和 Micro SD 卡座
  • 板载 CH32V003 IO 扩展芯片,用于 LCD 复位、LCD 背光 PWM、电池电压读取和扩展 IO 测试
  • 板载电池充电管理电路,预留 3.7 V 锂电池接口
  • 提供 UART、I2C、USB 和扩展 IO 等接口
  • 支持 ESP-IDF 和 Arduino 开发环境

板载资源

资源说明
主控模组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 锂电池接口

接口介绍

LCD 接口:用于连接 2.73 英寸 LCD 屏(点击展开)
ESP32-C5 / CH32V003LCD简介
GPIO6LCD_SCKSPI 时钟信号
GPIO7LCD_MOSISPI 数据输出信号
GPIO5LCD_MISOSPI 数据输入信号
GPIO4LCD_DC数据/命令选择信号
GPIO8LCD_CS片选信号,低电平有效
CH32V003 IO0LCD_RSTLCD 复位信号
CH32V003 PWMLCD_BLLCD 背光 PWM 控制
SD Card 接口:用于连接 Micro SD 卡(点击展开)
ESP32-C5SD Card简介
GPIO7MOSISD 卡 SPI 数据输入
GPIO6CLKSD 卡 SPI 时钟
GPIO5MISOSD 卡 SPI 数据输出
GPIO9CSSD 卡片选信号,低电平有效
I2C 总线:用于连接板载 I2C 外设(点击展开)
ESP32-C5I2C简介
GPIO27SDAI2C 数据信号
GPIO26SCLI2C 时钟信号
QMI8658 六轴传感器接口(点击展开)
ESP32-C5QMI8658简介
GPIO27SDAI2C 数据信号
GPIO26SCLI2C 时钟信号
0x6BI2C 地址QMI8658 默认通信地址
RTC 接口:板载实时时钟 PCF85063(点击展开)
ESP32-C5PCF85063简介
GPIO27SDAI2C 数据信号
GPIO26SCLI2C 时钟信号
0x51I2C 地址PCF85063 默认通信地址
SHTC3 温湿度传感器接口(点击展开)
ESP32-C5SHTC3简介
GPIO27SDAI2C 数据信号
GPIO26SCLI2C 时钟信号
0x70I2C 地址SHTC3 默认通信地址
UART0 接口:串口通信(点击展开)
ESP32-C5UART0简介
GPIO11TX串口发送
GPIO12RX串口接收
USB 接口:用于供电、下载和串口调试(点击展开)
ESP32-C5USB简介
GPIO14D+USB 差分数据 D+
GPIO13D-USB 差分数据 D-
板载按键接口(点击展开)
ESP32-C5Button简介
GPIO2PREV菜单导航按键
GPIO3NEXT菜单导航按键
GPIO28BOOT / ENTER下载模式按键,也可作为菜单确认按键
CH32V003 IO 扩展接口:用于 LCD、电池检测和扩展 IO 测试(点击展开)
CH32V003控制对象简介
IO0LCD_RSTLCD 复位控制
PWMLCD_BLLCD 背光 PWM 控制
ADCBAT_ADC电池电压检测
IO4~IO14EXIO扩展 IO 测试引脚

产品尺寸


开发方式

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 插件进行开发。


Arduino 开发

本章节包含以下内容,请按需阅读:

阅读前准备

运行示例前,请确认以下条件已经满足:

  • 已准备 ESP32-C5-LCD-2.73 开发板。
  • 已使用 USB 数据线连接开发板和电脑。
  • 已安装 Arduino IDE
  • 已安装支持 ESP32-C5 的 ESP32 Arduino Core。
  • 已下载产品示例程序包
  • 如需运行 01_lvgl_demo 或 07_example,请安装示例包内置的 libraries/lvgl
  • 如需运行 04_I2C_pcf85063 或 07_example,请安装 SensorLib,用于提供 SensorPCF85063.hpp

Arduino 入门教程

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

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

配置开发环境

1. 安装和配置 Arduino IDE

请参考 安装和配置 Arduino IDE 教程 下载并安装 Arduino IDE。

2. 安装 ESP32 开发板支持包

请在 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 串口。

ARDUINO 工程参数

ESP32-C5-LCD-2.73 Arduino 工程参数设置中,开发板需要选择 ESP32C5 Dev Module


3. 安装库和示例依赖

本产品 Arduino 示例主要使用 Arduino ESP32 Core 自带能力、示例目录内提供的源码,以及资料包中的库文件。

库或文件作用推荐版本或来源使用示例安装方式
Arduino ESP32 CoreESP32-C5 开发板支持、下载和基础外设接口v3.3.10全部示例Arduino IDE 开发板管理器
lvglLVGL 图形界面框架示例包 libraries/lvgl,LVGL v8.4.001_lvgl_demo07_example离线手动复制到 Arduino 库目录
SensorLib / SensorPCF85063.hppPCF85063 RTC 驱动SensorLib04_I2C_pcf8506307_exampleArduino Library Manager 或离线库目录
LVGL 版本

01_lvgl_demo 和 07_example 基于 LVGL v8.4.0。请勿替换为 LVGL v9,否则 lv_disp_drv_tlv_disp_draw_buf_tlv_disp_drv_register() 等接口会不兼容。

离线/手动安装方式:

  1. 下载并解压产品示例程序包

  2. 找到示例包中的 LVGL 库目录:

    code/arduino/libraries/lvgl
  3. 将 lvgl 文件夹完整复制到 Arduino 的库目录。

    Windows 默认库目录通常是:

    C:\Users\<用户名>\Documents\Arduino\libraries

    也可以在 Arduino IDE 中通过 File > Preferences 查看 Sketchbook location,其下的 libraries 文件夹就是库目录。

  4. 安装完成后重启 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

4. Arduino 工程参数设置

  1. 打开 Arduino IDE。
  2. 安装 esp32 by Espressif Systems v3.3.10 开发板支持包。
  3. 在 Tools > Board 中选择 ESP32C5 Dev Module
  4. 选择当前连接的 USB 串口。
  5. 打开 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 的板载硬件连接进行适配。

1. 板载资源

功能器件或接口引脚或说明
LCDILI9488,SPI,320 x 320SCLK GPIO6,MOSI GPIO7,MISO GPIO5,DC GPIO4,CS GPIO8
LCD 复位CH32V003 IO 扩展IO0
LCD 背光CH32V003 PWMPWM 寄存器 0x05
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
二次开发建议

显示、背光、复位、SD 卡和传感器引脚已经在示例中按产品硬件连接适配。常规二次开发建议优先修改应用层和 UI 逻辑;仅在更换硬件连接或移植到其他板卡时,再修改底层引脚定义。

2. 示例列表

示例目录基础例程说明主要验证内容
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 卡

3. 目录结构

当前 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 库目录。

4. 第一次运行推荐顺序

建议按以下顺序运行:

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_shtc303_I2C_qmi8658 和 04_I2C_pcf85063 验证 I2C 外设。
  • 然后用 02_SD_Card 验证 Micro SD 卡和 SDSPI。
  • 最后运行 01_lvgl_demo 和 07_example,验证 LCD、背光、LVGL 和综合页面。

5. 使用说明

  • Arduino 示例目录为 code/arduino/examples,请不要与 ESP-IDF 示例目录混用。
  • 本产品共用一组 I2C:SDA GPIO27SCL 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 SPI 引脚、SD 卡片选引脚和 CH32V003 IO 扩展配置。
  • 编译、屏幕点亮、I2C 地址等排查内容请参考 产品 FAQ

6. 示例说明

01_lvgl_demo

【功能说明】

该示例用于验证 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_RESLCD 分辨率,320 x 320
LCD_SPI_SCLK / LCD_SPI_MOSI / LCD_SPI_MISOLCD SPI 引脚,GPIO6/GPIO7/GPIO5
LCD_SPI_DC / LCD_SPI_CSLCD DC/CS 引脚,GPIO4/GPIO8
IO_EXT_LCD_RSTLCD 复位,CH32V003 IO0
io_ext_pwm()通过 CH32V003 PWM 设置背光
esp_lcd_new_panel_ili9488()创建 ILI9488 面板驱动
lv_demo_stress()启动 LVGL 压力测试界面

【正常运行现象】

  • LCD 显示 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 = 18LCD_RGB_ELEMENT_ORDER_BGR 和颜色反转配置

02_SD_Card

【功能说明】

该示例用于验证 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_CLKSD SCLK,GPIO6
PIN_NUM_MOSISD MOSI,GPIO7
PIN_NUM_MISOSD MISO,GPIO5
PIN_NUM_CSSD CS,GPIO9
SD_card_Init()初始化 SPI 总线并挂载 Micro SD 卡
s_example_write_file() / s_example_read_file()示例中的文件写入和读取接口

【正常运行现象】

  • 插入 FAT 或 FAT32 格式的 Micro SD 卡后,串口会打印 SD 卡类型、容量、写入长度、读回长度和 PASS 结果。

【常见排查】

现象可能原因处理方法
SD 卡挂载失败未插卡、卡格式异常或接触不良使用 FAT/FAT32 格式 Micro SD 卡,重新插拔后再测试
文件读写失败挂载失败或路径错误先确认 SD_card_Init() 已成功打印卡信息
与 LCD 示例切换后 SD 卡异常SPI 总线状态或 CS 电平未恢复重新上电后单独运行 02_SD_Card

03_I2C_qmi8658

【功能说明】

该示例用于读取板载 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_HQMI8658 I2C 地址,默认 0x6B
qmi8658_init()初始化 QMI8658
qmi8658_read_xyz()读取加速度和陀螺仪数据

【正常运行现象】

  • 串口会先输出 QMI8658 初始化信息,随后周期输出传感器数据。
  • 轻微倾斜或转动开发板时,加速度和陀螺仪数据会随姿态变化。

【常见排查】

现象可能原因处理方法
串口提示 QMI8658 初始化失败QMI8658 I2C 通信失败确认 I2C 引脚为 GPIO27/GPIO26,先运行 05_shtc3 或 06_exio 验证 I2C
数据一直不变化开发板静止或任务未运行轻微转动开发板,并确认串口波特率为 115200
编译报 I2C 相关接口错误Arduino ESP32 Core 版本不匹配使用包含 ESP32-C5 支持的开发板支持包

04_I2C_pcf85063

【功能说明】

该示例用于验证板载 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 时间

【正常运行现象】

  • 串口每秒输出一次 RTC 时间。

由于示例在 setup() 中每次上电都会重新写入固定测试时间,如需验证 RTC 持续计时,请注释或删除 i2c_rtc_setTime()

【常见排查】

现象可能原因处理方法
编译提示找不到 SensorPCF85063.hpp缺少 SensorLib 依赖安装 SensorLib 后重新编译
串口提示 Failed to find PCF85063RTC I2C 通信失败确认 I2C 引脚为 GPIO27/GPIO26,并先测试其它 I2C 示例
每次上电时间都回到固定时间示例主动写入测试时间注释或删除 i2c_rtc_setTime() 后再测试 RTC 走时

05_shtc3

【功能说明】

该示例用于读取板载 SHTC3 温湿度传感器。程序使用 Wire 发送 SHTC3 命令,启动后唤醒传感器、读取 ID、执行软复位,并在 loop() 中每秒读取一次温度和湿度。

示例读取数据时会校验 SHTC3 CRC,避免无效数据被当成正常温湿度输出。

【代码入口】

05_shtc3/05_shtc3.ino

建议优先查看:

代码作用
I2C_SDA / I2C_SCLI2C 引脚,SDA GPIO27、SCL GPIO26
SHTC3_ADDRSHTC3 I2C 地址,默认 0x70
SHTC3_CMD_READ_ID读取传感器 ID
SHTC3_CMD_MEASURE_T_RH触发温湿度测量
shtc3Crc()校验 SHTC3 返回数据
readShtc3()读取并换算温度、湿度

【正常运行现象】

  • 串口先输出 SHTC3 ID,随后周期输出温湿度。

【常见排查】

现象可能原因处理方法
串口提示 SHTC3 not foundI2C 通信失败确认 I2C 引脚为 GPIO27/GPIO26,确认开发板供电正常
串口提示 Failed to read SHTC3CRC 校验失败或传感器未正确响应保持开发板稳定供电,重新上电后再测试
温湿度数值偶发异常I2C 数据无效示例已做 CRC 校验,建议以通过校验的数据为准

06_exio

【功能说明】

该示例用于验证板载 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_ADDRCH32V003 I2C 地址,默认 0x24
IO_EXTENSION_Init(Wire)初始化 IO 扩展芯片
IO_EXTENSION_IO_Mode(0xFFF7)配置 IO 扩展引脚模式
IO_EXTENSION_Output()设置指定 IO 扩展引脚输出电平

【正常运行现象】

  • 串口输出 IO4~IO14 will toggle every second.
  • 随后每秒输出一次 IO4~IO14 的当前电平。

【常见排查】

现象可能原因处理方法
串口提示 IO extension not found at 0x24I2C 通信失败确认使用 SDA GPIO27、SCL GPIO26,确认开发板供电正常
后续 LCD 不正常CH32V003 未正常通信先确保 06_exio 正常,再排查显示和背光
想重新烧录 CH32V003 固件不需要CH32V003 出厂已烧录固件,正常使用无需操作

07_example

【功能说明】

该示例用于综合验证 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 按键并切换页面

【正常运行现象】

  • LCD 显示 System Status 页面。
  • 按下 BOOT 按键后,页面在系统状态、RTC、SHTC3、QMI8658 IMU 和 SD Card 之间切换。
  • 串口周期输出 RTC、温湿度、加速度、陀螺仪和 SD 卡容量信息。

【常见排查】

现象可能原因处理方法
编译找不到 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 页面。

器件准备

  • ESP32-C5-LCD-2.73 开发板 x1
  • USB 数据线 x1
  • Micro SD 卡 x1(仅 Photo 页面需要)
  • 可联网的 Wi-Fi 热点(仅 Weather 页面需要)

固件说明

  • 出厂固件位于 示例程序包 的 Firmware 目录中。
  • 出厂固件源码位于 示例程序包 的 code/idf/01_factory 目录中。
  • 示例启动后会初始化 NVS、Micro SD、CH32V003 IO 扩展、PCF85063 RTC、LCD、LVGL 和应用菜单。
  • 状态栏会显示时间和 Wi-Fi 状态,时间由 RTC 同步。

USB 下载注意事项

开发板使用 USB 下载程序

如果出现无法识别端口的情况,请进入 Boot 模式:

  1. 按住 BOOT 按键。
  2. 连接 USB 到电脑。
  3. 松开 BOOT 按键。

下载完成后,重新上电运行程序。

主界面与页面

启动后,LCD 显示出厂固件主界面。通过板载按键选择并进入各个页面。






Settings 页面

Settings 页面用于查看和配置板载功能:

  • 配置 Wi-Fi。
  • 调节 LCD 背光。
  • 查看 TF 卡容量。
  • 查看电池信息。
  • 查看 About 信息。

Weather 页面需要先在 Settings 页面配置 Wi-Fi。

Sensor 页面

Sensor 页面显示板载传感器数据:

  • QMI8658 加速度数据。
  • QMI8658 陀螺仪数据。
  • SHTC3 温湿度数据。

轻微转动开发板时,加速度和陀螺仪数据会随姿态变化。

Photo 页面

Photo 页面读取 Micro SD 卡中的图片文件:

  • 支持 /sdcard/photo 目录下的 .jpg 和 .jpeg 图片。
  • 页面提供上一张、下一张和返回控制。
  • 使用前请将 FAT 或 FAT32 格式的 Micro SD 卡插入开发板,并在卡中创建 photo 目录。

Weather 页面

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_qmi865806_shtc3 和 07_exio 示例排查


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 版本(图示仅为参考,请以实际为准)。


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


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

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

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


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


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


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


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


安装 Visual Studio Code 与 ESP-IDF 扩展

  1. 下载并安装 Visual Studio Code

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

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

  4. 在搜索框中输入 ESP-IDF,找到 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_factory02_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 GPIO27SCL 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 连接后状态图标会变化。





常见排查

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

常见排查

现象可能原因处理方法
屏幕不亮CH32V003、LCD 复位、背光或 SPI 初始化异常先运行 07_exio,再恢复 BSP 中 LCD 相关引脚定义
显示异常LCD 色彩格式或分辨率配置被修改确认 BSP_LCD_H_RESBSP_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

常见排查

现象可能原因处理方法
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()读取加速度和陀螺仪数据

运行效果

  • 串口周期输出加速度和陀螺仪数据。
  • 轻微转动开发板时,输出数据会随姿态变化。

常见排查

现象可能原因处理方法
初始化失败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 时间。

常见排查

现象可能原因处理方法
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温度优先、正常模式测量命令

运行效果

  • 串口每秒输出一次温度和湿度。

常见排查

现象可能原因处理方法
初始化失败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 输出范围


Flash 固件的烧录与擦除

当前产品提供了测试固件,可通过直接烧录测试固件来验证板载设备功能是否正常。

下文以烧录 ESP32-S3-Touch-LCD-2.8 出厂固件 为例,若烧录其他固件,操作步骤类推。

  • 下载并解压乐鑫官方烧录工具 Flash Download Tool(下载地址

  • 运行解压得到的 flash_download_tool_3.9.7.exe,根据开发板的主控芯片与下载接口选择,例如 ESP32-S3 与 USB(大部分设备选择 USB,具体以产品硬件设计为准)


  • 参数设置

    • 选择与开发板所对应的 COM 口
    • 选择 BAUD 为最高的 1152000
    • 点击该行的“...”按钮,选择微雪提供的 bin 文件,并在其右侧手动填写本页上方给出的烧录地址(比如 0x00),同时勾选该行最左侧的复选框
    • 点击 START 开始烧录


  • 等待烧录完成(烧录过程需要一定时间,请耐心等待)

  • 按下复位键,观察运行现象



相关资料

1. 硬件资料

开发板设计文件

2. 技术手册

3. 示例程序

4. 软件工具


技术支持

周一-周五(9:30-6:30)周六(9:30-5:30)

手机:13434470212

邮箱:services04@spotpear.cn

QQ:202004841




[教程导航]