English

简体中文

English

简体中文

Appearance

1. IDF Environment Installation ​

1.1 Introduction to ESP-IDF ​

ESP-IDF (Espressif IoT Development Framework) is the official open-source development framework provided by Espressif for the ESP32 series, used to develop IoT applications. ESP-IDF is characterized by its high degree of integration and portability, providing a complete SDK. Developers can use ESP-IDF libraries, components, and APIs for development. The features supported by ESP-IDF include the FreeRTOS multitasking operating system, low-power modes, Wi-Fi, Bluetooth, TCP/IP protocol stack, SSL/TLS security protocols, OTA upgrades, and more.

1.2 Installing VSCode ​

VSCode (Visual Studio Code) is a free, open-source code editor from Microsoft. It supports Windows, Linux, and macOS, and includes features such as smart code completion, automatic indentation, syntax highlighting, and code snippets. It also supports multiple programming languages, debugging, and version control tools. It can also be extended through plugins into a powerful development environment, supporting various popular programming languages and frameworks. VSCode has a simple and clear interface, strong extensibility, and you can easily modify the layout and add the plugins you need. It is a powerful, easy-to-use, and free code editor. We will set up the ESP-IDF environment in VSCode for code editing, downloading, and debugging.

1.2.1 Downloading VSCode ​

Open the VSCode official website and select the corresponding system and architecture to download.

Here we take 64-bit Windows 10 as an example. Click [Windows] to download.

After clicking, the download will start automatically.

1.2.2 Installing VSCode ​

  1. Accept the agreement
  1. Set the installation path Here I install it in a custom location. I created a new folder named VSCode on drive D.
  1. Set up shortcuts
  1. Set additional tasks
  1. Ready to install
  1. Installing
  1. Installation completed.

1.3 Installing the IDF Environment ​

There are two ways to install the ESP-IDF environment in VSCode: offline installation and online installation. They differ in the following ways:

  • Offline installation of the ESP-IDF environment: a. Download the complete ESP-IDF source code package, including all toolchains and components. b. It can be installed and used without a network connection, so you do not need to worry about network issues.
  • Online installation of the ESP-IDF environment: a. Use the ESP-IDF extension in VSCode. The extension automatically downloads and installs the required toolchains and components on first use. b. The installation process is relatively simple, with no need to manually configure environment variables and paths. c. You can always get the latest version of ESP-IDF from the network. d. You can quickly upgrade the corresponding toolchains and components. Overall, offline installation requires downloading the complete source code package and is suitable for environments without network or with restricted network access; online installation is done through the ESP-IDF extension in VSCode, which is convenient and fast, but requires a network connection and timely access to the latest version. Offline installation is recommended. For online installation, the Python download and installation step takes some time, because the domestic network download is slow and download failures may occur.

1.3.1 Offline Installation of the IDF Environment ​

Offline installation steps:

1.3.1.1 ESP-IDF Download ​

IDF offline download URL: https://dl.espressif.cn/dl/esp-idf/

1.3.1.2 IDF Offline Installation ​

VSCode must be closed during installation.

In the figure below, I created a new folder named ESP_IDF on drive D, which will be used to store ESP-IDF files.

Uncheck the development integration, leave others as default.

During installation, a prompt box will pop up asking whether to install the driver. Just choose to install or agree.

1.3.1.3 Installing the IDF Plugin ​

Open VSCode. In the VSCode Extensions pane, search for "espressif" and you can see that the IDF plugin has been installed. If it still shows Install, just click Install.

After the plugin is installed, open View - Command Palette (shortcut Ctrl+Shift+P). Type configure esp-idf extension and click it.

It will recognize our offline-installed IDF. Click it.

Then, in the options that pop up, select the last item. Use the existing setup. The plugin will automatically detect and recognize the location of the environment in the system. In the figure below, the first two methods are both online installations, which will be slow or simply fail to install if the network is poor. Because we have already set up the environment using the offline package, just select USE EXISTING SETUP.

Select to find ESP-IDF in the system.

If it can find the ESP-IDF path in the system, it will install automatically. Just wait for the installation to succeed.

If it cannot find the path, the following window will pop up, and you need to set the path yourself. The path you set is the path where we previously installed ESP-IDF offline.

Wait for the installation to complete.

Installation completed.

1.3.2 Online Installation of the IDF Environment ​

When the online installation reaches the Python download and installation step, it will take some time. Due to the domestic network, the failure rate is high. Offline installation is recommended.

1.3.2.1 ESP-IDF Plugin Installation ​

Note: The latest version of the plugin is V1.6.0. For a consistent experience, users can choose the same version as ours.

  1. Open VSCode, use the shortcut Shift+Ctrl+X to enter the Extensions manager.
  1. In the search bar, type "Espressif IDF", select the corresponding plugin, and click install.
  1. Use the shortcut F1 and type
c
esp-idf: configure esp-idf extension
  1. Select express (this tutorial is for first-time installers, so only the general initial installation tutorial is covered)
  1. After opening, this interface is displayed

If the above interface does not appear and the following interface appears instead, please uninstall the Espressif IDF plugin and install it again.

  1. Select the download server. We recommend that domestic users use Espressif as the download server.
  1. Select the desired ESP-IDF version. We select the latest V5.0.1 (note that ESP-IDF only started supporting ESP32-S3 from version V4.4).
  1. The following two are the ESP-IDF container installation address and the ESP-IDF tools installation address.
  • Note: If you have installed ESP-IDF before, or have failed before, please make sure to completely delete the files or create a brand-new path without Chinese characters.
  1. After configuration, click install to download.
  1. Enter the download page. It will automatically install the corresponding tools and environment. Just wait a moment.
  1. After the installation is complete, you will enter the following interface, indicating that the installation is complete.

1.4 Switching the Display Language ​

VSCode supports installing multiple language packs and provides a function to switch between installed language packs.

  1. Open the View menu, and open the Command Palette with the (Ctrl+Shift+P) shortcut.

In the Command Palette, type Configure Display Language, select the Configure Display Language command, and the list of installed language packs will be displayed.

Select the desired language pack from the list of installed language packs. (Here I have already downloaded Simplified Chinese.)

Follow the prompts to restart VSCode to complete the switch.

1.5 Create a New Project and Test ​

Open the command bar. In the top selection bar of the interface, select [View] -> [Command Palette], or you can enter the command bar through the F1 shortcut.

In the command bar, type [ESP-IDF: New Project].

Note! Only the input box with an arrow ">" is the command bar. If there is no arrow, it may be the search bar.

Wait for the loading to complete. (If a web loading error pops up, you need to reopen VSCode.)

On the new project page, configure the project name, project path, ESP32 chip, connection port (can be changed later), ESP32 core path, etc.

  1. Here I named the project [01_led].
  1. Select the creation and save path of the project. (I created a folder named ESPIDF_project on drive E. I will put all subsequent ESP32 project files in this folder. You can choose an appropriate path according to your own situation, and you don't have to follow our way.)

WARNING

📌 Note that Chinese characters cannot be used in the path!

  1. In the ESP32 chip or development board (Choose ESP-IDF Board) option, select the ESP32-S3 chip (via ESP USB Bridge) option.

    It is not necessarily (via ESP USB Bridge). As long as it is ESP32-S3, it's fine, because it can still be modified during compilation later.

  1. Download communication port (if you haven't connected the development board to the computer yet, you can ignore this).
  1. The project core directory can be left unset for now.

The final project creation configuration is shown in the figure below.

Click [Choose Template] to create from a template.

In the pop-up interface, there are two options to choose from: use the extension examples (Extension) or use the official IDF examples (ESP-IDF).

Select [template-app] under [Extension] to create the project. (There are many other examples, you can try them yourself.)

Click [Create project using template hello_world] to create the project.

After the creation is complete, the lower right corner will prompt [The project has been created. Do you want to open it in a new window?]. Click Yes to open a new VSCode window, or click NO to display the project in the current interface.

In the newly created project, find main.c and write the following code for testing.

c
#include <stdio.h>

void app_main(void)
{
  printf("www.lckfb.com");
}

Click the build button and wait for the build to complete.

The first build will take a relatively long time. Here is an introduction to the commonly used buttons.

After the build is complete, it is displayed as follows:

To ensure a successful download, you need to reselect the download port, chip, and download method. (The following is an animated GIF.)

Click the one-click build-download-debug button. Wait for the build and download to complete.

Downloading.

Download completed and the code we wrote outputs www.LCKFB.com. The test is successful.

1.6 Modify Project Configuration ​

When the connection is successful, click the settings button.

Modify the FLASH size In the search bar above, type [flash], and select the corresponding FLASH size according to the onboard FLASH size of the development board. The onboard W25Q64 of the development board is 8 MB.

Modify the system clock In the search bar above, type [cpu], and select the CPU frequency according to your needs. Here we select the maximum frequency of 240 MHz.

After modification, click the [Save] button to take effect.