Skip to main content

Working with Arduino

This section describes the environment setup, upload steps, and running behavior for the Arduino examples. Prepare the development board, a USB data cable that supports data transfer, and download the ESP32-C6-Touch-LCD-2.8 Example Programs.

This chapter includes the following sections. Please read as needed:

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.

Set Up the Development Environment​

1. Install Arduino IDE and the Board Support Package​

Refer to the tutorial Install and Configure Arduino IDE to install the IDE. In "File" > "Preferences", add the following to "Additional Boards Manager URLs":

https://espressif.github.io/arduino-esp32/package_esp32_index.json

Open the Boards Manager and install esp32 by Espressif Systems 3.3.12.

Development Environment Version

This document corresponds to Arduino-ESP32 3.3.12, and the examples are located in examples/arduino/examples. The display examples use the bundled LVGL 8.4.0; do not replace it with LVGL 9.

2. Configure the Example Libraries​

The libraries and configuration files required by the examples are provided with the source code in examples/arduino/libraries:

Library or File NameDescriptionVersionInstallation Method
board_configCH32V003 IO expander, battery ADC, ST7789 display, and CST3530 touch drivers1.0.0Use the bundled files
SensorLibSensor drivers such as PCF850630.3.1Use the bundled files
lvglGraphics interface framework8.4.0Use the bundled files
lv_conf.hLVGL configuration fileProvided with the projectPlace alongside the lvgl folder

Set "Sketchbook location" in "File" > "Preferences" to the examples/arduino folder in the downloaded repository, then restart Arduino IDE. The IDE will load the bundled libraries from the libraries directory under that location:

examples/arduino/
├── examples/
│ ├── 01_exio/
│ ├── 02_I2C_qmi8658/
│ ├── 03_SD_Card/
│ ├── 04_I2C_pcf85063/
│ ├── 05_shtc3/
│ ├── 06_lvgl_demo/
│ └── 07_battery_voltage/
└── libraries/
├── board_config/
├── lvgl/
├── SensorLib/
└── lv_conf.h
  • Keep libraries/lv_conf.h and place it alongside the lvgl folder.
  • If you use your own project folder, you can copy the entire contents of the bundled libraries into the libraries directory of that project folder.
Library Version Compatibility

This tutorial uses the libraries and configuration files provided with the source code. Do not install multiple versions of LVGL at the same time, to avoid selecting the wrong library during compilation. The interfaces of LVGL 8 and LVGL 9 are different; replacing the library version or mixing in display and touch drivers from other products may cause compilation failures or abnormal operation.

3. Select Project Parameters​

Connect the development board via USB and configure the following in the "Tools" menu:

OptionSetting
BoardESP32C6 Dev Module
Flash Size16 MB
Flash ModeQIO
PSRAMNot supported; no need to enable
Partition Scheme16M Flash (3MB APP/9.9MB FATFS)
PortThe serial port actually corresponding to the development board
Serial Monitor Baud Rate115200

The board has 16 MB Flash and no PSRAM; keep the example's drawing buffers and memory configuration.

4. Compile and Upload​

  1. From examples/arduino/examples, open the .ino file with the same name inside the desired example directory.
  2. Click "Verify" to compile. After compilation succeeds, click "Upload".
  3. After uploading, open the serial monitor, set the baud rate to 115200, and press RESET to view the boot information.
  4. Operate the development board as described below and check the screen or serial port behavior.

If you cannot connect during upload, disconnect USB, hold BOOT, reconnect USB, release BOOT once the port is detected, and then upload again.

When using Arduino CLI, you can run the following commands in the repository root directory. Replace COM5 with the actual serial port:

arduino-cli core install esp32:esp32@3.3.12
arduino-cli compile --fqbn esp32:esp32:esp32c6:FlashSize=16M,FlashMode=qio,PartitionScheme=app3M_fat9M_16MB --libraries examples/arduino/libraries examples/arduino/examples/06_lvgl_demo
arduino-cli upload -p COM5 --fqbn esp32:esp32:esp32c6:FlashSize=16M,FlashMode=qio,PartitionScheme=app3M_fat9M_16MB examples/arduino/examples/06_lvgl_demo

After flashing a basic example, the development board runs that example. To run the APP desktop, compile and flash the standalone factory project examples/factory.

Example Programs​

The examples are located in the examples/arduino/examples directory of the source package. The .ino file with the same name in each example folder is the entry file; keep the accompanying source files and header files in the same directory.

ExampleBasic DescriptionDependency LibraryView Results
01_exioEXIO6/7 level output and backlight switchingboard_configSerial port, level, and backlight changes
02_I2C_qmi8658Three-axis acceleration and angular velocityDrivers provided with the exampleSerial port
03_SD_CardTF card identification and capacityBuilt-in Arduino-ESP32 componentsSerial port
04_I2C_pcf85063RTC setting and readingSensorLibSerial port
05_shtc3Temperature and humidity reading with CRC checkArduino-ESP32 built-in WireSerial port
06_lvgl_demoDisplay, touch coordinates, and backlight adjustmentboard_config, lvglLCD
07_battery_voltageBattery voltage and raw ADC valueboard_config, lvglLCD, serial port

01_exio​

Example Description​

Controls EXIO6/7 outputs and the screen backlight through the onboard CH32V003, demonstrating the expanded IO and backlight control interfaces.

Hardware Connection​

Connect the development board to the computer using a USB data cable; you can use a multimeter to measure the voltage of the EXIO6/7 header pins relative to GND.

Code Analysis​

  • setup(): Initializes the serial port at 115200 baud and calls Board_IO_Init() to initialize the CH32V003.
  • loop(): Sets the EXIO6/7 levels via Board_IO_SetOutput() and toggles the backlight brightness via Board_SetBacklight(), executing once per second and outputting the results.

Running Effect​

After uploading, the EXIO6/7 outputs toggle between high and low levels every second, the backlight switches between off and full brightness, and the serial port outputs the corresponding status. This example does not display an LCD interface.

The CH32V003 comes preloaded with control firmware, so no separate flashing is required. This example only uses EXIO6/7 as test outputs; the other expanded IOs are used for onboard devices such as the screen, touch, and amplifier, so do not toggle them arbitrarily.

01_exio Extended IO level and backlight status serial port log

02_I2C_qmi8658​

Example Description​

Reads the three-axis acceleration and angular velocity of the onboard QMI8658 six-axis sensor via I2C and outputs them through the serial port.

Hardware Connection​

Connect the development board to the computer with a USB data cable; no external sensor is required.

Code Analysis​

  • setup(): Initializes the serial port and calls I2C_master_Init() to configure the I2C bus.
  • qmi8658c_example: A task created by xTaskCreate() handles sensor initialization, reading, and serial output; loop() performs no additional operations.

Running Effect​

After uploading, open the serial monitor to observe the three-axis acceleration (m/s²) and angular velocity (rad/s), printed about once per second. Gently tilt or rotate the development board and the data will change accordingly. Gravity is still measured when stationary, so the axes are not necessarily zero; this example does not light up the screen.

02_I2C_qmi8658 accelerometer and gyroscope serial port log

03_SD_Card​

Example Description​

Mounts the TF card and outputs the card information and capacity through the serial port.

Hardware Connection​

Back Up Test Card Data

This Arduino example may trigger formatting when the TF card fails to mount. Please back up the files on the card first and use a FAT32-formatted test card.

Insert the TF card before powering on, then connect the development board to the computer using a USB data cable.

Code Analysis​

  • setup(): Initializes the serial port and calls SD_card_Init() after a delay.
  • SD_card_Init(): Configures and mounts the TF card and prints the card information and the practical_size capacity value.
  • The mount configuration sets format_if_mount_failed to true, so the test card may be formatted if mounting fails; loop() does not perform cyclic reads or writes.

Running Effect​

The serial port displays the TF card information and the practical_size capacity. This example does not light up the screen. The current entry only performs mounting and capacity query; it does not automatically create test files or perform file read/write verification.

If you need to write files, read them back for verification, and display the results on the screen, you can run the ESP-IDF 02_sd_card example.

03_SD_Card card information and capacity serial port log

04_I2C_pcf85063​

Example Description​

Sets the date and time of the onboard PCF85063 real-time clock (RTC) and reads it periodically.

Hardware Connection​

Connect the development board to the computer using a USB data cable; no external clock module is required.

Code Analysis​

  • rtc_init(): Initializes the clock module.
  • i2c_rtc_setTime(2025, 9, 9, 14, 51, 30): Writes the demonstration time on each startup.
  • i2c_rtc_loop_task: Reads the RTC date and time and outputs them through the serial port every second.

Running Effect​

After uploading, the serial port time starts from September 9, 2025, 14:51:30 and increments every second; the screen does not light up. Each reset rewrites this demonstration time, with no network time synchronization.

To change the starting date and time, adjust i2c_rtc_setTime() in the sketch and upload again. To test the RTC running continuously, you can remove the call that sets the time.

04_I2C_pcf85063 real-time clock serial port log

05_shtc3​

Example Description​

Reads the onboard SHTC3 temperature and humidity sensor via I2C, verifies the data, and outputs the ambient temperature and relative humidity.

Hardware Connection​

Connect the development board to the computer with a USB data cable; no external sensor is required.

Code Analysis​

  • setup(): Initializes I2C using GPIO6 (SDA) and GPIO7 (SCL), resets the sensor, and reads the device ID.
  • readShtc3(): Wakes up the sensor, sends the measurement command, reads the temperature and humidity data and performs a Cyclic Redundancy Check (CRC), then converts the data to Celsius temperature and relative humidity.
  • loop(): Calls the read function and outputs the measurement results or error messages at intervals of about 1 second.

Running Effect​

After uploading, the serial port displays the temperature and relative humidity about once per second, and the screen does not light up. Sensor readings include a CRC check; if it reports that the sensor cannot be found or that reading failed, power cycle the device and check the serial port errors.

05_shtc3 temperature and humidity serial port log

06_lvgl_demo​

Example Description​

Uses LVGL 8 to create a display and touch test interface, verifying screen functionality with the ST7789 display driver, CST3530 touch driver, and backlight adjustment.

Hardware Connection​

Connect the development board to the computer using a USB data cable; no TF card or speaker is required.

Code Analysis​

  • setup(): Initializes the CH32V003, LCD, and touch controller, allocates the drawing buffer, and registers the LVGL display and input devices.
  • display_flush(): Sends the LVGL drawing data to the LCD and notifies LVGL when complete.
  • touch_read(): Reads the touch coordinates and updates the input state and the interface coordinate label.
  • brightness_slider_event_cb(): Responds to slider changes and calls Set_Backlight() to set the backlight.
  • loop(): Updates the LVGL time base and executes lv_timer_handler() to handle interface refresh and interaction.

Running Effect​

After uploading, the LCD displays Display OK and the touch status. Touch the screen and the coordinates update with the touch position; drag the bottom slider to adjust the backlight between 5% and 100%.

Use the bundled LVGL 8.4.0 and libraries/lv_conf.h, keeping the LV_COLOR_DEPTH 16 and LV_COLOR_16_SWAP 0 settings. The display driver is ST7789 and the touch driver is CST3530; the example is already adapted, so no additional GFX or other touch libraries need to be installed.

06_Lvgl_demo display, touch, and backlight adjustment interface

07_battery_voltage​

Example Description​

Reads the battery ADC sample value through the CH32V003, converts it to voltage, and displays it on the LCD and in the serial port.

Hardware Connection​

Connect a battery that matches the development board; verify the positive and negative terminals before connecting, then connect to the computer using a USB data cable.

Code Analysis​

  • setup(): Waits for the CH32V003 to initialize successfully, then initializes the LCD and LVGL, creates the voltage display label, and turns on the backlight.
  • Board_ReadBatteryVoltage(): Reads eight ADC samples and averages them, and converts the battery voltage based on a nominal 3.3 V reference voltage and a 3:1 voltage divider.
  • loop(): Reads the data once per second and updates the label and serial output; displays ADC read failed if reading fails.

Running Effect​

After uploading, the LCD and serial port update the battery voltage and the raw ADC value (0 to 1023) about once per second. This displays an estimated voltage, not the remaining battery percentage.

If no battery is connected or the contact is poor, the reading may be zero or abnormal. The calculation uses a nominal 3.3 V ADC reference voltage and a 3:1 voltage divider; if you need to verify accuracy, compare with a multimeter.

07_battery_voltage battery voltage on-screen display

07_battery_voltage battery voltage and ADC serial port log

Troubleshooting​

  • Library files not found: Check whether the project folder points to examples/arduino, confirm that the bundled libraries and lv_conf.h are complete, and then restart the IDE. lvgl.h corresponds to lvgl, and SensorPCF85063.hpp corresponds to SensorLib.
  • LVGL interface errors: Confirm that the bundled LVGL 8.4.0 is installed, and avoid mistakenly using LVGL 9 or other libraries with the same name.
  • Blank screen: First check the example list; the serial port sensor and TF card identification examples do not light up the screen. If a display example behaves abnormally, check the serial output for the initialization results of the LCD, touch, and CH32V003.
  • Upload failure or no serial output: Check the data cable and serial port selection, close other software that is occupying the serial port, and press RESET to retry; use 115200 baud for the serial monitor.

For more questions, see the ESP32-C6-Touch-LCD-2.8 FAQ.