Getting Started with ESP-IDF in VSCode

In the ESP32 development environment setup, people often prefer using VSCode (Visual Studio Code) and directly configure it with the Espressif IDF (ESP-IDF) plugin. While this method is straightforward, it has some drawbacks, mainly in terms of inconvenient environment maintenance and difficulty in switching ESP-IDF versions.

This article introduces a method called “ESP-IDF + VSCode” for development, successfully separating ESP-IDF tools from the compilation tools, making environment maintenance more convenient. With this method, we can maintain ESP-IDF tools separately and easily switch versions using Git. Additionally, we can still use VSCode as the editor, ensuring convenience in code writing.

Downloading Development Tools

  1. Downloading Tools
					mkdir -p ~/esp
cd ~/esp
git clone --recursive

  1. Download and install VSCode.
  2. Search and install ESP-IDF in VSCode.

Configuring ESP-IDF

  1. Configure plugin
					cd ~/esp/esp-idf
  1. Setting environment variables
					cd ~/esp/esp-idf
  1. Each time you open a new terminal window, you need to manually execute the command to set the ESP-IDF environment variables. To simplify this process, you can add an alias command to the ~/.bashrc file: alias get_idf=’. $HOME/esp/esp-idf/’, so you only need to run the get_idf command to automatically set the ESP-IDF environment variables for that terminal.
Configure IDF tools

Creating a Project

  1. Create a project using IDF tools

Create a project using IDF tools

  1. After entering the project directory, set the current project device to ESP32 by running the command set-target esp32.

Set the current project device to ESP32

  1. Open for editing using VSCode.

Open for editing using vscode

VSCode Configuration Issues


By default, when opening a project created using ESP-IDF in VSCode, you may encounter some problems, such as being unable to find corresponding files after adding them and being unable to navigate to the corresponding files. These issues are usually caused by incomplete VSCode configurations.

VSCode configuration issues


  1. Reinstall ESP-IDF and rerun the script in the directory, which configures the plugin.
					cd ~/esp/esp-idf
  1. Ensure that VSCode opens the target project path instead of a path containing multiple projects.
  2. In the search bar, find ESP-IDF:Add vscode configuration folder, click to generate the corresponding VSCode configuration files.
  3. In the generated configuration file, check c_cpp_properties.json to ensure that the header file paths are correctly set.
Correct header file path


Component Description

In ESP32 development, we typically want to split programs into separate .c files according to their functions, making it easier to edit, manage, and port. For example, a GPIO driver can be implemented in a separate drv_gpio.c file. However, unlike in some IDEs where this is automated, VSCode is just a code editor, and compilation is done using the CMake tool. Therefore, we need to adapt the relevant CMake files to achieve this functionality.

ESP32 components can be divided into several categories, recorded in the CMake variable COMPONENT_DIRS:

  • Internal ESP-IDF components: stored in IDF_PATH/components, which are the components provided by the official.
  • Extension components: stored in additional directories specified by EXTRA_COMPONENT_DIRS.
  • Project components: stored in the components directory under the project directory, which does not exist by default and needs to be created manually.

It’s important to note that the names of different components cannot be the same, otherwise, there will be overwriting. The compilation order of components is: Internal ESP-IDF components -> Extension components -> Project components. Components compiled later will override components with the same name compiled earlier. This characteristic also allows components to be copied to the project directory and modified to override ESP-IDF components. If this approach is taken, the ESP-IDF directory itself can remain unchanged.

Adding Project Components

To add project components, first, create a directory named components in the project’s root directory. Then, you can choose one of the following two methods to create components:

Method 1: Use IDF commands to create components

Use the following command to create components:

 -C <component set directory address> create-component <component name>

Method 2: Manually create components

  1. Create a new directory under the components directory, named after your component.
  2. Create your source files within the component directory.
  3. You can copy the CMakeLists.txt file from other components and modify it appropriately to suit your component.

Finally, write the program code required for the component, and after creating the component, clean the project: clean and rebuild: build.

Compiled successfully

Adding Extension Components

  1. First, create a directory to store the component set in the project’s root directory. For example, you can create a directory named user.
  2. Within the newly created component set directory, create a new directory to store your component. For example, create a directory named gpio within the user directory.
  3. You can choose to copy the CMakeLists.txt file from other components.

Copy CMakeLists.txt of other components

  1. Make necessary modifications in the CMakeLists.txt file as required.

Modify the CMakeLists.txt file

  1. Add the EXTRA_COMPONENT_DIRS directive in the top-level CMakeLists.txt file of the project, specifying the directory of the component set you just created. Please note that this addition should be made before the project() directive.


  1. Write corresponding drv_gpio.c and drv_gpio.h, and include them in main.c, then compile and test.

Compile the file and test

Errors when Referring to ESP-IDF Functions and Headers within Components

Once we’ve created a standalone component, such as the GPIO component, we’ll proceed to write the corresponding GPIO driver program within that component. While writing the driver program, we typically need to use other components from ESP-IDF. However, during compilation, you may encounter errors indicating that the corresponding files cannot be found.

Our driver program looks like this:


Error during compilation: ../user/gpio/drv_gpio.c:2:10: fatal error: driver/gpio.h: No such file or directory

The problem usually arises when dependencies are not resolved correctly, such as when the drv_gpio.c file we wrote does not specify its dependencies. This causes the compiler to be unable to find the required driver/gpio.h file, resulting in an error. To resolve this issue, we need to add the drv_gpio.c file to the COMPONENT_SRCS in the CMakeLists.txt file and explicitly list its dependencies using the REQUIRES directive, for example, REQUIRES driver.

Add dependencies

For this issue, some people might wonder why similar errors don’t occur when writing code within the default main component. This is because the main component is a special component, and by default, all dependencies are added to it in the project’s $ENV{IDF_PATH}/tools/cmake/project.cmake file.

You Might Be Interested

esp32 connect to wifi
Connecting ESP32 to WiFi in 4 Steps

Unlock the potential of your ESP32 with these 4 simple steps to WiFi connectivity! Dive into the world of IoT and remote control effortlessly, as

Getting Started with ESP-IDF in VSCode
Getting Started with ESP-IDF in VSCode

This guide introduces an efficient method, “ESP-IDF + VSCode,” for ESP32 development, simplifying environment setup and allowing seamless switching between ESP-IDF versions. It covers downloading

How to Enable Multi-Core on ESP32 Microcontroller
How to Enable Multi-Core on ESP32 Microcontroller

This comprehensive guide elucidates the process of enabling multi-core functionality on the ESP32 microcontroller, leveraging its dual-core architecture for enhanced parallel processing capabilities. Through detailed

esp32 pinout
ESP32 Pinout Reference Guide

The ESP32 is a versatile microcontroller with extensive functionalities. Its pinout includes GPIO pins for digital, analog, and capacitive touch, PWM pins for precise control,

Scroll to Top