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.

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

2. Installing Libraries

When installing Arduino libraries, there are generally two methods: online installation and offline installation. If the library installation requires offline installation, you must use the provided library files.
For most libraries, users can easily search for and install them via the Arduino IDE's online Library Manager. However, some open-source or custom libraries are not synchronized to the Arduino Library Manager and therefore cannot be found through online search. In this case, users can only install these libraries manually via offline methods.
The example package for the ESP32-S3-Touch-LCD-2 development board can be downloaded from here. The Arduino\libraries directory within the package already contains all the library files required for this tutorial.

Library/File Name	Description	Version	Installation Method
LVGL	Graphics library	v8.4.0	"Online installation" (requires copying the demos folder to src)
GFX_Library_for_Arduino	LCD driver library	v1.5.0	"Online Installation"
FastIMU	IUM driver library	v1.2.6	"Online Installation"
bsp_cst816	Touch driver library	-	"Offline Installation"

Version Compatibility Notes

There are strong dependencies between versions of LVGL and its driver libraries. For example, a driver written for LVGL v8 may not be compatible with LVGL v9. 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.

3. Arduino Project Parameter Settings

Example

The Arduino examples are located in the Arduino/examples directory of the example package.

Example	Basic Program Description	Dependency Library
01_factory	Comprehensive test program	lvgl, GFX_Library_for_Arduino, FastIMU, OneButton
02_gfx_helloworld	Display HelloWorld on the screen	GFX_Library_for_Arduino
03_sd_card_test	Test TF card	-
04_qmi8658_output	Print QMI8658 data over serial	FastIMU
05_lvgl_qmi8658	Display QMI8658 data using LVGL	lvgl, FastIMU
06_lvgl_battery	Display battery voltage using LVGL	lvgl, GFX_Library_for_Arduino
07_lvgl_brightness	Control and display screen brightness using LVGL	lvgl, GFX_Library_for_Arduino
08_lvgl_example	LVGL example program	lvgl, GFX_Library_for_Arduino
09_lvgl_camera	Display camera image using LVGL	lvgl, GFX_Library_for_Arduino
10_camera_web_server	Display camera image on a web page

01_factory

Example Description

This example tests the functions of the onboard modules of the ESP32-S3-Touch-LCD-2. The screen will display information about each module, and the user can switch pages via the touchscreen.

Hardware Connection

Connect the board to the computer.
Insert the OV5640 camera into the 24Pin Camera Interface on the board (the camera is optional; other functions are not affected).
Insert the TF card into the card slot (optional; other functions are not affected).

Code Analysis

Hardware Initialization

  Serial.begin(115200);
  bsp_i2c_init();          //Initialize I2C bus, commonly used to connect sensors, displays, etc.
  bsp_lv_port_init();      //Initialize the LVGL graphics library port to output graphics to display devices such as LCD
  bsp_spi_init();          //Initialize SPI bus, commonly used for communication with sensors, external storage, screens, etc.

LVGL graphics library configuration

  bsp_lv_port_run();       //Run LVGL-related drivers or loops, such as refreshing the display, etc.
  if (lvgl_lock(-1)) {     //Lock LVGL resources to ensure they do not conflict with other tasks when updating the UI
    lvgl_ui_init();        //Initialize UI, possibly including layout and control settings
    lvgl_unlock();         //Unlock LVGL, allowing other tasks to access LVGL
  }

Peripheral initialization

  app_qmi8658_init();                     //Initialize QMI8658 sensor (such as accelerometer, gyroscope, etc.)
  app_system_init();                      //Perform system-level initialization, such as clock, memory, reset, etc
  app_camera_init();                      //Initialize the camera module, prepare for image capture
  app_wifi_init(sta_ssid, sta_pass);      //Initialize Wi-Fi module, connect to specified Wi-Fi network

Application layer task execution

  app_qmi8658_run();       //Start QMI8658 sensor-related tasks, such as data acquisition, processing, etc.
  app_system_run();        //Start system tasks to ensure that system functions are running properly
  app_camera_run();        //Start camera-related tasks, usually to obtain image data and process or transmit it
  app_wifi_run();          //Start Wi-Fi related tasks, such as connection management, data transmission, etc.

Operation Result

Single‑click BOOT button: down; double‑click BOOT button: up; long‑press BOOT button: confirm.
System interface

QMI8658 interface, showing acquired X, Y, Z axis acceleration and angular velocity data.

Camera interface, showing the image captured by the camera.

Wi‑Fi interface, displaying the Wi‑Fi name and password to connect; after successful connection, the IP address is shown.

02_gfx_helloworld

Example Description

This example demonstrates the ESP32-S3-Touch-LCD-2 using the GFX_Library_for_Arduino library to drive the screen and display "HelloWorld".

Hardware Connection

Connect the board to the computer.

Code Analysis

Create an Arduino_ESP32SPI object bus to configure the SPI bus GPIOs, and create an Arduino_ST7789 object gfx to drive the ST7789 display.

  Arduino_DataBus *bus = new Arduino_ESP32SPI(
  EXAMPLE_PIN_NUM_LCD_DC /* DC */, EXAMPLE_PIN_NUM_LCD_CS /* CS */,
  EXAMPLE_PIN_NUM_LCD_SCLK /* SCK */, EXAMPLE_PIN_NUM_LCD_MOSI /* MOSI */, EXAMPLE_PIN_NUM_LCD_MISO /* MISO */);

  /* More display class: https://github.com/moononournation/Arduino_GFX/wiki/Display-Class */
  Arduino_GFX *gfx = new Arduino_ST7789(
  bus, EXAMPLE_PIN_NUM_LCD_RST /* RST */, EXAMPLE_LCD_ROTATION /* rotation */, true /* IPS */,
  EXAMPLE_LCD_H_RES /* width */, EXAMPLE_LCD_V_RES /* height */);

Operation Result

03_sd_card_test

Example Description

This example demonstrates testing TF card read/write functionality on the ESP32-S3-Touch-LCD-2.

Hardware Connection

Connect the board to the computer.
Insert the TF card into the card slot (the TF card needs to be formatted as FAT32).

Code Analysis

SPI interface initialization and TF card initialization.

  SPI.begin(sck, miso, mosi, cs);
  if (!SD.begin(cs)) {
    Serial.println("Card Mount Failed");
    return;
  }

Operation Result

Open the serial monitor

Insert the TF card into the computer, and and two files, test.txt and foo.test, will appear. The content of the foo.txt is Hello World!, and the test.txt is empty.

04_qmi8658_output

Example Description

This example demonstrates reading QMI8658 data on the ESP32-S3-Touch-LCD-2 and printing it over the serial port.

Hardware Connection

Connect the board to the computer.

Code Analysis

Initialize the QMI8658

  int err = IMU.init(calib, IMU_ADDRESS);
  if (err != 0) {
    Serial.print("Error initializing IMU: ");
    Serial.println(err);
    while (true) {
      ;
    }
  }

Operation Result

Open the serial monitor to see printed X, Y, Z axis acceleration, gyroscope, and QMI8658 internal temperature sensor data.

05_lvgl_qmi8658

Example Description

This example demonstrates reading QMI8658 data on the ESP32-S3-Touch-LCD-2 and displaying it using the LVGL library.

Hardware Connection

Connect the board to the computer.

Code Analysis

Initialize the UI and create a 100ms timer to obtain QMI8658 data.
```
  lvgl_qmi8658_ui_init(lv_scr_act());
```

Operation Result

06_lvgl_battery

Example Description

This example demonstrates using the LVGL library on the ESP32-S3-Touch-LCD-2 to display battery voltage and ADC values on the screen.

Hardware Connection

Connect the board to the computer.
Insert the battery into the battery header.

Code Analysis

Initialize the UI and create a 1000ms timer to obtain ADC data and convert it to voltage.
```
  lvgl_battery_ui_init(lv_scr_act());
```

Operation Result

07_lvgl_brightness

Example Description

This example demonstrates using the LVGL library on the ESP32-S3-Touch-LCD-2 to display screen brightness, with a slider to control the brightness.

Hardware Connection

Connect the board to the computer.

Code Analysis

Initialize the UI and create a slider value change callback; when the slider value changes, the screen brightness is adjusted.
```
  lvgl_brightness_ui_init(lv_scr_act());
```

Operation Result

08_lvgl_example

Example Description

This example demonstrates running the LVGL example program on the ESP32-S3-Touch-LCD-2.

Hardware Connection

Connect the board to the computer.

Note

If the lvgl library is installed online, you need to copy the demos folder to src.

Code Analysis

Select the LVGL example to run.

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

Operation Result

09_lvgl_camera

Example Description

This example displays camera images on the ESP32-S3-Touch-LCD-2 screen using the LVGL library.

Hardware Connection

Connect the board to the computer.
Insert the TF card into the card slot.

Code Analysis

Create a dedicated task to capture camera images.

  xTaskCreatePinnedToCore(camera_task, "camera_task_task", 1024 * 3, NULL, 1, NULL, 0);

Capture camera image and update the display.

  camera_fb_t *pic;
  lv_img_dsc_t img_dsc;
  img_dsc.header.always_zero = 0;
  img_dsc.header.w = 480;
  img_dsc.header.h = 320;
  img_dsc.data_size = 320 * 480 * 2;
  img_dsc.header.cf = LV_IMG_CF_TRUE_COLOR;
  img_dsc.data = NULL;
  // lv_img_set_src(img_camera, &pic);
  while (1)
  {
      pic = esp_camera_fb_get();

      if (NULL != pic)
      {
          img_dsc.data = pic->buf;
          if (lvgl_lock(-1))
          {
              lv_img_set_src(img_camera, &img_dsc);
              lvgl_unlock();
          }
      }
      esp_camera_fb_return(pic);
      vTaskDelay(pdMS_TO_TICKS(1));
  }

Operation Result

10_camera_web

Example Description

This example demonstrates how to drive the camera using the ESP32-S3-Touch-LCD-2. After connecting to Wi‑Fi, the program creates a web server. Users simply enter the device's IP address in a browser to access it. The web page can display the camera image and supports settings such as resolution and mirroring.

Hardware Connection

Connect the board to the computer.
Insert the OV5640 camera into the 24Pin Camera Interface on the board.

Code Analysis

Select the camera model and define related pins and configurations.

  #define CAMERA_MODEL_ESP_EYE  // Has PSRAM
  #define PWDN_GPIO_NUM 17  // Power down is not used
  #define RESET_GPIO_NUM -1 // Software reset will be performed
  #define XCLK_GPIO_NUM 8
  #define SIOD_GPIO_NUM 21
  #define SIOC_GPIO_NUM 16

  #define Y9_GPIO_NUM 2
  #define Y8_GPIO_NUM 7
  #define Y7_GPIO_NUM 10
  #define Y6_GPIO_NUM 14
  #define Y5_GPIO_NUM 11
  #define Y4_GPIO_NUM 15
  #define Y3_GPIO_NUM 13
  #define Y2_GPIO_NUM 12
  #define VSYNC_GPIO_NUM 6
  #define HREF_GPIO_NUM 4
  #define PCLK_GPIO_NUM 9

Wi‑Fi SSID and password to connect to.

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

Start the camera server to begin providing an HTTP video stream.

  startCameraServer();
  Serial.print("Camera Ready! Use 'http://");
  Serial.print(WiFi.localIP());
  Serial.println("' to connect");

Operation Result

Open the serial terminal; after connecting to Wi‑Fi, the IP address is shown.

Enter the IP address printed on the serial port in a browser.
Click "Start Stream" to see the camera image.

Give Feedback

Arduino Getting Started​

Setting Up the Development Environment​

1. Installing and Configuring the Arduino IDE​

2. Installing Libraries​

3. Arduino Project Parameter Settings​

Example​

01_factory​

02_gfx_helloworld​

03_sd_card_test​

04_qmi8658_output​

05_lvgl_qmi8658​

06_lvgl_battery​

07_lvgl_brightness​

08_lvgl_example​

09_lvgl_camera​

10_camera_web​

Arduino Getting Started

Setting Up the Development Environment

1. Installing and Configuring the Arduino IDE

2. Installing Libraries

3. Arduino Project Parameter Settings

Example

01_factory

02_gfx_helloworld

03_sd_card_test

04_qmi8658_output

05_lvgl_qmi8658

06_lvgl_battery

07_lvgl_brightness

08_lvgl_example

09_lvgl_camera

10_camera_web