产品 FAQ
串口与下载
问：如何查看当前使用的 COM 口？
答：Windows 系统可打开“设备管理器”并展开“端口（COM 和 LPT）”查看端口号。Linux 系统可在终端中使用 ls /dev/ttyUSB* 或 dmesg 查看串口设备。
问：重新下载程序时无法连接串口，如何处理？
答：
- 请先打开后台任务管理器，确认是否有其他应用占用串口，例如 Arduino IDE、VS Code 等。如有占用，请关闭相关应用后重试，必要时可重启电脑。
- 尝试进入下载模式：先断开 USB，长按开发板上的
BOOT按键，再接入电脑，最后松开BOOT按键。随后重新检查 COM 口是否可以正常识别。 - 请检查是否通过拓展坞连接开发板。如使用拓展坞，建议改为直连电脑 USB 接口。
- 若仍无法连接，请更换支持数据传输的 USB 线材进行测试。
问：为什么代码成功烧录后没有串口输出？
答：ESP32-C5-LCD-2.73 使用 ESP32-C5 原生 USB 功能。请检查工程中的 USB CDC、串口输出和端口配置，并确认串口监视器选择了正确端口和波特率。
出厂示例与基础使用
问：为什么工厂示例天气页面无法获取天气信息？
答：天气页面需要先连接可访问互联网的 Wi-Fi。请进入 01_factory 的 Settings 页面配置 Wi-Fi，并确认热点可以正常访问互联网。
如果 Wi-Fi 已连接但仍无法获取天气信息，请检查网络是否存在防火墙、无网络访问权限或 API 访问受限等情况。
问：没有 SD 卡时可以使用开发板吗？
答：可以使用。与 SD 卡读写、相册图片读取相关的功能不可用；LCD、LVGL、QMI8658、PCF85063、SHTC3 和 EXIO 测试仍可单独运行。
问：使用 SD 卡需要注意什么？
答：建议使用 64 GB 及以下容量的 Micro SD 卡，并格式化为 FAT 或 FAT32 格式。03_sd_card 会在 /sdcard/test.txt 中执行写入和读回校验；01_factory 的相册页面默认读取 /sdcard/photo 目录下的 .jpg 或 .jpeg 图片。
Arduino 开发
问：为什么 Arduino 示例需要使用 ESP32 Arduino Core v3.3.10？
答：ESP32-C5-LCD-2.73 板载 MCU 模组为 ESP32-C5-WROOM-1-N32R8，芯片版本属于 v1.2。较旧版本的 ESP32 Arduino Core 可能无法正确识别该开发板，导致开发板无法选择、串口下载失败或烧录异常。
请在 Arduino IDE 的开发板管理器中安装 esp32 by Espressif Systems v3.3.10。Arduino 工程参数设置中，开发板需要选择 ESP32C5 Dev Module。
问：Arduino 编译提示找不到库文件怎么办？
答：请先确认已经安装示例对应的库文件。Arduino 库通常复制到以下目录：
C:\Users\<用户名>\Documents\Arduino\libraries
常见缺失文件和对应库如下：
| 编译提示 | 对应示例 | 需要安装的库 | 说明 |
|---|---|---|---|
找不到 lvgl.h | 01_lvgl_demo、07_example | code/arduino/libraries/lvgl | 示例包内置 LVGL v8.4.0，不要同时安装多个不同版本的 LVGL |
找不到 SensorPCF85063.hpp | 04_I2C_pcf85063、07_example | SensorLib | 用于 PCF85063 RTC 驱动 |
复制完成后建议重启 Arduino IDE 再重新编译。
问：Arduino 示例屏幕不亮时应该先查哪里？
答：请优先运行 06_exio。本产品的 LCD 复位和背光控制都与 CH32V003 IO 扩展有关，如果 CH32V003 I2C 通信不正常，后续 LCD 示例也可能异常。
确认 06_exio 正常后，再检查 01_lvgl_demo 或 07_example。如果屏幕不亮，重点检查 ILI9488 引脚、CH32 IO0 复位、背光初始化和 LVGL 版本。
问：Arduino 示例中的 I2C 和 SD 卡引脚是什么？
答：Arduino 示例使用以下板载连接：
| 功能 | 引脚 |
|---|---|
| I2C SDA | GPIO27 |
| I2C SCL | GPIO26 |
| SD SCLK | GPIO6 |
| SD MOSI | GPIO7 |
| SD MISO | GPIO5 |
| SD CS | GPIO9 |
LCD 和 SD 卡共用 SPI 时钟、MOSI 和 MISO 引脚，切换示例后如出现总线状态异常，可重新上电后单独运行对应示例。
ESP-IDF 开发
问：ESP-IDF 示例烧录后没有看到预期现象，应先检查什么？
答：不同示例依赖的外设和准备文件不同。若程序可以正常烧录，但屏幕或串口没有预期现象，请先按下表检查：
| 示例 | 运行前需要注意的内容 |
|---|---|
01_factory | 工厂菜单示例。相册页面需要 SD 卡中存在 /photo 目录和 JPG 图片；天气页面需要先配置可联网 Wi-Fi。 |
02_lvgl_demo | 使用板载 LCD 和背光，运行 LVGL benchmark。 |
03_sd_card | 需要插入 FAT 或 FAT32 格式的 Micro SD 卡，串口会输出写入和读回校验结果。 |
04_qmi8658 | 主要查看串口输出的加速度和陀螺仪数据。 |
05_pcf85063 | 主要查看串口输出的 RTC 时间。 |
06_shtc3 | 主要查看串口输出的温湿度数据。 |
07_exio | 用于测试 CH32V003 IO 扩展，循环翻转 IO4~IO14，屏幕无演示界面。 |
问：为什么部分 ESP-IDF 示例烧录后屏幕不点亮？
答：部分示例不是 LCD 显示示例，屏幕不点亮属于正常现象，请优先查看串口日志或对应外设现象。
| 示例 | 屏幕状态说明 |
|---|---|
01_factory、02_lvgl_demo | 使用 LCD 显示界面，正常情况下屏幕应点亮。 |
03_sd_card、04_qmi8658、05_pcf85063、06_shtc3、07_exio | 主要通过串口或外设现象查看结果，不作为 LCD 演示示例。 |
如果运行的是带 LCD 显示的示例但屏幕仍不亮，请检查以下内容：
- 串口日志是否显示程序已经正常启动，是否有 LCD、LVGL、CH32V003 或背光初始化失败的报错。
- 是否使用支持数据传输且供电稳定的 USB 线，建议直连电脑 USB 接口测试。
- 是否烧录了正确的示例工程，并确认开发板型号与示例工程对应。
- 如基于示例二次开发，请先确认应用层仍调用了 LCD、LVGL 和背光相关接口。
二次开发
问：使用 AI 辅助修改 ESP-IDF 示例时，应该先告诉 AI 哪些前提？
答：建议在提问时先说明以下前提，避免 AI 误改底层驱动、引脚或 BSP：
我使用的是 Waveshare ESP32-C5-LCD-2.73，ESP-IDF 示例位于 code/idf，目标芯片为 esp32c5。
开发板已适配 ILI9488 LCD、CH32V003 IO 扩展、Micro SD、QMI8658、PCF85063 和 SHTC3。
常规二次开发请优先修改应用层或 UI 逻辑，不要优先修改 BSP、引脚定义、分区表和底层驱动。
CH32V003 固件出厂已烧录好，不需要单独为 CH32V003 烧录程序。
修改后请检查是否仍调用了 LCD、LVGL、背光和所需外设初始化接口。
常规功能修改建议从 main 或示例自带业务组件开始。除非明确需要更换硬件连接、调整底层驱动或适配新外设，否则不建议修改 BSP。
问：常见二次开发需求应该修改哪些位置？
答：可以先按下表定位，避免修改 BSP 或底层驱动。
| 需求 | 建议修改位置 |
|---|---|
| 修改工厂菜单入口 | 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 |
| 修改 LVGL benchmark 示例 | 02_lvgl_demo/main/main.c |
| 修改 SD 卡读写测试内容 | 03_sd_card/main/main.c |
| 修改 QMI8658 读取或输出格式 | 04_qmi8658/main/main.c |
| 修改 RTC 读取或时间设置逻辑 | 05_pcf85063/main/main.c |
| 修改 SHTC3 读取间隔或输出格式 | 06_shtc3/main/main.c |
| 修改 EXIO 输出范围或翻转间隔 | 07_exio/main/main.c |
硬件与接口
问：CH32 的作用是什么？为什么部分引脚由 CH32 控制？
答：CH32V003 主要作为 IO 扩展控制器使用。ESP32-C5 作为主控，通过 I2C 与 CH32V003 通信；CH32V003 作为从机，根据 ESP32-C5 下发的指令控制部分外设引脚。
由于 ESP32-C5 可用 GPIO 数量有限，板上将一些只需要高低电平或 PWM 控制的信号交由 CH32V003 管理，例如 LCD_RST 和 LCD 背光。背光 PWM 控制也由 CH32V003 提供。
CH32V003 出厂时已经烧录好控制固件，无需单独为 CH32V003 烧录程序。运行示例时，只需要编译和烧录 ESP32-C5 端的工程即可。
问：LCD 显示驱动是什么？
答：本产品的 LCD 显示驱动芯片为 ILI9488，分辨率为 320 x 320。BSP 和示例工程已经完成 ILI9488 显示驱动和背光等基础接口适配。
常规二次开发时，通常只需要修改应用层或 UI 逻辑；如果自行适配其他工程或框架，请注意 LCD 使用 SPI 接口，复位和背光由 CH32V003 控制。
问：板载 I2C 设备地址分别是多少？
答：本产品板载 I2C 设备共用 SDA GPIO27、SCL GPIO26。常用 7-bit I2C 地址如下：
| 设备 | 功能 | I2C 地址 |
|---|---|---|
| CH32V003 | IO 扩展、LCD 复位、背光控制 | 0x24 |
| QMI8658 | 六轴传感器 | 0x6B |
| PCF85063 | RTC 实时时钟 | 0x51 |
| SHTC3 | 温湿度传感器 | 0x70 |
以上地址为 7-bit I2C 地址；若使用某些扫描工具或数据手册中的 8-bit 读写地址，显示结果可能会不同。