# ESP-IDF Extension for VS Code [中文](./README_CN.md) [](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/) [](./README.md#Troubleshooting)  [](https://github.com/espressif/vscode-esp-idf-extension/releases) [](https://esp32.com/viewforum.php?f=40) Develop, build, flash, monitor, debug and [more](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/index.html) with Espressif chips using Espressif IoT Development Framework [(ESP-IDF)](https://github.com/espressif/esp-idf). **Latest master installer** for Visual Studio Code. You can use this VSIX to test the current github master of the extension by pressing F1 or click menu `View` -> `Command Palette...`, type `Install from VSIX` and then select the previously downloaded `.vsix` file to install the extension. Make sure to review our [Espressif documentation](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/index.html) first to properly use the extension. # How to use ## Install 1. Download and install [Visual Studio Code](https://code.visualstudio.com/). 2. Install ESP-IDF system prerequisites for your operating system: - Prerequisites for [MacOS and Linux](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/linux-macos-setup.html). - For Windows there is no additional prerequisites. 3. In Visual Studio Code, Open the **Extensions** view by clicking on the Extension icon in the Activity Bar on the side of Visual Studio Code or the **View: Show Extensions** command (shortcut: ⇧ ⌘ X or Ctrl+Shift+X). 4. Search for [ESP-IDF Extension](https://marketplace.visualstudio.com/items?itemName=espressif.esp-idf-extension). 5. Install the extension. After you install the extension, the  should appear in the VS Code Activity bar (left side set of icons). When you click the Espressif icon, you can see a list of basic commands provided by this extension.

6. From the command list, select **ESP-IDF: Open ESP-IDF Installation Manager** or press F1 and type `Open ESP-IDF Installation Manager`. After, choose the **ESP-IDF: ESP-IDF: Open ESP-IDF Installation Manager** option. > **NOTE:** For versions of ESP-IDF < 5.0, spaces are not supported inside configured paths. 7. Alternatively, you can download the ESP-IDF Installation Manager from the following link [ESP-IDF Installation Manager](https://dl.espressif.com/dl/eim/index.html) among the following options:: - Espressif: Faster speed in China using Espressif download servers links. - Github: Using github releases links. 8. Use the ESP-IDF Installation Manager to install the ESP-IDF and tools. If necessary, here is the [ESP-IDF Installation Manager Documentation](https://docs.espressif.com/projects/idf-im-ui/en/latest/general_info.html). 9. In Visual Studio Code, navigate to `View` > `Command Palette` and type `select current esp-idf version` and select **ESP-IDF: Select Current ESP-IDF Version** from the list. The list of available ESP-IDF setups will be shown, select which one you want to use for the current ESP-IDF project. The selected setup will save the selected ESP-IDF path as **idf.currentSetup** and the extension will configure environment variables for the current project saved as workspace folder state. You can review the setup by navigating to `View` > `Command Palette`, typing `doctor command`, and selecting **ESP-IDF: Doctor Command** from the list. 10. If everything is installed correctly, you will see a message that all settings have been configured. You can start using the extension. Check the [Troubleshooting](#Troubleshooting) section if you have any issues. ## Using the ESP-IDF Extension for VS Code This extension provides a list of icons in the status bar (blue bar in the bottom of VS Code window) for ESP-IDF commands. You can see the command to be executed when you hover the icon.

These icons will be used in the steps below showing common ESP-IDF use cases: 1. Press F1 and type **ESP-IDF: New Project** to create a new project from ESP-IDF examples. Select ESP-IDF and choose an example to create a new project from. 2. Once the project is created and opened in VS Code, set the serial port of your device by clicking status bar icon . Alternatively, press F1, type **ESP-IDF: Select Port to Use**, and choose the serial port to which your device is connected. 3. Select an Espressif target (esp32, esp32s2, etc.) by clicking status bar icon . Alternatively, press F1 and type **ESP-IDF: Set Espressif Device Target** command. 4. Next, configure your ESP-IDF project by clicking status bar icon  or press F1 and typing **ESP-IDF: SDK Configuration Editor** command (CTRL E G keyboard shortcut) where you can modify the ESP-IDF project settings. After all changes are made, click `Save` and close this window. You can see the output in the menu `View` -> `Output` and choose `ESP-IDF` from the dropdown list. 5. (OPTIONAL) Run **ESP-IDF: Run idf.py reconfigure Task** to generate the ``compile_commands.json`` file so language support works. Additionally you can configure the `.vscode/c_cpp_properties.json` as explained in [C/C++ Configuration](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/configureproject.html#c-and-c-code-navigation-and-syntax-highlight) documentation. 6. At this point, you can modify the code. When the project is completed, build your project by clicking status bar icon  or pressing F1 and typing **ESP-IDF: Build your Project**. 7. Flash to your device by clicking status bar icon , or pressing F1 and typing **ESP-IDF: Flash Your Project**. From there, select `UART`, `DFU` or `JTAG` depending on your serial connection, and start flashing the application to your device. 8. Change the flash method by clicking status bar icon , or pressing F1 and typing **ESP-IDF: Select Flash Method** to select from `UART`, `DFU` or `JTAG`. You can alternatively use one of the commands **ESP-IDF: Flash (UART) Your Project**, **ESP-IDF: Flash (with JTAG)** or **ESP-IDF: Flash (DFU) Your Project**. 9. Start a monitor by clicking status bar icon , or pressing F1 and typing **ESP-IDF: Monitor Device**, which will log the device activity in a Visual Studio Code terminal. 10. Make sure to configure your drivers as mentioned in ESP-IDF [Configure JTAG Interface](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/configure-ft2232h-jtag.html) documentation. 11. Before debugging your device, if you are using a connected ESP-IDF development board, the OpenOCD configuration will be automatically selected based on your connected board, including the USB location if available (requires OpenOCD version v0.12.0-esp32-20240821 or higher). Otherwise, you can manually select the device OpenOCD board configuration files by pressing F1 and typing **ESP-IDF: Select OpenOCD Board Configuration**. You can test the connection by clicking status bar icon  or pressing F1 and typing **ESP-IDF: OpenOCD Manager**. The output is shown in the menu `View` -> `Output` and choose `ESP-IDF` from the dropdown list. > **NOTE:** You can start or stop the OpenOCD in Visual Studio Code using the **ESP-IDF: OpenOCD Manager** command or by clicking the `OpenOCD Server (Running | Stopped)` button in the status bar. 12. If you want to start a debug session, just press F5 (ensure the project is built, flashed, and OpenOCD is properly connected for the debugger to function correctly). The debug session output can be seen in the menu `View` -> `Debug Console`. Check the [Troubleshooting](#Troubleshooting) section if you have any issues. # Further reading Check the [ESP-IDF Extension for VS Code Documentation](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/) for tutorials, commands and features provided. ## All Available Commands Press F1 or click menu `View` -> `Command Palette...` to show Visual Studio code commands, then type **ESP-IDF** to see all available extension commands.

Category	Command	Description	Keyboard Shortcuts (Mac)	Keyboard Shortcuts (Windows/Linux)
Settings	Add Docker Container Configuration	Add the .devcontainer files to the currently opened project directory, necessary to use a ESP-IDF project in a Docker container with Visual Studio Code Dev Containers extension.
	Add VS Code Configuration Folder	Add .vscode files to the currently opened project directory. This includes launch.json (for debugging), settings.json and c_cpp_properties.json (for syntax highlight).
	Open ESP-IDF Installation Manager	Open ESP-IDF Installation Manager (EIM) to install ESP-IDF, IDF Tools and Python virtual environment.
	Select Output and Notification Mode	This extension shows many notifications and output in the Output window ESP-IDF. This command allows you to set if to show notifications only, output only, both notifications and output, or neither.
	Select Where to Save Configuration Settings	In Visual Studio Code, settings can be saved in 3 places: User Settings (global settings), workspace ( .code-workspace file) or workspace folder (.vscode/settings.json). More information in working with multiple projects.
	Pick a Workspace Folder	When using a Visual Studio Code workspace with multiple folders, this command allows you to choose which workspace folder to apply this extension's commands to. More information in working with multiple projects.
Basic	Set Espressif Device Target	This will set the target for the current project (IDF_TARGET). Similar to idf.py set-target. For example, if you want to use ESP32 or ESP32-C3, you need to execute this command.
	SDK Configuration Editor	Launch a UI to configure your ESP-IDF project settings. This is equivalent to idf.py menuconfig.	⌘ I G	Ctrl E G
	Build Your Project	Build your project using `CMake` and `Ninja-build` as explained in ESP-IDF Build System Using Cmake Directly. You could modify the behavior of the build task with idf.cmakeCompilerArgs for Cmake configure step and idf.ninjaArgs for Ninja step. For example, using [-j N] where N is the number of jobs run in parallel.	⌘ I B	Ctrl E B
	Size Analysis of the Binaries	Launch UI with the ESP-IDF project binaries size information.	⌘ I S	Ctrl E S
	Select Port to Use	Select which serial port to use for ESP-IDF tasks, such as flashing or monitoring your device.	⌘ I P	Ctrl E P
	Flash Your Project	Write binary data to the ESP's flash chip from your current ESP-IDF project. This command will use either UART, DFU or JTAG based on idf.flashType.	⌘ I F	Ctrl E F
	Monitor Device	This command will execute idf.py monitor to start serial communication with Espressif device. Please take a look at the IDF Monitor.	⌘ I M	Ctrl E M
	Open ESP-IDF Terminal	Launch a terminal window configured with extension ESP-IDF settings. Similar to export.sh script from ESP-IDF CLI.	⌘ I T	Ctrl E T
	Select OpenOCD Board Configuration	Select the OpenOCD configuration files that match your Espressif device target, such as DevKitC or ESP-Wrover-Kit. This is necessary for flashing with JTAG or debugging your device.
	Build, Flash and Start a Monitor on Your Device	Build the project, write binaries program to device and start a monitor terminal with a single command. Similar to idf.py build flash monitor.	⌘ I D	Ctrl E D
Project creation	Create New ESP-IDF Component	Create a new component in the current directory based on ESP-IDF component template.
	Create New Empty Project	Ask for the new project name, choose the directory to create the project, and show a notification to open the newly created project.
	Import ESP-IDF Project	Import an existing ESP-IDF project, add .vscode and .devcontainer files to a new location, and optionally rename the project.
	New Project	Launch UI with a ESP-IDF project creation wizard using example templates from ESP-IDF and additional frameworks configured in the extension.	⌘ I N	Ctrl E N
Flashing	Select Flash Method	Select which flash method to use for Flash Your Project command. It can be DFU, JTAG or UART.
	Flash Your Project	Write binary data to the ESP's flash chip from your current ESP-IDF project. This command will use either UART, DFU or JTAG based on idf.flashType	⌘ I F	Ctrl E F
	Flash (DFU) Your Project	Write binary data to the ESP's flash chip from your current ESP-IDF project using DFU. Only for ESP32-S2 and ESP32-S3.
	Flash (UART) Your Project	Write binary data to the ESP's flash chip from your current ESP-IDF project using esptool.py.
	Flash (with JTAG)	Write binary data to the ESP's flash chip from your current ESP-IDF project using OpenOCD JTAG.
	Encrypt and Flash Your Project	Execute flashing the project program to device while adding --encrypt for partitions to be encrypted.
	Erase Flash Memory from Device	Execute esptool.py erase_flash command to erase flash chip (set to 0xFF bytes).	⌘ I R	Ctrl E R
Code coverage	Add Editor Coverage	Parse your project GCOV code coverage files to add color lines representing code coverage on currently opened source code file.
	Configure Project SDKConfig for Coverage	Set required values in your project SDKConfig to enable code coverage analysis.
	Get HTML Coverage Report for Project	Parse your project GCOV code coverage files to generate a HTML coverage report.
	Remove Editor Coverage	Remove editor colored lines from Add Editor Coverage command
Additional frameworks	Install ESP-ADF	Clone ESP-ADF inside the selected directory and set ADF_PATH in idf.customExtraVars configuration setting.
	Add Arduino ESP32 as ESP-IDF Component	Add Arduino-ESP32 as a ESP-IDF component in your current directory (${CURRENT_DIRECTORY}/components/arduino).
eFuse	Get eFuse Summary	Retrieve a list of eFuses and their corresponding values from the chip currently connected to the serial port and display in the ESP Explorer EFUSEEXPLORER.
	Clear eFuse Summary	Clear the eFuse Summary tree from ESP Explorer EFUSEEXPLORER.
QEMU	Launch QEMU Server	As described in QEMU documentation, this command will execute ESP32 QEMU from the project Dockerfile with the current project binaries.
	Launch QEMU Debug Session	As described in QEMU documentation, this command will start a debug session to ESP32 QEMU from the project Dockerfile with the current project binaries.
	Monitor QEMU Device	As described in QEMU documentation, this command will start a terminal to monitor the ESP32 QEMU from the project Dockerfile with the current project binaries.
Monitoring	Monitor Device	This command will execute idf.py monitor to start serial communication with Espressif device. Please take a look at the IDF Monitor Documentation.	⌘ I M	Ctrl E M
	Launch IDF Monitor for Core Dump Mode/GDB Stub Mode	Launch ESP-IDF Monitor with WebSocket capabilities. If you has configured the panic handler to gdbstub or core dump, the monitor will launch a post-mortem debug session of the chip.
	Monitor QEMU Device	As described in QEMU documentation, this command will start a terminal to monitor the ESP32 QEMU from the project Dockerfile with the current project binaries.
Editors	NVS Partition Editor	Launch UI to create a CSV file for ESP-IDF Non-Volatile Storage Library.
	Partition Table Editor	Launch UI to manage custom partition table as described in ESP-IDF Partition Tables.
	SDK Configuration Editor	Launch a UI to configure your ESP-IDF project settings. This is equivalent to idf.py menuconfig.	⌘ I G	Ctrl E G
Unit Testing	"Unit Test: Build Unit Test App"	Copy the unit test app in the current project, build the current project. More information in Unit testing documentation.
	Unit Test: Flash Unit Test App	Flash the unit test application to the connected device. More information in Unit testing documentation.
	Unit Test: Build and Flash Unit Test App for Testing	Copy the unit test app in the current project, build the current project and flash the unit test application to the connected device. More information in Unit testing documentation.
Scripts and Tools	Run idf.py reconfigure Task	This command will execute idf.py reconfigure (CMake configure task), which is useful for generating compile_commands.json for the C/C++ language support.
	Erase Flash Memory from Device	Execute esptool.py erase_flash command to erase flash chip (set to 0xFF bytes).	⌘ I R	Ctrl E R
	Dispose of Current SDK Configuration Editor Server Process	If you already executed the SDK Configuration Editor, a cache process will remain in the background for faster reopening. This command will dispose of such cache process.
	Doctor Command	Run a diagnostic of the extension setup settings and extension logs to provide a troubleshooting report.
	Troubleshoot Form	Launch UI for user to send a troubleshoot report with steps to reproduce. Run a diagnostic of the extension setup settings and extension logs to send to telemetry backend.
	Run ESP-IDF-SBOM Vulnerability Check	Creates Software bill of materials (SBOM) files in the Software Package Data Exchange (SPDX) format for applications generated by the Espressif IoT Development Framework (ESP-IDF).
	Save Default SDKCONFIG File (save-defconfig)	Generate sdkconfig.defaults files using the project current sdkconfig file.
	Show Ninja Build Summary	Execute the Chromium ninja-build-summary.py.
	Search in documentation...	Select some text from your source code file and search in ESP-IDF documentation with results right in the VS Code ESP-IDF Explorer tab.	⌘ I Q	Ctrl E Q
	Search Error Hint	Type some text to find a matching error from ESP-IDF hints dictionary.
	Load Image from LVGL C File	Load and display an image from a LVGL C file containing lv_image_dsc_t structure. This command allows you to view LVGL images without requiring a debug session.
	Open Image Viewer	Open the Image Viewer panel to display images from debug variables or LVGL C files. This panel provides tools for viewing and analyzing image data in various formats.
Cleanup	Clear ESP-IDF Search Results	Clear results from ESP Explorer Documentation Search Results.

## Commands for `tasks.json` and `launch.json` We have implemented some utilities commands that can be used in `tasks.json` and `launch.json` like: ```json "miDebuggerPath": "${command:espIdf.getToolchainGdb}" ``` - `espIdf.getExtensionPath`: Get the installed location absolute path. - `espIdf.getOpenOcdScriptValue`: Return the value of OPENOCD_SCRIPTS computed from ESP-IDF Tools path, `idf.customExtraVars`, or the system's OPENOCD_SCRIPTS environment variable. - `espIdf.getOpenOcdConfigs`: Return the openOCD configuration files as string. Example `-f interface/ftdi/esp_ftdi.cfg -f target/esp32.cfg`. - `espIdf.getProjectName`: Return the project name from current workspace folder `build/project_description.json`. - `espIdf.getToolchainGcc`: Return the absolute path of the toolchain GCC for the ESP-IDF target given by current IDF_TARGET in sdkconfig or `idf.customExtraVars`["IDF_TARGET"] configuration setting. - `espIdf.getToolchainGdb`: Return the absolute path of the toolchain gdb for the ESP-IDF target given by current IDF_TARGET in sdkconfig or `idf.customExtraVars`["IDF_TARGET"] configuration setting. - `espIdf.getIDFTarget`: Return the current IDF_TARGET from sdkconfig or `idf.customExtraVars`["IDF_TARGET"] configuration setting. See an example in the [debugging](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/debugproject.html) documentation. ## Available Tasks in `tasks.json` A template `tasks.json` is included when creating a project using **ESP-IDF: New Project**. These tasks can be executed by pressing F1, writing `Tasks: Run task` and selecting one of the following: 1. `Build` - Build Project 2. `Set Target to esp32` 3. `Set Target to esp32s2` 4. `Clean` - Clean the project 5. `Flash` - Flash the device 6. `Monitor` - Start a monitor terminal 7. `OpenOCD` - Start the OpenOCD server 8. `BuildFlash` - Execute a build followed by a flash command Note that for OpenOCD tasks, you need to define `OpenOCD_SCRIPTS` in your system environment variables with OpenOCD scripts folder path. # Troubleshooting If something is not working, please check for any error on one of these: > **NOTE:** Set `idf.OpenOCDDebugLevel` configuration setting to 3 or more in your /.vscode/settings.json to show debug level logs of OpenOCD server in `ESP-IDF` output. > **NOTE:** Set `verbose: true` in your /.vscode/launch.json for more detailed debug adapter output. 1. In Visual Studio Code select menu **View** > **Output** > **ESP-IDF**. This output information is useful to know what is happening in the extension. 2. In Visual Studio Code select menu **View** > **Command Palette...** and type `ESP-IDF: Doctor Command` to generate a report of your environment configuration and it will be copied in your clipboard to paste anywhere. 3. Check log file which can be obtained from: - Windows: `%USERPROFILE%\.vscode\extensions\espressif.esp-idf-extension-VERSION\esp_idf_vsc_ext.log` - Linux & MacOSX: `$HOME/.vscode/extensions/espressif.esp-idf-extension-VERSION/esp_idf_vsc_ext.log` 4. In Visual Studio Code, select menu **Help** > **Toggle Developer Tools** and copy any error in the Console tab related to this extension. 5. In Visual Studio Code select menu **View** > **Output** > **Extension Host**. This output information is useful to know what is happening during the extensions activation. If no extension command work, you could share the output here to see the error stack. 5. Visual Studio Code allows you to configure settings at different levels: **Global (User Settings)**, **Workspace** and **Workspace Folder**, so make sure your project has the right settings. The `ESP-IDF: Doctor command` result might give the values from user settings instead of the workspace folder settings. - Workspace folder configuration settings are defined in ``${workspaceFolder}/.vscode/settings.json`` - Workspace configuration settings are defined in the workspace's ``.code-workspace`` file - User settings defined in ``settings.json`` - **Windows**: ``%APPDATA%\Code\User\settings.json`` - **MacOS**: ``$HOME/Library/Application Support/Code/User/settings.json`` - **Linux**: ``$HOME/.config/Code/User/settings.json`` This extension uses the ``idf.saveScope`` configuration setting (which can only be defined in User Settings) to specify where to save settings for features such as the Setup Wizard. You can modify this using the ``ESP-IDF: Select where to Save Configuration Settings`` command. 6. Refer to the [OpenOCD troubleshooting FAQ](https://github.com/espressif/OpenOCD-esp32/wiki/Troubleshooting-FAQ) for help with application tracing, debugging, or other OpenOCD-related issues that may appear in the OpenOCD output. 7. In some cases, the default shell (Powershell, zsh, sh, .etc) configured in VS Code could affect the behavior of the extension. Make sure that MSYS/MinGW is not set in the environment and the variables don't conflict with terminal behavior. The `ESP-IDF: Doctor Command` shows which shell is detected by the extension when running tasks like building, flashing and monitoring. More information in [here](https://code.visualstudio.com/docs/terminal/profiles). If there is any Python package error, please try to reinstall the required Python packages with the [ESP-IDF Installation Manager](https://docs.espressif.com/projects/idf-im-ui/en/latest/general_info.html). > **NOTE:** When downloading ESP-IDF using git cloning in Windows, if you receive errors like "unable to create symlink", enabling `Developer Mode` while cloning ESP-IDF could help resolve the issue. If you can't resolve the error, please search in the [github repository issues](http://github.com/espressif/vscode-esp-idf-extension/issues) for existing errors or open a new issue [here](https://github.com/espressif/vscode-esp-idf-extension/issues/new/choose). # Code of Conduct This project and everyone participating in it is governed by the [Code of Conduct](./docs/CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to [vscode@espressif.com](mailto:vscode@espressif.com). # License This extension is licensed under the Apache License 2.0. Please see the [LICENSE](./LICENSE) file for additional copyright notices and terms.