ESP-IDF

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

• ESP-IDF Getting Started
• Setting Up Development Environment
• Example

ESP-IDF Getting Started

New to ESP32 ESP-IDF development and looking to get started quickly? We have prepared a general Getting Started Tutorial for you.

• Section 1: Environment Setup
• Section 2: Running Examples
• Section 3: Creating a Project
• Section 4: Using Components
• Section 5: Debugging
• Section 6: FreeRTOS
• Section 7: Peripherals
• Section 8: Wi-Fi Programming
• Section 9: BLE Programming

Please Note: This tutorial uses the ESP32-S3-Zero as a teaching example, and all hardware code is based on its pinout. Before you start, it is recommended that you check the pinout of your development board to ensure the pin configuration is correct.

Setting Up Development Environment

info

For the ESP32-S3-DualEye-LCD-1.28 development board, ESP-IDF version V5.4.1 or above is required.

note

The following guide uses Windows as an example, demonstrating development using VS Code + the ESP-IDF extension. macOS and Linux users should refer to the official documentation.

Install the ESP-IDF Development Environment

1. Download the installation manager from the ESP-IDF Installation Manager page. This is Espressif's latest cross-platform installer. The following steps demonstrate how to use its offline installation feature.

   Click the Offline Installer tab on the page, then select Windows as the operating system and choose your desired version from the filter bar.

   

   After confirming your selection, click the download button. The browser will automatically download two files: the ESP-IDF Offline Package (.zst) and the ESP-IDF Installer (.exe).

   

   Please wait for both files to finish downloading.

2. Once the download is complete, double-click to run the ESP-IDF Installer (eim-gui-windows-x64.exe).

   The installer will automatically detect if the offline package exists in the same directory. Click Install from archive.

   

   Next, select the installation path. We recommend using the default path. If you need to customize it, ensure the path does not contain Chinese characters or spaces. Click Start installation to proceed.

   

3. When you see the following screen, the ESP-IDF installation is successful.

   

4. We recommend installing the drivers as well. Click Finish installation, then select Install driver.

   

Install Visual Studio Code and the ESP-IDF Extension

1. Download and install Visual Studio Code.

2. During installation, it is recommended to check Add "Open with Code" action to Windows Explorer file context menu to facilitate opening project folders quickly.

3. In VS Code, click the Extensions icon in the Activity Bar on the side (or use the shortcut Ctrl + Shift + X) to open the Extensions view.

4. Enter ESP-IDF in the search box, locate the ESP-IDF extension, and click Install.

   

5. For ESP-IDF extension versions ≥ 2.0, the extension will automatically detect and recognize the ESP-IDF environment installed in the previous steps, requiring no manual configuration.

Example

The ESP-IDF example programs are located in the ESP-IDF directory of the example package.

Example	Basic Description
01_Text_Number	Test text and number display
02_Shapes_on_Circular	Draw shapes
03_Animated_Eye1	Animated eye simulation
04_SD_gif_show	Display GIF images from TF card
05_Clock	Clock
06_music_player	Test onboard device functions

01_Text_Number

Example Description

• This example demonstrates text and number display on dual LCD screens. The core functionality is "dual-screen synchronous display of fixed text + dynamic numbers", cycling through two-digit numbers from 00 to 99, testing text and number display on the LCD screens.

Hardware Connection

• Connect the development board to the computer.

Code Analysis

• Text_Number() main initialization function, obtains the active screen objects of the two displays and creates the UI:
  • Calls create_screen_ui() for each screen to create the UI layout, using vertical arrangement: text on top, number below
  • lv_timer_create(update_numbers, 1000, NULL); creates a timer with a 1-second interval for number updates (created only once)
• update_numbers(): timer callback function, called every 1000 ms (1 second) to update the numbers and refresh the display
  • (number + 1) % 100; increments the number (loop 0-99)
  • lv_label_set_text() updates the number label display on both screens

Operation Result

• LCD Screen Display

  

02_Shapes_on_Circular

Example Description

• This example sequentially displays squares, triangles, and circles in random colors on the LCD screen. It is suitable for learning ESP32 interaction with the LCD display, drawing random-colored squares, triangles, and circles at the screen center, switching every 3 seconds, testing graphics drawing stability.

Hardware Connection

• Connect the development board to the computer.

Code Analysis

• Shapes_on_Circular() main initialization function, initializes the random number generator, creates the initial shape, and starts a timer to switch shapes every 3 seconds
• random_color() generates random RGB colors to provide diverse display effects for shapes
  • Uses rand() % 256 to generate RGB components in the range 0-255
• create_base_shape(): generic shape creation function, can create squares and circles by adjusting the corner radius
  • Creates an LVGL object with specified size, removes default styles, sets background color, opacity, removes border
  • Controls the corner radius via the radius_val parameter (0 = square, LV_RADIUS_CIRCLE = circle)

Operation Result

• LCD Screen Display

  

03_Animated_Eye1

Example Description

• This example is a dual-screen synchronous animated eye program based on the LVGL graphics library. It implements real-time rendering and motion logic for "human-like eyes" — both LCD screens synchronously display realistic eyes, and the pupils move smoothly toward random targets, simulating a "natural scanning" eye movement.

Hardware Connection

• Connect the development board to the computer.

Code Analysis

• Animated_Eye1() program entry, initializes and starts the eye animation, creates a timer to update the eye animation effects
  • Uses a fixed random seed srand(12345) to ensure reproducible random behavior
  • Creates an animation timer with a 50 ms interval lv_timer_create(eye_anim_timer, 50, NULL)
• draw_eye() core eye drawing function, draws the parts of the eye layer by layer (from outside to inside) to give the eye a realistic appearance
  • Calculates the fixed center coordinates and radius of the sclera (white of the eye) (applies SCALE_FACTOR=1.5 scaling)
  • Calculates the actual iris coordinates based on the pupil position, restricts within MAX_OFFSET_RATIO=0.3
  • Calculates pupil offset: extra offset PUPIL_OFFSET=6 pixels along the iris movement direction
  • Layer drawing: sclera, iris, pupil, highlight
• eye_anim_timer(): timer callback function, responsible for "update target position → calculate new pupil position → dual-screen sync → redraw eyes" to achieve animation effects

Operation Result

• LCD Screen Display

  

04_SD_gif_show

Example Description

• This example scans GIF images in the root directory of the TF card and plays them synchronously on both LCD screens. The BOOT button can be used to switch GIF images, testing TF card reading and LCD screen image display.

Hardware Connection

• Copy the GIF images from this project directory to the root directory of the TF card (paths and names can be modified as needed; note that the GIF frame rate should be low, otherwise playback may be choppy)
• Note: Connect the TF card. If recognition fails, format the TF card as FAT32 (if it fails initially, wait a while and then reset to check again)
• Connect the development board to the computer.

Code Analysis

• Lvgl_Eyes() main initialization function, creates dual-screen GIF eye display
  • Initializes the FAT file system lv_fs_fatfs_init() for TF card access
  • Calls find_gif_files() to scan GIF files in the TF card root directory
  • Creates GIF display objects on both screens and calls load_current_gif() to load and play the first GIF file
• eyes_next_gif() switches to the next GIF image
  • Cycles increment current_gif_index (wraps to first after reaching the end)

Operation Result

• LCD Screen Display

  

• Press the BOOT button to switch to the next GIF image

05_Clock

Example Description

• This example implements a clock function synchronously displayed on two screens based on the LVGL framework, including an analog clock (with hands and tick marks) and digital time display.

Hardware Connection

• Connect the development board to the computer.

Code Analysis

• Clock() main program entry, initializes the clocks on both LCD screens, sets the initial state, and starts a timer for dynamic updates
  • Calls create_clock_elements() for each screen to create the clock canvas and time label
  • Gets the current time and calculates initial hand angles
• get_current_time() time retrieval and processing, obtains the current time from the system
• draw_clock_ticks() draws the clock ticks, draws 12 ticks on the clock canvas, where the 3, 6, 9, and 12 o'clock positions are longer and wider major ticks, and the others are minor ticks
• draw_clock() complete clock drawing, integrates tick and hand drawing to generate a full analog clock face
  • Calls draw_hand() to draw the three hands

Operation Result

• LCD Screen Display

  

06_music_player

Example Description

• This example demonstrates the functionality of the onboard devices. Screen 2 displays parameters such as TF Card and Flash Size, while Screen 1 is the music playback interface. Additionally, this example adds speech recognition functionality.

Hardware Connection

• Insert the TF card into the development board
• Connect the development board to the computer.

Code Analysis

• Driver_Init() initializes hardware, drivers, and system resources, and creates a task to loop through hardware driver operations
  • Hardware initialization: Driver_Init() initializes multiple hardware modules such as I2C bus, sensors, etc.
  • Modular Design: The initialization function distributes hardware initialization across different modules, making it easy to maintain and extend. If new hardware needs support, simply add the initialization code here.
• Lvgl_Example1() displays the screen UI

Operation Result

• LCD Screen Display

• LCD Screen Display Parameter Description

  Parameter	Function	Description
  SD Card	Displays the TF card size	Connect 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 Size	Displays the Flash size	Onboard 16MB Flash
  Battery Voltage	Battery voltage	Battery voltage can be detected when a battery is connected
  Wireless scan	Displays the number of Wi-Fi networks scanned	"..OK" will be displayed at the end of the scan
  Backlight brightness	Brightness slider	Adjusts 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 MIC test audio formats are provided below (Note: if the "hi esp" wake-up fails, please reposition the audio to the point where the wake word is played and try again)

• 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

    // Commands
    Turn on the backlight
    Turn off the backlight
    Backlight is brightest
    Backlight is darkest

• Note: In this example, speech recognition is only available before playing audio.

  

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 the English recognition model
  • Switch to Chinese/English Recognition Model
    • If the following two files exist in the project, delete them
      
    • Go to the file sdkconfig.defaults and locate this section
      
      • Comment out ① with "#" to switch to the English recognition model
      • Comment out ② with "#" to switch to the Chinese recognition model

Generating Voice Control Commands

Environment Preparation

• Check if Python is installed on the computer
• Open the command line: Win+R -> enter cmd
  
  • ①. Enter python --version. If a Python version number appears, it means it is installed
  • ②. Enter where python to view the Python installation location
  • The Python environment under the C drive is the one automatically installed when VS Code was installed
  • The environment under the E drive is the Python environment used for the following steps

warning

If the environment is not installed, please refer to Python Environment Installation Tutorial. If already installed, please continue.

• Enter pip install g2p_en at the command line to install the g2p_en package
• Install the resource package and place it in the corresponding user's C:\Users\username\AppData\Roaming path. Double-click to extract the file
• Enter pip install pypinyin at the command line to install the pypinyin library

Generating Chinese Pinyin

• Download the Chinese command generation file
• Switch the command line path to the Chinese command generation folder (the path varies by user; the following is for reference only)

  cd /d E:\download\Generate_Chinese_command

• Execute multinet_pinyin.py at the command line to generate Chinese Pinyin

  python multinet_pinyin.py "要转为拼音的中文"

  Example:

  python multinet_pinyin.py "你好微雪电子"

  

Generating English Phonemes

• Download the English command generation file
• Switch the command line path to the English command generation folder (the path varies by user; the following is for reference only)

  cd /d E:\download\Generate_English_command

• Execute gen_sr_commands.py at the command line to generate phoneme commands

  python gen_sr_commands.py "English text to convert to phonemes"

  Example:

  python gen_sr_commands.py "hello waveshare"

  

Modifying Commands

• Under Arduino
  
• Under ESP-IDF
  • Chinese Commands
    
  • English Commands