Skip to main content

Working with Arduino

This chapter contains 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 Installing and Configuring Arduino IDE to download and install the Arduino IDE and add ESP32 support.

2. Installing Libraries​

To run the example, you need to install the corresponding library.

The example program package for the ESP32-S3-AUDIO-Board development board can be downloaded from here. The arduino\libraries directory within the package already includes all the library files required for this tutorial.

Library/File NameDescriptionVersionInstallation Method
LVGLUI graphics libraryv8.3.10Manual
ESP32-audioI2S-masterAudio decoding libraryv2.0.0Manual
es7210Audio driver library—Manual
es8311Audio driver library—Manual
esp_lcd_jd9853LCD driver library—Manual
TCA9555I/O expander driver library—Manual
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.

Installation Steps:

  1. Navigate to the downloaded example package.

  2. Copy all folders (Arduino_DriveBus, GFX_Library_for_Arduino, etc.) in the Arduino\libraries directory to the Arduino library folder.

    info

    The path to the Arduino libraries folder is typically: c:\Users\<username>\Documents\Arduino\libraries.

    You can also locate it in the Arduino IDE by going to File > Preferences and checking 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.

Example​

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

ExampleBasic Program DescriptionDependency Library
01_LVGL_ArduinoTest onboard device functionsLVGL, ESP32-audioI2S-master

Arduino Project Parameter Settings​

  • If the example being flashed contains a speech recognition model, select "ESP SR 16M (3MB APP/7MB SPIFFS/2.9MB MODEL)" for the Partition Scheme.
  • If the example being flashed does not contain a speech recognition model, select "16M Flash (3MB APP/9.9MB FATFS)" or another appropriate scheme.

01_LVGL_Arduino​

Example Description​

  • This example demonstrates the functions of various onboard devices. Screen 2 displays parameters such as SD Card, Flash Size, a backlight brightness slider, etc. Screen 1 is the music playback interface. Additionally, this example includes a voice recognition feature, which is only enabled before audio playback.

Hardware Connection​

  • The program runs fully only when the TF card (containing MP3 files), screen, and camera are connected.
  • Connect the development board to the computer.

Code Analysis​

  • setup: Hardware initialization, peripheral configuration, etc.

    • Hardware initialization: Inside setup(), multiple initialization functions configure and initialize hardware components connected to the Arduino, such as RTC, gyroscope, LCD display, TF card, audio module, microphone, etc. These initializations ensure the hardware operates correctly.
    • GUI initialization: Calls Lvgl_Init() to initialize LVGL (Light and Versatile Graphics Library), a widely used graphics library for embedded systems. Lvgl_Example1() is an example program that demonstrates how to render a graphical interface on the display.
    • Task scheduling: The Driver_Loop() function creates a task (DriverTask) to manage and cyclically execute some peripheral operations.

  • loop: Primarily used for GUI updates and task scheduling.

    • LVGL task loop: Lvgl_Loop() is a loop function of the LVGL library, used to handle GUI updates, event responses, and other UI-related operations. In embedded systems, graphics libraries typically need to be called frequently in the main loop to maintain screen refresh and real-time interactivity.
    • Task scheduling control: vTaskDelay(pdMS_TO_TICKS(5)) pauses the task for 5 milliseconds. vTaskDelay is a delay function in FreeRTOS, aiming to reduce CPU usage, avoid occupying too much time slice, and ensure other system tasks (such as peripheral processing) can execute on time.

Operation Result​

  • LCD Screen Display Parameter Description
ParameterFunctionDescription
SD CardDisplays the TF card sizeConnect a TF card. If recognition fails, please format the TF card to FAT32 (if initial recognition fails, wait a moment and then reset to check again)
Flash SizeDisplays the Flash sizeOnboard 16MB Flash
RTC TimeDisplays the RTC timeDisplays the current RTC time. If the RTC time is inconsistent with the current time, it is because the RTC does not retain data when powered off. To keep the RTC time accurate, connect an RTC battery and update the RTC time
Backlight brightnessBrightness sliderAdjusts screen brightness
  • Page 2 is the UI page for playing mp3 audio files located in the root directory of the TF card
  • This program enables voice recognition by default. The wake word is "hi esp". After waking up, the backlight dims, and you can speak the command (if the backlight does not dim, it means it was not woken up; recognition requires standard pronunciation and a slower speaking pace)
  • Several formats of MIC test audio are provided below (note: if "hi esp" fails to wake, please reposition the audio to the point where the wake word is played again and replay it).
  • Please do not perform voice recognition while audio is being played through the speaker
  • The reason the test audio plays the wake word twice is that the current firmware version requires a focus step for the first wake-up (metaphorically), and the current firmware does not allow disabling this feature

Switching Between Chinese/English Recognition Models​

  • The initial state of the environment defaults to the English recognition environment. Follow the steps below to switch to the Chinese recognition model or revert to the English recognition model.
  • Switching to Chinese Recognition Model
Setting up the Chinese recognition environment
  • Download the provided program file Program using the Chinese model
  • Navigate to the path C:\Users\Waveshare\AppData\Local\Arduino15\packages\esp32\hardware\esp32\3.0.2\libraries\ESP_SR\src (where Waveshare is the computer username)
  • Replace the esp32-hal-sr.c file in this path with the downloaded file
  • Download the Chinese model Chinese Model - Wake Word 'hi lexin'
  • Navigate to the path C:\Users\Waveshare\AppData\Local\Arduino15\packages\esp32\tools\esp32-arduino-libs\idf-release_v5.1-bd2b9390ef\esp32s3\esp_sr (where Waveshare is the computer username)
  • Replace the srmodels.bin file in this path with the downloaded file
  • Modify the recognition commands in the program to Chinese commands (using Pinyin)
  • Switching to English Recognition Model
Setting up the English recognition environment
  • The initial state of the environment defaults to the English recognition environment. If it has not been switched to Chinese, do not perform the following modifications
  • If it was previously modified for Chinese recognition, download the provided program file Program Using English Model(https://files.waveshare.com/wiki/common/Use_the_English_model_program.zip)
  • Navigate to the path C:\Users\Waveshare\AppData\Local\Arduino15\packages\esp32\hardware\esp32\3.0.2\libraries\ESP_SR\src (where Waveshare is the computer username)
  • Replace the esp32-hal-sr.c file in this path with the downloaded file
  • Download the English model English Model - Wake Word 'hi esp’
  • Navigate to the path C:\Users\Waveshare\AppData\Local\Arduino15\packages\esp32\tools\esp32-arduino-libs\idf-release_v5.1-bd2b9390ef\esp32s3\esp_sr (where Waveshare is the computer username)
  • Replace the srmodels.bin file in this path with the downloaded file
  • Modify the recognition commands in the program to English commands