Working with ESP-IDF

This chapter includes the following sections, please read as needed:

• ESP-IDF Getting Started
• Setting Up the 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 the Development Environment

Please refer to Install ESP-IDF Development Environment.

Version Note

The ESP32-C5-Touch-LCD-2.8 examples require ESP-IDF v5.5.4.

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.

Version Selection

The screenshots in this section use ESP-IDF V5.5.2 as an example. When installing, please select the ESP-IDF version that matches your board's example.

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 the ESP-IDF version you need (the version shown in the screenshot is for reference only — choose the version that fits your actual needs).

   

   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 examples are located in the example/ESP-IDF-V554 directory of the example package. Each example project has been adapted to the onboard hardware resources of the ESP32-C5-Touch-LCD-2.8 and can be used to verify display, touch, audio, TF card, Wi‑Fi, sensors, and GUI functionality.

Building and Flashing

Navigate to any ESP-IDF example directory and run:

cd example/ESP-IDF-V554/02_2048
idf.py build flash monitor

If you need to specify a serial port, replace COMx with the actual port, for example COM5:

idf.py -p COMx build flash monitor

Example List

Example Directory	Description
01_ch32_test	CH32V003 I/O expander test, verifies output toggling and input reading
02_2048	2048 game based on LVGL v9, supports touch interaction, score tracking, and game result prompts
03_sd_lvgl	Mounts a TF card, reads the Test.txt file from the root directory, and displays the content on the LCD
04_sd_music	Scans MP3 files from the /sdcard/music directory on the TF card and automatically plays the first one
05_spiff_music	Reads MP3 files from the SPIFFS /music directory and implements a music player with an LVGL interface
06_wifi_weather	Connects to a specified Wi‑Fi network, retrieves real‑time weather data for Shenzhen, and displays it on the screen
07_Ball_qmi	Reads QMI8658 accelerometer data and implements a gravity ball that moves with the board's tilt
08_bookesia	Implements a touch drawing board application using the ESP‑Brookesia framework, with a status bar and memory info

Usage Notes

• For secondary development, we recommend modifying the application layer or UI logic first. The BSP already provides initialization and low‑level interface definitions for the board's basic hardware resources. Routine UI, interaction, and business logic changes typically do not require BSP modifications. Only modify the BSP if you change hardware connections, adapt low‑level drivers, or add new peripherals.
• 01_ch32_test tests the onboard CH32V003 I/O expander. CH32V003 is pre‑programmed at the factory and does not require separate CH32 firmware flashing. Running this ESP32-C5 example is sufficient to verify I/O expander communication and control.
• The UI for 02_2048 is generated with GUI Guider. The layout is mainly in components/generated/setup_scr_Game2048.c, event functions are in components/generated/events_init.c, and custom initialization and extension logic are in components/custom/custom.c.
• Before running 03_sd_lvgl, place a Test.txt file in the root directory of the TF card.
• Before running 04_sd_music, create a music folder in the root directory of the TF card and place .mp3 files inside.
• 05_spiff_music uses MP3 files stored in SPIFFS and is suitable for implementing a music player with an LVGL interface.
• 06_wifi_weather connects to the weather-wifi hotspot by default, password 12345678, supporting both 2.4 GHz and 5 GHz bands. To change the hotspot or city, adjust the corresponding configuration in the example source code.
• For 07_Ball_qmi, keep the board flat and stationary during calibration to avoid noticeable ball drift.
• 08_bookesia uses the ESP‑Brookesia framework and serves as a reference for secondary development involving touch GUI, multi‑app interfaces, and drawing board functionality.

01_ch32_test

Example Description

• This example verifies the onboard CH32V003 I/O expander.
• The program initializes the I2C bus and CH32V003 I/O expander, then tests output and input reading functions.
• It first configures IO_EXP_PIN_0 through IO_EXP_PIN_7 as outputs and toggles them high/low cyclically, then switches to input mode and reads the input states.

Hardware Connection

• Connect the board to your computer via USB.
• This example uses only the onboard CH32V003 I/O expander and does not require external modules.

Running Effect

• Serial output shows I2C initialization, I/O expander initialization, output level toggling, and input level reading results.
• If I/O expander communication is normal, you will see successful configuration, output, and reading logs for IO_EXP_PIN_0~7.

02_2048

Example Description

• This example implements the 2048 game using LVGL v9.
• The UI is generated with GUI Guider. The main.c in the project calls setup_ui(), custom_init() and events_init() in sequence to create the UI, perform custom initialization, and bind events.
• The screen displays a 4×4 grid, current score, highest score, and a restart button.
• Supports swipe gestures for tile movement; matching numbers are merged and the score is updated accordingly.
• A victory prompt is shown when 2048 is reached, and a game‑over prompt when no moves remain.
• For secondary development, refer to components/generated/setup_scr_Game2048.c for the 2048 page layout, components/generated/events_init.c for touch and button event logic, and components/custom/custom.c for custom initialization and business extension logic.

Hardware Connection

• Connect the board to your computer via USB.
• This example uses the onboard LCD and capacitive touchscreen and does not require external modules.

Running Effect

• The LCD displays the 2048 game interface.
• Swipe on the touchscreen to control tile movement and see real‑time score updates and game results.

03_sd_lvgl

Example Description

• This example demonstrates TF card file reading and LVGL display.
• After startup, the program initializes the LCD and LVGL UI, then mounts the TF card.
• It reads the Test.txt file from the root directory of the TF card and displays its content on the LCD.
• If the TF card is not detected or file reading fails, the screen shows an appropriate error message.

Hardware Connection

• Connect the board to your computer via USB.
• Insert a FAT32‑formatted TF card into the slot.
• Place a Test.txt file in the root directory of the TF card.

Running Effect

• The LCD initially shows Waiting for SD card....
• After a successful read, the screen displays the text content from Test.txt.
• If no TF card is detected, it shows SD card not detected!.

04_sd_music

Example Description

• This example verifies MP3 audio playback from a TF card.
• The program initializes the onboard I/O expander, mounts the TF card, and scans for .mp3 files in the /sdcard/music directory.
• After detecting music files, it initializes the audio driver and amplifier, and automatically plays the first MP3.
• This example primarily tests the TF card reading, audio codec, amplifier, and speaker playback chain.

Hardware Connection

• Connect the board to your computer via USB.
• Insert a FAT32‑formatted TF card into the slot.
• Create a music folder in the root directory of the TF card and place .mp3 audio files inside.
• Connect a speaker to the onboard Speaker interface.

Running Effect

• Serial output shows the list of scanned MP3 files.
• The program automatically plays the first MP3 file found.
• If TF card mounting fails or no MP3 files are found, serial output shows an error message.

05_spiff_music

Example Description

• This example implements a music player UI using SPIFFS and LVGL v9.
• The program mounts the SPIFFS file system and scans for .mp3 files in the /spiffs/music directory.
• The screen displays album art and playback control buttons.
• When the play button is pressed, the program plays the first MP3 and the album art rotates continuously.
• Pressing the button again pauses playback; the rotation stops and resumes from the paused angle when playback continues.
• After playback finishes, the program automatically stops the animation and resets the play button state.

Hardware Connection

• Connect the board to your computer via USB.
• Connect a speaker to the onboard Speaker interface.
• The MP3 files must be pre‑packaged into the SPIFFS music directory.

Running Effect

• The LCD displays the music player interface.
• Click the play button to start playback and see the rotating album art animation.
• Supports play, pause, and playback‑end state recovery.

06_wifi_weather

Example Description

• This example demonstrates Wi‑Fi connectivity and weather data display.
• The program connects to a fixed Wi‑Fi hotspot and retrieves real‑time weather data for Shenzhen via HTTP request.
• The screen displays city, date, weather status, temperature, humidity, wind speed, and wind direction.
• Supports automatic Wi‑Fi reconnection on disconnection.
• Weather data refreshes periodically, approximately every 5 minutes after a successful fetch.

Default Wi‑Fi Configuration

Item	Default Value
Wi-Fi SSID	weather-wifi
Wi-Fi Password	12345678
Wi-Fi Band	2.4 GHz or 5 GHz
Weather City	Shenzhen
Request Server	cn.apihz.cn

Hardware Connection

• Before powering on, turn on a Wi‑Fi hotspot that matches the example configuration.
• Connect the board to your computer via USB and power it on.
• The hotspot can use either 2.4 GHz or 5 GHz band, but the SSID and password must match the example, and the hotspot must have internet access.
• This example uses the onboard LCD and Wi‑Fi, and does not require external modules.

Running Effect

• After connecting to Wi‑Fi, the screen displays Shenzhen weather information.
• If the hotspot is not available or network access fails, the program will keep retrying connection and requests.

07_Ball_qmi

Example Description

• This example demonstrates QMI8658 accelerometer interaction with LVGL.
• The program initializes QMI8658 with 8G range and 500 Hz output data rate.
• After startup, it performs a level calibration to eliminate offset in the stationary state.
• After calibration, a ball appears at the center of the screen and moves in real time according to the board's tilt direction.
• The ball's movement is constrained to stay within the screen boundaries and rounded corner area.

Hardware Connection

• Connect the board to your computer via USB.
• This example uses the onboard LCD and QMI8658 six‑axis sensor and does not require external modules.
• Place the board flat on a stable desk during calibration.

Running Effect

• The screen shows a green ball.
• When you tilt the board, the ball moves in the direction of gravity.
• Serial output shows calibration status and sensor‑related logs.

08_bookesia

Example Description

• This example implements a phone‑style GUI using the ESP‑Brookesia framework.
• It uses a 240×320 dark theme with a status bar, app manager, and touch interaction.
• The example installs system default apps and additionally installs a Drawing Board app.
• The Drawing Board app supports freehand drawing on the capacitive touchscreen.
• The status bar clock refreshes every second.
• The recent tasks view periodically displays SRAM and PSRAM usage.

Hardware Connection

• Connect the board to your computer via USB.
• This example uses the onboard LCD and capacitive touchscreen and does not require external modules.

Running Effect

• The LCD displays the ESP‑Brookesia style interface.
• You can enter the Drawing Board app via touch and start drawing.
• The system interface supports status bar, recent tasks, and memory information display.