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. Install and Configure 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.1.0

2. Installing Libraries​

The example program uses the LVGL graphics library to drive the AMOLED display. First confirm the development board PCB version, then download the corresponding example program:

The Arduino\libraries directory in the V1 package contains the library files required by the examples; for V1.1, install the dependencies according to the instructions in the repository.

Library NameDescriptionVersionInstallation Method
LVGLGraphics libraryv8.4.0Offline installation
Version Compatibility Note

The V1 and V1.1 example programs are not interchangeable. There are also version dependencies between LVGL and the driver library. Please use the library version provided or specified by the corresponding package, and avoid mixing versions.

V1 Library Installation Steps:

  1. Extract the V1 example package.

  2. Copy the library folders from the Arduino\libraries directory to the Arduino libraries directory.

    info

    The Arduino libraries directory is typically: C:\Users\<Username>\Documents\Arduino\libraries.

    You can also view the "Sketchbook location" in Arduino IDE via File > Preferences; the libraries folder inside it is the libraries directory.

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

3. Additional Tips​

The ESP32-S3-Touch-AMOLED-1.64 uses the native USB interface of the ESP32-S3. To use the USB serial port via Serial.println(), enable USB CDC On Boot in the Tools menu of Arduino IDE.

Example​

The Arduino example programs are located in the Arduino directory of the corresponding package.

Demo-flow-01

ExampleBasic DescriptionDependency Library
01_ADC_TestRead the current system voltage value-
02_I2C_QMI8658Print the raw data from the IMU-
03_SD_CardLoad and display TF card information-
04_WIFI_APSet to AP mode, can obtain the MAC address of connected devices-
05_WIFI_STASet to STA mode to connect to Wi-Fi and obtain an IP address-
06_LVGL_TestLVGL exampleLVGL

Arduino Project Settings​

ESP32-S3-Touch-AMOLED-1

01_ADC_Test​

Example Description

  • The analog voltage connected via GPIO is converted to a digital value by the ADC. The actual system voltage is then calculated and printed to the terminal.

Hardware Connection

  • Connect the board to the computer using a USB cable.

ESP32-S3-Touch-AMOLED-1

Code Analysis

  • adc_bsp_init(void): Initializes ADC1, including creating an ADC one-shot trigger unit and configuring Channel 3 of ADC1.
  • adc_get_value(float *value,int *data): Reads the value from Channel 3 of ADC1, calculates the corresponding voltage based on the reference voltage and resolution, and stores it at the location pointed to by the passed pointer. Stores 0 if the read fails.
  • adc_example(void* parameter): After initializing ADC1, 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 the program is compiled and downloaded, you can view the printed ADC values and voltage output by opening the Serial Monitor, as shown in the following image:

ESP32-S3-Touch-AMOLED-1

  • The ADC sampling value is around 1900, and the system voltage is about 4.9V. For detailed analysis, refer to the schematic.

02_I2C_QMI8658​

Example Description

  • The QMI8658 chip is initialized via the I2C protocol, and then the corresponding attitude information is read and printed to the terminal every 1 second.

Hardware Connection

  • Connect the board to the computer using a USB cable (refer to Example 01).

Code Analysis

  • qmi8658c_example(void* parameter): This function initializes the QMI8658 device and, in an infinite loop, reads and prints accelerometer, gyroscope, and temperature data every 1 second. As the board rotates, the gyroscope data increases with rotation speed, and the accelerometer calculates the corresponding acceleration based on the current position.

Expected Behavior

  • Open the serial monitor to view the raw data output from the IMU (Euler angles require conversion), as shown in the figure below:

ESP32-S3-Touch-AMOLED-1

  • Data is output every 1 second. For modifications or reference, you can directly access the qmi source file.

03_SD_Card​

Example Description

  • The TF card is driven via SPI or SDMMC, selected by macro definition. After successfully mounting the TF card, its information is printed to the terminal.

Hardware Connection

  • Insert a TF card (must be smaller than 64GB) into the board, then connect the board to the computer using a USB cable (refer to Example 01).

Code Analysis

  • The communication protocol for the TF card can be selected by the user. In the sd_card_bsp.cpp source file, find the #define SDMMC_U macro definition and uncomment it to use SDMMC mode to drive the TF card.

    //#define SDMMC_U

Expected Behavior

  • Click to open the Serial Monitor device. You can see the output TF card information; practical_size indicates the actual capacity of the TF card, as shown below:

ESP32-S3-AMOLED-1

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

04_WIFI_AP​

Example Description

  • This example can set the development board as a hotspot, allowing phones or other devices in STA mode to connect to the development board.

Hardware Connection

  • Connect the board to the computer using a USB cable (refer to Example 01).

Code Analysis

  • In the 05_WIFI_AP.ino file, locate ssid and password. Phones or other STA-mode devices can then connect to the board using this SSID and password.

    const char *ssid = "ESP32_AP";
    const char *password = "12345678";

Expected Behavior

After flashing the program, open the serial terminal, if the device is successfully connected to the hotspot, the MAC address of the device will be output, as shown in the figure: ESP32-S3-LCD-1

05_WIFI_STA​

Example Description

  • This example sets the development board as a station, allowing it to connect to an available AP. After successful connection, it prints the obtained IP information to the terminal.

Hardware Connection

  • Connect the board to the computer using a USB cable (refer to Example 01).

Code Modification

This project configures the chip in STA mode to connect to Wi-Fi and obtain an IP address. Before compiling and downloading the firmware, some code modifications are required. You must change the Wi-Fi router name and password to those available in your environment.
ESP32-S3-AMOLED-1

Code Analysis

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

Expected Behavior

  • The chip successfully connects to Wi-Fi in STA mode, and after clicking on the Serial Monitor, you can see the obtained IP address, as shown in the figure.

ESP32-S3-AMOLED-1

06_LVGL_Test​

Example Description

  • Implements multifunctional GUI interfaces on the screen by porting LVGL.

Hardware Connection

  • Connect the board to the computer using a USB cable (refer to Example 01).

Code Analysis

For LVGL, lvgl_conf.h is its configuration file. Some common settings are described below. LVGL examples and file systems can also be configured in the conf file.

/*Color depth: 1 (1 byte per pixel), 8 (RGB332), 16 (RGB565), 32 (ARGB8888)*/
#define LV_COLOR_DEPTH 16//Color depth, a macro definition that must be concerned with porting LVGL


#define LV_MEM_CUSTOM 0
#if LV_MEM_CUSTOM == 0
    /*Size of the memory available for `lv_mem_alloc()` in bytes (>= 2kB)*/
    #define LV_MEM_SIZE (48U * 1024U)          /*[bytes]*/

    /*Set an address for the memory pool instead of allocating it as a normal array. Can be in external SRAM too.*/
    #define LV_MEM_ADR 0     /*0: unused*/
    /*Instead of an address give a memory allocator that will be called to get a memory pool for LVGL. E.g. my_malloc*/
    #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>   /*Header for the dynamic memory function*/
    #define LV_MEM_CUSTOM_ALLOC   malloc
    #define LV_MEM_CUSTOM_FREE    free
    #define LV_MEM_CUSTOM_REALLOC realloc
#endif     /*LV_MEM_CUSTOM*/
//The above section is mainly for LVGL memory allocation, 
//which defaults to lv_mem_alloc() versus lv_mem_free().

Code Modification

  • The display chip itself does not support hardware rotation. If rotation is needed, it can be implemented in software. In the lcd_bsp.c file, find the #define EXAMPLE_Rotate_90 macro definition and uncomment it to enable software rotation. Note that software rotation performance is inferior to hardware rotation.

    //#define EXAMPLE_Rotate_90

Expected Behavior

  • The LVGL example has relatively high requirements for RAM and ROM, so the program must be configured according to the environment setup requirements. After flashing, the device's operation effect is as follows:

ESP32-S3-Touch-AMOLED-1

For more learning and usage of LVGL, refer to the LVGL official documentation