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

Version Compatibility Note

The ESP32-S3-Touch-AMOLED-1.64 comes in V1 and V1.1 versions, and the example programs for the two versions are not interchangeable. Please first confirm the development board PCB version, then use the corresponding example program, and select the ESP-IDF version according to the instructions in the example project.

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 example programs are located in the ESP-IDF directory of the corresponding package:

• V1 Example
• V1.1 Example

Example	Basic Description	Dependency Library
01_ADC_Test	Read the current system voltage value	-
02_I2C_QMI8658	Print the raw data from the IMU	-
03_SD_Card	Load and display TF card information	-
04_WIFI_AP	Set to AP mode, can obtain the MAC address of connected devices	-
05_WIFI_STA	Set to STA mode to connect to Wi-Fi and obtain an IP address	-
06_LVGL_Test	LVGL example	LVGL
07_FactoryProgram	Comprehensive project	LVGL

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.

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 flashing the program, open the monitor to see the output of ADC values and voltage, as shown below:

• The ADC sampling value is around 1960, and the system voltage is about 4.92V. 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

---

After the example is flashed, the running result of the device is as follows:

• Open the serial monitor to see the raw data from the IMU (Euler angles need to be converted separately), as shown below:

• Data is output every 1 second. If you need to modify or reference the code, you can directly edit the qmi source files.

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.c source file, find the SD_Read_Mode 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:

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 softap_example_main.c file, find the SSID and PASSWORD definitions. Phones or other STA-mode devices can use this SSID and password to connect to the development board.

  #define EXAMPLE_ESP_WIFI_SSID      "waveshare_esp32"
  #define EXAMPLE_ESP_WIFI_PASSWORD      "wav123456"

Expected Behavior

---

After flashing the program, open the serial terminal, if the device is successfully connected to the hotspot, the MAC address and IP address of the device will be output, as shown in the figure:

05_WIFI_STA

Example Description

• This example configures the development board as a STA device to connect to a router, thereby accessing the system network.

Hardware Connection

---

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

Code Analysis

---

• In the esp_wifi_bsp.c file, find the ssid and password definitions and modify them to match the SSID and password of an available router in your environment.

  wifi_config_t wifi_config = {
        .sta = {
          .ssid = "PDCN",
          .password = "1234567890",
        },
    };

Expected Behavior

---

After flashing the program, open the serial terminal, if the device is successfully connected to the hotspot, the IP address obtained will be output, as shown in the figure:

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

• The display chip itself does not support hardware rotation. If rotation is needed, it can be implemented in software. In the main.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

---

• After the program is flashed, the device operation result is as follows:

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

07_FactoryProgram

Example Description

---

• A comprehensive project that tests onboard features. Note that for this example, IDF version matters. Versions V5.2.0 and above may not be able to scan for nearby Wi-Fi. If you need to test this, you can use a lower version for compilation or use the BIN firmware provided by us.

Hardware Connection

---

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

Expected Behavior

---

• Swipe left or right to switch pages. First, RGB colors are displayed every 1.5 seconds, which allows you to check if the screen is working properly.

• After displaying RGB, it will automatically jump to the clock interface.

• Swipe left to see the page with onboard hardware information.

• Swipe left again to see the function interface.

• Click the Wi-Fi icon to enter the Wi-Fi test interface, then click the Scan button to scan for nearby Wi-Fi networks.

• Click "Exit" to return to the previous interface, then click the BLE icon to enter the BLE test interface, and click the Scan button to scan for nearby BLE devices.