Programming ESP32 with ESP-IDF using VS Code – Getting Started Guide

Learn how to program the ESP32 boards with the ESP-IDF (Espressif IoT Development Framework). The ESP-IDF was developed by Espressif and it is intended for development of Internet of Things (IoT) applications with Wi-Fi, Bluetooth, power management and several other features.

We recommend installing the ESP-IDF on VS Code IDE (Microsoft Visual Studio Code). In this guide, we’ll cover how to prepare the ESP-IDF on Windows, Mac OS X or Linux Ubuntu operating systems to program ESP32 boards.

Introduction to ESP-IDF (Espressif IoT Development Framework)

ESP-IDF, Espressif IoT Development Framework, is the original framework developed by Espressif (the developer of ESP32 chips) to program the ESP32. It is an SDK to develop applications for ESP332 chips using C and C++ programming languages that gives you low-level access to the hardware.

Being the “official” way to program the ESP32, it means the SDK is frequently updated to support the release of newer versions of ESP32 chips. On the other hand, it may take a while for new chips to be supported in the Arduino IDE. The following table shows the current supported ESP32 SoC series by ESP-IDF:

• ESP32
• ESP32-S2, ESP32-S3
• ESP32-C2, ESP32-C3, ESP32-C5, ESP32-C6, ESP32-C61
• ESP32-H2
• ESP32-P4

ESP-IDF or Arduino IDE?

Compared with Arduino IDE, ESP-IDF gives you more options for customization, performance, and control over ESP32 peripherals, configurations, and tasks. It uses RealTime OS (FreeRTOS) using programming based on tasks, while the Arduino IDE uses the setup() and loop() configuration.

ESP-IDF is much more complex to use than Arduino IDE. You need to understand a lot more about how the system and hardware work, and you’ll need to build and understand configurations for memory management, FreeRTOS tasks, peripheral initialization, and more.

This complexity gives you more control over your boards, but you’re also more likely to run into errors, configuration problems, etc. With that said, if you’re not familiar with Arduino IDE or if you’re just getting started with the ESP32, we don’t recommend getting into ESP-IDF at the moment.

Installing VS Code

Follow the next instructions to install VS Code on your Operating System:

• A) Windows
• B) MacOS X
• C) Linux

A) Installing VS Code on Windows (Visual Studio Code)

Go to code.visualstudio.com and download the stable build for your operating system (Windows).

Click on the installation wizard to start the installation and follow all the steps to complete the installation. Accept the agreement and press the Next button.

Select the following options and click Next.

Press the Install button.

Finally, click Finish to finish the installation.

Open VS Code, and you’ll be greeted by a Welcome tab with the released notes of the newest version.

That’s it. Visual Studio Code was successfully installed.

B) Installing VS Code on Mac OS X (Visual Studio Code)

Go to code.visualstudio.com and download the stable build for your operating system (Mac OS X).

After downloading the Visual Studio Code application file, you’ll be prompted with the following message. Press the “Open” button.

Or open your Downloads folder and open Visual Studio Code.

After that, you’ll be greeted by a Welcome tab with the released notes of the newest version.

That’s it. Visual Studio Code was successfully installed.

C) Installing VS Code on Linux Ubuntu (Visual Studio Code)

Go to code.visualstudio.com and download the stable build for your operating system (Linux Ubuntu).

Save the installation file:

To install it, open a Terminal window, navigate to your Downloads folder and run the following command to install VS Code.

$ cd Downloads
~/Downloads $ sudo apt install ./code_1.49.1-1600299189_amd64.deb

When the installation is finished, VS Code should be available in your applications menu.

Open VS Code, and you’ll be greeted by a Welcome tab with the released notes of the newest version.

That’s it. Visual Studio Code was successfully installed.

Installing Python

To program the ESP32 with pioarduino, you need Python 3.5 or a later version installed on your computer. Follow the instructions according to your operating system:

• A) Installing Python on Windows
• B) Installing Python on MacOS
• C) Installing Python on Ubuntu Linux

A) Installing Python on Windows

Go to python.org/downloads and download Python 3.13.3 or a later version.

Open the downloaded file to start the Python installation wizard. The following windows show up.

Important: make sure you check the option Add Python to PATH. Then, you can click on the Install Now button. You may also need to check the “Use admin privileges when installing py.exe”.

If the installation is successful, you’ll get the following message.

Finally, click the Close button.

Installing Python on Mac OS X

Open a Terminal window. You can open it through Spotlight Search. To launch Spotlight, click the small magnifying glass icon in your menu bar (or press Cmd+Space).

Then, type “terminal” and click on the Terminal icon to launch it.

To install Python, I’ll be using Homebrew.  If you don’t have the brew command available, type the next command in the Terminal window:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

Here’s how it looks on the Terminal window:

Then, run the brew command to install Python 3.13:

brew install python3

Here’s how it looks on the Terminal window:

Now, you can proceed to this section to install the pioarduino extension.

Installing Python on Linux Ubuntu

To program the ESP32 boards with pioarduino IDE, you need Python 3.5 or a later version installed on your computer.

Open the Terminal window and check that you already have Python 3 installed. Run the following command:

python3 --version

It should return the current installed version:

python 3.13.3

If you don’t have Python installed, run the next command to install it:

sudo apt install python3

Whether you already have Python installed or not, you need to run the following command to install Python utilities.

sudo apt install python3-distutils

Installing the ESP-IDF Extension for VS Code

To access the ESP-IDF tools, you need to install the official ESP-IDF extension on VS Code. Open VS Code and click the Extensions icon in the left sidebar or click Ctrl+Shift+X to open the Extensions tab.

Search for “ESP-IDF“, select the ESP-IDF by Espressif Systems and click the Install button.

Press the “Trust Publisher & Install” button. The installation will take some time to complete.

That’s it! The ESP-IDF extension by Espressif Systems is now installed in your IDE, the following welcome screen should appear.

Next, follow these instructions to configure the ESP-IDF Extension:

1. Open the ESP-IDF Espressif extension panel
2. Expand the “Advanced” menu
3. Click the “Configure ESP-IDF Extension” option
4. Choose the “EXPRESS” setup mode to configure the ESP-IDF Tools

During the ESP-IDF Express Setup screen, you’ll be prompted to select the ESP-IDF version. At the time of writing this guide, the latest released version is v5.4.1. We recommend using version 5.X to follow along. Press the “Install” button.

Note: you can leave all other default options or change the ESP-IDF directory if you need to.

That’s it, you’ll see a similar screen while the ESP-IDF extension is being configured. Wait a few minutes until this process is completed.

Installing the C/C++ Extensions for VS Code (optional)

This step is optional, but since you’ll be using the C++ language with the ESP-IDF framework to program the ESP32 boards, we recommend installing these C/C++ extensions for VS Code. Open VS Code and click on the Extensions icon to open the Extensions tab.

Search for “C/C++“, select the first option and click the Install button.

You can also install the “C/C++ Extension Pack“.

Programming ESP32 with ESP-IDF using VS Code – Hello World Code

The ESP-IDF installation comes with a vast examples folder that you can experiment with. For this initial getting started guide, we’ll build and flash a basic “Hello World” code to the ESP32 board.

To open the examples folder, follow these steps:

1. Open the ESP-IDF Espressif extension
2. Expand the “Advanced” menu
3. Click the “Show Examples” option
4. Choose the “Use ESP-IDF v5.4.1” to select the framework version

In the left sidebar, under the “get-started” section open the “hello_world” example.

A new page opens in the IDE with the information about the example: which chips are supported, general information about the example and instructions on how to use it.

On the top of the page, click the button “Select location for creating hello_world project“.

A new window opens to select the target folder to save all your project file, you can use any directory. Create a new folder or navigate to the desired workplace, then “Select Folder for New Project“.

Note: do NOT use a Google Drive / One Drive / Dropbox folder, because while your code is building it will write/create many files and if it’s on a cloud folder this process might be extremely slow.

After selecting the folder for your new Hello World project, you’ll need allow those files to be accessed. Press the “Yes, I trust the authors” button to continue with the correct permissions.

To find the Hello World code example, follow these steps:

1. Open the project explorer by clicking the first icon on the left sidebar
2. Select the HELLO_WORLD folder and expand the “main” section
3. Click the “hello_world_main.c” file
4. The example loads in the code tab

Here’s the full hello_world_main.c code:

// SPDX-FileCopyrightText: 2010-2022 Espressif Systems (Shanghai) CO LTD * SPDX-License-Identifier: CC0-1.0

#include <stdio.h>
#include <inttypes.h>
#include "sdkconfig.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_chip_info.h"
#include "esp_flash.h"
#include "esp_system.h"

void app_main(void)
{
    printf("Hello world!\n");

    /* Print chip information */
    esp_chip_info_t chip_info;
    uint32_t flash_size;
    esp_chip_info(&chip_info);
    printf("This is %s chip with %d CPU core(s), %s%s%s%s, ",
           CONFIG_IDF_TARGET,
           chip_info.cores,
           (chip_info.features & CHIP_FEATURE_WIFI_BGN) ? "WiFi/" : "",
           (chip_info.features & CHIP_FEATURE_BT) ? "BT" : "",
           (chip_info.features & CHIP_FEATURE_BLE) ? "BLE" : "",
           (chip_info.features & CHIP_FEATURE_IEEE802154) ? ", 802.15.4 (Zigbee/Thread)" : "");

    unsigned major_rev = chip_info.revision / 100;
    unsigned minor_rev = chip_info.revision % 100;
    printf("silicon revision v%d.%d, ", major_rev, minor_rev);
    if(esp_flash_get_size(NULL, &flash_size) != ESP_OK) {
        printf("Get flash size failed");
        return;
    }

    printf("%" PRIu32 "MB %s flash\n", flash_size / (uint32_t)(1024 * 1024),
           (chip_info.features & CHIP_FEATURE_EMB_FLASH) ? "embedded" : "external");

    printf("Minimum free heap size: %" PRIu32 " bytes\n", esp_get_minimum_free_heap_size());

    for (int i = 10; i >= 0; i--) {
        printf("Restarting in %d seconds...\n", i);
        vTaskDelay(1000 / portTICK_PERIOD_MS);
    }
    printf("Restarting now.\n");
    fflush(stdout);
    esp_restart();
}

View raw code

Build and Flash Hello World ESP-IDF Code Example to the ESP32 Board

In order to build and flash ESP-IDF code to the ESP32, you’ll need to always follow this procedure. You need to select the flash method (UART), the COM port number, the target device (ESP32), build the code, and the flash it to the board. All these commands are available in the bottom menu bar of VS Code.

First, click the “Star” icon and select the flash method as UART.

While having your ESP32 board connected to your computer, click the COM Port (plug icon) and select the correct port number that refers to your ESP32.

You also need to select the target device, click the chip icon on the bottom bar. In my case, I have an ESP32 with the esp32s3 chip.

For this board, I also need to select the configuration: ESP32-S chip (via builtin USB-JTAG).

Finally, your command bar on the bottom of VS Code should have similar options selected.

For this guide we won’t be writing any code or modifying the existing example code, so you can just Build Project by clicking the wrench icon as shown in the image below.

The first time you build a project it usually takes a bit more time, but once completed it should print a similar message in the Terminal menu and show a “Build Successfully” message.

This is the final step, you can now Flash the Hello World ESP-IDF project to the ESP32 by clicking the “Flash Device” button that has a thunder icon.

Depending on your board, you might need to hold the on-board BOOT button on your ESP32 to put into flashing mode and once the process is completed, it will popup a info message saying “Flash Done“.

If you followed all the steps, the Hello World Code should be running successfully in your board. This example only gives you feedback by printing a message in the “Terminal” window, so you need to open it. Click the “Monitor Device” tool that is illustrated with a screen icon.

The terminal should be printing a message saying “Hello world!“, some details about your board, and then it restarts after 10 seconds. This process is repeated indefinitely.

Your board is now running a basic example. You can modify this line in the hello_world_main.c file to print a different message in the Terminal window:

printf("Hello world!\n");

Troubleshooting – Common Problems Solved

COM Port Not Available – Installing Drivers

If you don’t see your ESP’s COM port available, it means you don’t have the drivers installed. Take a closer look at the chip next to the voltage regulator on the board and check its name. The ESP32 DEVKIT V1 DOIT board uses the CP2102 chip. Alternatively, many ESP32 boards also use the CH340 drivers.

After they are installed, restart VS Code, and you should see the COM port in the Devices menu.

If you’re having trouble installing the CP210x drivers, you can check the following tutorials:

• Install ESP32 USB Drivers – CP210x USB to UART Bridge (Windows PC)
• Install ESP32 USB Drivers – CP210x USB to UART Bridge (Mac OS X)

Failed to Flash Your Board

If you get the following error while uploading the code:

"Connecting........... A fatal error occurred: Failed to connect to ESP32-S3: No serial data received." 

It usually means that your board is not in flashing mode when you’re uploading the code. 

When this happens, you need to press the ESP32 on-board BOOT button when you start seeing many dots in the debugging window.

For more information about this issue, you can follow this guide:

• [SOLVED] Failed to connect to ESP32: Timed out waiting for packet header

Wrong Chip Argument

If you get the following error while uploading the code:

A fatal error occurred: This chip is ESP32-S3 not ESP32. Wrong --chip argument?

You might need to confirm if you’ve selected the correct target device, or check the exact chip that your ESP32 board has. Then, select the correct chip, build the code again and flash it to your board.

Wrapping Up

In this tutorial, you learned how to program the ESP32 with the ESP-IDF framework using VS Code. ESP-IDF is the official way, developed by Espressif, to program ESP32 boards. While it gives you more control over your hardware, it’s also much more complex to use and requires more knowledge about the hardware and configurations.

This was a basic guide to get you started. We hope you found it useful. Let us know if you’d like to see more tutorials for ESP-IDF.

Meanwhile, you can check our ESP32 resources (with Arduino IDE) to learn more about the ESP32 board:

• Learn ESP32 with Arduino IDE (eBook)
• More ESP32 Projects and Tutorials…

Thanks for reading.