Features​

• Utilizes the ESP32-C5-WROOM-1 series module, equipped with a RISC-V 32-bit processor running at up to 240MHz.
• Integrated 384KB SRAM, 320KB ROM, 8MB PSRAM, and 32MB Flash, balancing program execution, GUI rendering, and data storage requirements.
• Integrated 2.4 GHz and 5 GHz dual‑band Wi‑Fi, Bluetooth 5 (LE), and IEEE 802.15.4 (supporting Zigbee 3.0 and Thread) wireless connectivity.
• Onboard battery charging management module, with a reserved 3.7V MX1.25 lithium battery interface for external battery power supply.
• Type‑C interface for power, programming, and debugging, supporting reversible insertion.
• Onboard 2.8inch LCD with 240 × 320 resolution, 262K colors.
• Supports I2C capacitive touch control with interrupt support.
• Exposes UART, I2C, and some I/O interfaces; integrated full‑speed USB serial port.
• Onboard QMI8658 six‑axis sensor, RTC clock sensor, SHTC3 temperature and humidity sensor, and TF card slot.
• Supports flexible clock, multiple power modes, and other precise controls to enable low‑power operation in various scenarios.
• Onboard ES8311 audio codec chip, NS4150B power amplifier chip, microphone, and speaker for voice interaction and audio playback.
• Supports ESP‑IDF / Arduino development environments for quick prototyping and secondary development.

Onboard Resources​

Interface Introduction​

Dimensions​

This section provides usage instructions for each functional example in the factory firmware, helping users understand the onboard resources and interface usage of the ESP32-C5-Touch-LCD-2.8. Before running the examples, please prepare the following components:

Required Components​

• ESP32-C5-Touch-LCD-2.8 ×1
• TF Card ×1
• Speaker ×1
• Battery ×1

Wi-Fi Configuration​

• Before use, turn on a Wi-Fi hotspot. The ESP32-C5 supports dual-band Wi‑Fi; you can choose either the 2.4 GHz or 5 GHz band according to your environment.
• Wi‑Fi SSID: weather-wifi
• Wi‑Fi Password: 12345678
• Band: 2.4 GHz / 5 GHz. Note that some phones may not support 5 GHz hotspots. If you cannot connect, switch to a 2.4 GHz hotspot.
• The Wi‑Fi SSID and password in the factory firmware are fixed. The hotspot you use must match the above configuration; otherwise, the device will not be able to connect.

Precautions​

⚠️ USB Download Precautions (Important)​

BAT_PWR Button Test​

• After connecting the battery, the device can be powered directly by the battery and will turn on the screen (controlled by hardware circuitry, not software).
• Long‑press the BAT_PWR button for about 2 seconds to power off. After power‑off, press the BAT_PWR button again to power on.

Firmware Download​

• The factory firmware is located in the Firmware directory of the example package.

Example Overview​

• The firmware uses the brookesia component to implement an APP‑style interface, including Settings, Photo Album, Music Player, 2048 Game, Weather, Drawing Board, Xiaozhi AI, Gravity Ball, Factory, and other apps.

App Example Introduction​

Settings APP​

• Supports Wi‑Fi scanning and provisioning. Click wifi config in the Wi‑Fi interface to scan a QR code for network provisioning.

• Allows adjusting display brightness, viewing TF card size, and checking the MAC address in the product info section.

  
  

XiaoZhi AI APP​

• Tap the APP to launch the Xiaozhi AI application, which is consistent with the version adapted for the Xiaozhi official website and operates in the same way.
• Long‑press the BOOT button to return to the brookesia interface.

Sensor APP​

• Displays real‑time data from various sensors.
• When you rotate the board, the gyroscope data changes accordingly; the RTC clock increments by the second.
• When you cover the temperature/humidity sensor with your hand, the humidity value will gradually rise, while the temperature value usually changes little or remains stable.

Drawing Board APP​

• Allows freehand drawing.

2048 APP​

• Displays the current score and the best score in real time, and supports restarting the game with one tap.

MusicPlayer APP​

• Supports playing MP3 audio files.
• Before use, connect a speaker to the onboard speaker connector, then tap the play button to play the MP3 file stored in Flash.
• Currently, the example only supports play and pause; switching tracks is not supported.

Weather APP​

• After the device connects to the network, it will automatically fetch and parse the current day's weather information for Shenzhen within a few seconds.
• For secondary development, modify the ESP‑IDF example 06_wifi_weather as needed.

Gravity Ball​

• This example demonstrates a gravity ball app based on the six‑axis IMU. The ball moves in real time according to the board's tilt angle and orientation changes.
• Before use, place the board flat on a table and wait for the ball to finish loading before picking it up.
• Tap the BOOT button to reset the ball's position.

Photo Album APP​

• Supports displaying JPG images at 240×320 resolution or lower.

• Emulates a digital photo album interface. This APP requires a TF card. Copy the photo folder from the example program sdcard/ directory to the root of the TF card.

This chapter includes the following sections, please read as needed:

• Arduino Getting Started
• Setting Up the Development Environment
• Example
• FAQ

Arduino Getting Started​

New to Arduino ESP32 development and looking for a quick start? We have prepared a comprehensive Getting Started Tutorial for you.

• Section 0: Getting to Know ESP32
• Section 1: Installing and Configuring Arduino IDE
• Section 2: Arduino Basics
• Section 3: Digital Output/Input
• Section 4: Analog Input
• Section 5: Pulse Width Modulation (PWM)
• Section 6: Serial Communication (UART)
• Section 7: I2C Communication
• Section 8: SPI Communication
• Section 9: Wi-Fi Basics
• Section 10: Web Server
• Section 11: Bluetooth
• Section 12: LVGL GUI Development
• Section 13: Comprehensive Project

Note: This tutorial uses the ESP32-S3-Zero as a reference example, and all hardware code is based on its pinout. Before you start, we recommend checking the pinout of your development board to ensure the pin configuration is correct.

Setting Up the Development Environment​

1. Installing and Configuring the Arduino IDE​

Please refer to the tutorial Installing and Configuring the Arduino IDE to download and install the Arduino IDE.

2. Installing the ESP32 Board Support Package​

Install the esp32 by Espressif Systems board support package in the Arduino IDE Board Manager.

ESP32-C5-Touch-LCD-2.8 Board Installation Requirements:

After installation, select the appropriate ESP32-C5 board in Arduino IDE and select the USB serial port currently connected.

3. Installing Libraries and Example Dependencies​

The Arduino examples for this product minimize external library dependencies, primarily using the built-in capabilities of the Arduino ESP32 core and the source code provided within the example directories. The example package already includes the required libraries in the example/Arduino-v3.3.10/lib directory. You can copy them manually for offline installation, which is suitable for environments without internet access or where the Arduino Library Manager is inconvenient to use.

Offline / Manual Installation:

1. Download and extract the product example program package. Subsequent library installation can be done offline without downloading third-party libraries from the Arduino Library Manager.

2. Locate the library directories in the example package:

   example/Arduino-v3.3.10/lib/lvgl
   example/Arduino-v3.3.10/lib/SensorLib
   

3. Copy the lvgl and SensorLib folders to your Arduino libraries directory.

   The default libraries directory on Windows is usually:

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

   You can also check the Sketchbook location via File > Preferences in the Arduino IDE; the libraries folder under that path is the libraries directory.

4. Restart Arduino IDE after installation, then open the examples to compile.

Installation Verification:

• The lvgl and SensorLib directories can be seen under Documents\Arduino\libraries.
• Documents\Arduino\libraries\SensorLib\library.properties shows version=0.3.1.
• Documents\Arduino\libraries\lvgl\library.properties shows version=8.4.0.
• The lv_conf.h file in the 06_lvgl_demo directory must remain in the example directory. Do not move it to the global Arduino libraries directory or delete it.
• Do not keep multiple different versions of lvgl or SensorLib simultaneously to avoid header file conflicts.
• If compiling 04_I2C_pcf85063 fails with SensorPCF85063.hpp not found, confirm that lib/SensorLib from the example package has been copied to the Arduino libraries directory.

4. Arduino Project Parameter Settings​

1. Open Arduino IDE.
2. Install esp32 by Espressif Systems v3.3.10.
3. In Tools > Board, select ESP32C5 Dev Module.
4. Select the USB serial port currently connected.
5. Open the corresponding .ino file in example/Arduino-v3.3.10 to compile and flash.

When using arduino-cli, refer to the following commands:

arduino-cli core install esp32:esp32@3.3.10
arduino-cli compile --fqbn esp32:esp32:esp32c5 example/Arduino-v3.3.10/06_lvgl_demo

Example​

The Arduino examples are located in the example/Arduino-v3.3.10 directory of the example package. Each example has been adapted to the actual hardware connections of the ESP32-C5-Touch-LCD-2.8.

1. Onboard Resources​

2. Example List​

3. Directory Structure​

The current Arduino examples directory contains the following projects:

example/Arduino-v3.3.10
|-- 01_exio
|-- 02_I2C_qmi8658
|-- 03_SD_Card
|-- 04_I2C_pcf85063
|-- 05_shtc3
|-- 06_lvgl_demo
`-- lib
    |-- SensorLib
    `-- lvgl

Each subdirectory is an independent Arduino example. To open an example, open the .ino file inside that directory, for example:

example/Arduino-v3.3.10/01_exio/01_exio.ino

lib/SensorLib is the RTC driver library used by 04_I2C_pcf85063 (SensorLib v0.3.1). lib/lvgl is the LVGL v8.4.0 library used by 06_lvgl_demo. Before compiling 04_I2C_pcf85063, you need to copy SensorLib at minimum. Before compiling 06_lvgl_demo, you need to copy lvgl at minimum.

4. Recommended First‑Run Order​

It is recommended to run the examples in the following order:

01_exio
  -> 02_I2C_qmi8658
  -> 03_SD_Card
  -> 04_I2C_pcf85063
  -> 05_shtc3
  -> 06_lvgl_demo

• Start with 01_exio to verify the CH32V003 I/O expander and I2C bus. LCD reset, touch reset, and backlight are all related to CH32V003, so confirm this example works first.
• Then use 02_I2C_qmi8658 to verify 6‑axis sensor data reading.
• Then use 03_SD_Card to verify the TF card and SDSPI.
• Then use 04_I2C_pcf85063 to verify RTC time setting and reading.
• Then use 05_shtc3 to verify SHTC3 temperature/humidity reading and CRC checking.
• Finally, run 06_lvgl_demo to verify LCD, backlight, touch, and LVGL all together.

5. Usage Notes​

• The Arduino example directory is example/Arduino-v3.3.10. Do not mix it with the ESP‑IDF example directory.
• This product uses a shared I2C bus: SDA GPIO0, SCL GPIO1. CH32V003, QMI8658, PCF85063, SHTC3, and CST3530 are all on this I2C bus.
• Insert a FAT or FAT32‑formatted TF card before running 03_SD_Card.
• 04_I2C_pcf85063 writes a fixed test time on every power‑up by default. To enable continuous RTC time‑keeping, comment out i2c_rtc_setTime().
• 06_lvgl_demo has already been adapted for ST7789 display and CST3530 touch. No additional GFX display library or third‑party touch library is required.
• If you copy code from other projects, pay special attention to the LCD and touch reset pins: LCD_RST = CH32 EXIO1, TP_RST = CH32 EXIO0.
• For compilation, display, touch, I2C address, and other troubleshooting, refer to the FAQ.

6. Example Details​

01_exio​

Function Description

This example verifies communication with the onboard CH32V003 I/O expander. CH32V003 communicates with the ESP32‑C5 via I2C at address 0x24. The example configures EXIO0~EXIO7 as outputs and toggles them every second.

CH32V003 is pre‑programmed with firmware at the factory; no separate CH32 firmware flashing is required.

Code Entry

01_exio/01_exio.ino
01_exio/io_extension.cpp
01_exio/io_extension.h

Recommended key code sections:

Expected Behavior

• Serial log output should look similar to this:

Troubleshooting

02_I2C_qmi8658​

Function Description

This example reads the onboard QMI8658 6‑axis sensor. After initializing I2C, the program creates a qmi8658c_example task that reads accelerometer and gyroscope data every second and outputs it over serial.

Code Entry

02_I2C_qmi8658/02_I2C_qmi8658.ino
02_I2C_qmi8658/i2c_bsp.cpp
02_I2C_qmi8658/qmi8658c.cpp

Recommended key code sections:

Expected Behavior

• Serial outputs QMI8658 initialization information, followed by sensor data every second.
• When you gently tilt or rotate the board, the accelerometer and gyroscope values change accordingly. The log should look like this:

Troubleshooting

03_SD_Card​

Function Description

This example verifies the TF card interface. It uses SDSPI mode to mount the TF card at /sd_card by default, and prints TF card information and capacity upon success.

Code Entry

03_SD_Card/03_SD_Card.ino
03_SD_Card/sd_card_bsp.cpp
03_SD_Card/sd_card_bsp.h

Recommended key code sections:

Expected Behavior

• With a FAT32‑formatted TF card inserted, the serial prints TF card type, capacity, and other information. The log should look like this:

Troubleshooting

04_I2C_pcf85063​

Function Description

This example verifies the onboard PCF85063 RTC. The program initializes the RTC and calls the following in setup():

i2c_rtc_setTime(2025, 9, 9, 14, 51, 30);

It then creates an i2c_rtc_loop_task task that reads and prints RTC time every second.

Code Entry

04_I2C_pcf85063/04_I2C_pcf85063.ino
04_I2C_pcf85063/rtc_bsp.cpp
04_I2C_pcf85063/rtc_bsp.h

Recommended key code sections:

Expected Behavior

• Serial outputs RTC time every second. The log should look like this:

Since the example writes a fixed test time on every power‑up, if you want to verify continuous RTC time‑keeping, comment out or delete i2c_rtc_setTime().

Troubleshooting

05_shtc3​

Function Description

This example reads the onboard SHTC3 temperature and humidity sensor. The program uses Wire to send SHTC3 commands, wakes the sensor, reads its ID, performs a soft reset, and reads temperature and humidity every second in loop().

CRC checking is implemented to prevent invalid data from being treated as normal temperature/humidity readings.

Code Entry

05_shtc3/05_shtc3.ino

Recommended key code sections:

Expected Behavior

• Serial outputs the SHTC3 ID first, then periodically outputs temperature and humidity. The log should look like this:

Troubleshooting

06_lvgl_demo​

Function Description

This example verifies LCD display, backlight, touch, and LVGL basic UI. It does not depend on the GFX display library. The LCD driver is adapted from the ST7789 example into Display_ST7789, the touch driver is adapted from the CST3530 example into Touch_CST3530, and CH32V003 I/O expansion, LCD reset, touch reset, and backlight control are consolidated in Board_IO.

The UI displays the board name, display status, touch status, touch coordinates, and backlight brightness.

Code Entry

06_lvgl_demo/06_lvgl_demo.ino
06_lvgl_demo/Board_IO.cpp
06_lvgl_demo/Board_IO.h
06_lvgl_demo/Display_ST7789.cpp
06_lvgl_demo/Display_ST7789.h
06_lvgl_demo/Touch_CST3530.cpp
06_lvgl_demo/Touch_CST3530.h
06_lvgl_demo/lv_conf.h

Recommended key code sections:

Expected Behavior

The LCD displays the ESP32-C5 Touch LCD 2.8 example UI. When you touch the screen, the UI updates with touch coordinates. Dragging the progress bar at the bottom adjusts backlight brightness. Serial output shows:

ESP32-C5-Touch-LCD-2.8 Arduino LVGL demo
Touch controller CST3530 initialized
LVGL demo started

If touch is not recognized, the UI displays Touch: not found.

Troubleshooting

XiaozhiAI (XiaoZhi AI) is an open-source AI voice chatbot project based on the ESP32 development board, aiming to bring the general intelligence of large language models (LLMs) to edge devices. It provides a software-hardware integrated solution supporting full-duplex voice conversations and IoT device control, dedicated to assisting developers in building highly customized physical AI agents quickly and at low cost.

This article demonstrates how to flash firmware for Waveshare ESP32 development boards that support XiaoZhi AI, covering two methods: flashing without a development environment (directly flashing precompiled firmware) and flashing with a development environment (compiling from source and flashing).

0. Firmware Flashing Process Reference​

1. Flashing Without a Development Environment​

1.1 Download Firmware from XiaoZhi Official GitHub​

1. Visit the XiaoZhi GitHub to download the firmware file for your device. Click Assets to expand the full file list:

   
   

2. Refer to the Flash Firmware Flashing and Erasing Tutorial to complete the firmware flashing.

1.2 Download Firmware from Waveshare GitHub​

1. Visit the Waveshare GitHub repository and download the appropriate firmware version for your needs:

   
   

2. Refer to the Flash Firmware Flashing and Erasing Tutorial to complete the firmware flashing.

2. Flashing with ESP-IDF Environment​

2.1 Download the Project from XiaoZhi GitHub​

Visit the XiaoZhi AI Chatbot repository to download the complete project code:

2.2 Environment Setup​

Refer to the ESP-IDF Environment Setup Tutorial to configure the development environment.

2.3 Configuration and Compilation​

1. Click  to select the target device. Choose the chip model corresponding to your development board (e.g., esp32s3):

   
   

   TIP

   When setting the target device, ESP-IDF will automatically configure the corresponding toolchain and libraries. This process may take some time, please be patient. For more details, please refer to the Official Documentation.

2. Click  to open the ESP-IDF terminal, then execute the command idf.py menuconfig to enter the configuration interface. Select Xiaozhi Assistant:

   
   

3. Select Board Type to choose the development board type:

   
   

4. Choose the product model corresponding to your development board:

   
   

5. Choose XiaoZhi-AI default display language:

   
   

   
   

6. Press the S key to save the configuration and exit. Then click the  to automatically complete compilation, flashing, and serial monitoring.

2.4 Start Network Provisioning​

1. Connect your phone or computer to the device's Wi-Fi hotspot: Xiaozhi-xxxxxx. After successful connection, the configuration page should automatically pop up. If not, manually open a browser and visit http://192.168.4.1.

2. On the network configuration page, select the Wi-Fi name you want to connect to (only 2.4G band is supported; to connect to an iPhone hotspot, enable Max Compatibility in your phone's system settings). The SSID will be auto-filled. Enter the password and click Connect to start connecting:

   

2.5 Add a New Device to the Management Console​

1. Ensure the device has successfully connected to the Internet. The device will then broadcast a 6-digit device verification code (you can wake the device again to replay the code).

2. Visit the XiaoZhi AI Console. If you haven't registered, complete the registration and log in:

   
   

   
   

   
   

3. Enter the 6-digit verification code. The device will automatically activate and appear on the Device Management page, ready for normal use.

4. Say the wake word "Hello XiaoZhi" to wake the device and start voice conversations.

5. ESP32-S3-Touch-AMOLED-1.8 Button Instructions:

   • BOOT button: Press to wake XiaoZhi
   • PWR button: Short press to power on; long press for more than 6 seconds to power off

   
   

3. XiaoZhi Resources​

• XiaoZhi AI Chatbot Encyclopedia
• XiaoZhi AI Chatbot FAQ

This chapter includes the following sections, please read as needed:

• ESP-IDF Getting Started
• Setting Up the Development Environment
• Example

ESP-IDF Getting Started​

New to ESP32 ESP-IDF development and looking to get started quickly? We have prepared a general Getting Started Tutorial for you.

• Section 1: Environment Setup
• Section 2: Running Examples
• Section 3: Creating a Project
• Section 4: Using Components
• Section 5: Debugging
• Section 6: FreeRTOS
• Section 7: Peripherals
• Section 8: Wi-Fi Programming
• Section 9: BLE Programming

Please Note: This tutorial uses the ESP32-S3-Zero as a teaching example, and all hardware code is based on its pinout. Before you start, it is recommended that you check the pinout of your development board to ensure the pin configuration is correct.

Setting Up the Development Environment​

Please refer to Install ESP-IDF Development Environment.

Install the ESP-IDF Development Environment​

1. Download the installation manager from the ESP-IDF Installation Manager page. This is Espressif's latest cross-platform installer. The following steps demonstrate how to use its offline installation feature.

   Click the Offline Installer tab on the page, then select Windows as the operating system and the ESP-IDF version you need (the version shown in the screenshot is for reference only — choose the version that fits your actual needs).

   
   

   After confirming your selection, click the download button. The browser will automatically download two files: the ESP-IDF Offline Package (.zst) and the ESP-IDF Installer (.exe).

   
   

   Please wait for both files to finish downloading.

2. Once the download is complete, double-click to run the ESP-IDF Installer (eim-gui-windows-x64.exe).

   The installer will automatically detect if the offline package exists in the same directory. Click Install from archive.

   
   

   Next, select the installation path. We recommend using the default path. If you need to customize it, ensure the path does not contain Chinese characters or spaces. Click Start installation to proceed.

   
   

3. When you see the following screen, the ESP-IDF installation is successful.

   
   

4. We recommend installing the drivers as well. Click Finish installation, then select Install driver.

   
   

Install Visual Studio Code and the ESP-IDF Extension​

1. Download and install Visual Studio Code.

2. During installation, it is recommended to check Add "Open with Code" action to Windows Explorer file context menu to facilitate opening project folders quickly.

3. In VS Code, click the Extensions icon  in the Activity Bar on the side (or use the shortcut Ctrl + Shift + X) to open the Extensions view.

4. Enter ESP-IDF in the search box, locate the ESP-IDF extension, and click Install.

   
   

5. For ESP-IDF extension versions ≥ 2.0, the extension will automatically detect and recognize the ESP-IDF environment installed in the previous steps, requiring no manual configuration.

Example​

The ESP-IDF examples are located in the example/ESP-IDF-V554 directory of the example package. Each example project has been adapted to the onboard hardware resources of the ESP32-C5-Touch-LCD-2.8 and can be used to verify display, touch, audio, TF card, Wi‑Fi, sensors, and GUI functionality.

Building and Flashing​

Navigate to any ESP-IDF example directory and run:

cd example/ESP-IDF-V554/02_2048
idf.py build flash monitor

If you need to specify a serial port, replace COMx with the actual port, for example COM5:

idf.py -p COMx build flash monitor

Example List​

Usage Notes​

• For secondary development, we recommend modifying the application layer or UI logic first. The BSP already provides initialization and low‑level interface definitions for the board's basic hardware resources. Routine UI, interaction, and business logic changes typically do not require BSP modifications. Only modify the BSP if you change hardware connections, adapt low‑level drivers, or add new peripherals.
• 01_ch32_test tests the onboard CH32V003 I/O expander. CH32V003 is pre‑programmed at the factory and does not require separate CH32 firmware flashing. Running this ESP32-C5 example is sufficient to verify I/O expander communication and control.
• The UI for 02_2048 is generated with GUI Guider. The layout is mainly in components/generated/setup_scr_Game2048.c, event functions are in components/generated/events_init.c, and custom initialization and extension logic are in components/custom/custom.c.
• Before running 03_sd_lvgl, place a Test.txt file in the root directory of the TF card.
• Before running 04_sd_music, create a music folder in the root directory of the TF card and place .mp3 files inside.
• 05_spiff_music uses MP3 files stored in SPIFFS and is suitable for implementing a music player with an LVGL interface.
• 06_wifi_weather connects to the weather-wifi hotspot by default, password 12345678, supporting both 2.4 GHz and 5 GHz bands. To change the hotspot or city, adjust the corresponding configuration in the example source code.
• For 07_Ball_qmi, keep the board flat and stationary during calibration to avoid noticeable ball drift.
• 08_bookesia uses the ESP‑Brookesia framework and serves as a reference for secondary development involving touch GUI, multi‑app interfaces, and drawing board functionality.

01_ch32_test​

Example Description​

• This example verifies the onboard CH32V003 I/O expander.
• The program initializes the I2C bus and CH32V003 I/O expander, then tests output and input reading functions.
• It first configures IO_EXP_PIN_0 through IO_EXP_PIN_7 as outputs and toggles them high/low cyclically, then switches to input mode and reads the input states.

Hardware Connection​

• Connect the board to your computer via USB.
• This example uses only the onboard CH32V003 I/O expander and does not require external modules.

Running Effect​

• Serial output shows I2C initialization, I/O expander initialization, output level toggling, and input level reading results.
• If I/O expander communication is normal, you will see successful configuration, output, and reading logs for IO_EXP_PIN_0~7.

02_2048​

Example Description​

• This example implements the 2048 game using LVGL v9.
• The UI is generated with GUI Guider. The main.c in the project calls setup_ui(), custom_init() and events_init() in sequence to create the UI, perform custom initialization, and bind events.
• The screen displays a 4×4 grid, current score, highest score, and a restart button.
• Supports swipe gestures for tile movement; matching numbers are merged and the score is updated accordingly.
• A victory prompt is shown when 2048 is reached, and a game‑over prompt when no moves remain.
• For secondary development, refer to components/generated/setup_scr_Game2048.c for the 2048 page layout, components/generated/events_init.c for touch and button event logic, and components/custom/custom.c for custom initialization and business extension logic.

Hardware Connection​

• Connect the board to your computer via USB.
• This example uses the onboard LCD and capacitive touchscreen and does not require external modules.

Running Effect​

• The LCD displays the 2048 game interface.
• Swipe on the touchscreen to control tile movement and see real‑time score updates and game results.

03_sd_lvgl​

Example Description​

• This example demonstrates TF card file reading and LVGL display.
• After startup, the program initializes the LCD and LVGL UI, then mounts the TF card.
• It reads the Test.txt file from the root directory of the TF card and displays its content on the LCD.
• If the TF card is not detected or file reading fails, the screen shows an appropriate error message.

Hardware Connection​

• Connect the board to your computer via USB.
• Insert a FAT32‑formatted TF card into the slot.
• Place a Test.txt file in the root directory of the TF card.

Running Effect​

• The LCD initially shows Waiting for SD card....
• After a successful read, the screen displays the text content from Test.txt.
• If no TF card is detected, it shows SD card not detected!.

04_sd_music​

Example Description​

• This example verifies MP3 audio playback from a TF card.
• The program initializes the onboard I/O expander, mounts the TF card, and scans for .mp3 files in the /sdcard/music directory.
• After detecting music files, it initializes the audio driver and amplifier, and automatically plays the first MP3.
• This example primarily tests the TF card reading, audio codec, amplifier, and speaker playback chain.

Hardware Connection​

• Connect the board to your computer via USB.
• Insert a FAT32‑formatted TF card into the slot.
• Create a music folder in the root directory of the TF card and place .mp3 audio files inside.
• Connect a speaker to the onboard Speaker interface.

Running Effect​

• Serial output shows the list of scanned MP3 files.
• The program automatically plays the first MP3 file found.
• If TF card mounting fails or no MP3 files are found, serial output shows an error message.

05_spiff_music​

Example Description​

• This example implements a music player UI using SPIFFS and LVGL v9.
• The program mounts the SPIFFS file system and scans for .mp3 files in the /spiffs/music directory.
• The screen displays album art and playback control buttons.
• When the play button is pressed, the program plays the first MP3 and the album art rotates continuously.
• Pressing the button again pauses playback; the rotation stops and resumes from the paused angle when playback continues.
• After playback finishes, the program automatically stops the animation and resets the play button state.

Hardware Connection​

• Connect the board to your computer via USB.
• Connect a speaker to the onboard Speaker interface.
• The MP3 files must be pre‑packaged into the SPIFFS music directory.

Running Effect​

• The LCD displays the music player interface.
• Click the play button to start playback and see the rotating album art animation.
• Supports play, pause, and playback‑end state recovery.

06_wifi_weather​

Example Description​

• This example demonstrates Wi‑Fi connectivity and weather data display.
• The program connects to a fixed Wi‑Fi hotspot and retrieves real‑time weather data for Shenzhen via HTTP request.
• The screen displays city, date, weather status, temperature, humidity, wind speed, and wind direction.
• Supports automatic Wi‑Fi reconnection on disconnection.
• Weather data refreshes periodically, approximately every 5 minutes after a successful fetch.

Default Wi‑Fi Configuration​

Hardware Connection​

• Before powering on, turn on a Wi‑Fi hotspot that matches the example configuration.
• Connect the board to your computer via USB and power it on.
• The hotspot can use either 2.4 GHz or 5 GHz band, but the SSID and password must match the example, and the hotspot must have internet access.
• This example uses the onboard LCD and Wi‑Fi, and does not require external modules.

Running Effect​

• After connecting to Wi‑Fi, the screen displays Shenzhen weather information.
• If the hotspot is not available or network access fails, the program will keep retrying connection and requests.

07_Ball_qmi​

Example Description​

• This example demonstrates QMI8658 accelerometer interaction with LVGL.
• The program initializes QMI8658 with 8G range and 500 Hz output data rate.
• After startup, it performs a level calibration to eliminate offset in the stationary state.
• After calibration, a ball appears at the center of the screen and moves in real time according to the board's tilt direction.
• The ball's movement is constrained to stay within the screen boundaries and rounded corner area.

Hardware Connection​

• Connect the board to your computer via USB.
• This example uses the onboard LCD and QMI8658 six‑axis sensor and does not require external modules.
• Place the board flat on a stable desk during calibration.

Running Effect​

• The screen shows a green ball.
• When you tilt the board, the ball moves in the direction of gravity.
• Serial output shows calibration status and sensor‑related logs.

08_bookesia​

Example Description​

• This example implements a phone‑style GUI using the ESP‑Brookesia framework.
• It uses a 240×320 dark theme with a status bar, app manager, and touch interaction.
• The example installs system default apps and additionally installs a Drawing Board app.
• The Drawing Board app supports freehand drawing on the capacitive touchscreen.
• The status bar clock refreshes every second.
• The recent tasks view periodically displays SRAM and PSRAM usage.

Hardware Connection​

• Connect the board to your computer via USB.
• This example uses the onboard LCD and capacitive touchscreen and does not require external modules.

Running Effect​

• The LCD displays the ESP‑Brookesia style interface.
• You can enter the Drawing Board app via touch and start drawing.
• The system interface supports status bar, recent tasks, and memory information display.

1. Hardware Resources​

• Development Board Design Files

  • Schematic Diagram
  • Mechanical Drawing

2. Technical Manuals​

• ESP32-C5 Chip Official Manuals

  • Datasheet
  • Technical Reference Manual

• Onboard Component Datasheets

  • ES8311 Datasheet
  • ES8311 User Manual
  • ST7789V2 Datasheet
  • QMI8658 Datasheet

3. Example​

• ESP32-C5-Touch-LCD-2.8 Example (GitHub)

4. Software Tools​

• Arduino:
  • Arduino IDE Official Download Link
• VS Code:
  • VS Code Official Download Link
• Debugging Tools:
  • Serial Port Debug Assistant
• Firmware Flashing Tool:
  • Flash_download_tool
• Other Resource Links:
  • ESP32-Arduino Official Documentation
  • ESP32-Arduino Official Resources
  • ESP-IDF Official Resources
  • MicroPython Official Documentation

Support

Monday-Friday (9:30-6:30) Saturday (9:30-5:30)

Email: services01@spotpear.com