• sales

    +86-0755-88291180

ESP32-C5-LCD-2.73 User Guide

Features

  • Equipped with the ESP32-C5-WROOM-1-N32R8 module, with the onboard MCU being ESP32-C5
  • Features a RISC-V 32-bit processor with a main frequency of 240 MHz
  • Integrated 384 KB SRAM, 320 KB ROM, 8 MB PSRAM, and 32 MB Flash
  • Supports 2.4 GHz / 5 GHz dual-band Wi-Fi, Bluetooth 5 (LE), and IEEE 802.15.4, which can be used for Zigbee 3.0 and Thread related development
  • Uses a USB Type-C interface for power supply, downloading, and serial debugging
  • Onboard 2.73inch LCD, display driver chip ILI9488, resolution 320 x 320, RGB666 color format
  • Onboard QMI8658 6-axis sensor, PCF85063 RTC, SHTC3 temperature and humidity sensor, and TF card slot
  • Onboard CH32V003 IO expansion chip for LCD reset, LCD backlight PWM, battery voltage reading, and extended IO testing
  • Onboard battery charging management circuit, with a reserved 3.7 V lithium battery interface
  • Provides interfaces such as UART, I2C, USB, and extended IO
  • Supports ESP-IDF and Arduino development environments

Onboard Resources

ResourceDescription
Main Control ModuleESP32-C5-WROOM-1-N32R8
Display2.73inch LCD, ILI9488, 320 x 320
Storage ExpansionTF card slot
Attitude SensorQMI8658 6-axis sensor
Real-Time ClockPCF85063 RTC
Temperature and Humidity SensorSHTC3
IO ExpansionCH32V003, I2C address 0x24
PowerUSB Type-C power supply, reserved 3.7 V lithium battery interface

Interface Introduction

LCD Interface: Used to connect the 2.73inch LCD screen (Click to expand)
ESP32-C5 / CH32V003LCDDescription
GPIO6LCD_SCKSPI clock signal
GPIO7LCD_MOSISPI data output signal
GPIO5LCD_MISOSPI data input signal
GPIO4LCD_DCData/command select signal
GPIO8LCD_CSChip select, active low
CH32V003 IO0LCD_RSTLCD reset signal
CH32V003 PWMLCD_BLLCD backlight PWM control
TF Card Interface: Connects to a TF card (click to expand)
ESP32-C5TF CardDescription
GPIO7MOSISPI data input to TF card
GPIO6CLKSPI clock to TF card
GPIO5MISOSPI data output from TF card
GPIO9CSTF card chip select, active low
I2C Bus: Connects to onboard I2C peripherals (click to expand)
ESP32-C5I2CDescription
GPIO27SDAI2C data signal
GPIO26SCLI2C clock signal
QMI8658 Six‑axis Sensor Interface (click to expand)
ESP32-C5QMI8658Description
GPIO27SDAI2C data signal
GPIO26SCLI2C clock signal
0x6BI2C AddressQMI8658 default communication address
RTC Interface: Onboard PCF85063 real‑time clock (click to expand)
ESP32-C5PCF85063Description
GPIO27SDAI2C data signal
GPIO26SCLI2C clock signal
0x51I2C AddressPCF85063 default communication address
SHTC3 Temperature and Humidity Sensor Interface (click to expand)
ESP32-C5SHTC3Description
GPIO27SDAI2C data signal
GPIO26SCLI2C clock signal
0x70I2C AddressSHTC3 default communication address
UART0 Interface: Serial communication (click to expand)
ESP32-C5UART0Description
GPIO11TXSerial transmit
GPIO12RXSerial receive
USB Interface: Power, programming, and serial debug (click to expand)
ESP32-C5USBDescription
GPIO14D+USB differential data D+
GPIO13D-USB differential data D-
Onboard Button Interface (Click to expand)
ESP32-C5ButtonDescription
GPIO2PREVMenu navigation button
GPIO3NEXTMenu navigation button
GPIO28BOOT / ENTERDownload mode button, also serves as the menu confirmation button
CH32V003 IO Expansion Interface: For LCD, battery detection, and extended IO testing (Click to expand)
CH32V003Controlled ObjectDescription
IO0LCD_RSTLCD reset control
PWMLCD_BLLCD backlight PWM control
ADCBAT_ADCBattery voltage detection
IO4-IO14EXIOExtended IO test pins

Dimensions


Development Methods

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.


Working with Arduino

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

BEFORE YOU BEGIN

Before running the examples, please ensure the following conditions are met:

  • ESP32-C5-LCD-2.73 development board is ready.
  • The board is connected to the PC via a USB data cable.
  • Arduino IDE is installed.
  • ESP32 Arduino Core supporting ESP32-C5 is installed.
  • The product's example program package has been downloaded.
  • To run 01_lvgl_demo or 07_example, please install the libraries/lvgl included in the example package.
  • To run 04_I2C_pcf85063 or 07_example, please install SensorLib, which provides SensorPCF85063.hpp.

Arduino Getting Started

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.

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.

VERSION NOTE

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 NameBoard Installation RequirementVersion 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.

ARDUINO PROJECT PARAMETER SETTINGS

In the ESP32-C5-LCD-2.73 Arduino project settings, the board must be selected as ESP32C5 Dev Module.


3. Installing Libraries and Example Dependencies

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 FilePurposeRecommended Version / SourceExamplesInstallation Method
Arduino ESP32 coreESP32-C5 board support, download, and basic peripheral interfacesv3.3.10All examplesArduino IDE Board Manager
lvglLVGL GUI frameworklibraries/lvgl in example package, LVGL v8.4.001_lvgl_demo07_exampleOffline manual copy to Arduino libraries directory
SensorLib / SensorPCF85063.hppPCF85063 RTC driverSensorLib04_I2C_pcf8506307_exampleArduino Library Manager or offline libraries directory
LVGL VERSION

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_tlv_disp_draw_buf_t, and lv_disp_drv_register() will be incompatible.

Offline / Manual Installation:

  1. Download and extract the product example program package.

  2. Locate the LVGL library directory in the example package:

    code/arduino/libraries/lvgl
  3. 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.

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

Installation Verification:

  • The lvgl directory is visible under Documents\Arduino\libraries.
  • Documents\Arduino\libraries\lvgl\library.properties shows version=8.4.0.
  • The 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.
  • Do not keep multiple versions of lvgl simultaneously to avoid header file conflicts.
  • If compiling 04_I2C_pcf85063 or 07_example results in an error indicating SensorPCF85063.hpp is missing, please verify that SensorLib is installed.

4. Arduino Project Settings

  1. Open Arduino IDE.
  2. Install the esp32 by Espressif Systems v3.3.10 board support package.
  3. In Tools > Board, select ESP32C5 Dev Module.
  4. Select the USB serial port currently connected.
  5. Open the corresponding .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

Example

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.

1. Onboard Resources

FeatureDevice or InterfacePins or Notes
LCDILI9488, SPI, 320 x 320SCLK GPIO6, MOSI GPIO7, MISO GPIO5, DC GPIO4, CS GPIO8
LCD ResetCH32V003 I/O ExpanderIO0
LCD BacklightCH32V003 PWMPWM Register 0x05
I/O ExpanderCH32V003, I2C address 0x24SDA GPIO27, SCL GPIO26
6‑axis IMUQMI8658, I2C address 0x6BSDA GPIO27, SCL GPIO26
RTCPCF85063, I2C address 0x51SDA GPIO27, SCL GPIO26
Temp/Humidity SensorSHTC3, I2C address 0x70SDA GPIO27, SCL GPIO26
TFSDSPISCLK GPIO6, MOSI GPIO7, MISO GPIO5, CS GPIO9
BOOT ButtonUser ButtonGPIO28
SECONDARY DEVELOPMENT RECOMMENDATIONS

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.

2. Example List

Example DirectoryBasic DescriptionMain Test Content
01_lvgl_demoRuns the LVGL stress test interface based on ILI9488 and LVGL v8.4.0LCD, Backlight, LVGL
02_SD_CardMounts TF card via SDSPI and performs file write and read-back checksTF, SDSPI, File I/O
03_I2C_qmi8658Reads QMI8658 6‑axis sensor data and outputs accelerometer and gyroscope data over serialIMU, I2C bus
04_I2C_pcf85063Initializes the PCF85063 RTC, sets a test time, and periodically prints RTC time over serialRTC, I2C bus
05_shtc3Reads SHTC3 temperature and humidity sensor ID, temperature, and humidity, and outputs over serialTemp/Humidity sensor, CRC check
06_exioTests the onboard CH32V003 IO expander, toggles IO4-IO14 output levels cyclicallyIO expansion, I2C bus
07_exampleComprehensively displays RTC, SHTC3, QMI8658, and TF card status, with BOOT button for page switchingLCD, Backlight, Sensors, RTC, TF Card

3. Directory Structure

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
  • First, use 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.
  • Then, use 05_shtc303_I2C_qmi8658, and 04_I2C_pcf85063 to verify the I2C peripherals.
  • Next, use 02_SD_Card to verify the TF card and SDSPI.
  • Finally, run 01_lvgl_demo and 07_example to verify the LCD, backlight, LVGL, and the comprehensive dashboard.

5. Usage Notes

  • The Arduino example directory is code/arduino/examples. Please do not mix it with the ESP-IDF example directory.
  • This product shares a single I2C bus: SDA GPIO27SCL GPIO26. CH32V003, QMI8658, PCF85063, and SHTC3 are all on this I2C bus.
  • Before running 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.
  • If copying code from other projects, please pay special attention to the LCD SPI pins, TF card chip select (CS) pin, and CH32V003 IO expansion configuration.
  • For troubleshooting compilation, screen illumination, I2C addresses, etc., please refer to the FAQ.

6. Example Details

01_lvgl_demo

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:

CodePurpose
LCD_H_RES / LCD_V_RESLCD resolution, 320 x 320
LCD_SPI_SCLK / LCD_SPI_MOSI / LCD_SPI_MISOLCD SPI pins, GPIO6/GPIO7/GPIO5
LCD_SPI_DC / LCD_SPI_CSLCD DC/CS pins, GPIO4/GPIO8
IO_EXT_LCD_RSTLCD 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

  • The LCD displays the LVGL stress test interface.
  • The serial port outputs ESP32-C5-LCD-2.73 Arduino LVGL demo and LVGL stress demo started.

Troubleshooting

SymptomPossible CauseAction
Compilation error: lvgl.h not foundLVGL from the example package not installedCopy code/arduino/libraries/lvgl to the Arduino libraries directory
Compilation errors related to lv_disp_drv_tLVGL v9 is being usedDelete the incorrect LVGL version and use LVGL v8.4.0 from the example package
Screen stays offCH32V003, LCD reset, backlight, or ILI9488 initialization abnormalRun 06_exio first to confirm CH32V003 is working; then restore the original pin configuration in 01_lvgl_demo
Display color abnormalPixel format or color order configuration modifiedKeep bits_per_pixel = 18LCD_RGB_ELEMENT_ORDER_BGR, and the color inversion configuration as provided in the example

02_SD_Card

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:

CodePurpose
PIN_NUM_CLKTF SCLK, GPIO6
PIN_NUM_MOSITF MOSI, GPIO7
PIN_NUM_MISOTF MISO, GPIO5
PIN_NUM_CSTF 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

  • After inserting a TF card formatted as FAT or FAT32, the serial port prints the TF card type, capacity, write length, read length, and a PASS result.

Troubleshooting

SymptomPossible CauseAction
TF card mount failsNo card inserted, invalid format, or poor contactUse a FAT/FAT32 TF card, re‑insert, and retest
File read/write failsMount failure or incorrect pathConfirm SD_card_Init() prints card info successfully
TF card abnormal after switching from LCD examplesSPI bus state or CS level not restoredRestart the board and run 02_SD_Card separately

03_I2C_qmi8658

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:

CodePurpose
I2C_master_Init()Initializes I2C with SDA GPIO27, SCL GPIO26, 400 kHz
QMI8658_SLAVE_ADDR_HQMI8658 I2C address, default 0x6B
qmi8658_init()Initializes QMI8658
qmi8658_read_xyz()Reads accelerometer and gyroscope data

Expected Behavior

  • The serial port first outputs QMI8658 initialization information, then periodically outputs sensor data.
  • When the development board is slightly tilted or rotated, the accelerometer and gyroscope data will change accordingly.

Troubleshooting

SymptomPossible CauseAction
Serial port indicates QMI8658 initialization failedQMI8658 I2C communication failureConfirm I2C pins are GPIO27/GPIO26; run 05_shtc3 or 06_exio first to verify I2C
Data remains unchangedBoard is stationary or task not runningGently rotate the board and confirm the serial baud rate is 115200
Compilation errors for I2C-related interfacesArduino ESP32 Core version mismatchUse a board support package that includes ESP32-C5 support

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 to review:

CodePurpose
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

  • The serial port outputs the RTC time once per second.

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

SymptomPossible CauseAction
Compilation error: SensorPCF85063.hpp not foundMissing SensorLib dependencyInstall SensorLib and recompile
Serial shows Failed to find PCF85063RTC I2C communication failureConfirm I2C pins are GPIO27/GPIO26; test other I2C examples first
Time always resets to fixed value on power‑upExample actively writes test timeComment out or delete i2c_rtc_setTime() and retest

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 to review:

CodePurpose
I2C_SDA / I2C_SCLI2C pins, SDA GPIO27, SCL GPIO26
SHTC3_ADDRSHTC3 I2C address, default 0x70
SHTC3_CMD_READ_IDReads sensor ID
SHTC3_CMD_MEASURE_T_RHTriggers temperature/humidity measurement
shtc3Crc()CRC check for SHTC3 data
readShtc3()Reads and converts temperature and humidity

Expected Behavior

  • The serial port first outputs the SHTC3 ID, then periodically outputs temperature and humidity.

Troubleshooting

SymptomPossible CauseAction
Serial shows SHTC3 not foundI2C communication failureConfirm I2C pins are GPIO27/GPIO26 and ensure the board is powered
Serial shows Failed to read SHTC3CRC failure or sensor not respondingKeep power stable, power cycle, and retest
Occasional abnormal temperature/humidity valuesInvalid I2C dataThe example includes CRC checking; use data that passes the check

06_exio

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:

CodePurpose
Wire.begin(I2C_SDA, I2C_SCL)Initialize I2C with SDA GPIO27, SCL GPIO26
IO_EXTENSION_ADDRCH32V003 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

  • The serial port outputs IO4-IO14 will toggle every second.
  • Then outputs the current levels of IO4-IO14 once per second.

Troubleshooting

SymptomPossible CauseAction
Serial shows IO extension not found at 0x24I2C communication failureConfirm SDA GPIO27, SCL GPIO26 and ensure the board is powered
LCD subsequently malfunctioningCH32V003 not communicating properlyFirst ensure 06_exio runs normally, then troubleshoot display and backlight
Need to re‑flash CH32V003 firmwareNot requiredCH32V003 is pre-flashed from the factory; no action required for normal use

07_example

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:

CodePurpose
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

  • The LCD displays the System Status page.
  • Pressing the BOOT button toggles the page among System Status, RTC, SHTC3, QMI8658 IMU, and TF Card.
  • The serial port periodically outputs RTC, temperature/humidity, accelerometer, gyroscope, and TF card capacity information.

Troubleshooting

SymptomPossible CauseAction
Compilation error: lvgl.h not foundLVGL from the example package not installedCopy code/arduino/libraries/lvgl to the Arduino libraries directory
Compilation error: SensorPCF85063.hpp not foundMissing SensorLib dependencyInstall SensorLib and recompile
Page displays a peripheral as NOPeripheral initialization or communication failureRun the corresponding basic example for that peripheral separately first
BOOT button cannot switch pagesButton GPIO configuration abnormalConfirm the example retains BOOT_BUTTON = GPIO_NUM_28 and INPUT_PULLUP configuration
TF page shows unmountedTF card not inserted or format invalidInsert a FAT/FAT32 formatted TF card and restart the board for testing


Factory Firmware Instructions

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.

Hardware Preparation

  • ESP32-C5-LCD-2.73 development board x1
  • USB cable x1
  • TF card x1 (required only for the Photo page)
  • Wi-Fi hotspot with internet access (required only for the Weather page)

Firmware Description

  • The factory firmware is located in the Firmware directory of the example package.
  • The source code for the factory firmware is located in the code/idf/01_factory directory of the example program package.
  • Upon startup, the example initializes NVS, TF, CH32V003 IO expansion, PCF85063 RTC, LCD, LVGL, and the application menu.
  • The status bar displays the time and Wi-Fi status, with the time synchronized from the RTC.

USB Download Notes

USING USB TO DOWNLOAD PROGRAMS TO THE DEVELOPMENT BOARD

If the port cannot be recognized, please enter Boot mode:

  1. Press and hold the BOOT button.
  2. Connect the USB to the computer.
  3. Release the BOOT button.

After the download is complete, power cycle the board to run the program.

Main Interface and Pages

Upon startup, the LCD displays the factory firmware main interface. Use the onboard buttons to select and enter each page.



Settings Page

The Settings page is used to view and configure onboard functions:

  • Configure Wi-Fi.
  • Adjust LCD backlight.
  • View TF card capacity.
  • View battery information.
  • View About information.

For the Weather page to function, Wi-Fi must first be configured in the Settings page.

Sensor Page

The Sensor page displays onboard sensor data:

  • QMI8658 accelerometer data.
  • QMI8658 gyroscope data.
  • SHTC3 temperature and humidity data.

When the development board is slightly tilted or rotated, the accelerometer and gyroscope data will change accordingly.

Photo Page

The Photo page reads image files from the TF card:

  • Supports .jpg and .jpeg images in the /sdcard/photo directory.
  • The page provides Previous, Next, and Back controls.
  • Before use, insert a TF card formatted as FAT or FAT32 into the development board and create a photo directory on the card.

Weather Page

The Weather page is used to display weather information. Before use, configure Wi-Fi with internet access in the Settings page.

Troubleshooting

SymptomPossible CauseAction
Screen stays offPower supply abnormal, LCD reset failure, or backlight not turned onReconnect the USB and restart; for program troubleshooting, refer to the ESP-IDF 02_lvgl_demo and 07_exio examples
Weather page shows no dataWi-Fi not connected or network unavailableConfigure Wi-Fi in the Settings page and confirm the hotspot can access the internet
Photo page shows no imagesTF card not mounted, directory does not exist, or image format mismatchConfirm the /photo directory exists on the TF card and place .jpg or .jpeg images inside
Sensor page shows no dataI2C peripheral initialization failureRefer to the ESP-IDF 04_qmi865806_shtc3, and 07_exio examples for troubleshooting


Working with ESP-IDF

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

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.

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.

VERSION NOTE

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.

NOTE

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.

VERSION SELECTION

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.

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 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 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.

Building and Flashing

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

Board Resources

FeatureDevice or InterfacePins or Notes
LCDILI9488, SPI, 320 x 320, RGB666SCLK GPIO6, MOSI GPIO7, MISO GPIO5, DC GPIO4, CS GPIO8
LCD ResetCH32V003 I/O ExpanderIO0
LCD BacklightCH32V003 PWMIO Expansion PWM
I/O ExpanderCH32V003, I2C address 0x24SDA GPIO27, SCL GPIO26
6‑axis IMUQMI8658, I2C address 0x6BSDA GPIO27, SCL GPIO26
RTCPCF85063, I2C address 0x51SDA GPIO27, SCL GPIO26
Temp/Humidity SensorSHTC3, I2C address 0x70SDA GPIO27, SCL GPIO26
TFSDSPISCLK GPIO6, MOSI GPIO7, MISO GPIO5, CS GPIO9
BOOT ButtonUser ButtonGPIO28

Example List

Example DirectoryDescription
01_factoryFactory example, featuring main menu, settings, sensor, photo, and weather pages
02_lvgl_demoInitialize LCD and LVGL, runs the LVGL benchmark example
03_sd_cardMount TF card, writes and reads back a test file
04_qmi8658Read QMI8658 accelerometer and gyroscope data, and outputs them via serial port
05_pcf85063Read PCF85063 RTC time and output it periodically via serial port
06_shtc3Read SHTC3 temperature and humidity data, and output them periodically via serial port
07_exioTest CH32V003 IO expansion by cyclically toggling IO4-IO14 output levels

Usage Notes

  • For secondary development, we recommend modifying the application layer or UI logic first. The BSP already defines and initializes the basic hardware resources and low-level interfaces of the development board. Only modify BSP-related code when changing hardware connections, adjusting low-level drivers, or adapting new peripherals.
  • 01_factory and 02_lvgl_demo use LVGL v9.5.0 and esp_lvgl_adapter.
  • For 01_factory and 03_sd_card, it is recommended to insert a TF card formatted as FAT or FAT32 before running.
  • The Photo page of 01_factory reads .jpg or .jpeg images from the /sdcard/photo directory by default.
  • This product shares a single I2C bus: SDA GPIO27SCL GPIO26. CH32V003, QMI8658, PCF85063, and SHTC3 are all on this I2C bus.
  • Example 07 is an EXIO expansion IO test, primarily used to observe IO outputs or serial port status; it does not include an operational effect image.

01_factory

Example Description

  • This example is the factory application example. Upon startup, it initializes NVS, TF, CH32V003 IO expansion, PCF85063 RTC, LCD, LVGL, and the application menu.
  • The program synchronizes the system time from the RTC and displays the time and Wi-Fi status in the status bar.
  • The menu registers the Settings, Sensor, Photo, and Weather applications.
  • The Settings page includes items such as Wi-Fi, Backlight, TF Card Capacity, Battery Info, and About.
  • The Sensor page displays QMI8658 accelerometer and gyroscope data, as well as SHTC3 temperature and humidity data.
  • The Photo page reads JPG images from the /sdcard/photo directory and provides Previous, Next, and Back controls.
  • The Weather page is used to display weather information; Wi-Fi must first be configured via the Settings page.

Hardware Connection

  • Connect the board to your computer via USB.
  • To use the Photo page, insert a TF card formatted as FAT or FAT32, create a photo directory on the TF card, and place .jpg or .jpeg images inside.
  • To use the Weather page, configure Wi-Fi with internet access.

Code Entry

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:

CodePurpose
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

Expected Behavior

  • The LCD displays the factory menu main interface.
  • Pages for Settings, Sensor, Photo, and Weather can be accessed via buttons.
  • The status bar updates the time every second, and the status icon changes after Wi-Fi connection.





Common Troubleshooting

SymptomPossible CauseAction
Photo page indicates no imagesTF card not mounted, directory does not exist, or image format mismatchConfirm the /photo directory exists on the TF card and place .jpg or .jpeg images inside
Weather page shows no dataWi-Fi not connected or network unavailableConfigure Wi-Fi in the Settings page and confirm the hotspot has internet access
Sensor page shows no dataI2C peripheral initialization failedRun 04_qmi865805_pcf8506306_shtc3, and 07_exio separately first

02_lvgl_demo

Example Description

  • This example is used to verify the LCD, backlight, and LVGL graphics refresh.
  • The program initializes NVS, CH32V003 IO expansion, ILI9488 LCD, LVGL, and backlight.
  • After initialization, it calls lv_demo_benchmark() to run the LVGL benchmark example.

Hardware Connection

  • Connect the board to your computer via USB.
  • The example uses the onboard LCD and backlight; no external modules are required.

Code Entry

02_lvgl_demo/main/main.c
02_lvgl_demo/components/waveshare__esp32_c5_lcd_2_73

Recommended key code sections to review:

CodePurpose
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

Expected Behavior

  • The LCD displays the LVGL benchmark screen.
  • The serial port outputs logs related to LCD, LVGL, and benchmark operations.

Common Troubleshooting

SymptomPossible CauseAction
Screen stays offCH32V003, LCD reset, backlight, or SPI initialization abnormalRun 07_exio first, then restore the LCD-related pin definitions in the BSP
Display abnormalLCD color format or resolution configuration modifiedConfirm BSP_LCD_H_RESBSP_LCD_V_RES are 320, and BSP_LCD_BITS_PER_PIXEL is 18

03_sd_card

Example Description

  • This example is used to verify TF card read/write operations.
  • The program first sets the LCD CS GPIO8 high to prevent chip select conflicts when the LCD and TF card share the SPI bus.
  • It then calls bsp_sdcard_mount() to mount the TF card at the mount point /sdcard.
  • Upon successful mounting, the program writes to /sdcard/test.txt, then reads it back and verifies the content.

Hardware Connection

  • Connect the board to your computer via USB.
  • Insert a TF card formatted as FAT or FAT32.

Code Entry

03_sd_card/main/main.c
03_sd_card/components/waveshare__esp32_c5_lcd_2_73

Recommended key code sections to review:

CodePurpose
BSP_LCD_CSLCD CS, GPIO8, pulled high before test
bsp_sdcard_mount()Mount TF card
BSP_SD_MOUNT_POINTTF 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

Expected Behavior

  • The serial port prints TF card information.
  • Upon passing the test, it outputs TF CARD TEST PASS.

Common Troubleshooting

SymptomPossible CauseAction
TF card mount failsNo card inserted, invalid format, or poor contactUse a FAT/FAT32 TF card, re‑insert, and retest
File write or read-back failedFile system corrupted or card not writableReplace the TF card or reformat it before testing again
Abnormal behavior after switching from LCD examplesSPI bus or chip select state not restoredRestart the board and run 03_sd_card separately

04_qmi8658

Example Description

  • This example is used to verify the onboard QMI8658 6-axis sensor.
  • The program calls bsp_qmi8658_drv_init() to initialize QMI8658.
  • Data units are configured as acceleration m/s^2 and gyroscope dps.
  • The main loop checks the data ready status every 200 ms, reads the data, and outputs it via the serial port.

Hardware Connection

  • Connect the board to your computer via USB.
  • The example uses the onboard QMI8658; no external modules are required.

Code Entry

04_qmi8658/main/main.c
04_qmi8658/components/waveshare__esp32_c5_lcd_2_73

Recommended key code sections to review:

CodePurpose
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

Expected Behavior

  • The serial port periodically outputs accelerometer and gyroscope data.
  • When the board is slightly tilted or rotated, the output data will change accordingly.

Common Troubleshooting

SymptomPossible CauseAction
Initialization failedI2C communication errorConfirm I2C uses SDA GPIO27, SCL GPIO26, and run 07_exio or 06_shtc3 first
Data remains unchangedBoard stationary or data not updatedSlightly rotate the board and confirm the serial monitor is running

05_pcf85063

Example Description

  • This example is used to verify the onboard PCF85063 RTC.
  • The program calls bsp_pcf85063a_drv_init() to initialize the RTC.
  • The main loop calls pcf85063a_get_time_date() every second to read the date, time, and day of the week, and outputs them via the serial port.

Hardware Connection

  • Connect the board to your computer via USB.
  • The example uses the onboard PCF85063; no external modules are required.

Code Entry

05_pcf85063/main/main.c
05_pcf85063/components/waveshare__esp32_c5_lcd_2_73

Recommended key code sections to review:

CodePurpose
bsp_pcf85063a_drv_init()Initialize PCF85063 RTC
pcf85063a_get_time_date()Read RTC date and time
pcf85063a_datetime_tRTC date and time structure

Expected Behavior

  • The serial port outputs the RTC time once per second.

Common Troubleshooting

SymptomPossible CauseAction
RTC read failedPCF85063 I2C communication errorConfirm I2C uses SDA GPIO27, SCL GPIO26, and test other I2C examples
Time does not match expectationsRTC not set or battery power status abnormalRun 01_factory first to synchronize the system time, or add RTC time setting logic to the code

06_shtc3

Example Description

  • This example is used to verify the onboard SHTC3 temperature and humidity sensor.
  • The program delays for 1 second, then calls bsp_shtc3_drv_init() to initialize SHTC3.
  • The main loop calls shtc3_get_th() every second to read temperature and humidity, and outputs them via the serial port.

Hardware Connection

  • Connect the board to your computer via USB.
  • The example uses the onboard SHTC3; no external modules are required.

Code Entry

06_shtc3/main/main.c
06_shtc3/components/waveshare__esp32_c5_lcd_2_73

Recommended key code sections to review:

CodePurpose
bsp_shtc3_drv_init()Initialize SHTC3
shtc3_get_th()Read temperature and humidity
SHTC3_REG_T_CSD_NMTemperature-first, normal mode measurement command

Expected Behavior

  • The serial port outputs temperature and humidity once per second.

Common Troubleshooting

SymptomPossible CauseAction
Initialization failedSHTC3 I2C communication errorConfirm I2C uses SDA GPIO27, SCL GPIO26, and ensure the board is powered properly
Temperature/humidity read failedSensor did not respond correctly or I2C data errorRestart the board and test again; compare with 04_qmi8658 or 05_pcf85063 to check I2C status

07_exio

Example Description

  • This example is used to verify CH32V003 IO expansion output control.
  • The program calls bsp_io_expander_init() to initialize CH32V003.
  • The example configures the IO expansion pin mode to 0xFFF7, then toggles the output levels of IO4-IO14 once per second.
  • The CH32V003 is pre-flashed with firmware from the factory; no separate flashing of the CH32 firmware is required.

Hardware Connection

  • Connect the board to your computer via USB.
  • The example uses the onboard CH32V003 IO expansion chip; no external modules are required.

Code Entry

07_exio/main/main.c
07_exio/components/waveshare__esp32_c5_lcd_2_73

Recommended key code sections to review:

CodePurpose
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_14Output toggle range

Expected Behavior

  • The output levels of IO4-IO14 toggle once per second.
  • This example does not include an operational effect image.

Common Troubleshooting

SymptomPossible CauseAction
Subsequent LCD or backlight examples malfunctionCH32V003 not communicating properlyFirst confirm 07_exio can run, then troubleshoot LCD reset and backlight control
IO output does not changeIO expansion initialization failed or output range modifiedKeep IO_EXTENSION_IO_Mode(0xFFF7) and the IO4-IO14 output range as in the example


Firmware Flashing and Erasing

This product provides test firmware that can be flashed directly to verify whether the onboard devices are functioning properly.

  • Firmware download: ESP32-C5-LCD-2.73 Example. The bin file is located in the Firmware directory of the example package.
  • Flash address: 0x00

The 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

    • Select the COM port for the development board
    • Set BAUD to the maximum value, 1152000
    • Click the "..." button in the row, select the bin file provided by Waveshare, manually enter the flash address given at the top of this page in the field to its right, and select the leftmost checkbox in the row
    • Click START to begin flashing


  • Wait for flashing to complete (this may take some time; please be patient)

  • Press the reset button and verify the result



Resources

1. Hardware Resources

2. Technical Manuals

3. Example

4. Software Tools

Support

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

Email: services01@spotpear.com


TAG: DTM3202 ESP32 MLX90640 Raspberry Pi 5 Case Pi5 Raspberry Pi CM5 IO BASE A Mini Board a Base Development Platform Compute Module 5 IO Board ESP32 C6 Development Board 1.47 inch LCD Display Screen ST7789 For Arduino WiFi6/LVGL/HMI Onborad SD-Port/RGB-LED Jetson Nano Development Kit JETSON-NANO-DEV-KIT Replace For Jetson-Nano-Developer-Kit-B01 Raspberry Pi 5 Raspberry Pi 13.3 inch FHD AMOLED 1080P Capacitive TouchScreen Display Type-C/HDMI For Computer PC Raspberry Pi 5 Camera User Guide SP485EN ESP32-P4 DEV-KIT C6 WiFi6 MIPI DSI 7/10.1 inch Display/CSI Camera/Audio Speaker For AI Deepseek Raspberry Pi 5 PCIe to USB3.2 Gen1 Hub 5Gbps For Raspberry Pi OS Drive free ESP32 C6 Development Board 1.47 inch LCD Touch Screen 1.47inch Display 172&amp;times;320SD AXS5106L JD9853 Raspberry Pi Audio user guide Raspberry Pi Camera 8MP IMX415 also For Luckfox-Omni3576 RK3576 ESP32-P4-WIFI6 3.5inch LCD Display AI Development Board 320×480 3.5 inch TouchScreen Deepseek Bevelopment Board Raspberry Pi 5 CR2032

[Tutorial Navigation]