FAQ

Serial Port and Downloading

Q: How can I check the current COM port?

A: On Windows, open Device Manager and expand "Ports (COM & LPT)" to view the port number. On Linux, use ls /dev/ttyUSB* or dmesg in the terminal to check for the serial device.

Q: I cannot connect to the serial port when reprogramming the device. What should I do?

A:

1. First, open the task manager and check whether other applications, such as Arduino IDE or VS Code, are occupying the serial port. If so, close the relevant application and retry. Restart your computer if necessary.
2. Try entering download mode: disconnect USB, press and hold the BOOT button on the board, reconnect to your computer, then release the BOOT button. Afterwards, re‑check whether the COM port is detected correctly.
3. Check whether you are connecting the board through a docking station or hub. If so, try connecting directly to a USB port on your computer.
4. If the issue persists, try multiple USB cables that support data transfer, such as phone data cables.

Q: Why is there no serial output after successfully flashing the code?

A: The ESP32‑C6‑Touch‑LCD‑2.8 uses the native USB functionality of the ESP32‑C6. Check the USB CDC, serial output, and port configuration in your project, and make sure the serial monitor is using the correct port and baud rate.

Factory Firmware and Basic Usage

Q: Why can't the weather example in the factory firmware retrieve weather information?

A: The weather example requires connecting to a specified Wi‑Fi hotspot before it can access the weather API to fetch data. Please follow these steps to verify:

1. Turn on the Wi‑Fi hotspot before powering up the board, and ensure the hotspot name and password match those in the example program:

   Wi‑Fi SSID: weather-wifi
   Wi‑Fi Password: 12345678
   

2. If the weather information still cannot be retrieved, first try connecting to the hotspot with your phone or computer to confirm that the hotspot is working and has internet access.

3. The ESP32-C6 only supports 2.4GHz Wi-Fi, not 5GHz. Verify that the SSID and password are correct, and check whether the network has firewall restrictions, no internet access permissions, or limited API access.

Q: Can I use the board without a TF card?

A: Yes. Examples that require TF card read/write or audio file reading will not work.

Q: What should I be aware of when using the TF card?

A: The board supports TF cards up to 64 GB. Please format the card as FAT32 before use.

Working with Arduino

Q: Why is ESP32 Arduino Core v3.3.10 required for the Arduino examples?

A: The ESP32-C6-Touch-LCD-2.8 uses the ESP32-C6-WROOM-1 MCU module with a maximum frequency of 160MHz. Older versions of the ESP32 Arduino Core may not correctly identify this board, causing issues such as the board not being selectable, serial download failures, or flashing errors.

Please install esp32 by Espressif Systems v3.3.10 in the Arduino IDE Board Manager and use the example/Arduino-v3.3.10 examples from the product resource package. In the Arduino project settings, select ESP32C6 Dev Module as the board.

Q: What should I do if Arduino compilation fails with library files not found?

A: First, verify that the required libraries for the example have been installed. Arduino libraries should be copied to the following directory:

C:\Users\<username>\Documents\Arduino\libraries

Common missing files and their corresponding libraries are listed below:

Compilation Error	Corresponding Example	Library Directory to Copy	Notes
lvgl.h not found	06_lvgl_demo	example/Arduino-v3.3.10/lib/lvgl	LVGL v8.4.0 is included in the example package; do not install multiple versions of LVGL simultaneously
SensorPCF85063.hpp not found	04_I2C_pcf85063	example/Arduino-v3.3.10/lib/SensorLib	The SensorLib version in the example package is v0.3.1

After copying, restart Arduino IDE and recompile. The SensorLib version can be verified by checking version=0.3.1 in SensorLib/library.properties.

Q: What should I check first if the screen does not light up or touch does not respond in the Arduino examples?

A: Please run 01_exio first. On this product, LCD reset, touch reset, and backlight control are all related to the CH32V003 I/O expander. If CH32V003 I2C communication is not working, subsequent LCD and touch examples may also behave abnormally.

After confirming 01_exio works, check 06_lvgl_demo. If the screen does not light up, focus on the ST7789 pins, CH32 EXIO reset pins, backlight initialization, and LVGL version. If touch does not respond, verify that the Touch_CST3530 file retains its original configuration.

The touch controller is CST3530 with I2C address 0x58, using SDA GPIO6, SCL GPIO7, touch interrupt GPIO18, and touch reset controlled by CH32V003 EXIO0. The 06_lvgl_demo example has already been adapted for the ST7789 display and CST3530 touch; no additional GFX display library or third‑party touch library is required in normal cases.

Working with ESP-IDF

Q: What should I check first if the ESP-IDF example does not show the expected behavior after flashing?

A: Different examples depend on different peripherals and preparation files. If the program flashes successfully but the screen, serial, or audio does not behave as expected, please refer to the table below:

Example	Pre‑run Checklist
01_ch32_test	Primarily check serial logs to verify CH32 I/O expander functionality; no screen UI is displayed. The CH32V003 firmware is pre‑flashed at the factory and does not require separate flashing
02_2048	Uses the onboard LCD and touchscreen. After power‑up, swipe on the screen to interact. The UI is generated with GUI Guider; UI and event code are in the components/generated directory
03_sd_lvgl	Requires a FAT32‑formatted TF card with a Test.txt file in the root directory
04_sd_music	Requires a FAT32‑formatted TF card with a music folder in the root directory and .mp3 files inside. A speaker must also be connected
05_spiff_music	Music files come from the SPIFFS file system within the project, not the TF card. MP3 files should be placed in the example project's spiffs/music directory.
06_wifi_weather	Requires an internet-connected 2.4GHz Wi-Fi hotspot to be turned on first, default SSID weather-wifi, password 12345678; ESP32-C6 does not support 5GHz Wi-Fi
07_Ball_qmi	Place the board flat during startup calibration. After calibration, tilt the board to observe ball movement
08_bookesia	Uses the onboard LCD and touchscreen. After power‑up, interact with the UI and drawing board app via touch

Q: Why does the screen not turn on for some ESP-IDF examples after flashing?

A: Some examples are not LCD display examples. It is normal for the screen to remain off. Please check the serial logs or corresponding peripheral behavior first.

Example	Screen Status Description
01_ch32_test	This example tests the CH32 I/O expander; results are primarily viewed via serial logs, and no GUI is displayed
04_sd_music	This example verifies TF card MP3 playback. The main observable behavior is music playing through the speaker; the screen is not the primary output
02_2048, 03_sd_lvgl, 05_spiff_music, 06_wifi_weather, 07_Ball_qmi, 08_bookesia	These examples use the LCD for display or UI; the screen should normally turn on

If you are running an LCD‑enabled example but the screen remains off, check the following:

1. Check the serial log to see if the program started successfully and if there are any errors related to LCD, touch, or backlight initialization failures.
2. Ensure you are using a USB cable that supports data transfer and provides stable power. We recommend connecting directly to a USB port on your computer.
3. Verify that you have flashed the correct example and that the board model matches the example.
4. If you are modifying the example, confirm that the application layer still calls the LCD, LVGL, and backlight initialization interfaces. Routine UI and business logic modifications do not require BSP changes. Only modify the BSP if you change hardware connections, adapt low‑level drivers, or add new peripherals.

Q: What is the difference between 04_sd_music and 05_spiff_music? Aren't they both for playing audio?

A: Both 04_sd_music and 05_spiff_music are audio playback examples, but they differ in where the audio files are stored and their applicable scenarios.

1. The 04_sd_music example plays audio files from the TF card. Before using it, format the TF card as FAT32, create a music folder in the root directory, and place .mp3 audio files into that folder.

2. The 05_spiff_music example plays audio files stored in the Flash file system, making it suitable for building a music player interface with LVGL.

The key difference is that on the ESP32-C6, the TF card and LCD share SPI bus resources defined by the BSP. If audio data is frequently read from the TF card while refreshing the LVGL interface, real‑time performance may degrade, causing playback stuttering or display issues. Therefore, 04_sd_music is mainly used to verify TF card audio playback functionality without turning on the display, while 05_spiff_music plays audio from Flash, allowing better integration with the screen interface for a complete music player demonstration.

Q: Where should the MP3 files be placed for the 05_spiff_music example? Do I need to manually flash SPIFFS?

A: The MP3 files for the 05_spiff_music example are not stored on the TF card. They should be placed in the example project's spiffs/music directory.

The example has already configured the following in main/CMakeLists.txt:

spiffs_create_partition_image(storage ../spiffs FLASH_IN_PROJECT)

Therefore, when you run idf.py build flash monitor, the project will package the spiffs directory and flash it to the storage partition. If you need to change the music, place the new .mp3 files in 05_spiff_music/spiffs/music and rebuild/flash the project.

AI and Secondary Development

Q: What prerequisites should I tell the AI when using it to help modify ESP-IDF examples?

A: We recommend providing the following context when asking the AI for help, to avoid unintended modifications to low‑level drivers, pin definitions, or the BSP:

I am using the Waveshare ESP32-C6-Touch-LCD-2.8 with ESP-IDF v5.5.4, and the example is based on LVGL v9.
The BSP, LCD, touch, backlight, audio, sensors, and CH32 I/O expansion for this board have already been adapted.
For routine secondary development, please focus on modifying the application layer or UI logic first. Do not modify the BSP, pin definitions, partition table, or low‑level drivers unless necessary.
The CH32V003 firmware is pre‑flashed at the factory; no separate flashing is required.
After modifications, please verify that the LCD, LVGL, touch, and backlight initialization interfaces are still being called.

For routine functional modifications, start with main, components/generated, components/custom, or the example's own business components. Only modify the BSP if you are changing hardware connections, adapting low‑level drivers, or adding new peripherals.

Q: Where should I make changes for common secondary development tasks?

A: Use the table below as a starting point to locate the relevant code without modifying the BSP or low‑level drivers.

Requirement	Suggested Modification Location
Modify the 2048 UI layout	02_2048/components/generated/setup_scr_Game2048.c
Modify 2048 touch, button, or game events	02_2048/components/generated/events_init.c
Add custom initialization or extension logic for 2048	02_2048/components/custom/custom.c
Change the TF card text display content	No code change needed; modify the Test.txt file in the TF card root directory
Change TF card music files	No code change needed; place .mp3 files in the music folder on the TF card root
Change SPIFFS music files	Place .mp3 files in 05_spiff_music/spiffs/music and rebuild/flash
Modify Wi‑Fi SSID, password, city, or API path for weather	Modify WIFI_SSID, WIFI_PASSWORD, WEB_PATH, etc., in 06_wifi_weather/components/generated/events_init.c. Do not modify the Wi‑Fi example settings in sdkconfig
Modify gravity ball sensitivity, calibration, or movement logic	07_Ball_qmi/components/ball_qmi/ball_qmi.c and ball_qmi.h
Modify Brookesia drawing board entry or application logic	See 08_bookesia/main/main.cpp and the example's built‑in application code

Hardware and Interfaces

Q: What is the purpose of the CH32? Why are some pins controlled by CH32?

A: The CH32 is a microcontroller from WCH, primarily used as an I/O expander controller. The ESP32‑C6 acts as the main controller and communicates with the CH32 via I2C. The CH32, functioning as a slave device, controls certain peripheral pins according to commands sent by the ESP32‑C6.

The board offloads signals that only require high/low level or PWM control to the CH32, such as LCD_RST, TP_RST, RTC_INT, PA_CTRL, and LCD_BL. The corresponding expansion pins are EXIO1, EXIO0, EXIO2, EXIO3, and EXIO_PWM; EXIO4~EXIO7 are available for user expansion

Additionally, backlight PWM control is also provided by the CH32 via EXIO_PWM. Users can refer to the 01_ch32_test example and the relevant interfaces in the BSP project for integration and secondary development.

The CH32V003 is pre‑flashed with control firmware at the factory. No separate flashing is required. When running the examples, you only need to compile and flash the ESP32-C6 side.

Q: What are the LCD display driver and touch driver respectively?

A: The LCD display driver chip is ST7789, and the capacitive touch driver chip is CST3530.

The BSP and example projects have already adapted the ST7789 display driver, CST3530 touch driver, and basic interfaces such as backlight. For routine secondary development, you typically only need to modify the application layer or UI logic. If you are porting to other projects or frameworks, note that the LCD uses SPI and the touch uses I2C.

Q: What are the I2C device addresses on the board?

A: The onboard I2C devices share SDA GPIO6 and SCL GPIO7. The touch interrupt uses GPIO18, QMI8658 INT1 uses GPIO19, and the RTC interrupt is controlled by CH32V003 EXIO2. The common 7‑bit I2C addresses are:

Device	Function	I2C Address
CH32V003	I/O expander, LCD reset, touch reset, backlight control	0x24
QMI8658	6‑axis sensor	0x6B
PCF85063	RTC real‑time clock	0x51
SHTC3	Temperature and humidity sensor	0x70
CST3530	Capacitive touch	0x58

The above addresses are 7‑bit I2C addresses. Some scanning tools or datasheets may use 8‑bit read/write addresses, which may appear differently.

Q: Can I remove the screen myself?

A: The screen is bonded to the backplane. Do not attempt to remove it or pry open the adhesive layer, as this may damage the display.

Q: What is the maximum brightness of the screen?

A: 450 cd/㎡.