Working with Arduino

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

Arduino Getting Started
Setting Up the Development Environment
Example
FAQ

Before Reading

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

The ESP32-C5-Touch-LCD-2.8 or ESP32-C5-Touch-LCD-2.8-EN development boards are ready.
The board is connected to your computer via a USB data cable.
You have installed the Arduino IDE.
You have installed the ESP32 Arduino Core. The corresponding example directory is Arduino-v3.3.10. Please use an Arduino-ESP32 version that matches the example package.
You have downloaded the product example program package.
To run 04_I2C_pcf85063, install the lib/SensorLib included in the example package. To run 06_lvgl_demo, install the lib/lvgl included in the example package.

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-Touch-LCD-2.8 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 you use an older version of the ESP32 Arduino core, the board may not be correctly identified, causing serial download failures or preventing the program from being flashed.

ESP32-C5-Touch-LCD-2.8 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.

Arduino Project Parameter Settings

In the Arduino project settings for the ESP32-C5-Touch-LCD-2.8, select ESP32C5 Dev Module as the board.

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.

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 graphics framework	`lib/lvgl` in example package, LVGL v8.4.0	`06_lvgl_demo`	Offline copy to Arduino libraries directory
`SensorLib` / `SensorPCF85063.hpp`	PCF85063 RTC driver	`lib/SensorLib` in example package, SensorLib v0.3.1	`04_I2C_pcf85063`	Offline copy to Arduino libraries directory

LVGL Version

06_lvgl_demo is based on LVGL v8.4.0. Do not replace it with LVGL v9, as interfaces such as lv_disp_drv_t, lv_disp_draw_buf_t, lv_disp_drv_register(), and lv_indev_drv_t are not compatible.

Offline / Manual Installation:

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.

Locate the library directories in the example package:

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

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

Open Arduino IDE.
Install esp32 by Espressif Systems v3.3.10.
In Tools > Board, select ESP32C5 Dev Module.
Select the USB serial port currently connected.
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

Feature	Device or Interface	Pins or Notes
LCD	ST7789, SPI, 240 x 320, RGB565	SCLK GPIO6, MOSI GPIO7, DC GPIO9, CS GPIO10
LCD Reset	CH32V003 I/O Expander	EXIO1
LCD Backlight	CH32V003 PWM	CH32 PWM
Touch	CST3530, I2C	SDA GPIO0, SCL GPIO1, INT GPIO5
Touch Reset	CH32V003 I/O Expander	EXIO0
I/O Expander	CH32V003, I2C address `0x24`	SDA GPIO0, SCL GPIO1
6‑axis IMU	QMI8658, I2C address `0x6B`	SDA GPIO0, SCL GPIO1
RTC	PCF85063, I2C address `0x51`	SDA GPIO0, SCL GPIO1
Temp/Humidity Sensor	SHTC3, I2C address `0x70`	SDA GPIO0, SCL GPIO1
TF	SDSPI	SCLK GPIO6, MOSI GPIO7, MISO GPIO8, CS GPIO23

Secondary Development Recommendations

Display, touch, backlight, reset, and sensor pins have already been adapted to the product hardware connections in the examples. For routine secondary development, we recommend focusing on application‑layer and UI logic modifications. Do not change the underlying pin definitions unless you are porting the code to a different board or modifying the hardware connections.

2. Example List

Example Directory	Basic Description	Main Test Content
01_exio	Tests the onboard CH32V003 I/O expander, toggles EXIO0~EXIO7 output levels cyclically	I/O expansion, I2C bus
02_I2C_qmi8658	Reads QMI8658 6‑axis sensor data and outputs accelerometer and gyroscope data over serial	IMU, I2C bus
03_SD_Card	Mounts a TF card via SDSPI, prints TF card info and capacity, and provides file read/write interfaces	TF, SDSPI
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_lvgl_demo	Displays a touch example UI using ST7789, CST3530, and LVGL v8.4.0	LCD, backlight, touch, LVGL

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:

Code	Purpose
`Wire.begin(I2C_SDA, I2C_SCL)`	Initializes I2C with SDA GPIO0, SCL GPIO1
`IO_EXTENSION_ADDR`	CH32V003 I2C, default `0x24`
`IO_EXTENSION_Init(Wire)`	Initializes the I/O expander
`IO_EXTENSION_IO_Mode(0xFF)`	Configures EXIO0~EXIO7 as outputs
`IO_EXTENSION_Output()`	Sets the output level of a specified EXIO pin

Expected Behavior

Serial log output should look similar to this:

Arduino EXIO test serial log

Troubleshooting

Symptom	Possible Cause	Action
Serial shows `IO extension not found at 0x24`	I2C communication failure	Confirm SDA GPIO0, SCL GPIO1 and ensure the board is powered
LCD or touch malfunctions later	CH32V003 not communicating	First ensure `01_exio` works, then debug display and touch
Need to re‑flash CH32V003 firmware	Not required	CH32V003 is pre‑programmed at the factory; no action needed for normal use

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:

Code	Purpose
`I2C_master_Init()`	Initializes I2C with SDA GPIO0, SCL GPIO1, 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

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:

Arduino QMI8658 test serial log

Troubleshooting

Symptom	Possible Cause	Action
Serial shows `qmi8658_init fail`	QMI8658 I2C communication failure	Confirm I2C pins are GPIO0/GPIO1; run `01_exio` or `05_shtc3` 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 related to I2C interfaces	Arduino ESP32 core version mismatch	Use `esp32 by Espressif Systems v3.3.10`

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:

Code	Purpose
`PIN_NUM_CLK`	TF SCLK, GPIO6
`PIN_NUM_MOSI`	TF MOSI, GPIO7
`PIN_NUM_MISO`	TF MISO, GPIO8
`PIN_NUM_CS`	TF CS, GPIO23
`SD_card_Init()`	Initializes SPI bus and mounts TF card
`s_example_write_file()` / `s_example_read_file()`	Example file write/read interfaces

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:

Arduino TF card test serial log

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
Compilation errors related to SDMMC/SDSPI interfaces	Arduino ESP32 core version mismatch	Use `v3.3.10`
File read/write fails	Mount failure or incorrect path	Confirm `SD_card_Init()` prints card info successfully

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:

Code	Purpose
`rtc.begin(Wire, SENSOR_SDA, SENSOR_SCL)`	Initializes PCF85063 with SDA GPIO0, SCL GPIO1
`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

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

Arduino PCF85063 test serial log

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 fails with `SensorPCF85063.hpp` not found	Missing SensorLib dependency	Copy `example/Arduino-v3.3.10/lib/SensorLib` to Arduino `libraries` directory
Serial shows `Failed to find PCF85063`	RTC I2C communication failure	Confirm I2C pins are GPIO0/GPIO1; 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

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:

Code	Purpose
`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

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

Arduino SHTC3 temperature and humidity test serial log

Troubleshooting

Symptom	Possible Cause	Action
Serial shows `SHTC3 not found`	I2C communication failure	Confirm I2C pins are GPIO0/GPIO1 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

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:

Code	Purpose
`LCD_WIDTH` / `LCD_HEIGHT`	LCD resolution, 240 x 320
`EXAMPLE_PIN_NUM_SCLK` / `EXAMPLE_PIN_NUM_MOSI`	LCD SPI pins, GPIO6/GPIO7
`EXAMPLE_PIN_NUM_LCD_DC` / `EXAMPLE_PIN_NUM_LCD_CS`	LCD DC/CS pins, GPIO9/GPIO10
`BOARD_LCD_RST_EXIO`	LCD reset, CH32V003 EXIO1
`BOARD_TP_RST_EXIO`	Touch reset, CH32V003 EXIO0
`CST3530_ADDR`	CST3530 I2C address, default `0x58`
`LCD_Init()`	Initializes SPI bus and ST7789 panel
`TOUCH2_Init()`	Initializes CST3530 touch
`create_demo_ui()`	Creates LVGL example UI

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

Symptom	Possible Cause	Action
Compilation fails with `lvgl.h` not found	LVGL not installed from example package	Copy `example/Arduino-v3.3.10/lib/lvgl` to Arduino `libraries` directory
Compilation errors related to `lv_disp_drv_t` / `lv_indev_drv_t`	LVGL v9 used	Remove the incorrect version and use LVGL v8.4.0 from the example package
Screen does not light up	CH32V003, LCD reset, backlight, or ST7789 initialization failure	Run `01_exio` first to confirm CH32V003 is working; then restore original pin configuration in `06_lvgl_demo`
Touch does not respond	CST3530 not detected or touch reset issue	Confirm I2C uses GPIO0/GPIO1, touch interrupt is GPIO5, and touch reset is CH32 EXIO0
Display colors are incorrect	RGB565 byte order or color depth modified	Confirm `lv_conf.h` uses `LV_COLOR_DEPTH 16` and keep the `LV_COLOR_16_SWAP` configuration from the example

Give Feedback

Arduino Getting Started​

Setting Up the Development Environment​

1. Installing and Configuring the Arduino IDE​

2. Installing the ESP32 Board Support Package​

3. Installing Libraries and Example Dependencies​

4. Arduino Project Parameter Settings​

Example​

1. Onboard Resources​

2. Example List​

3. Directory Structure​

4. Recommended First‑Run Order​

5. Usage Notes​

6. Example Details​

01_exio​

02_I2C_qmi8658​

03_SD_Card​

04_I2C_pcf85063​

05_shtc3​

06_lvgl_demo​

Arduino Getting Started

Setting Up the Development Environment

1. Installing and Configuring the Arduino IDE

2. Installing the ESP32 Board Support Package

3. Installing Libraries and Example Dependencies

4. Arduino Project Parameter Settings

Example

1. Onboard Resources

2. Example List

3. Directory Structure

4. Recommended First‑Run Order

5. Usage Notes

6. Example Details

01_exio

02_I2C_qmi8658

03_SD_Card

04_I2C_pcf85063

05_shtc3

06_lvgl_demo