跳到主要内容

产品 FAQ

串口与下载​

问：如何查看当前使用的 COM 口？

答：Windows 系统可打开“设备管理器”并展开“端口（COM 和 LPT）”查看端口号。Linux 系统可在终端中使用 ls /dev/ttyUSB* 或 dmesg 查看串口设备。

问：重新下载程序时无法连接串口，如何处理？

答：

  1. 请先打开后台任务管理器，确认是否有其他应用占用串口，例如 Arduino IDE、VS Code 等。如有占用，请关闭相关应用后重试，必要时可重启电脑。
  2. 尝试进入下载模式：先断开 USB，长按开发板上的 BOOT 按键，再接入电脑，最后松开 BOOT 按键。随后重新检查 COM 口是否可以正常识别。
  3. 请检查是否通过拓展坞连接开发板。如使用拓展坞，建议改为直连电脑 USB 接口。
  4. 若仍无法连接，请更换多条支持数据传输的 USB 线材进行测试，例如手机数据线。
问：为什么代码成功烧录后没有串口输出？

答：ESP32-C6-Touch-LCD-2.8 使用 ESP32-C6 原生 USB 功能。请检查工程中的 USB CDC、串口输出和端口配置，并确认串口监视器选择了正确端口和波特率。

出厂固件与基础使用​

问：为什么运行出厂固件天气示例时无法获取天气信息？

天气示例需要先连接到指定 Wi-Fi 热点后，才能访问天气 API 获取数据。请按以下步骤检查：

  1. 上电前请先开启 Wi-Fi 热点，并确保热点名称和密码与示例程序一致：

    Wi-Fi 名称：weather-wifi
    Wi-Fi 密码：12345678

  2. 若仍无法获取天气信息，请先使用手机或电脑连接该热点，确认热点可以正常连接并可访问互联网。

  3. ESP32-C6 仅支持 2.4GHz Wi-Fi，不支持 5GHz Wi-Fi。请确认热点名称和密码正确，并检查网络是否存在防火墙、无网络访问权限或 API 访问受限等情况。

问：没有 SD 卡时可以使用开发板吗？

答：可以使用。与 SD 卡读写、音频读取相关的示例不可用。

问：使用 SD 卡需要注意什么？

答：最大仅支持 64G 及其以下的 SD 卡，使用前请先格式化为 FAT32 格式。

Arduino 开发​

问：为什么 Arduino 示例必须使用 ESP32 Arduino Core v3.3.10？

答：ESP32-C6-Touch-LCD-2.8 板载 MCU 模组为 ESP32-C6-WROOM-1，主频最高 160MHz。较旧版本的 ESP32 Arduino Core 可能无法正确识别该开发板，导致开发板无法选择、串口下载失败或烧录异常。

请在 Arduino IDE 的开发板管理器中安装 esp32 by Espressif Systems v3.3.10，并使用产品资料包中的 example/Arduino-v3.3.10 示例。Arduino 工程参数设置中，开发板需要选择 ESP32C6 Dev Module。

问：Arduino 编译提示找不到库文件怎么办？

答：请先确认已经安装示例对应的库文件。Arduino 库统一复制到以下目录：

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

常见缺失文件和对应库如下：

编译提示对应示例需要复制的库目录说明
找不到 lvgl.h06_lvgl_demoexample/Arduino-v3.3.10/lib/lvgl示例包内置 LVGL v8.4.0，不要同时安装多个不同版本的 LVGL
找不到 SensorPCF85063.hpp04_I2C_pcf85063example/Arduino-v3.3.10/lib/SensorLib示例包内 SensorLib 版本为 v0.3.1

复制完成后建议重启 Arduino IDE 再重新编译。SensorLib 版本可在 SensorLib/library.properties 中查看 version=0.3.1。

问：Arduino 示例屏幕不亮或触摸没有反应时应该先查哪里？

答：请优先运行 01_exio。本产品的 LCD 复位、触摸复位和背光控制都与 CH32V003 IO 扩展有关，如果 CH32V003 I2C 通信不正常，后续 LCD 和触摸示例也可能异常。

确认 01_exio 正常后，再检查 06_lvgl_demo。如果是屏幕不亮，重点检查 ST7789 引脚、CH32 EXIO 复位脚、背光初始化和 LVGL 版本；如果是触摸没有反应，重点检查 Touch_CST3530 文件是否保持原始配置。

触摸芯片为 CST3530，I2C 地址为 0x58，使用 SDA GPIO6、SCL GPIO7，触摸中断为 GPIO18，触摸复位由 CH32V003 的 EXIO0 控制。06_lvgl_demo 已经适配 ST7789 显示和 CST3530 触摸，正常情况下不需要额外引入 GFX 显示库或第三方触摸库。

ESP-IDF 开发​

问：ESP-IDF 示例烧录后没有看到预期现象，应先检查什么？

答：不同示例依赖的外设和准备文件不同。若程序可以正常烧录，但屏幕、串口或音频没有预期现象，请先按下表检查：

示例运行前需要注意的内容
01_ch32_test主要查看串口日志，用于验证 CH32 IO 扩展功能，屏幕无演示界面；CH32V003 固件出厂已烧录好，无需单独烧录。
02_2048使用板载 LCD 和触摸屏，上电后可在屏幕上滑动操作；UI 基于 GUI Guider 生成，界面和事件代码位于 components/generated 目录。
03_sd_lvgl需要插入 FAT32 格式的 Micro SD 卡，并在 SD 卡根目录放置 Test.txt 文件。
04_sd_music需要插入 FAT32 格式的 Micro SD 卡，在根目录创建 music 文件夹，并放入 .mp3 文件；同时需要连接喇叭。
05_spiff_music音乐文件来自工程内的 SPIFFS 文件系统，不是 SD 卡。MP3 文件应放在示例工程的 spiffs/music 目录中。
06_wifi_weather需要先开启可联网的 2.4GHz Wi-Fi 热点，默认名称为 weather-wifi，密码为 12345678；ESP32-C6 不支持 5GHz Wi-Fi。
07_Ball_qmi启动校准时请将开发板水平放置，校准后倾斜开发板观察小球移动。
08_bookesia使用板载 LCD 和触摸屏，上电后通过触摸操作界面和画板应用。
问：为什么部分 ESP-IDF 示例烧录后屏幕不点亮？

答：部分示例不是 LCD 显示示例，屏幕不点亮属于正常现象，请优先查看串口日志或对应外设现象。

示例屏幕状态说明
01_ch32_test该示例用于测试 CH32 IO 扩展，主要通过串口查看测试结果，不会显示图形界面。
04_sd_music该示例用于验证 SD 卡 MP3 播放链路，主要现象是喇叭播放音乐，屏幕不作为主要演示输出。
02_2048、03_sd_lvgl、05_spiff_music、06_wifi_weather、07_Ball_qmi、08_bookesia这些示例会使用 LCD 显示界面或内容，正常情况下屏幕应点亮。

如果运行的是带 LCD 显示的示例但屏幕仍不亮，请检查以下内容：

  1. 串口日志是否显示程序已经正常启动，是否有 LCD、触摸或背光初始化失败的报错。
  2. 是否使用支持数据传输且供电稳定的 USB 线，建议直连电脑 USB 接口测试。
  3. 是否烧录了正确的示例工程，并确认开发板型号与示例工程对应。
  4. 如基于示例二次开发，请先确认应用层仍调用了 LCD、LVGL 和背光相关接口。常规 UI 和业务逻辑修改不需要优先改 BSP；仅在更换硬件连接、调整底层驱动或适配新外设时，再修改 BSP 相关代码。
问：04_sd_music 和 05_spiff_music 的区别是什么，不都是播放音频吗？

答：04_sd_music 和 05_spiff_music 都是音频播放示例，但音频文件的存放位置和适用场景不同。

  1. 04_sd_music 示例播放的是 SD 卡中的音频文件。使用前请先将 SD 卡格式化为 FAT32，然后在 SD 卡根目录创建 music 文件夹，并将 .mp3 后缀的音频文件放入该文件夹中。

  2. 05_spiff_music 示例播放的是存储在 Flash 文件系统中的音频文件，适合用于配合 LVGL 界面实现音乐播放器效果。

两者的核心区别在于：ESP32-C6 的 SD 卡和 LCD 屏幕共用 BSP 定义的 SPI 总线资源。如果在播放过程中频繁从 SD 卡读取音频数据，同时还要刷新 LVGL 界面，可能会导致实时性下降、播放卡顿或显示异常。因此，04_sd_music 示例主要用于验证 SD 卡音频播放功能，不点亮屏幕；而 05_spiff_music 将音频文件放在 Flash 中播放，可以更好地配合屏幕界面，实现完整的音乐播放器演示效果。

问：05_spiff_music 的 MP3 文件应该放在哪里？是否需要手动烧录 SPIFFS？

答：05_spiff_music 示例的 MP3 文件不放在 SD 卡中，而是放在示例工程的 spiffs/music 目录中。

该示例已经在 main/CMakeLists.txt 中配置了：

spiffs_create_partition_image(storage ../spiffs FLASH_IN_PROJECT)

因此正常执行 idf.py build flash monitor 时，工程会把 spiffs 目录一起打包并烧录到 Flash 的 storage 分区。若需要更换音乐，请将 .mp3 文件放到 05_spiff_music/spiffs/music 目录后重新编译烧录。

AI 与二次开发​

问：使用 AI 辅助修改 ESP-IDF 示例时，应该先告诉 AI 哪些前提？

答：建议在提问时先说明以下前提，避免 AI 误改底层驱动、引脚或 BSP：

我使用的是 Waveshare ESP32-C6-Touch-LCD-2.8，ESP-IDF 版本为 v5.5.4，示例基于 LVGL v9。
开发板的 BSP、LCD、触摸、背光、音频、传感器和 CH32 IO 扩展已经适配完成。
常规二次开发请优先修改应用层或 UI 逻辑，不要优先修改 BSP、引脚定义、分区表和底层驱动。
CH32V003 固件出厂已烧录好，不需要单独为 CH32V003 烧录程序。
修改后请检查是否仍调用了 LCD、LVGL、触摸和背光初始化接口。

常规功能修改建议从 main、components/generated、components/custom 或示例自带的业务组件开始。除非明确需要更换硬件连接、调整底层驱动或适配新外设，否则不建议修改 BSP。

问：常见二次开发需求应该修改哪些位置？

答：可以先按下表定位，避免修改 BSP 或底层驱动。

需求建议修改位置
修改 2048 界面布局02_2048/components/generated/setup_scr_Game2048.c
修改 2048 触摸、按钮、游戏事件02_2048/components/generated/events_init.c
添加 2048 自定义初始化或扩展逻辑02_2048/components/custom/custom.c
修改 SD 卡文本显示内容不需要改代码，修改 SD 卡根目录下的 Test.txt 文件即可。
更换 SD 卡播放音乐不需要改代码，将 .mp3 文件放入 SD 卡根目录的 music 文件夹。
更换 SPIFFS 音乐将 .mp3 文件放入 05_spiff_music/spiffs/music 后重新编译烧录。
修改天气 Wi-Fi 名称、密码、城市或 API 路径06_wifi_weather/components/generated/events_init.c 中的 WIFI_SSID、WIFI_PASSWORD、WEB_PATH 等配置。不要优先修改 sdkconfig 中的 Wi-Fi 示例配置。
修改重力小球灵敏度、校准或移动逻辑07_Ball_qmi/components/ball_qmi/ball_qmi.c 和 ball_qmi.h。
修改 Brookesia 画板示例入口或应用逻辑查看 08_bookesia/main/main.cpp 以及示例自带应用相关代码。

硬件与接口​

问：CH32 的作用是什么？为什么部分引脚由 CH32 控制？

CH32 是沁恒单片机，主要作为 IO 扩展控制器使用。ESP32-C6 作为主控，通过 I2C 与 CH32 通信；CH32 作为从机，根据 ESP32-C6 下发的指令控制部分外设引脚。

板上将一些只需要高低电平或 PWM 控制的信号交由 CH32 管理，例如 LCD_RST、TP_RST、RTC_INT、PA_CTRL 和 LCD_BL 等。对应扩展引脚分别为 EXIO1、EXIO0、EXIO2、EXIO3 和 EXIO_PWM；EXIO4~EXIO7 可用于用户扩展。

此外，背光 PWM 控制也由 CH32 提供，对应 EXIO_PWM。可参考 01_ch32_test 示例及 BSP 工程中的相关接口进行调用和二次开发。

CH32V003 出厂时已经烧录好控制固件，无需单独为 CH32V003 烧录程序。运行示例时，只需要编译和烧录 ESP32-C6 端的工程即可。

问：LCD 显示驱动和触摸驱动分别是什么？

答：本产品的 LCD 显示驱动芯片为 ST7789，电容触摸驱动芯片为 CST3530。

BSP 和示例工程已经完成 ST7789 显示驱动、CST3530 触摸驱动以及背光等基础接口适配。常规二次开发时，通常只需要修改应用层或 UI 逻辑；如果自行适配其他工程或框架，请注意 LCD 使用 SPI 接口，触摸使用 I2C 接口。

问：板载 I2C 设备地址分别是多少？

答：本产品板载 I2C 设备共用 SDA GPIO6、SCL GPIO7。触摸中断使用 GPIO18，QMI8658 的 INT1 使用 GPIO19，RTC 中断由 CH32V003 的 EXIO2 控制。常用 7-bit I2C 地址如下：

设备功能I2C 地址
CH32V003IO 扩展、LCD 复位、触摸复位、背光控制0x24
QMI8658六轴传感器0x6B
PCF85063RTC 实时时钟0x51
SHTC3温湿度传感器0x70
CST3530电容触摸0x58

以上地址为 7-bit I2C 地址；若使用某些扫描工具或数据手册中的 8-bit 读写地址，显示结果可能会不同。

问：屏幕可以自行拆卸吗？

答：屏幕与背板采用贴合结构。请避免自行拆卸或撬开胶层，拆解可能导致屏幕损坏。

问：屏幕的最大亮度是多少？

答：450 cd/㎡