Google Chat:---
+86-0755-88291180
sales@spotpear.com
dragon_manager@163.com
tech-support@spotpear.com
zhoujie@spotpear.com
WhatsApp:13246739196
WhatsApp:13424403025
| Resource | Description |
|---|---|
| Main Control Module | ESP32-C5-WROOM-1-N32R8 |
| Display | 2.73inch LCD, ILI9488, 320 x 320 |
| Storage Expansion | TF card slot |
| Attitude Sensor | QMI8658 6-axis sensor |
| Real-Time Clock | PCF85063 RTC |
| Temperature and Humidity Sensor | SHTC3 |
| IO Expansion | CH32V003, I2C address 0x24 |
| Power | USB Type-C power supply, reserved 3.7 V lithium battery interface |
| ESP32-C5 / CH32V003 | LCD | Description |
|---|---|---|
| GPIO6 | LCD_SCK | SPI clock signal |
| GPIO7 | LCD_MOSI | SPI data output signal |
| GPIO5 | LCD_MISO | SPI data input signal |
| GPIO4 | LCD_DC | Data/command select signal |
| GPIO8 | LCD_CS | Chip select, active low |
| CH32V003 IO0 | LCD_RST | LCD reset signal |
| CH32V003 PWM | LCD_BL | LCD backlight PWM control |
| ESP32-C5 | TF Card | Description |
|---|---|---|
| GPIO7 | MOSI | SPI data input to TF card |
| GPIO6 | CLK | SPI clock to TF card |
| GPIO5 | MISO | SPI data output from TF card |
| GPIO9 | CS | TF card chip select, active low |
| ESP32-C5 | I2C | Description |
|---|---|---|
| GPIO27 | SDA | I2C data signal |
| GPIO26 | SCL | I2C clock signal |
| ESP32-C5 | QMI8658 | Description |
|---|---|---|
| GPIO27 | SDA | I2C data signal |
| GPIO26 | SCL | I2C clock signal |
0x6B | I2C Address | QMI8658 default communication address |
| ESP32-C5 | PCF85063 | Description |
|---|---|---|
| GPIO27 | SDA | I2C data signal |
| GPIO26 | SCL | I2C clock signal |
0x51 | I2C Address | PCF85063 default communication address |
| ESP32-C5 | SHTC3 | Description |
|---|---|---|
| GPIO27 | SDA | I2C data signal |
| GPIO26 | SCL | I2C clock signal |
0x70 | I2C Address | SHTC3 default communication address |
| ESP32-C5 | UART0 | Description |
|---|---|---|
| GPIO11 | TX | Serial transmit |
| GPIO12 | RX | Serial receive |
| ESP32-C5 | USB | Description |
|---|---|---|
| GPIO14 | D+ | USB differential data D+ |
| GPIO13 | D- | USB differential data D- |
| ESP32-C5 | Button | Description |
|---|---|---|
| GPIO2 | PREV | Menu navigation button |
| GPIO3 | NEXT | Menu navigation button |
| GPIO28 | BOOT / ENTER | Download mode button, also serves as the menu confirmation button |
| CH32V003 | Controlled Object | Description |
|---|---|---|
| IO0 | LCD_RST | LCD reset control |
| PWM | LCD_BL | LCD backlight PWM control |
| ADC | BAT_ADC | Battery voltage detection |
| IO4-IO14 | EXIO | Extended IO test pins |

The ESP32-C5-LCD-2.73 supports two development frameworks: Arduino IDE and ESP-IDF. You can select the development tool based on your project requirements.
Arduino IDE is an open-source electronic prototyping platform, suitable for verifying basic examples such as LCD, TF, I2C sensors, RTC, temperature and humidity sensors, and EXIO.
ESP-IDF, short for Espressif IoT Development Framework, is the development framework launched by Espressif for the ESP series of chips, including a compiler, debugger, flashing tools, and supporting command‑line or VS Code plugin‑based development.
This chapter includes the following sections, please read as needed:
Before running the examples, please ensure the following conditions are met:
01_lvgl_demo or 07_example, please install the libraries/lvgl included in the example package.04_I2C_pcf85063 or 07_example, please install SensorLib, which provides SensorPCF85063.hpp.New to Arduino ESP32 development and looking for a quick start? We have prepared a comprehensive Getting Started Tutorial for you.
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.
Please refer to the tutorial Installing and Configuring the Arduino IDE to download and install the Arduino IDE.
Install the esp32 by Espressif Systems board support package in the Arduino IDE Board Manager.
The ESP32-C5-LCD-2.73 uses the ESP32-C5-WROOM-1-N32R8 MCU module, which is a v1.2 chip. Please use version v3.3.10 of the esp32 by Espressif Systems package.
If an older version of ESP32 Arduino Core is used, the board may not be correctly recognized, leading to serial download failures or inability to flash the program.
ESP32-C5-LCD-2.73 Board Installation Requirements:
| Board Name | Board Installation Requirement | Version Requirement |
|---|---|---|
| ESP32 by Espressif Systems | "Offline Installation" / "Online Installation" | v3.3.10 |
After installation, select the appropriate ESP32-C5 board in Arduino IDE and select the USB serial port currently connected.
In the ESP32-C5-LCD-2.73 Arduino project settings, the board must be selected as ESP32C5 Dev Module.

The Arduino examples for this product primarily utilize the built-in capabilities of Arduino ESP32 Core, the source code provided in the example directories, and the library files included in the resource package.
| Library or File | Purpose | Recommended Version / Source | Examples | Installation Method |
|---|---|---|---|---|
| Arduino ESP32 core | ESP32-C5 board support, download, and basic peripheral interfaces | v3.3.10 | All examples | Arduino IDE Board Manager |
lvgl | LVGL GUI framework | libraries/lvgl in example package, LVGL v8.4.0 | 01_lvgl_demo, 07_example | Offline manual copy to Arduino libraries directory |
SensorLib / SensorPCF85063.hpp | PCF85063 RTC driver | SensorLib | 04_I2C_pcf85063, 07_example | Arduino Library Manager or offline libraries directory |
01_lvgl_demo and 07_example are based on LVGL v8.4.0. Please do not replace them with LVGL v9, as interfaces such as lv_disp_drv_t, lv_disp_draw_buf_t, and lv_disp_drv_register() will be incompatible.
Offline / Manual Installation:
Download and extract the product example program package.
Locate the LVGL library directory in the example package:
code/arduino/libraries/lvgl
Copy the entire lvgl folder to the 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.
Restart Arduino IDE after installation, then open the examples to compile.
Installation Verification:
lvgl directory is visible under Documents\Arduino\libraries.Documents\Arduino\libraries\lvgl\library.properties shows version=8.4.0.lv_conf.h file in the 01_lvgl_demo and 07_example directories must remain within their respective example directories. Do not move it to the global Arduino libraries directory or delete it.lvgl simultaneously to avoid header file conflicts.04_I2C_pcf85063 or 07_example results in an error indicating SensorPCF85063.hpp is missing, please verify that SensorLib is installed.esp32 by Espressif Systems v3.3.10 board support package.Tools > Board, select ESP32C5 Dev Module..ino file under code/arduino/examples for compilation and flashing.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 code/arduino/examples/01_lvgl_demo
The Arduino examples are located in the code/arduino/examples directory of the example package. Each example has been adapted to the onboard hardware connections of the ESP32-C5-LCD-2.73.
| Feature | Device or Interface | Pins or Notes |
|---|---|---|
| LCD | ILI9488, SPI, 320 x 320 | SCLK GPIO6, MOSI GPIO7, MISO GPIO5, DC GPIO4, CS GPIO8 |
| LCD Reset | CH32V003 I/O Expander | IO0 |
| LCD Backlight | CH32V003 PWM | PWM Register 0x05 |
| I/O Expander | CH32V003, I2C address 0x24 | SDA GPIO27, SCL GPIO26 |
| 6‑axis IMU | QMI8658, I2C address 0x6B | SDA GPIO27, SCL GPIO26 |
| RTC | PCF85063, I2C address 0x51 | SDA GPIO27, SCL GPIO26 |
| Temp/Humidity Sensor | SHTC3, I2C address 0x70 | SDA GPIO27, SCL GPIO26 |
| TF | SDSPI | SCLK GPIO6, MOSI GPIO7, MISO GPIO5, CS GPIO9 |
| BOOT Button | User Button | GPIO28 |
Display, backlight, reset, TF card, and sensor pins have been adapted according to the product's hardware connections in the examples. For general secondary development, it is recommended to prioritize modifications to the application layer and UI logic. Only modify the underlying pin definitions when changing hardware connections or porting to other boards.
| Example Directory | Basic Description | Main Test Content |
|---|---|---|
| 01_lvgl_demo | Runs the LVGL stress test interface based on ILI9488 and LVGL v8.4.0 | LCD, Backlight, LVGL |
| 02_SD_Card | Mounts TF card via SDSPI and performs file write and read-back checks | TF, SDSPI, File I/O |
| 03_I2C_qmi8658 | Reads QMI8658 6‑axis sensor data and outputs accelerometer and gyroscope data over serial | IMU, I2C bus |
| 04_I2C_pcf85063 | Initializes the PCF85063 RTC, sets a test time, and periodically prints RTC time over serial | RTC, I2C bus |
| 05_shtc3 | Reads SHTC3 temperature and humidity sensor ID, temperature, and humidity, and outputs over serial | Temp/Humidity sensor, CRC check |
| 06_exio | Tests the onboard CH32V003 IO expander, toggles IO4-IO14 output levels cyclically | IO expansion, I2C bus |
| 07_example | Comprehensively displays RTC, SHTC3, QMI8658, and TF card status, with BOOT button for page switching | LCD, Backlight, Sensors, RTC, TF Card |
The current Arduino examples directory contains the following projects:
code/arduino
|-- examples
| |-- 01_lvgl_demo
| |-- 02_SD_Card
| |-- 03_I2C_qmi8658
| |-- 04_I2C_pcf85063
| |-- 05_shtc3
| |-- 06_exio
| `-- 07_example
`-- libraries
`-- lvgl
Each subdirectory is an independent Arduino example. To open an example, open the .ino file inside that directory, for example:
code/arduino/examples/01_lvgl_demo/01_lvgl_demo.ino
libraries/lvgl is the LVGL v8.4.0 library file used by 01_lvgl_demo and 07_example. Before compiling these two examples, you need to copy lvgl to the Arduino libraries directory.
It is recommended to run the examples in the following order:
06_exio
-> 05_shtc3
-> 03_I2C_qmi8658
-> 04_I2C_pcf85063
-> 02_SD_Card
-> 01_lvgl_demo
-> 07_example
06_exio to verify the CH32V003 IO expansion and I2C bus. Since LCD reset and backlight control are both related to CH32V003, it is recommended to confirm this example works properly first.05_shtc3, 03_I2C_qmi8658, and 04_I2C_pcf85063 to verify the I2C peripherals.02_SD_Card to verify the TF card and SDSPI.01_lvgl_demo and 07_example to verify the LCD, backlight, LVGL, and the comprehensive dashboard.code/arduino/examples. Please do not mix it with the ESP-IDF example directory.SDA GPIO27, SCL GPIO26. CH32V003, QMI8658, PCF85063, and SHTC3 are all on this I2C bus.02_SD_Card and 07_example, insert a TF card formatted as FAT or FAT32.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().01_lvgl_demo and 07_example are already adapted for ILI9488 display. No additional GFX display library is required.Function Description
This example is used to verify LCD display, backlight, and basic LVGL operation. The program initializes the ILI9488 LCD via SPI, uses CH32V003 to control LCD reset and backlight, and then starts the LVGL stress test interface.
Code Entry
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
Recommended key code sections to review:
| Code | Purpose |
|---|---|
LCD_H_RES / LCD_V_RES | LCD resolution, 320 x 320 |
LCD_SPI_SCLK / LCD_SPI_MOSI / LCD_SPI_MISO | LCD SPI pins, GPIO6/GPIO7/GPIO5 |
LCD_SPI_DC / LCD_SPI_CS | LCD DC/CS pins, GPIO4/GPIO8 |
IO_EXT_LCD_RST | LCD reset, CH32V003 IO0 |
io_ext_pwm() | Set backlight via CH32V003 PWM |
esp_lcd_new_panel_ili9488() | Create ILI9488 panel driver |
lv_demo_stress() | Start LVGL stress test interface |
Expected Behavior
ESP32-C5-LCD-2.73 Arduino LVGL demo and LVGL stress demo started.
Troubleshooting
| Symptom | Possible Cause | Action |
|---|---|---|
Compilation error: lvgl.h not found | LVGL from the example package not installed | Copy code/arduino/libraries/lvgl to the Arduino libraries directory |
Compilation errors related to lv_disp_drv_t | LVGL v9 is being used | Delete the incorrect LVGL version and use LVGL v8.4.0 from the example package |
| Screen stays off | CH32V003, LCD reset, backlight, or ILI9488 initialization abnormal | Run 06_exio first to confirm CH32V003 is working; then restore the original pin configuration in 01_lvgl_demo |
| Display color abnormal | Pixel format or color order configuration modified | Keep bits_per_pixel = 18, LCD_RGB_ELEMENT_ORDER_BGR, and the color inversion configuration as provided in the example |
Function Description
This example verifies the TF card interface. The program mounts the TF card via SDSPI at the mount point /sd_card, then writes to sd_rw_test.txt and performs a read-back verification.
Code Entry
02_SD_Card/02_SD_Card.ino
02_SD_Card/sd_card_bsp.cpp
02_SD_Card/sd_card_bsp.h
Recommended key code sections to review:
| Code | Purpose |
|---|---|
PIN_NUM_CLK | TF SCLK, GPIO6 |
PIN_NUM_MOSI | TF MOSI, GPIO7 |
PIN_NUM_MISO | TF MISO, GPIO5 |
PIN_NUM_CS | TF CS, GPIO9 |
SD_card_Init() | Initialize SPI bus and mount TF card |
s_example_write_file() / s_example_read_file() | Example file write and read interfaces |
Expected Behavior
PASS result.
Troubleshooting
| Symptom | Possible Cause | Action |
|---|---|---|
| TF card mount fails | No card inserted, invalid format, or poor contact | Use a FAT/FAT32 TF card, re‑insert, and retest |
| File read/write fails | Mount failure or incorrect path | Confirm SD_card_Init() prints card info successfully |
| TF card abnormal after switching from LCD examples | SPI bus state or CS level not restored | Restart the board and run 02_SD_Card separately |
Function Description
This example reads the onboard QMI8658 6‑axis sensor. The program initializes I2C, creates the qmi8658c_example task, periodically reads accelerometer and gyroscope data, and outputs them via the serial port.
Code Entry
03_I2C_qmi8658/03_I2C_qmi8658.ino
03_I2C_qmi8658/i2c_bsp.cpp
03_I2C_qmi8658/qmi8658c.cpp
03_I2C_qmi8658/qmi8658c.h
Recommended key code sections to review:
| Code | Purpose |
|---|---|
I2C_master_Init() | Initializes I2C with SDA GPIO27, SCL GPIO26, 400 kHz |
QMI8658_SLAVE_ADDR_H | QMI8658 I2C address, default 0x6B |
qmi8658_init() | Initializes QMI8658 |
qmi8658_read_xyz() | Reads accelerometer and gyroscope data |
Expected Behavior

Troubleshooting
| Symptom | Possible Cause | Action |
|---|---|---|
| Serial port indicates QMI8658 initialization failed | QMI8658 I2C communication failure | Confirm I2C pins are GPIO27/GPIO26; run 05_shtc3 or 06_exio first to verify I2C |
| Data remains unchanged | Board is stationary or task not running | Gently rotate the board and confirm the serial baud rate is 115200 |
| Compilation errors for I2C-related interfaces | Arduino ESP32 Core version mismatch | Use a board support package that includes ESP32-C5 support |
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 to review:
| Code | Purpose |
|---|---|
rtc.begin(Wire, SENSOR_SDA, SENSOR_SCL) | Initializes PCF85063 with SDA GPIO27, SCL GPIO26 |
i2c_rtc_setTime() | Sets RTC time |
i2c_rtc_get() | Reads RTC time structure |
i2c_rtc_loop_task() | Periodically reads and prints RTC time over serial |
Expected Behavior

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
| Symptom | Possible Cause | Action |
|---|---|---|
Compilation error: SensorPCF85063.hpp not found | Missing SensorLib dependency | Install SensorLib and recompile |
Serial shows Failed to find PCF85063 | RTC I2C communication failure | Confirm I2C pins are GPIO27/GPIO26; test other I2C examples first |
| Time always resets to fixed value on power‑up | Example actively writes test time | Comment out or delete i2c_rtc_setTime() and retest |
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 to review:
| Code | Purpose |
|---|---|
I2C_SDA / I2C_SCL | I2C pins, SDA GPIO27, SCL GPIO26 |
SHTC3_ADDR | SHTC3 I2C address, default 0x70 |
SHTC3_CMD_READ_ID | Reads sensor ID |
SHTC3_CMD_MEASURE_T_RH | Triggers temperature/humidity measurement |
shtc3Crc() | CRC check for SHTC3 data |
readShtc3() | Reads and converts temperature and humidity |
Expected Behavior

Troubleshooting
| Symptom | Possible Cause | Action |
|---|---|---|
Serial shows SHTC3 not found | I2C communication failure | Confirm I2C pins are GPIO27/GPIO26 and ensure the board is powered |
Serial shows Failed to read SHTC3 | CRC failure or sensor not responding | Keep power stable, power cycle, and retest |
| Occasional abnormal temperature/humidity values | Invalid I2C data | The example includes CRC checking; use data that passes the check |
Function Description
This example verifies communication with the onboard CH32V003 I/O expander. The CH32V003 communicates with ESP32-C5 via I2C at address 0x24. The example configures IO4-IO14 as outputs and toggles their levels once per second.
CH32V003 is pre‑programmed with firmware at the factory; no separate CH32 firmware flashing is required.
Code Entry
06_exio/06_exio.ino
06_exio/io_extension.cpp
06_exio/io_extension.h
Recommended key code sections to review:
| Code | Purpose |
|---|---|
Wire.begin(I2C_SDA, I2C_SCL) | Initialize I2C with SDA GPIO27, SCL GPIO26 |
IO_EXTENSION_ADDR | CH32V003 I2C, default 0x24 |
IO_EXTENSION_Init(Wire) | Initialize the I/O expander |
IO_EXTENSION_IO_Mode(0xFFF7) | Configure IO expansion pin modes |
IO_EXTENSION_Output() | Set output level for specific IO expansion pins |
Expected Behavior
IO4-IO14 will toggle every second.
Troubleshooting
| Symptom | Possible Cause | Action |
|---|---|---|
Serial shows IO extension not found at 0x24 | I2C communication failure | Confirm SDA GPIO27, SCL GPIO26 and ensure the board is powered |
| LCD subsequently malfunctioning | CH32V003 not communicating properly | First ensure 06_exio runs normally, then troubleshoot display and backlight |
| Need to re‑flash CH32V003 firmware | Not required | CH32V003 is pre-flashed from the factory; no action required for normal use |
Function Description
This example is used to comprehensively verify the LCD, backlight, RTC, SHTC3, QMI8658, and TF card. Upon startup, the program initializes I2C, CH32V003, ILI9488, LVGL, and onboard peripherals. The LCD displays system status, RTC, temperature/humidity, IMU, and TF card information.
Press the BOOT button to switch pages.
Code Entry
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
Recommended key code sections to review:
| Code | Purpose |
|---|---|
init_lcd_panel() | Initialize SPI bus and ILI9488 panel |
init_lvgl() | Initialize LVGL display buffer and refresh callback |
init_peripherals() | Sequentially check RTC, SHTC3, QMI8658, and TF card |
refresh_sensors() | Periodically read sensor and RTC data |
refresh_screen() | Refresh LCD display content according to the current page |
handle_button() | Read GPIO28 BOOT button and switch pages |
Expected Behavior
System Status page.
Troubleshooting
| Symptom | Possible Cause | Action |
|---|---|---|
Compilation error: lvgl.h not found | LVGL from the example package not installed | Copy code/arduino/libraries/lvgl to the Arduino libraries directory |
Compilation error: SensorPCF85063.hpp not found | Missing SensorLib dependency | Install SensorLib and recompile |
Page displays a peripheral as NO | Peripheral initialization or communication failure | Run the corresponding basic example for that peripheral separately first |
| BOOT button cannot switch pages | Button GPIO configuration abnormal | Confirm the example retains BOOT_BUTTON = GPIO_NUM_28 and INPUT_PULLUP configuration |
| TF page shows unmounted | TF card not inserted or format invalid | Insert a FAT/FAT32 formatted TF card and restart the board for testing |
This section describes how to use the factory firmware for the ESP32-C5-LCD-2.73. The factory firmware corresponds to the ESP-IDF example program 01_factory, which includes the Main Interface, Settings, Sensor, Photo, and Weather pages.
Firmware directory of the example package.code/idf/01_factory directory of the example program package.If the port cannot be recognized, please enter Boot mode:
After the download is complete, power cycle the board to run the program.
Upon startup, the LCD displays the factory firmware main interface. Use the onboard buttons to select and enter each page.





The Settings page is used to view and configure onboard functions:
For the Weather page to function, Wi-Fi must first be configured in the Settings page.
The Sensor page displays onboard sensor data:
When the development board is slightly tilted or rotated, the accelerometer and gyroscope data will change accordingly.
The Photo page reads image files from the TF card:
.jpg and .jpeg images in the /sdcard/photo directory.photo directory on the card.The Weather page is used to display weather information. Before use, configure Wi-Fi with internet access in the Settings page.
| Symptom | Possible Cause | Action |
|---|---|---|
| Screen stays off | Power supply abnormal, LCD reset failure, or backlight not turned on | Reconnect the USB and restart; for program troubleshooting, refer to the ESP-IDF 02_lvgl_demo and 07_exio examples |
| Weather page shows no data | Wi-Fi not connected or network unavailable | Configure Wi-Fi in the Settings page and confirm the hotspot can access the internet |
| Photo page shows no images | TF card not mounted, directory does not exist, or image format mismatch | Confirm the /photo directory exists on the TF card and place .jpg or .jpeg images inside |
| Sensor page shows no data | I2C peripheral initialization failure | Refer to the ESP-IDF 04_qmi8658, 06_shtc3, and 07_exio examples for troubleshooting |
This chapter includes the following sections, please read as needed:
New to ESP32 ESP-IDF development and looking to get started quickly? We have prepared a general Getting Started Tutorial for you.
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.
Please refer to Install ESP-IDF Development Environment.
The ESP32-C5-LCD-2.73 examples use ESP-IDF v5.5.3, with the project target chip set to esp32c5. If using other ESP-IDF versions, please refer to the dependencies.lock and sdkconfig files in the example project.
The following guide uses Windows as an example, demonstrating development using VS Code + the ESP-IDF extension. macOS and Linux users should refer to the official documentation.
The screenshots in this section use ESP-IDF V5.5.2 as an example. When installing, please select the ESP-IDF version that matches your board's example.
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.
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.

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

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

Download and install Visual Studio Code.
During installation, it is recommended to check Add "Open with Code" action to Windows Explorer file context menu to facilitate opening project folders quickly.
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.
Enter ESP-IDF in the search box, locate the ESP-IDF extension, and click Install.

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.
The ESP-IDF example programs are located in the code/idf directory of the example program package. Each example project has been adapted to the onboard hardware resources of the ESP32-C5-LCD-2.73 and can be used to verify functions such as LCD, LVGL, TF, QMI8658, PCF85063, SHTC3, and CH32V003 IO expansion.
Navigate to any ESP-IDF example directory and run:
cd code/idf/02_lvgl_demo
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
| Feature | Device or Interface | Pins or Notes |
|---|---|---|
| LCD | ILI9488, SPI, 320 x 320, RGB666 | SCLK GPIO6, MOSI GPIO7, MISO GPIO5, DC GPIO4, CS GPIO8 |
| LCD Reset | CH32V003 I/O Expander | IO0 |
| LCD Backlight | CH32V003 PWM | IO Expansion PWM |
| I/O Expander | CH32V003, I2C address 0x24 | SDA GPIO27, SCL GPIO26 |
| 6‑axis IMU | QMI8658, I2C address 0x6B | SDA GPIO27, SCL GPIO26 |
| RTC | PCF85063, I2C address 0x51 | SDA GPIO27, SCL GPIO26 |
| Temp/Humidity Sensor | SHTC3, I2C address 0x70 | SDA GPIO27, SCL GPIO26 |
| TF | SDSPI | SCLK GPIO6, MOSI GPIO7, MISO GPIO5, CS GPIO9 |
| BOOT Button | User Button | GPIO28 |
| Example Directory | Description |
|---|---|
| 01_factory | Factory example, featuring main menu, settings, sensor, photo, and weather pages |
| 02_lvgl_demo | Initialize LCD and LVGL, runs the LVGL benchmark example |
| 03_sd_card | Mount TF card, writes and reads back a test file |
| 04_qmi8658 | Read QMI8658 accelerometer and gyroscope data, and outputs them via serial port |
| 05_pcf85063 | Read PCF85063 RTC time and output it periodically via serial port |
| 06_shtc3 | Read SHTC3 temperature and humidity data, and output them periodically via serial port |
| 07_exio | Test CH32V003 IO expansion by cyclically toggling IO4-IO14 output levels |
01_factory and 02_lvgl_demo use LVGL v9.5.0 and esp_lvgl_adapter.01_factory and 03_sd_card, it is recommended to insert a TF card formatted as FAT or FAT32 before running.01_factory reads .jpg or .jpeg images from the /sdcard/photo directory by default.SDA GPIO27, SCL GPIO26. CH32V003, QMI8658, PCF85063, and SHTC3 are all on this I2C bus./sdcard/photo directory and provides Previous, Next, and Back controls.photo directory on the TF card, and place .jpg or .jpeg images inside.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
Recommended key code sections to review:
| Code | Purpose |
|---|---|
system_manage_service_init() | Initialize system management service |
bsp_sdcard_mount() | Mount TF card |
bsp_io_expander_init() | Initialize CH32V003 IO expansion |
bsp_pcf85063a_drv_init() | Initialize PCF85063 RTC |
bsp_display_start() | Initialize LCD and LVGL |
butmenu_register_app() | Register Settings, Sensor, Photo, Weather applications |





| Symptom | Possible Cause | Action |
|---|---|---|
| Photo page indicates no images | TF card not mounted, directory does not exist, or image format mismatch | Confirm the /photo directory exists on the TF card and place .jpg or .jpeg images inside |
| Weather page shows no data | Wi-Fi not connected or network unavailable | Configure Wi-Fi in the Settings page and confirm the hotspot has internet access |
| Sensor page shows no data | I2C peripheral initialization failed | Run 04_qmi8658, 05_pcf85063, 06_shtc3, and 07_exio separately first |
lv_demo_benchmark() to run the LVGL benchmark example.02_lvgl_demo/main/main.c
02_lvgl_demo/components/waveshare__esp32_c5_lcd_2_73
Recommended key code sections to review:
| Code | Purpose |
|---|---|
bsp_io_expander_init() | Initialize CH32V003 IO expansion |
IO_EXTENSION_Output(IO_EXTENSION_IO_0, ...) | Control LCD reset |
bsp_display_start() | Initialize LCD and LVGL |
bsp_display_backlight_on() | Turns on backlight |
lv_demo_benchmark() | Run LVGL benchmark |

| Symptom | Possible Cause | Action |
|---|---|---|
| Screen stays off | CH32V003, LCD reset, backlight, or SPI initialization abnormal | Run 07_exio first, then restore the LCD-related pin definitions in the BSP |
| Display abnormal | LCD color format or resolution configuration modified | Confirm BSP_LCD_H_RES, BSP_LCD_V_RES are 320, and BSP_LCD_BITS_PER_PIXEL is 18 |
bsp_sdcard_mount() to mount the TF card at the mount point /sdcard./sdcard/test.txt, then reads it back and verifies the content.03_sd_card/main/main.c
03_sd_card/components/waveshare__esp32_c5_lcd_2_73
Recommended key code sections to review:
| Code | Purpose |
|---|---|
BSP_LCD_CS | LCD CS, GPIO8, pulled high before test |
bsp_sdcard_mount() | Mount TF card |
BSP_SD_MOUNT_POINT | TF card mount point, default /sdcard |
tf_card_read_write_test() | Write, read back, and verify test file |
sdmmc_card_print_info() | Print TF card information |
TF CARD TEST PASS.
| Symptom | Possible Cause | Action |
|---|---|---|
| TF card mount fails | No card inserted, invalid format, or poor contact | Use a FAT/FAT32 TF card, re‑insert, and retest |
| File write or read-back failed | File system corrupted or card not writable | Replace the TF card or reformat it before testing again |
| Abnormal behavior after switching from LCD examples | SPI bus or chip select state not restored | Restart the board and run 03_sd_card separately |
bsp_qmi8658_drv_init() to initialize QMI8658.m/s^2 and gyroscope dps.04_qmi8658/main/main.c
04_qmi8658/components/waveshare__esp32_c5_lcd_2_73
Recommended key code sections to review:
| Code | Purpose |
|---|---|
bsp_qmi8658_drv_init() | Initialize QMI8658 |
qmi8658_set_accel_unit_mps2() | Set acceleration unit to m/s^2 |
qmi8658_set_gyro_unit_dps() | Set gyroscope unit to dps |
qmi8658_is_data_ready() | Check if data is ready |
qmi8658_read_sensor_data() | Read accelerometer and gyroscope data |

| Symptom | Possible Cause | Action |
|---|---|---|
| Initialization failed | I2C communication error | Confirm I2C uses SDA GPIO27, SCL GPIO26, and run 07_exio or 06_shtc3 first |
| Data remains unchanged | Board stationary or data not updated | Slightly rotate the board and confirm the serial monitor is running |
bsp_pcf85063a_drv_init() to initialize the RTC.pcf85063a_get_time_date() every second to read the date, time, and day of the week, and outputs them via the serial port.05_pcf85063/main/main.c
05_pcf85063/components/waveshare__esp32_c5_lcd_2_73
Recommended key code sections to review:
| Code | Purpose |
|---|---|
bsp_pcf85063a_drv_init() | Initialize PCF85063 RTC |
pcf85063a_get_time_date() | Read RTC date and time |
pcf85063a_datetime_t | RTC date and time structure |

| Symptom | Possible Cause | Action |
|---|---|---|
| RTC read failed | PCF85063 I2C communication error | Confirm I2C uses SDA GPIO27, SCL GPIO26, and test other I2C examples |
| Time does not match expectations | RTC not set or battery power status abnormal | Run 01_factory first to synchronize the system time, or add RTC time setting logic to the code |
bsp_shtc3_drv_init() to initialize SHTC3.shtc3_get_th() every second to read temperature and humidity, and outputs them via the serial port.06_shtc3/main/main.c
06_shtc3/components/waveshare__esp32_c5_lcd_2_73
Recommended key code sections to review:
| Code | Purpose |
|---|---|
bsp_shtc3_drv_init() | Initialize SHTC3 |
shtc3_get_th() | Read temperature and humidity |
SHTC3_REG_T_CSD_NM | Temperature-first, normal mode measurement command |

| Symptom | Possible Cause | Action |
|---|---|---|
| Initialization failed | SHTC3 I2C communication error | Confirm I2C uses SDA GPIO27, SCL GPIO26, and ensure the board is powered properly |
| Temperature/humidity read failed | Sensor did not respond correctly or I2C data error | Restart the board and test again; compare with 04_qmi8658 or 05_pcf85063 to check I2C status |
bsp_io_expander_init() to initialize CH32V003.07_exio/main/main.c
07_exio/components/waveshare__esp32_c5_lcd_2_73
Recommended key code sections to review:
| Code | Purpose |
|---|---|
bsp_io_expander_init() | Initialize CH32V003 IO expansion |
IO_EXTENSION_IO_Mode(0xFFF7) | Configure IO expansion pin modes |
IO_EXTENSION_Output() | Set output level for specific IO expansion pins |
IO_EXTENSION_IO_4 / IO_EXTENSION_IO_14 | Output toggle range |
| Symptom | Possible Cause | Action |
|---|---|---|
| Subsequent LCD or backlight examples malfunction | CH32V003 not communicating properly | First confirm 07_exio can run, then troubleshoot LCD reset and backlight control |
| IO output does not change | IO expansion initialization failed or output range modified | Keep IO_EXTENSION_IO_Mode(0xFFF7) and the IO4-IO14 output range as in the example |
This product provides test firmware that can be flashed directly to verify whether the onboard devices are functioning properly.
Firmware directory of the example package.0x00The following uses flashing the ESP32-S3-Touch-LCD-2.8 factory firmware as an example. The same steps apply when flashing other firmware.
Download and extract Espressif's official Flash Download Tool (Download)
Run flash_download_tool_3.9.7.exe and select the development board's MCU and download interface, such as ESP32-S3 and USB (most devices use USB; refer to the product's hardware design for the correct interface).

Parameter settings

Wait for flashing to complete (this may take some time; please be patient)
Press the reset button and verify the result

Development Board Design Files
ESP32-C5 Chip Official Manuals
Onboard Component Datasheets
Monday-Friday (9:30-6:30) Saturday (9:30-5:30)
Email: services01@spotpear.com