Working with Arduino

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

Arduino Getting Started
Setting Up Development Environment
Demo

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 Development Environment

1. Installing and Configuring Arduino IDE

Please refer to the Arduino IDE Installation and Configuration Tutorial to download and install the Arduino IDE and add ESP32 board support.

2. Selecting Board and Port

In the Arduino IDE, after installing the ESP32 board package, select the board type: Waveshare ESP32S3 XIP.
After connecting the ESP32-S3-Touch-LCD-7B to your computer, select the corresponding serial port in the "Tools" menu.

3. Example Code Package and Libraries

The Arduino example programs and required library files for the ESP32-S3-Touch-LCD-7B are included in the example code package.
The example code package can be downloaded from the following link:
- ESP32-S3-Touch-LCD-7B-BOX-Demo.zip (same path as the ESP-IDF example package)
After extraction, the Arduino examples are located in the Arduino/examples directory, and the library files are in the Arduino/libraries directory. You can add the libraries to the Arduino IDE following the general Arduino tutorial.

Demo

The Arduino demos are located in the Arduino/examples directory of the demo package. Below are the functional descriptions and operational effects for each example.

Demo	Basic Description
01_GPIO	Test GPIO output controlling an LED
02_UART	Test UART serial loopback
03_I2C	Test I2C communication with I/O expander for backlight control
04_CAN	Test CAN interface transmission/reception and alerts
05_RS485	Test RS485 data loopback
06_LCD	Test RGB LCD display and rotation
07_SD	Test TF card mounting and information display
08_TOUCH	Test capacitive touchscreen multi-touch
09_DISPLAY_BMP	Read and switch BMP images from TF card
10_WIFI_SCAN	Scan for nearby WiFi networks and display the list
11_WIFI_STA	Connect to a specified WiFi network as a station and display the IP address
12_WIFI_AP	Create an AP hotspot and display connected devices
13_LVGL_TRANSPLANT	Run the LVGL Demo, showcasing the graphical interface
14_LVGL_BTN	Use an LVGL button to control an LED on/off
15_LVGL_SLIDER	Use a slider to adjust brightness and display voltage

Examples 08, 09, 13, 14, 15 are only applicable to boards with a touchscreen.

General Code Flashing Steps (applicable to all examples):

Connect the development board's USB TO UART Type-C interface to your computer using a USB cable to provide power and enable serial download.

In the Arduino IDE, select the board type Waveshare ESP32S3 XIP.
Select the correct serial port.
Adjust parameters in the example as needed (e.g., WiFi SSID/password).
Click the "Upload" button and wait for compilation and flashing to complete.

The following sections describe the hardware connection, code structure, and operational effect for each example.

01_GPIO

Hardware Connection

Connect the development board to a computer using a USB cable
Connect the LED module to the specified GPIO pin (GPIO6 is used in the example)

Code Analysis

setup():
- Initializes GPIO6 and configures it as output mode
loop():
- In a loop, alternately outputs high and low levels to control the GPIO pin, thereby controlling the LED on/off, achieving an approximately 1 Hz blinking effect

Demo Flashing

Follow the "General Code Flashing Steps", select Waveshare ESP32S3 XIP and the corresponding serial port, then click upload

Operation Result

The screen has no display
The external LED blinks at approximately 1 Hz

02_UART

Hardware Connection

Connect the UART port of the board to the computer using a USB cable

Code Analysis

setup():
- Initializes the serial port using Serial.begin(), setting the baud rate, data format, and receive/transmit pins
- Checks in a loop to ensure the serial port is initialized successfully
loop():
- In the main loop, checks if data is available on the serial port
- If data is available, reads one byte and immediately sends it back, implementing UART data loopback

Demo Flashing

Steps are the same as for 01_GPIO: select the board and serial port, then upload the example

Operation Result

Open a serial debugging assistant and send a message to the ESP32-S3-Touch-LCD-7B
The development board will echo the received message back to the serial debugging assistant unchanged

03_I2C

Hardware Connection

Connect the board's UART port to your computer using a USB cable to power the development board

Code Analysis

setup():
- Calls DEV_I2C_Init() to initialize the I2C bus
- Calls IO_EXTENSION_Init() to initialize the I/O expander chip
DEV_I2C_Init(): Responsible for initializing the I2C device
IO_EXTENSION_Init(): Responsible for initializing the I/O expander chip
IO_EXTENSION_Output(uint8_t pin, uint8_t value): Controls the specified pin of the I/O expander chip to output high/low level
loop():
- In the main loop, periodically pulls the DISP pin high or low via the I/O expander chip, causing the screen backlight to blink periodically

Demo Flashing

Steps are the same as for 01_GPIO

Operation Result

The screen backlight blinks at approximately 1 Hz

04_CAN

Hardware Connection

Connect the development board to a computer using a USB cable
Use a USB-CAN-A tool board to connect it to the board's CAN interface

Code Analysis

setup():
- Initializes I2C, I/O expansion, and the CAN interface
- Before initializing CAN, sets IO_EXTENSION_IO_5 high; otherwise, the CAN interface will not work
- Calls can_init(twai_timing_config_t, twai_filter_config_t, twai_general_config_t) to complete TWAI (CAN controller) initialization
loop():
- Calls can_read_alerts() to read triggered CAN alerts and obtain TWAI status information into alerts_triggered
- Based on different alert types (error passive, bus error, transmission failure, transmission success, etc.), prints corresponding logs and status information, such as bus error count, number of pending messages, transmission error counter, etc
- When a valid data frame is received, it echoes it back unchanged, implementing a CAN loopback test

Demo Flashing

Steps are the same as for 01_GPIO

Operation Result

The screen has no display
After configuring and starting the USB-CAN-A_TOOL, send a CAN message to the ESP32-S3-Touch-LCD-7B. The device will return the same CAN message (images: ESP32-S3-Touch-LCD-7B-Arduino-01.png, ESP32-S3-Touch-LCD-7B-Arduino-02.png)

05_RS485

Hardware Connection

Connect the development board to a computer using a USB cable
Use a USB to RS485 converter to connect to the board's RS485 interface

Code Analysis

setup():
- Initializes Serial1 using RS485.begin(), setting the baud rate, data format, and transmit/receive pins
- Checks in a loop to ensure the serial port is initialized successfully
loop():
- In the main loop, checks if data is available on the RS485 port
- If data is available, reads one byte and immediately sends it back, implementing RS485 data loopback

Demo Flashing

Steps are the same as for 01_GPIO

Operation Result

Open a serial debugging assistant (in RS485 mode) and send data with a newline to the ESP32-S3-Touch-LCD-7B
The device will echo the received data back to the serial debugging assistant unchanged

06_LCD

Hardware Connection

Connect the development board to a computer using a USB cable

Code Analysis

setup():
- Sequentially initializes I2C, I/O expansion, and the RGB LCD, then turns on the backlight
- Creates a buffer to store image data
- Initializes GUI image data, sets the image format and rotation angle (the rotation angle can be modified in the example)
- Controls the screen to sequentially display a color bar, pattern, text, and image, for testing LCD functionality
waveshare_esp32_s3_rgb_lcd_init(): Initializes the RGB LCD
waveshare_rgb_lcd_bl_on(): Turns on the LCD backlight

Demo Flashing

Steps are the same as for 01_GPIO

Operation Result

The ESP32-S3-Touch-LCD-7B will first display an RGB565 color bar, then a pattern and text, and finally an image

07_SD

Hardware Connection

Connect the development board to a computer using a USB cable
Insert the TF card into the TF card slot on the ESP32-S3-Touch-LCD-7B

Code Analysis

setup():
- Performs a series of initialization operations and tests the TF card, displaying relevant information on the screen
sd_mmc_init():
- Initializes the TF card and mounts the file system
read_sd_capacity(uint64_t *total_capacity, uint64_t *available_capacity):
- Reads the TF card's capacity information (total capacity and available capacity)

Demo Flashing

Steps are the same as for 01_GPIO

Operation Result

After running, the ESP32-S3-Touch-LCD-7B will display the TF card information
If mounting fails or no card is present, it will display "SD Card Fail!"

08_TOUCH

Hardware Connection

Connect the development board to a computer using a USB cable

Code Analysis

setup():
- Performs a series of initialization operations and tests the touchscreen, displaying touch points on the screen
touch_gt911_init():
- Initializes the GT911 touch chip
touch_gt911_read_point(uint8_t max_touch_cnt):
- Reads the current touch coordinates, identifying up to 5 touch points

Demo Flashing

Steps are the same as for 01_GPIO

Operation Result

Touching the screen will display touch points on the screen
Touching five positions simultaneously will display five points in different colors

09_DISPLAY_BMP

Hardware Connection

Connect the development board to a computer using a USB cable
Copy the images from the example directory to a TF card, then insert it into the ESP32-S3-Touch-LCD-7B

Code Analysis

setup():
- Performs a series of initialization operations and reads BMP image files from the TF card
- Draws left and right arrows on the screen. Touching the arrows switches the displayed image
list_files(const char *base_path):
- Reads BMP image filenames under the specified path and saves them into BmpPath
GUI_ReadBmp(UWORD Xstart, UWORD Ystart, const char *path):
- Reads BMP image data from the TF card into a buffer. Xstart and Ystart determine the display position

Demo Flashing

Steps are the same as for 01_GPIO

Operation Result

If mounting is successful, left and right arrows will be displayed on the screen
Clicking the arrows will display the images, and clicking again allows switching left or right

10_WIFI_SCAN

Hardware Connection

Connect the development board to a computer using a USB cable

Code Analysis

setup():
- Performs a series of initialization operations and scans for nearby WiFi networks
- Displays the scanned WiFi names on the screen (the current font set may not support Chinese SSID display)
wifi_scan():
- Performs the actual WiFi scan and writes the results into a buffer

Demo Flashing

Steps are the same as for 01_GPIO

Operation Result

After running, it starts scanning for nearby WiFi networks
After the scan completes, the screen displays a list of found WiFi network names

11_WIFI_STA

Hardware Connection

Connect the development board to a computer using a USB cable

Code Analysis

setup():
- Performs a series of initialization operations and connects to a specified 2.4 GHz WiFi network
- After successful connection, displays the IP address assigned by the WiFi network on the screen

Demo Flashing

Steps are the same as for 01_GPIO. You need to configure the correct SSID and password in the code

Operation Result

After flashing and running, the development board connects to the configured WiFi network
After successful connection, it prints the IP address on the screen

12_WIFI_AP

Hardware Connection

Connect the development board to a computer using a USB cable

Code Analysis

setup():
- Performs a series of initialization operations and creates a hotspot named ESP32-S3-Touch-LCD-7B
- Displays the MAC addresses of devices currently connected to the hotspot on the screen

Demo Flashing

Steps are the same as for 01_GPIO

Operation Result

After successful flashing, the development board operates as an AP hotspot
The screen displays a list of MAC addresses of connected devices

13_LVGL_TRANSPLANT

Hardware Connection

Connect the development board to a computer using a USB cable

Code Analysis

setup():
- Performs a series of initialization operations and runs the LVGL Demo
- Uses the lv_demo_widgets example from LVGL version 8.4 to showcase common widgets and basic interaction

Demo Flashing

Steps are the same as for 01_GPIO

Operation Result

After running, it automatically enters the lv_demo_widgets interface, allowing touch interaction

Other Notes

If screen "drift" or other issues occur during use, refer to the official Espressif FAQ for troubleshooting
When using custom UI programs, if you encounter insufficient memory, select a larger partition table in the "Tools" menu of the Arduino IDE

14_LVGL_BTN

Hardware Connection

Connect the development board to a computer using a USB cable
Connect the LED module to the specified GPIO pin (the example uses the same pin as 01_GPIO)

Code Analysis

setup():
- Performs a series of initialization operations and initializes LVGL
- Creates a button widget and binds a click callback function
- In the callback, toggles the level of the target GPIO pin, thereby controlling the LED on/off

Demo Flashing

Steps are the same as for 01_GPIO: select Waveshare ESP32S3 XIP and the correct serial port, then upload the example

Operation Result

A button is displayed on the screen
Clicking the button changes the GPIO pin state, thus controlling the external LED's on/off state

15_LVGL_SLIDER

Hardware Connection

Connect the development board to a computer using a USB cable
Connect the LED module to the specified GPIO pin

Code Analysis

setup():
- Performs a series of initialization operations and initializes LVGL
- Creates a slider widget and a text widget to display information such as battery voltage
- In the slider's event callback, adjusts the LED brightness and screen backlight brightness based on the slider position, and updates the text display

Demo Flashing

Steps are the same as for 01_GPIO

Operation Result

The screen displays a slider and the current battery voltage
Dragging the slider adjusts the brightness of both the LED and the screen backlight simultaneously, while the text area dynamically updates information like battery voltage

Arduino Getting Started​

Setting Up Development Environment​

1. Installing and Configuring Arduino IDE​

2. Selecting Board and Port​

3. Example Code Package and Libraries​

Demo​

01_GPIO​

Hardware Connection​

Code Analysis​

Demo Flashing​

Operation Result​

02_UART​

Hardware Connection​

Code Analysis​

Demo Flashing​

Operation Result​

03_I2C​

Hardware Connection​

Code Analysis​

Demo Flashing​

Operation Result​

04_CAN​

Hardware Connection​

Code Analysis​

Demo Flashing​

Operation Result​

05_RS485​

Hardware Connection​

Code Analysis​

Demo Flashing​

Operation Result​

06_LCD​

Hardware Connection​

Code Analysis​

Demo Flashing​

Operation Result​

07_SD​

Hardware Connection​

Code Analysis​

Demo Flashing​

Operation Result​

08_TOUCH​

Hardware Connection​

Code Analysis​

Demo Flashing​

Operation Result​

09_DISPLAY_BMP​

Hardware Connection​

Code Analysis​

Demo Flashing​

Operation Result​

10_WIFI_SCAN​

Hardware Connection​

Code Analysis​

Demo Flashing​

Operation Result​

11_WIFI_STA​

Hardware Connection​

Code Analysis​

Demo Flashing​

Operation Result​

12_WIFI_AP​

Hardware Connection​

Code Analysis​

Demo Flashing​

Operation Result​

13_LVGL_TRANSPLANT​

Hardware Connection​

Code Analysis​

Demo Flashing​

Operation Result​

Other Notes​

14_LVGL_BTN​

Hardware Connection​

Code Analysis​

Demo Flashing​

Operation Result​

15_LVGL_SLIDER​

Hardware Connection​

Code Analysis​

Arduino Getting Started

Setting Up Development Environment

1. Installing and Configuring Arduino IDE

2. Selecting Board and Port

3. Example Code Package and Libraries

Demo

01_GPIO

Hardware Connection

Code Analysis

Demo Flashing

Operation Result

02_UART

Hardware Connection

Code Analysis

Demo Flashing

Operation Result

03_I2C

Hardware Connection

Code Analysis

Demo Flashing

Operation Result

04_CAN

Hardware Connection

Code Analysis

Demo Flashing

Operation Result

05_RS485

Hardware Connection

Code Analysis

Demo Flashing

Operation Result

06_LCD

Hardware Connection

Code Analysis

Demo Flashing

Operation Result

07_SD

Hardware Connection

Code Analysis

Demo Flashing

Operation Result

08_TOUCH

Hardware Connection

Code Analysis

Demo Flashing

Operation Result

09_DISPLAY_BMP

Hardware Connection

Code Analysis

Demo Flashing

Operation Result

10_WIFI_SCAN

Hardware Connection

Code Analysis

Demo Flashing

Operation Result

11_WIFI_STA

Hardware Connection

Code Analysis

Demo Flashing

Operation Result

12_WIFI_AP

Hardware Connection

Code Analysis

Demo Flashing

Operation Result

13_LVGL_TRANSPLANT

Hardware Connection

Code Analysis

Demo Flashing

Operation Result

Other Notes

14_LVGL_BTN

Hardware Connection

Code Analysis

Demo Flashing

Operation Result

15_LVGL_SLIDER

Hardware Connection

Code Analysis