Working with Arduino

This chapter introduces the Arduino development environment configuration, dependency library installation methods, and the functionality and operational behavior of the Arduino example programs in the product repository for the ESP32-S3-Touch-AMOLED-2.06.

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

Arduino Getting Started
Setting Up the Development Environment
Example

Before You Begin

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

The ESP32-S3-Touch-AMOLED-2.06 development board is ready.
The board is connected to the PC via a USB data cable.
Arduino IDE is installed.
The esp32 by Espressif Systems board package is installed, version v3.2.0 or higher.
The ESP32-S3-Touch-AMOLED-2.06 Arduino example programs have been downloaded.
The libraries and configuration files in the examples/arduino/libraries directory have been installed as described on this page.

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 Arduino IDE Installation and Configuration Tutorial to download and install the Arduino IDE and add ESP32 board support.

Install the following in the Arduino IDE Board Manager:

Board Package	Installation Method	Version Requirement
`esp32 by Espressif Systems`	Online or offline installation	v3.2.0 or higher

2. Set Arduino Project Parameters

After opening any example, it is recommended to configure as follows:

Arduino IDE Option	Recommended Setting
Board	`ESP32S3 Dev Module`
Port	COM port corresponding to the board
USB CDC On Boot	`Enabled`
Flash Size	Match the onboard 32MB Flash
PSRAM	Enable OPI PSRAM
Partition Scheme	For LVGL examples, select a partition scheme with sufficient application space

USB Serial Port Note

The Type-C download and debugging interface of this product is routed from the ESP32-S3 native USB. Examples 01 to 07 use HWCDC USBSerial to output debugging information. If you write your own code and use Serial, please enable USB CDC On Boot. It is recommended to set the serial monitor baud rate to 115200.

3. Install Dependency Libraries

The product repository provides offline libraries that match the examples. It is recommended to use the versions provided in the repository directly:

examples/arduino/libraries
├── Arduino_DriveBus
├── Arduino_GFX
├── SensorLib
├── XPowersLib
├── lvgl
├── Mylibrary
│   └── pin_config.h
└── lv_conf.h

Library or File	Purpose	Recommended Version or Notes	Installation Method
`Arduino_DriveBus`	I2C driver for FT3168 touch controller	Provided in example package	Manual installation
`Arduino_GFX`	CO5300 AMOLED display driver and basic graphics drawing	v1.6.0; usually displayed as `GFX Library for Arduino` in Library Manager	Recommended to use the example package version
`lvgl`	LVGL graphics library framework	v9.3.0	Recommended to use the example package version
`SensorLib`	Drivers for devices such as PCF85063 RTC, QMI8658 IMU	v0.3.1	Recommended to use the example package version
`XPowersLib`	AXP2101 Driver for AXP2101 power management chip	v0.2.6	Recommended to use the example package version
`Mylibrary/pin_config.h`	Development board pin and hardware parameter definitions	Provided in example package	Manual installation
`lv_conf.h`	LVGL features, fonts, and example configuration	Provided in example package	Manual installation

Recommended installation steps:

Download or clone the product repository.
Locate the examples/arduino/libraries directory.
Copy the library folders and configuration files from this directory to the Arduino libraries directory.

The default libraries directory on Windows is typically:
```
C:\Users\<username>\Documents\Arduino\libraries
```
Alternatively, in Arduino IDE, go to File > Preferences to check the Sketchbook location. The libraries folder within that location is the libraries directory.
Restart Arduino IDE, then open and compile the examples.

LVGL Version Compatibility

The current Arduino examples for this product use LVGL v9.3.0. The code includes the following LVGL v9 interfaces:

lv_display_t
lv_display_create()
lv_display_set_buffers()
lv_indev_create()
lv_tick_set_cb()

Do not use the LVGL v8.4.0 from the ESP32-S3-Touch-AMOLED-2.16 examples. The display driver, input device, and buffer APIs differ significantly between LVGL v8 and v9; mixing them will cause numerous compilation errors.

If you install LVGL online via the Arduino Library Manager, you also need to ensure the demos directory can be found by the following header file include path:

#include <demos/lv_demos.h>

To avoid version and directory structure mismatches, it is strongly recommended to use the lvgl and lv_conf.h provided in the product repository.

4. Compile and Upload

In Arduino IDE, open the .ino file inside the example directory that shares the same name as the directory.
Select ESP32S3 Dev Module and the correct COM port.
Check USB CDC, Flash, PSRAM, and partition settings.
Click "Verify/Compile" to confirm there are no missing libraries or version conflicts.
Click "Upload" and wait for the program to finish downloading.
To view debugging information, open the serial monitor and set it to 115200.

If the device does not automatically enter download mode, you can press and hold BOOT, reconnect the USB, and then upload again.

Example

The Arduino examples are located in the Arduino/examples directory of the product repository.

Example Program	Basic Function	Main Dependencies
01_HelloWorld	Display random text using Arduino GFX	Arduino_GFX
02_GFX_AsciiTable	Draw an ASCII character table on the screen	Arduino_GFX
03_LVGL_PCF85063_simpleTime	Read PCF85063 RTC and display date and time using LVGL	LVGL, SensorLib, Arduino_DriveBus
04_LVGL_QMI8658_ui	Read QMI8658 and plot three-axis acceleration curves using LVGL	LVGL, SensorLib, Arduino_DriveBus
05_LVGL_AXP2101_ADC_Data	Read AXP2101 power data and display it	LVGL, XPowersLib, Arduino_DriveBus
06_LVGL_Arduino_v9	Run LVGL v9 Widgets example and verify touch	LVGL, Arduino_DriveBus
07_LVGL_SD_Test	Mount TF card and display card information and root directory files	LVGL, Arduino_DriveBus, SD_MMC
08_ES8311	Play built-in audio and perform microphone-to-speaker audio loopback	ESP_I2S, ES8311 driver included in example

1. Directory Structure

examples/arduino
├── 01_HelloWorld
├── 02_GFX_AsciiTable
├── 03_LVGL_PCF85063_simpleTime
├── 04_LVGL_QMI8658_ui
├── 05_LVGL_AXP2101_ADC_Data
├── 06_LVGL_Arduino_v9
├── 07_LVGL_SD_Test
├── 08_ES8311
└── libraries

Each numbered directory is an independent Arduino project. When opening an example, open the .ino file inside the corresponding directory that shares the same name, for example:

examples/arduino/01_HelloWorld/01_HelloWorld.ino

The audio example also includes driver and audio data files:

08_ES8311
├── 08_ES8311.ino
├── canon.h
├── es8311.c
├── es8311.h
└── es8311_reg.h

Recommended First-Run Order

01_HelloWorld
  ↓
02_GFX_AsciiTable
  ↓
03_LVGL_PCF85063_simpleTime
  ↓
04_LVGL_QMI8658_ui
  ↓
05_LVGL_AXP2101_ADC_Data
  ↓
06_LVGL_Arduino_v9
  ↓
07_LVGL_SD_Test
  ↓
08_ES8311

First, use 01_HelloWorld and 02_GFX_AsciiTable to verify the display, resolution, and drawing orientation.
Then use 03 to 05 to verify the RTC, IMU, and power management chip, respectively.
Use 06_LVGL_Arduino_v9 to comprehensively verify LVGL v9, display buffering, and touch input.
Insert a TF card and run 07_LVGL_SD_Test.
Finally, run 08_ES8311 to verify audio playback and loopback.

2. Example Descriptions

01_HelloWorld

Function Description

This example uses Arduino GFX to initialize the CO5300 AMOLED screen. It first displays a red Hello World! text on the screen, then continuously draws the same text at random positions with random colors and sizes.

Main functions:

Create the Arduino_ESP32QSPI display bus.
Create the Arduino_CO5300 display object.
Use screen parameters of 410×502 and a 22-pixel column offset.
Clear the screen and display the fixed text.
Continuously draw random text in loop().

Code Entry

01_HelloWorld/01_HelloWorld.ino

Code	Purpose
`Arduino_ESP32QSPI(...)`	Create QSPI display bus
`Arduino_CO5300(...)`	Create CO5300 display object
`gfx->begin()`	Initialize the display
`gfx->fillScreen(WHITE)`	Clear screen with white
`gfx->setTextColor(...)`	Set text color
`gfx->setTextSize(...)`	Set random text scaling
`gfx->println("Hello World!")`	Draw text

Expected Behavior

The screen first displays a red Hello World!. After two seconds, it starts continuously displaying the same text at random locations with different colors and sizes.

Troubleshooting

Symptom	Possible Cause	Suggested Action
`Arduino_GFX_Library.h` not found	Arduino_GFX not installed or directory hierarchy incorrect	Use the `Arduino_GFX` from the example package and check the `library.properties` file location
Screen stays off	Development board, PSRAM, display pins, or library version mismatch	Restore the `pin_config.h` and library versions from the example package
Image is shifted overall	Missing column offset parameter for CO5300	Restore the `22`-pixel column offset in the `Arduino_CO5300` constructor
No serial output	Wrong USB port selected	Select the port corresponding to the native USB CDC and set baud rate to 115200

02_GFX_AsciiTable

Function Description

This example uses Arduino GFX to draw an ASCII character table on the AMOLED screen, used to check character drawing, screen coordinates, row/column layout, and display orientation.

Main functions:

Initialize the CO5300 display.
Calculate the number of rows and columns that can be displayed based on screen dimensions.
Draw row and column numbers.
Draw ASCII characters one by one.

Code Entry

02_GFX_AsciiTable/02_GFX_AsciiTable.ino

Code	Purpose
`gfx->width()` / `gfx->height()`	Get current screen dimensions
`gfx->setCursor(...)`	Set character drawing position
`gfx->print(...)`	Draw row and column numbers
`gfx->drawChar(...)`	Draw a single ASCII character

Expected Behavior

The screen displays the ASCII character table with row and column numbers. The image remains static after drawing is complete.

Troubleshooting

Symptom	Possible Cause	Suggested Action
Character table goes off screen	Screen width/height or character spacing modified	Check `LCD_WIDTH` and `LCD_HEIGHT` in `pin_config.h`
Characters or image misaligned	CO5300 offset parameters incorrect	Use the display object constructor parameters from the official example
Character orientation incorrect	Display rotation parameter modified	Restore the default rotation setting from the example

03_LVGL_PCF85063_simpleTime

Function Description

This example uses SensorLib to drive the PCF85063 RTC, displays the time and date in the center of the screen using LVGL v9, and initializes the FT3168 touch controller.

Main functions:

Initialize the CO5300 display and FT3168 touch controller.
Initialize the PCF85063 RTC.
Set the initial date and time for the RTC.
Create LVGL v9 display device, input device, and full-screen buffer.
Read the RTC every second and refresh the screen labels and serial output.

Code Entry

03_LVGL_PCF85063_simpleTime/03_LVGL_PCF85063_simpleTime.ino

Function or Code	Role
`rtc.begin(...)`	Initialize PCF85063
`rtc.setDateTime(...)`	Set RTC date and time
`rtc.getDateTime()`	Get current date and time
`lv_display_create(...)`	Create LVGL v9 display device
`lv_indev_create()`	Create LVGL touch input device
`lv_label_set_text(...)`	Update time display

Expected Behavior

The screen displays two lines in the center:

HH:MM:SS
DD-MM-YYYY

The serial port outputs year, month, day, hour, minute, and second every second.

RTC Time Setting

The official example executes rtc.setDateTime(...) on every startup, writing the fixed date and time from the code. In real projects, this should be modified to user settings, network time synchronization, or writing only on the first boot; otherwise, the RTC will be reset on every restart.

Troubleshooting

Symptom	Possible Cause	Suggested Action
RTC stops running after initialization	I2C pins, address, or SensorLib version incorrect	Check `IIC_SDA`, `IIC_SCL` and SensorLib v0.3.1
Serial shows `Failed to find PCF8563`	The official example error message uses the PCF8563 name	The actual device on this board is PCF85063; still troubleshoot as an RTC I2C communication failure
LVGL v9 APIs not found	LVGL v8 installed by mistake	Install LVGL v9.3.0 from the example package
Font `lv_font_montserrat_40` undefined	`lv_conf.h` does not enable the corresponding font	Use the `lv_conf.h` from the example package

04_LVGL_QMI8658_ui

Function Description

This example uses SensorLib to read the QMI8658 6-axis IMU and plots the X, Y, and Z acceleration curves in real-time using an LVGL Chart.

Main functions:

Initialize the display, FT3168 touch, and LVGL v9.
Initialize QMI8658.
Configure the accelerometer to ±4g, 1000Hz.
Create three LVGL curves with different colors.
Output accelerometer and gyroscope data to serial port.

Code Entry

04_LVGL_QMI8658_ui/04_LVGL_QMI8658_ui.ino

Function or Code	Role
`qmi.begin(...)`	Initialize QMI8658
`qmi.configAccelerometer(...)`	Configure accelerometer range and output data rate
`qmi.enableAccelerometer()`	Enable accelerometer
`lv_chart_create(...)`	Create line chart
`lv_chart_add_series(...)`	Add X, Y, and Z curves
`lv_chart_set_next_value(...)`	Add new acceleration data

Expected Behavior

The screen displays a three-axis acceleration line chart. When the board is moved or tilted, the red, green, and blue curves change accordingly. The serial port outputs in a format similar to:

{ACCEL: x,y,z}
{GYRO: x,y,z}

Troubleshooting

Symptom	Possible Cause	Suggested Action
Displays `Failed to find QMI8658`	IMU I2C communication failure	Check `QMI8658_L_SLAVE_ADDRESS`, I2C pins, and SensorLib
Chart does not refresh	LVGL task handling or IMU data ready logic abnormal	Ensure `loop()` is called continuously in `lv_task_handler()`
Serial has data but screen shows no chart	LVGL buffer allocation or display driver abnormal	Run 01 and 02 to verify the display first, then check PSRAM and LVGL version
Curve changes are not obvious	Development board is stationary	Move or tilt the board for testing

05_LVGL_AXP2101_ADC_Data

Function Description

This example uses XPowersLib to drive the AXP2101 power management chip and displays power and battery status using LVGL v9.

Main displayed data includes:

PMU temperature
Charging, discharging, and standby status.
Whether VBUS is connected and valid.
Charging state
Battery voltage, VBUS voltage, and system voltage.
Battery percentage

Code Entry

05_LVGL_AXP2101_ADC_Data/05_LVGL_AXP2101_ADC_Data.ino

Function or Code	Role
`Wire.begin(IIC_SDA, IIC_SCL)`	Initialize the I2C bus for AXP2101
`power.disableIRQ(...)` / `power.enableIRQ(...)`	Configure AXP2101 interrupts
`adcOn()`	Enable temperature, battery, VBUS, and system voltage detection
`adcOff()`	Disable related ADC detection
`power.getBattVoltage()`	Read battery voltage
`power.getVbusVoltage()`	Read VBUS voltage
`power.getSystemVoltage()`	Read system voltage
`power.getBatteryPercent()`	Read battery percentage
`lv_label_set_text(...)`	Update power information on the screen

Expected Behavior

The screen displays the AXP2101 power status, voltages, and battery percentage. When USB is connected or disconnected, or battery status changes, the displayed content will update accordingly.

Troubleshooting

Symptom	Possible Cause	Suggested Action
Displays PMU offline	AXP2101 I2C communication failure	Check I2C pins, address, and `pin_config.h`
`XPowersLib.h` not found	XPowersLib not installed	Use XPowersLib v0.2.6 from the example package
Battery percentage not displayed	No battery detected	Check battery connection, polarity, and protection status
Voltage data abnormal	ADC not enabled or power supply unstable	Confirm `adcOn()` is called, and check USB/battery connections

06_LVGL_Arduino_v9

Function Description

This example is used to verify LVGL v9 display, touch, and the Widgets example. The code runs by default:

lv_demo_widgets();

Other examples are commented in the code:

// lv_demo_benchmark();
// lv_demo_keypad_encoder();
// lv_demo_music();
// lv_demo_stress();

Code Entry

06_LVGL_Arduino_v9/06_LVGL_Arduino_v9.ino

Function or Code	Role
`FT3168->begin()`	Initialize FT3168 touch controller
`lv_tick_set_cb(millis_cb)`	Set system tick source for LVGL
`lv_display_create(...)`	Create LVGL v9 display device
`lv_display_set_buffers(...)`	Configure full-screen direct rendering buffer
`lv_indev_create()`	Create touch input device
`lv_demo_widgets()`	Start Widgets example

Expected Behavior

The screen displays the LVGL Widgets example, and the controls can be interacted with via touch. When the screen is touched, the serial port outputs coordinates, for example:

Data x 123
Data y 245

Usage Notes

This example uses a 410×502 full-screen RGB565 buffer, which consumes significant memory. OPI PSRAM must be properly enabled.
If the online installed LVGL version does not include a compilable demos directory, compilation will fail at lv_demo_widgets().
Under this scenario, the refresh performance of Arduino GFX may be lower than that of the ESP-IDF double-buffering and anti-tearing examples.

Troubleshooting

Symptom	Possible Cause	Suggested Action
`lv_display_t` not found	LVGL v8 installed	Switch to LVGL v9.3.0
`lv_demo_widgets` not found	Example source not enabled or directory location incorrect	Use the LVGL and `lv_conf.h`
Screen black or repeatedly reboots	PSRAM not enabled or buffer allocation failed	Enable OPI PSRAM and select a suitable partition scheme
Touch not responding	FT3168 initialization failed or interrupt pin incorrect	Check if the serial port continuously outputs `FT3168 initialization fail`
Touch coordinates orientation incorrect	Display rotation and touch mapping not synchronized	Restore the rotation and touch mapping from the official example

07_LVGL_SD_Test

Function Description

This example uses the SD_MMC driver built into the ESP32 Arduino Core to mount a TF card, and displays the card type, capacity, and root directory file list using LVGL.

Main functions:

Initialize the display, touch, and LVGL v9.
Set TF card pins via SD_MMC.setPins(...).
Mount /sdcard in 1-bit mode.
Detect card types such as MMC, SDSC, SDHC, etc.
Get card capacity.
Enumerate root directory files and display them simultaneously on the screen and serial output.

Code Entry

07_LVGL_SD_Test/07_LVGL_SD_Test.ino

Function or Code	Role
`SD_MMC.setPins(...)`	Set SDMMC clock, command, and data pins
`SD_MMC.begin("/sdcard", true)`	Mount TF card in 1-bit mode
`SD_MMC.cardType()`	Get card type
`SD_MMC.cardSize()`	Get card capacity
`listDir(SD_MMC, "/", 0)`	Enumerate root directory files
`lv_label_set_long_mode(...)`	Set long text auto-wrapping

Expected Behavior

After a formatted TF card is inserted, the screen displays something like:

SD_MMC Card Type: SDHC
SD_MMC Card Size: 29764MB
Listing directory: /
FILE: example.txt  SIZE: 123

Usage Notes

The current example calls listDir(..., 0), which only lists the root directory and does not recursively display subdirectory contents.
It is recommended to use a common FAT32 formatted TF card for initial testing.
If there are many files, the label content may exceed the screen's visible area. You can reduce the number of files in the root directory for testing.

Troubleshooting

Symptom	Possible Cause	Suggested Action
Displays `Card Mount Failed`	TF card not inserted properly, incompatible format, or pin error	Reinsert the card, use FAT32, and restore `pin_config.h`
Displays `No SD_MMC card attached`	No valid card detected	Power off, reinsert the card, and restart for testing
Capacity is normal but files not displayed	Files are in subdirectories or root directory is empty	Place test files in the TF card root directory
Screen text is incomplete	Too many files in root directory	Reduce the number of files or add a scrolling container to the interface

08_ES8311

Function Description

This example uses the ESP_I2S from the ESP32 Arduino Core and the ES8311 driver included in the example. It first plays the built-in PCM audio from canon.h, then enters audio loopback: reads audio from the microphone and writes it back to the speaker.

Main functions:

Initialize I2S in 16kHz, 16-bit, stereo mode.
Initialize ES8311 via I2C.
Set playback volume and microphone gain.
Enable amplifier control pin.
Play the built-in audio from canon.h.
Continuously perform audio read and write-back in loop().

Code Entry

08_ES8311/08_ES8311.ino

Related files:

08_ES8311/es8311.c
08_ES8311/es8311.h
08_ES8311/es8311_reg.h
08_ES8311/canon.h

Function or Code	Role
`i2s.setPins(41, 45, 40, 42, 16)`	Set MCLK, BCLK, WS, DOUT, and DIN pins
`i2s.begin(...)`	Start I2S in 16kHz, 16-bit, stereo mode
`Wire.begin(IIC_SDA, IIC_SCL)`	Initializes I2C
`digitalWrite(46, HIGH)`	Turn on amplifier control
`es8311_codec_init()`	Initialize ES8311 and set volume and microphone gain
`i2s.write((uint8_t *)canon_pcm, canon_pcm_len)`	Play built-in PCM audio
`i2s.readBytes(...)`	Read microphone audio
`i2s.write(...)`	Write the read audio back to the output

Expected Behavior

This example does not use the display. After startup, the device first plays the built-in audio, and the serial port outputs:

[echo] Echo start

It then enters audio loopback. When you speak into the microphone, the sound will be played through the audio output path.

If I2S read/write fails, the serial port may output:

[echo] i2s read failed
[echo] i2s write failed

Troubleshooting

Symptom	Possible Cause	Suggested Action
No display on screen	This example does not initialize the display	Judge the operating status by sound and serial output
No sound	Amplifier not enabled, speaker chain or volume abnormal	Check GPIO46, audio connections, and `EXAMPLE_VOICE_VOLUME`
Microphone loopback sound is very low	Microphone gain is too low	Adjust `EXAMPLE_MIC_GAIN` within the allowed range
`ESP_I2S.h` or I2S API compilation fails	Arduino-ESP32 version too old	Use v3.2.0 or higher
Program is large or compiles slowly	`canon.h` contains built-in PCM data	This is normal; if necessary, select a larger application partition

Common Issues Summary

Issue	Suggested Action
Many LVGL types or functions missing	Verify you are using LVGL v9.3.0, not v8.x
Compiler selected multiple libraries with the same name	Delete or move duplicate LVGL, Arduino_GFX, SensorLib, XPowersLib from the Arduino libraries directory
LVGL example compiles but reboots when running	Enable OPI PSRAM and check the serial output for buffer allocation failure messages
Serial monitor has no output	Select the correct native USB port; enable USB CDC, or use `HWCDC USBSerial` from the examples
Upload fails or port not found	Use a USB cable that supports data transfer; re-enter download mode; check the COM port in Device Manager
Display position, touch coordinates, or peripheral pins abnormal	Do not use `pin_config.h` from other product sizes; you must use the version from the ESP32-S3-Touch-AMOLED-2.06 example package

Give Feedback

Arduino Getting Started​

Setting Up the Development Environment​

1. Installing and Configuring the Arduino IDE​

2. Set Arduino Project Parameters​

3. Install Dependency Libraries​

4. Compile and Upload​

Example​

1. Directory Structure​

2. Example Descriptions​

01_HelloWorld​

02_GFX_AsciiTable​

03_LVGL_PCF85063_simpleTime​

04_LVGL_QMI8658_ui​

05_LVGL_AXP2101_ADC_Data​

06_LVGL_Arduino_v9​

07_LVGL_SD_Test​

08_ES8311​

Common Issues Summary​

Arduino Getting Started

Setting Up the Development Environment

1. Installing and Configuring the Arduino IDE

2. Set Arduino Project Parameters

3. Install Dependency Libraries

4. Compile and Upload

Example

1. Directory Structure

2. Example Descriptions

01_HelloWorld

02_GFX_AsciiTable

03_LVGL_PCF85063_simpleTime

04_LVGL_QMI8658_ui

05_LVGL_AXP2101_ADC_Data

06_LVGL_Arduino_v9

07_LVGL_SD_Test

08_ES8311

Common Issues Summary