Skip to main content

Working with Arduino

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.

Setting Up the Development Environment​

1. Installing and Configuring the Arduino IDE​

Please refer to the tutorial Install and Configure Arduino IDE to download and install the Arduino IDE and add ESP32 support.

Board Support PackageInstallation MethodVersion Requirement
esp32 by Espressif Systems"Offline Installation" / "Online Installation"≥3.0.7

The environment setup is performed on Windows 10. Linux and Mac users may refer to Arduino-esp32 Environment Setup.

2. Installing Libraries​

To run the example, you need to install the corresponding library. The example code uses the LVGL graphics library to drive the AMOLED display.

You can download the example programs for the corresponding version of the ESP32-S3-Touch-AMOLED-2.41 board from Related Resources. The library folder locations are as follows:

  • V1: Arduino\libraries
  • V2: 01_Arduino_Libraries
Library NameDescriptionVersionInstallation Method
LVGLGraphics Libraryv8.4.0"Offline Installation"
Version Compatibility Note

There are strong dependencies between versions of LVGL and its driver libraries. To ensure that the examples can be reproduced reliably, it is recommended to use the specific versions listed in the table above. Mixing different versions of libraries may lead to compilation failures or runtime errors.

Installation Steps:

  1. Download the example package corresponding to your hardware version from Related Resources and extract it.

  2. Copy all folders from the library directory of the corresponding version to the Arduino libraries folder: use Arduino/libraries for V1, and 01_Arduino_Libraries for V2.

    info

    The Arduino libraries folder is usually located at: C:\Users\<username>\Documents\Arduino\libraries.

    You can also locate it in Arduino IDE via File > Preferences, and check the "Sketchbook location". The libraries folder is the libraries subfolder within this path.

  3. For other installation methods, please refer to: Arduino Library Management Tutorial.

3. Additional Tips​

  1. Select the development board according to your hardware version:

    • V1: Select Waveshare ESP32-S3-Touch-AMOLED-2.41.
    • V2: Select ESP32S3 Dev Module, and configure the Flash, PSRAM, and USB options according to Tools Configuration.png from the V2 repository.

  2. The ESP32-S3-Touch-AMOLED-2.41 uses the ESP32-S3 native USB interface, not UART-to-USB. For serial communication:

    • The printf() function can be used directly;

    • To use the Serial.println() function, additional configuration is required: Enable the "USB CDC On Boot" option in the IDE's Tools menu, or declare an HWCDC object in your code to handle USB serial communication.

      note

      Set "USB CDC On Boot" in the Arduino IDE "Tools" menu.

Example​

Version Note

V1 and V2 have different pin definitions and project configurations; the example programs cannot be used interchangeably. Please confirm the actual hardware version of your board first, and then download the corresponding version from Related Resources.

The Arduino example programs are located in:

  • V1: Arduino/examples
  • V2: 02_Example/Arduino

The following example descriptions are based on the V1 package. The directory names and implementations of V2 examples may differ; please refer to the programs in the V2 repository.

Example Flow

ExampleBasic DescriptionDependency Library
01_ADC_TestRead the current system voltage-
02_I2C_PCF85063Print real-time clock from RTC chip-
03_I2C_QMI8658Print raw data from the IMU-
04_SD_CardLoad and display TF card information-
05_WIFI_STASet to STA mode, connect to Wi-Fi and obtain IP address-
06_WIFI_APSet to AP mode, obtain IP addresses of connected devices-
07_EX_GPIOUse extended I/O and internal I/O-
08_Li_ION_TestEnable lithium battery-
09_LVGL_TestLVGL exampleLVGL
Arduino_PlayablityPlayability example program-

01_ADC_Test​

This example converts the analog voltage connected through GPIO to digital values via ADC, then calculates the actual system voltage and prints it to the terminal.

Example 1 Figure

ADC Pin Description​

ADC_CHANGPIO_PIN
ADC2_CHANNEL_6GPIO17

Code Walkthrough​

  • adc_bsp_init(void): Initializes ADC2, including creating an ADC single-shot trigger unit and configuring ADC2 channel 6.
  • adc_get_value(float *value, int *data): Reads the value from ADC2 channel 6, calculates the corresponding voltage based on reference voltage and resolution, and stores it in the location pointed to by the passed pointer. If read fails, stores 0.
  • adc_example(void* parameter): After initializing ADC2, creates an ADC task that reads the ADC value every 1 second, and calculates the system voltage from the raw ADC value.

Expected Behavior​

After compiling and uploading the program, open the serial monitor to see the printed ADC value and voltage. The ADC sample value is approximately 1900, and the system voltage is about 4.9 V.

02_I2C_PCF85063​

This example uses the I2C protocol to initialize the PCF85063 chip, set the time, periodically read the time, and print it to the terminal.

RTC Chip Pin Description​

RTCGPIO_PIN
RTC_SDAGPIO47
RTC_SCLGPIO48
RTC_INTEXIO4

Code Walkthrough​

  • void PCF85063_example(void* parameter): Creates an RTC task to implement the RTC functionality, reading the RTC chip clock every 10 seconds and printing it to the terminal.

Expected Behavior​

Open the serial monitor to see the printed RTC time. The data is output every 10 seconds.

03_I2C_QMI8658​

This example uses the I2C protocol to initialize the QMI8658 chip, then reads the corresponding attitude data every 1 second and prints it to the terminal.

IMU Attitude Chip Pin Description​

IMUGPIO_PIN
IMU_SDAGPIO47
IMU_SCLGPIO48
IMU_INT1EXIO4
IMU_INT2EXIO3

Code Walkthrough​

  • qmi8658c_example(void* parameter): Initializes the QMI8658 device, then in an infinite loop reads and prints accelerometer, gyroscope, and temperature data every 1 second. When rotating the board, the gyroscope data increases with faster rotation, while the accelerometer calculates the corresponding acceleration based on the current position.

Expected Behavior​

Open the serial monitor to see the raw data from the IMU (Euler angles need to be converted by the user). The data is output every 1 second.

04_SD_Card​

This example uses a macro definition to select either SPI or SDMMC to drive the TF card. Once the TF card is successfully mounted, its information is printed to the terminal.

Example 4 Figure

TF Card Control Pin Description​

SPI/MMCGPIO_PIN
CSGPIO2
MISO/D0GPIO6
MOSI/CMDGPIO5
SCLK/MCLKGPIO4

Code Walkthrough​

  • The user can select the communication protocol for the TF card. In the sd_card_bsp.cpp source file, find the macro SD_Read_Mode. By default, it uses the SDMMC communication protocol, but can be changed to SDSPI.
#define SD_Read_Mode USER_SPI

Expected Behavior​

Open the serial monitor to see the printed TF card information; practical_size is the actual capacity of the TF card.

Want to learn more about using the TF card with the Arduino ESP32 library? Please refer to Arduino ESP32 TF Library Usage

05_WIFI_STA​

This example configures the development board as a station that can connect to an available AP. Upon successful connection, it prints the obtained IP information to the terminal.

Example 5 Figure

Code Modification​

This project configures the chip in STA mode and connects to Wi-Fi. Before compiling and downloading the firmware, modify the Wi-Fi SSID and password in the code to match your network credentials.

Code Walkthrough​

  • wifi_init(void): Initializes the ESP32 Wi-Fi connection. It sets the ESP32 as a Wi-Fi station, attempts to connect to the specified Wi-Fi network (via ssid and password). If connection succeeds, it prints the local IP address; if it fails to connect within a certain time (20 × 500 ms), it prints a connection failure message. The function can also enable auto-connect and auto-reconnect features.

Expected Behavior​

After the chip connects to Wi-Fi in STA mode, the obtained IP address can be viewed in the serial monitor.

06_WIFI_AP​

This example configures the development board as an AP and waits for STA devices to connect.

Code Walkthrough​

This code initializes serial communication on the ESP32, then creates a Wi-Fi access point with SSID "bsp_esp_demo" and password "waveshare". The loop contains no other continuous operations.

const char* ssid     = "bsp_esp_demo";
const char* password = "waveshare";

WiFi.softAP(ssid, password);

Expected Behavior​

Use a phone or other device to connect to the Wi-Fi. The default SSID is bsp_esp_demo and the password is waveshare.

07_EX_GPIO​

This example tests the basic functionality of the extended I/O and internal GPIO.

Example 7 Figure

Hardware Connection​

You need to use two wires to connect EXIO5 to EXIO6, and GPIO2 to GPIO1.

GPIO Shorting Description​

GPIOxGPIOy
GPIO1GPIO2
EXIO5EXIO6

Code Walkthrough​

  • I2C_master_Init(): Initializes I2C, which is the communication protocol for the external extended I/O.
  • esp32_gpio_init(): Initializes GPIO, setting GPIO1 and EXIO5 as outputs, and GPIO2 and EXIO6 as inputs.
  • loop(): Contains the logic for testing GPIO functions; can be modified as needed.

Expected Behavior​

The serial monitor outputs GPIO test passed. to indicate success, and GPIO test failed. to indicate failure.

08_Li_ION_Test​

This example controls GPIO to enable power supply from the lithium battery.

Code Walkthrough​

  • BAT_GPIO_Init(): Uses GPIO16 to control the lithium battery power supply; initializes GPIO16.
  • BAT_ON(): Enables the lithium battery to supply power to the system.
  • BAT_OFF(): Disables the lithium battery power supply to the system.

Expected Behavior​

After enabling the lithium battery power supply in software, connect the battery, and then the PWR button can be used to control power delivery from the lithium battery.

09_LVGL_Test​

This example ports LVGL to implement some multi-functional GUI interfaces on the screen.

Example 9 Rotated 90° Rotate_90

Example 9 No Rotation Rotate_NONO

Code Analysis​

For LVGL, lvgl_conf.h is its configuration file. Below are some commonly used settings:

/*Color depth: 1 (1 byte per pixel), 8 (RGB332), 16 (RGB565), 32 (ARGB8888)*/
#define LV_COLOR_DEPTH 16 // Macro definition that must be considered when porting LVGL

#define LV_MEM_CUSTOM 0
#if LV_MEM_CUSTOM == 0
    #define LV_MEM_SIZE (48U * 1024U)          /*[bytes]*/
    #define LV_MEM_ADR 0     /*0: unused*/
    #if LV_MEM_ADR == 0
        #undef LV_MEM_POOL_INCLUDE
        #undef LV_MEM_POOL_ALLOC
    #endif
#else       /*LV_MEM_CUSTOM*/
    #define LV_MEM_CUSTOM_INCLUDE <stdlib.h>
    #define LV_MEM_CUSTOM_ALLOC   malloc
    #define LV_MEM_CUSTOM_FREE    free
    #define LV_MEM_CUSTOM_REALLOC realloc
#endif     /*LV_MEM_CUSTOM*/

Other LVGL examples and file system settings can also be configured in the conf file.

Code Modification​

If you need to rotate the display 90 degrees, locate the AMOLED_Rotate macro definition in the 09_LVGL_Test.ino file and choose one of the two:

#define AMOLED_Rotate  Rotate_90      // Landscape
#define AMOLED_Rotate  Rotate_NONO    // Portrait

Expected Behavior​

The LVGL example consumes a significant amount of RAM and ROM; ensure the development board is configured according to the environment setup requirements. The operation result after programming is shown in the images above.

For more LVGL learning and usage, refer to the LVGL Official Documentation.

Arduino_Playablity​

We also provide some playability programs for your reference. Note that the following examples are all based on ESP32_Arduino versions below V3.0; the environment setup can be referenced below.

Playability Figure 1 Statement

Playability Figure 2 Ammeter

Usage Steps​

  1. Install ESP32-2.0.x: Arduino Board Manager Tutorial
  2. Download the example program: ESP32-S3-AMOLED-2.41-Arduino_Playability
  3. Port the library files: Offline Library Porting Tutorial
  4. Compile and upload the example code.

Parameter Settings​

The example program requires parameter modification.

Playablity Parameters