ESP-IDF

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

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

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-LCD-1.9 development board, ESP-IDF version V5.5.0 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.

Demo

The ESP-IDF demos are located in the ESP-IDF directory of the demo package.

Demo	Basic Program 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_WS2812_Test	Drive WS2812RGB LEDs
05_WIFI_AP	Set to AP mode to obtain the IP address of the access device	-
06_WIFI_STA	Set to STA mode to connect to WiFi and obtain an IP address	-
07_LVGL_Test	LVGL demo	LVGL
08_FactoryProgram	Comprehensive demo	LVGL

01_ADC_Test

Demo 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. This task reads the ADC value every second and calculates the system voltage from the raw ADC reading.

Operation Result

• After the program is compiled and downloaded, you can view the printed ADC values and voltage output by opening the Serial Monitor, as shown in the following image:

  

02_I2C_QMI8658

Demo Description

• Initialize the QMI8658 chip via the I2C protocol, then read the corresponding attitude information every 1 second and print it to the terminal.

Hardware Connection

• Connect the board to the computer using a USB cable

Code Analysis

• qmi8658c_example(void* parameter): This function initializes the QMI8658 device. In an infinite loop, it reads and prints accelerometer, gyroscope, and temperature data every 1 second. As the board rotates faster, the gyroscope data increases accordingly. The accelerometer calculates the corresponding acceleration based on its current orientation.

Operation Result

• Open the serial monitor to view the raw data output from the IMU (Euler angles require conversion), as shown in the figure below:

  

03_SD_Card

Demo Description

• Drive the TF card using SDMMC. After successfully mounting the TF card, print the TF card information to the terminal and read/write data to the writeTest.txt file every 1 second.

Hardware Connection

• Connect the board to the computer using a USB cable

Code Analysis

• In the user_app.c file, find the #define sdcard_write_Test line and uncomment it to test the TF card read/write function.

  //#define sdcard_write_Test

Operation Result

• 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:

  

04_WS2812_Test

Demo Description

• Drive the WS2812 RGB LEDs to create a flowing rainbow effect. This example is only applicable to the ESP32-S3-LCD-1.9.

Hardware Connection

• Connect the board to the computer using a USB cable

Code Analysis

• First, analyze the macro definitions in the ws2812_bsp.h file:

  #define LEDS_COUNT  2 // Number of WS2812-RGB LED beads
  #define LEDS_PIN    15 //WS2812-GPIO control pin

• Analyze the main functions:

  void ws2812_Init(void); //Initialize ws2812
  uint32_t ws2812_Wheel(uint8_t pos); //Convert 0-255 colors to standard 24-bit RGB color values
  void ws2812_set_pixel(uint8_t id,uint8_t r,uint8_t g,uint8_t b); //Push the r, g, and b color values to the corresponding WS2812

Operation Result

• The actual effect is as follows:

05_WIFI_AP

Demo Description

• This demo 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

Code Analysis

• In the file softap_example_main.c, find SSID and PASSWORD, and then your phone or other device in STA mode can use the SSID and PASSWORD to connect to the development board.

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

Operation Result

• After flashing the program, open the Serial Terminal. If a device successfully connects to the hotspot, the MAC address of that device will be output, as shown:

  

06_WIFI_STA

Demo Description

• This example can configure the development board as a STA device to connect to a router, thereby enabling access to the system network.

Hardware Connection

• Connect the board to the computer using a USB cable

Code Analysis

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

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

Operation Result

• 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:

  

07_LVGL_Test

Demo Description

• Implements various multifunctional GUI interfaces on the screen by porting LVGL V8.

Hardware Connection

• Connect the board to the computer using a USB cable

Code Analysis

• If you need to rotate the display by 90 degrees, you can find the Direction macro definition in the main.c file and choose one of the two.

  #define Rotate 1    //Rotation 90
  #define Normal 0    //Normal
  #define Direction   Normal

• For compatibility with the ESP32-S3-LCD-1.9, touch is disabled by default in this example. To enable touch, locate the EXAMPLE_USE_TOUCH macro definition in main.c and set it to 1.

  #define EXAMPLE_USE_TOUCH  0

Operation Result

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

  

08_FactoryProgram

Demo Description

• This is a comprehensive project for testing onboard functions. This example requires a specific IDF version, and versions V5.5.0 and above may not be able to scan for surrounding WiFi. If the test fails due to a high version, you can compile using a lower version or directly use the BIN firmware we provide.

Hardware Connection

• Connect the board to the computer using a USB cable

Code Analysis

• ESP32-S3-LCD-1.9 switches the pages by clicking the BOOT button, double click to turn on/off the backlight, and long press to test the TF card read/write; ESP32-S3-Touch-LCD-1.9 can be controlled through the BOOT button or Touch.

Operation Result

• The program flashing is complete, wait for the primary colors (RGB) display, as shown in the figure:

  

• After the RGB is displayed, it will automatically switch to the clock interface,as shown below:

  

• Single-click the BOOT button to switch pages. The page displays some onboard hardware information, as shown in the figure: