ESP-IDF VS Code Extension

Develop, build, flash, monitor, debug and more with Espressif chips using Espressif IoT Development Framework (ESP-IDF)

Table of content

1. Tutorials
2. Quick links
3. Prerequisites
4. How to use
5. Available commands
6. Commands for tasks.json and launch.json
7. Available Tasks in tasks.json
8. Code of Conduct
9. License

Tutorials

1. Install the extension and dependencies.
2. Basic usage
3. Debug
4. Code coverage
5. Application tracing
6. Heap tracing and SystemView tracing
7. Partition table editor
8. NVS Partition editor
9. CMakeLists.txt editor
10. ESP-ADF, ESP-MDF and other frameworks
11. eFuse Explorer
12. Rainmaker

Quick links

• Build from source code and how to install
• Configuration settings
• Chips and supported frameworks
• Commands
• Contribute
• Github Repository
• Github issues
• How to use
• See all features
• Setup process
• Tutorials
• Releases
• Working with multiple projects

Prerequisites

There are few dependencies required in your system and available in environment variable PATH before installing this extension:

All the other dependencies like ESP-IDF and ESP-IDF Tools can be installed using the ESP-IDF: Configure ESP-IDF extension setup wizard or following the steps in the setup documentation.

Please note that this extension only supports the release versions of ESP-IDF, you can still use the extension on master branch or some other branch, but certain feature might not properly work.

How to use

• Install this extension in your Visual Studio Code.

• Then

  • Either open Visual Studio Code and create a workspace folder.
  • Run code ${YOUR_PROJECT_DIR} from the command line.

• Check you have installed the Prerequisites

• Press F1 and type ESP-IDF: Configure ESP-IDF extension to open the extension configuration wizard. This will install ESP-IDF and tools and configure the extension.

• Please take a look at SETUP for details about extension configuration.

• Press F1 and type ESP-IDF: Create project from extension template to generate a template ESP-IDF project or ESP-IDF: Show Examples Projects to create from ESP-IDF examples.

• Configure the .vscode/c_cpp_properties.json as explained in C/C++ Configuration.

  Note: If you want to get code navigation and ESP-IDF function references, the Microsoft C/C++ Extension can be used to resolve header/source links. By default, projects created with ESP-IDF: Create project from extension template or ESP-IDF: Show Examples Projects tries to resolve headers by manually recursing ESP-IDF directory sources with the Tag Parser engine. This can be optimized by building the project first and configure your project to use build/compile_commands.json as explained in C/C++ Configuration.

• Do some coding!

• Check you set the correct port of your device by pressing F1, typing ESP-IDF: Select port to use: and choosing the serial port your device is connected.

• Select an Espressif target (esp32, esp32s2, etc.) with the ESP-IDF: Set Espressif device target command.

• When you are ready, build your project. Then flash to your device by pressing F1 and typing ESP-IDF: Flash your device then selecting Flash allows you to flash the device.

• You can later start a monitor by pressing F1 and typing ESP-IDF: Monitor your device which will log the activity in a Visual Studio Code terminal.

• If you want to start a debug session, just press F5 (make sure you had at least build and flash once before so the debugger works correctly). To make sure you can debug your device, set the proper idf.openOcdConfigs settings in your settings.json or by pressing F1 and typing ESP-IDF: Device configuration.

Available commands

Click F1 to show Visual studio code actions, then type ESP-IDF to see possible actions.

The Add Arduino-ESP32 as ESP-IDF Component command will add Arduino-ESP32 as a ESP-IDF component in your current directory (${CURRENT_DIRECTORY}/components/arduino).

You can also use the ESP-IDF: Create project from extension template command with arduino-as-component template to create a new project directory that includes Arduino-esp32 as an ESP-IDF component.

NOTE Not all versions of ESP-IDF are supported. Make sure to check Arduino-ESP32 to see if your ESP-IDF version is compatible.

The Install ESP-ADF will clone ESP-ADF to a selected directory and set idf.espAdfPath (idf.espAdfPathWin in Windows) configuration setting.

The Install ESP-MDF will clone ESP-MDF to a selected directory and set idf.espMdfPath (idf.espMdfPathWin in Windows) configuration setting.

The Show Examples Projects command allows you create a new project using one of the examples in ESP-IDF, ESP-ADF or ESP-MDF directory if related configuration settings are set.

Commands for tasks.json and launch.json

We have implemented some utilities commands that can be used in tasks.json and launch.json like

"miDebuggerPath": "${command:espIdf.getXtensaGdb}"

as shown in the debugging documentation.

• espIdf.getExtensionPath: Get the installed location absolute path.
• espIdf.getOpenOcdScriptValue: Return the value of OPENOCD_SCRIPTS from idf.customExtraVars or from system OPENOCD_SCRIPTS environment variable.
• espIdf.getOpenOcdConfig: Return the openOCD configuration files as string. Example -f interface/ftdi/esp32_devkitj_v1.cfg -f board/esp32-wrover.cfg.
• espIdf.getProjectName: Return the project name from current workspace folder build/project_description.json.
• espIdf.getXtensaGcc: Return the absolute path of the xtensa toolchain gcc for the ESP-IDF target given by idf.adapterTargetName configuration setting and idf.customExtraPaths.
• espIdf.getXtensaGdb: Return the absolute path of the xtensa toolchain gdb for the ESP-IDF target given by idf.adapterTargetName configuration setting and idf.customExtraPaths.

Available Tasks in tasks.json

There is also some tasks defined in Tasks.json, which can be executed by running F1 and 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.

Code of Conduct

This project and everyone participating in it is governed by the Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to vscode@espressif.com.

License

This extension is licensed under the Apache License 2.0. Please see the LICENSE file for additional copyright notices and terms.