Working with Arduino

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

• Arduino Getting Started
• Setting Up the Development Environment
• Example

Arduino Getting Started

New to Arduino ESP32 development and looking for a quick start? We have prepared a comprehensive Getting Started Tutorial for you.

• Section 0: Getting to Know ESP32
• Section 1: Installing and Configuring Arduino IDE
• Section 2: Arduino Basics
• Section 3: Digital Output/Input
• Section 4: Analog Input
• Section 5: Pulse Width Modulation (PWM)
• Section 6: Serial Communication (UART)
• Section 7: I2C Communication
• Section 8: SPI Communication
• Section 9: Wi-Fi Basics
• Section 10: Web Server
• Section 11: Bluetooth
• Section 12: LVGL GUI Development
• Section 13: Comprehensive Project

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

• ESP32-related boards require the "esp32 by Espressif Systems" board support package.
• For installation instructions, refer to the Arduino Board Manager Tutorial.
• For the ESP32-C5-LCD-1.47, select a board package version that includes ESP32-C5 support.

3. Installing the Libraries

The example programs require the following Arduino libraries. If you are installing libraries manually in Arduino IDE, refer to the Arduino Library Manager Tutorial.

Library Name	Description
GFX Library for Arduino	LCD graphics driver library, used as GFX_Library_for_Arduino in the examples
lvgl 9.5.0	Graphics library, used for LVGL-related examples

Version Compatibility Note

LVGL has version dependencies with the example code. Please use lvgl 9.5.0 to avoid compilation failures or display issues caused by version mismatches.

Example

• The example programs are located in the examples/arduino directory of the resource package. Before flashing, ensure that the board model, USB port, and partition scheme are correctly configured.

• The root directory of the resource package already contains the libraries folder. Before compiling examples in Arduino IDE, open "File" > "Preferences" and set the "Sketchbook location" to the root directory of the resource package, i.e., the esp32-c5-lcd-1.47 folder that contains both libraries and examples. After setting, restart Arduino IDE, then open the examples to compile and flash.

Board Resources

Feature	Resource	GPIO or Notes
LCD	ST7789, SPI, 172 × 320, RGB565	SCLK GPIO7, MOSI GPIO6, CS GPIO23, DC GPIO24, RST GPIO26
LCD Backlight	LEDC PWM	GPIO10
TF	SDSPI	SCLK GPIO7, MOSI GPIO6, MISO GPIO5, CS GPIO4
RGB LED	WS2812B, 1 LED	GPIO8, RGB order
SPIFFS	Internal Flash file system	Select a partition scheme that includes SPIFFS
Wi-Fi	ESP32-C5 built-in wireless	No extra GPIO needed

Arduino Project Parameter Settings

1. Open Arduino IDE.
2. In "Tools" > "Board", select the ESP32-C5 board.
3. Select the currently connected USB port.
4. To view serial output, enable USB CDC or use the corresponding serial configuration as described in the example notes.
5. Before compiling 06_spiffs_rw and 08_board_showcase, select a partition scheme that includes SPIFFS.

When using arduino-cli to compile, refer to the following commands:

arduino-cli lib install "GFX Library for Arduino"
arduino-cli lib install "lvgl@9.5.0"
arduino-cli compile --fqbn esp32:esp32:esp32c5 arduino/02_lvgl_hello

Example List

Example Directory	Description
01_lcd_panel_basic	Initialize the LCD using GFX_Library_for_Arduino and draw color blocks
02_lvgl_hello	Start LVGL 9.5.0 and display a basic interface on the LCD
03_backlight_fade	Use LEDC to adjust the LCD backlight and display the brightness value via LVGL
04_ws2812_rgb	Use rgbLedWrite() to control the onboard WS2812B RGB LED to cycle through different colors
05_sdcard_rw	Show a TF status page and perform file write and read-back verification
06_spiffs_rw	Mount SPIFFS and perform file write and read-back verification in internal Flash
07_wifi_scan	Scan nearby Wi-Fi networks and output the scan results with strong signals via serial
08_board_showcase	Comprehensive demonstration of LCD, WS2812B, SPIFFS, TF card, and Wi-Fi status

01_lcd_panel_basic

Example Description

• This example initializes the ST7789 LCD using GFX_Library_for_Arduino without starting LVGL.
• The LCD first displays a multi-color stripe background, then shows a moving color block to check display and partial refresh functionality.

Hardware Connection

• Connect the development board to the computer.
• This example uses only the onboard LCD and backlight; no external modules are required.

Code Analysis

• setup(): Initializes serial, LCD backlight, and LCD driver, then calls draw_color_bars() to draw the background.
• init_backlight(): Configures LEDC PWM backlight output on GPIO10.
• draw_color_bars(): Draws multiple color stripes across the screen width.
• loop(): Periodically calls draw_motion_frame() to refresh the area where the moving color block is located.

Running Effect

• The LCD displays a multi-color stripe background with a color block moving up and down continuously.

02_lvgl_hello

Example Description

• This example starts LVGL 9.5.0 and outputs the LVGL display to the LCD via GFX_Library_for_Arduino.
• The screen shows the board name, LCD resolution, SPI pin information, and a status bar.

Hardware Connection

• Connect the development board to the computer.
• This example uses only the onboard LCD and backlight; no external modules are required.

Code Analysis

• setup(): Resets the LCD, then initializes the display driver, LVGL, and the example UI.
• reset_lcd_panel(): Controls CS, DC, and RST pins according to the LCD reset timing.
• init_display(): Initializes the ST7789 and sets screen orientation and backlight.
• init_lvgl(): Creates the LVGL display object, configures the refresh callback and display buffer.
• create_ui(): Creates UI elements such as title, device info, and status bar.
• loop(): Calls lvgl_loop_once() to handle LVGL periodic tasks.

Running Effect

• The LCD shows the LVGL example interface, including the board name, LCD parameters, and SPI pin information.

03_backlight_fade

Example Description

• This example uses LEDC PWM to adjust the LCD backlight brightness.
• The LVGL page simultaneously displays the current brightness percentage and a progress bar.

Hardware Connection

• Connect the development board to the computer.
• This example uses only the onboard LCD and backlight; no external modules are required.

Code Analysis

• setup(): Initializes the LCD, LVGL, and the backlight example UI.
• init_display(): Starts the LCD and sets the initial backlight.
• init_lvgl(): Configures the LVGL display buffer and refresh callback.
• create_ui(): Creates a brightness value label and a progress bar.
• loop(): Periodically calls set_backlight() and update_ui() to vary the backlight brightness as a percentage.
• lvgl_loop_once(): Advances the LVGL tick and handles UI refresh.

Running Effect

• The LCD backlight brightness cycles, and the percentage and progress bar on the screen update synchronously.

04_ws2812_rgb

Example Description

• This example uses rgbLedWrite() from the ESP32 Arduino core to control the onboard WS2812B RGB LED.
• The LED cycles through colors such as red, green, blue, etc.

Hardware Connection

• Connect the development board to the computer.
• This example uses only the onboard RGB LED; no external modules are required.

Code Analysis

• setup(): Initializes serial and prints the example name.
• set_led(): Wraps the RGB LED color setting. For the onboard LED, the parameter order is red, green, blue.
• loop(): Calls set_led() at fixed intervals to cycle the RGB LED through different colors.

Running Effect

• The onboard WS2812B RGB LED switches colors in sequence.

05_sdcard_rw

Example Description

• This example mounts a TF card via SDSPI and performs file write and read-back verification.
• The LCD page shows the TF card mount, write, read, and result statuses.

Hardware Connection

• Connect the development board to the computer.
• Insert a FAT or FAT32-formatted TF card into the board.

Code Analysis

• setup(): Initializes the LCD, LVGL, TF card pins, and status UI, then performs the TF card read/write test.
• init_sd_pins(): Configures the TF card related pin states.
• mount_sd_card(): Mounts the TF card via SDSPI and reads card type and capacity.
• write_file(): Writes a test file to the TF card.
• read_file(): Reads back the test file content and verifies data consistency.
• set_item() and set_summary(): Update the step status and final result on the LCD.
• loop(): Calls lvgl_loop_once() to keep the UI refreshed.

Running Effect

• The LCD displays the TF card capacity, file write/read results, and the serial outputs detection information simultaneously.

06_spiffs_rw

Example Description

• This example mounts the SPIFFS file system in internal Flash.
• The program writes /hello.txt, reads it back, and outputs the content via serial.

Hardware Connection

• Connect the development board to the computer.
• Before compiling and flashing, select a partition scheme that includes SPIFFS.

Code Analysis

• setup(): Initializes serial, mounts SPIFFS with SPIFFS.begin(true), and prints total and used capacity.
• write_read_check(): Deletes the old test file, writes new content, reads it back, and checks if the string matches.
• loop(): This example has no loop task.

Running Effect

• The serial outputs SPIFFS capacity information, the read-back content, and the test completion status.

07_wifi_scan

Example Description

• This example uses the ESP32-C5 built-in Wi-Fi to scan for nearby networks.
• The serial outputs the SSID, RSSI, and channel information of discovered networks.

Hardware Connection

• Connect the development board to the computer.
• Ensure there are 2.4 GHz or 5 GHz Wi-Fi networks within range.

Code Analysis

• setup(): Initializes serial, sets Wi-Fi to STA mode, and disconnects any existing connection.
• loop(): Calls WiFi.scanNetworks() to scan, then outputs the number of networks, SSID, RSSI, and channel for each.
• WiFi.scanDelete(): Frees the resources used by the scan results.

Running Effect

• The serial outputs Wi-Fi scan results approximately every 5 seconds.

08_board_showcase

Example Description

• This example comprehensively tests the LCD, backlight, WS2812B RGB LED, SPIFFS, TF card, and Wi-Fi scanning.
• The LCD page shows the status of each feature as RUN, PASS, WARN or FAIL.

Hardware Connection

• Connect the development board to the computer.
• If you want to test the TF card, insert a FAT or FAT32-formatted TF card into the board.
• Before compiling and flashing, select a partition scheme that includes SPIFFS.

Code Analysis

• setup(): Initializes the LCD, LVGL, status UI, and the comprehensive test flow.
• create_ui(): Creates the board resource status panel.
• run_showcase(): Sequentially checks the LCD, RGB LED, SPIFFS, TF card, and Wi-Fi.
• file_rw_check(): Performs file write and read-back verification on SPIFFS or the TF card.
• mount_sd_card(): Mounts the TF card and reads capacity information.
• set_item(): Updates the status and description text for each feature.
• loop(): Calls lvgl_loop_once() to keep the UI refreshed.

Running Effect

• The LCD shows the test result for each feature; after completion, the final status is displayed at the bottom. If no TF card is inserted or no Wi-Fi is scanned, the corresponding items show a warning.

Usage Notes

• Before running 05_sdcard_rw, insert a FAT or FAT32-formatted TF card.
• 06_spiffs_rw and 08_board_showcase require a partition scheme that includes SPIFFS.
• The LCD and TF share SPI clock and MOSI pins; the examples are already configured for the onboard connections.
• The onboard RGB LED examples pass color parameters in the order red, green, blue.