/vscode-esp-idf-extension

Visual Studio Code extension for ESP-IDF projects

Primary LanguageTypeScriptApache License 2.0Apache-2.0

espressif logo

ESP-IDF VS Code Extension

Documentation ESP32 Version Releases Forum

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

Make sure to review our documentation first to properly use the extension.

Quick User Guide for the ESP-IDF VS Code Extension

Table of content

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

Prerequisites

There are few dependencies required in your system and available in environment variable PATH before installing this extension. Please review ESP-IDF Prerequisites documentation.

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.

NOTE: If you are using Windows Subsystem for Linux (WSL) 2, please take a look at the additional requirements in WSL Documentation needed in the WSL distribution.

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

  • (OPTIONAL) Press F1 and type ESP-IDF: Select where to save configuration settings, which can be User settings, Workspace settings or workspace folder settings. Please take a look at Working with multiple projects for more information. Default is User settings.

  • On the first time using the extension, 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.

    NOTE: Please take a look at SETUP documentation or the Install tutorial for details about extension configuration.

  • Press F1 and type ESP-IDF: Show Examples Projects to create a new project from ESP-IDF examples.

  • Configure the .vscode/c_cpp_properties.json as explained in C/C++ Configuration. There is a default configuration that should work but you might want to modify it to your needs.

    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. If you are using one of our boards, use the ESP-IDF: Select OpenOCD Board Configuration to choose the openOCD configuration files for the extension openOCD server.

  • When you are ready, build your project by pressing F1 and typing ESP-IDF: Build your project.

  • 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 device activity in a Visual Studio Code terminal.

  • To make sure you can debug your device, select the your board by pressing F1 and typing ESP-IDF: Select OpenOCD Board Configuration or manually define the openOCD configuration files with idf.openOcdConfigs configuration in your settings.json.

  • 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).

Available commands

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

Command Description Keyboard Shortcuts (Mac) Keyboard Shortcuts (Windows/ Linux)
Add Arduino ESP32 as ESP-IDF Component
Add docker container configuration
Add Editor coverage
Add OpenOCD rules file (For Linux users)
Add vscode configuration folder
Build, Flash and start a monitor on your device ⌘ I D Ctrl E D
Build your project ⌘ I B Ctrl E B
Configure ESP-IDF extension
Configure Paths
Configure project sdkconfig for coverage
Create project from extension template ⌘ I C Ctrl E C
Create new ESP-IDF Component
Device configuration
Dispose current SDK Configuration editor server process
Doctor command
Erase flash memory from device ⌘ I R Ctrl E R
Flash your project ⌘ I F Ctrl E F
Full clean project ⌘ I X Ctrl E X
Get HTML Coverage Report for project
Import ESP-IDF Project
Install ESP-ADF
Install ESP-IDF Python Packages
Install ESP-MDF
Launch IDF Monitor for CoreDump / GDB-Stub Mode
Launch QEMU server
Launch QEMU debug session
Monitor your device ⌘ I M Ctrl E M
Monitor QEMU device
New Project ⌘ I N Ctrl E N
Open ESP-IDF Terminal ⌘ I T Ctrl E T
Open NVS Partition Editor
Pick a workspace folder
SDK Configuration editor ⌘ I G Ctrl E G
Search in documentation... ⌘ I Q Ctrl E Q
Select port to use ⌘ I P Ctrl E P
Select OpenOCD Board Configuration
Select where to save configuration settings
Set default sdkconfig file in project
Set Espressif device target
Show Examples Projects
Show ninja build summary
Size analysis of the binaries ⌘ I S Ctrl E S
Remove Editor coverage

About commands

  1. 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).

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

  2. 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.

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

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

  5. 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 correctly defined.

Commands for tasks.json and launch.json

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

"miDebuggerPath": "${command:espIdf.getXtensaGdb}"
  • 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.

See an example in the debugging documentation.

Available Tasks in tasks.json

A template Tasks.json is included when creating a project using ESP-IDF: Create project from extension template. These tasks can be executed by running 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: Use idf.openOcdDebugLevel to 3 or more to show debug logging in OpenOCD server output.

  1. In Visual Studio Code select menu "View" -> Output -> ESP-IDF, ESP-IDF Debug Adapter, Heap Trace, OpenOCD and SDK Configuration Editor.
  2. Use the ESP-IDF: Doctor command to generate a report of your 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

  1. In Visual Studio Code, select menu "Help" -> Toggle Developer Tools and copy any error in the Console tab related to this extension.

  2. Make sure that your extension is properly configured as described in JSON Manual Configuration. Visual Studio Code allows the user to configure settings at different levels: Global (User Settings), Workspace and WorkspaceFolder. The doctor command might give the values from user settings instead of the workspace folder settings.

If there is any Python package error, please try to reinstall the required python packages with the ESP-IDF: Install ESP-IDF Python Packages command.

If the user can't resolve the error, please search in the github repository issues for existing errors or open a new issue here.

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.