ESP-IDF workshop - Preliminary setup

Introduction

#

In this guide, we’ll walk set up the development environment to work on projects based on the ESP-IDF toolchain.

We’ll use the open-source IDE VS Code and the ESP-IDF extension for VS Code, which allows you to configure the toolchain, build projects, and flash the memory of Espressif modules.

If you don’t have an Espressif development kit available, you can still complete all the steps in this guide except for the last one.

For the final step, you’ll need a physical board with an Espressif SoC, for example, the ESP32-S3-DevKitC-1.

The guide is divided into 5 parts:

1. Installing VS Code and prerequisites
2. Installing the ESP-IDF extension for VS Code
3. Configuring the ESP-IDF toolchain via Espressif Installation Manager (EIM)
4. Building the first project
5. Flashing the module

Installing VS Code and Prerequisites

#

This step depends on your operating system. Follow the appropriate guide below:

• 🐧 Linux: Installing VS Code and prerequisites
• 🪟 Windows: Installing VS Code
• 🍎 macOS: Installing VS Code and prerequisites

Installing the ESP-IDF Extension for VS Code

#

Once all prerequisites are installed, we can add the ESP-IDF extension to VS Code. Using the ESP-IDF extension, we’ll then install and configure the ESP-IDF toolchain.

• Open VS Code

• Click the Extensions icon (four squares) on the left

  

• In the search bar, type esp-idf

  

• Click “Install” on the first result, ESP-IDF

  • If prompted, click “Accept and Install”

Configuring the ESP-IDF Toolchain via EIM

#

Once the ESP-IDF extension is installed, we need to install the toolchain. This is done through the Installation Manager.

• Open the Command Palette by pressing F1 and type
  

  > ESP-IDF: Open ESP-IDF Installation Manager
  

• Click on the drop down menu item
  

  

• When asked about the mirror, choose Github
  

  

• After a few seconds, the installation manager GUI will appear.

• Click on Easy Installation
  

  

• You’ll be presented with a welcome screen. Click on Start Installation

  

• Choose the latest stable release (v5.5.3 as of today)

  

• Wait for the installation to finish. This will take some time. You can monitor the progress using the progress bar.

  

• Once finished, click on Go to Dashboard to verify the installation

  

• You should see v5.5.3 among the installed versions

  

• You can now close the Espressif Installation Manager GUI

Building the First Project

#

Now that the extension and toolchain are installed, it’s time to test building a project. We’ll create a new project based on one of the examples included with the ESP-IDF toolchain.

Create a Project from an Example

#

• Open the Command Palette (F1 or CTRL+SHIFT+P)

• Type ESP-IDF: New Project and select it

• In the dropdown menu, select ESP-IDF v5.5.3

  

• In the New Project tab, expand the ESP-IDF Examples menu

  

• Expand get-started and choose hello_world

• Click Create project using template hello_world

  

• In the project details, choose the Espressif SoC you will be using (you can change it later if required)

  

• In the next screen, click Open project to open a new VS Code window with the newly created project

  

• You should now see the files for the hello_world example project in the right panel

  

Specify the Target

#

To build and flash the project to your Espressif module, you must tell the compiler which SoC you’re targeting.

In the previous step, we already chose the target, so no further steps are required.

However, if you need to change the target, you can:

• Open the command palette (F1 or CTRL+SHIFT+P) and type
  ESP-IDF: Set Espressif Device Target
• In the following dropdown → select ESP32-S3 chip (via builtin USB-JTAG)

Build the Project

#

Now, let’s build the project.

• Open the command palette (F1 or CTRL+SHIFT+P)
• Type ESP-IDF: Build Your Project

  

• A terminal will open at the bottom showing build messages
• When the build finishes, you’ll see the memory usage summary

  

If you see the summary screen, both the toolchain and extension were installed correctly.

If you have an Espressif development board, proceed to the next section to verify USB connectivity.

Flashing the Module

#

Once the project is built, it’s time to flash the module. The ESP-IDF extension for VS Code provides the command: > ESP-IDF: Flash (UART) Your Project

However, the most commonly used command is:

> ESP-IDF: Build, Flash and Start a Monitor on Your Device

This command not only builds and flashes the project to the device but also starts a serial monitor directly in the editor terminal.

To flash the module:

1. Select the port your development board is connected to
2. Run the command: > ESP-IDF: Build, Flash and Start a Monitor on Your Device

sudo usermod -a -G dialout $USER

Development board ports

#

Modern Espressif development board, usually have two USB ports, called UART and USB (see picture below)

1. The UART port is connected to the UART pins of the Espressif SoC via a USB→UART bridge chip.
2. The USB port is connected directly to D+ and D- pins of the Espressif SoC.

To program the module, connect your computer to the UART port.

Select the port to which the development board is connected

#

• Connect the board to your computer via USB
• If VS Code is closed, reopen it and open your project folder
  • File → Open Folder or File → Open Recent
• Open the command palette and type: > ESP-IDF: Select Port to Use (COM, tty, usbserial)

  

• Select the port (Silicon Labs – the USB/UART bridge on the development board)

  

• The port name will now appear in the bottom status bar

  

If your operating system doesn’t automatically detect the connected board, refer to the appropriate guide:

• 🪟 Windows
• 🐧 Linux
• 🍎 macOS

Flash the Module and Start the Monitor

#

• Open the command palette and type: > ESP-IDF: Build, Flash and Start a Monitor on Your Device

  

• From the dropdown → select UART

  

• Wait for the flashing process to complete and for the monitor to start
• In the terminal, you’ll see the boot messages and the “hello world!” output

  

If you see the message in the terminal, your setup is working correctly and you’re ready for the workshop and to start developing projects based on ESP-IDF.

Conclusion

#

In this guide, we covered how to install VS Code, the ESP-IDF extension, and the ESP-IDF toolchain. We also went through how to create, build, and flash a project to your development board. Your development environment is now ready to use.