Skip to content

Latest commit

 

History

History
526 lines (474 loc) · 32.8 KB

FEATURES.md

File metadata and controls

526 lines (474 loc) · 32.8 KB
Raw

ESP-IDF Extension Features for Visual Studio Code

This extension provides many features to ease development of ESP-IDF Projects.

Commands

List of all the commands contributed by the extension

Here's the complete HTML table that combines the given information:

Command Description Description Keyboard Shortcuts (Mac) Keyboard Shortcuts (Windows/ Linux)
Add Arduino ESP32 as ESP-IDF Component Add Arduino-ESP32 as a ESP-IDF component in your current directory (${CURRENT_DIRECTORY}/components/arduino).
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 Remote - Containers extension
Add Editor coverage Parse your project GCOV Code coverage files to add color lines representing code coverage on currently opened source code file
Add OpenOCD rules file (For Linux users) Add OpenOCD permissions to /etc/udev/rules.d to allow OpenOCD execution.
Add vscode configuration folder Add .vscode files to the currently opened project directory. These include launch.json (for debugging), settings.json and c_cpp_properties.json for syntax highlight.
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
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
Clear eFuse Summary Clear the eFuse Summary tree from ESP Explorer EFUSEEXPLORER
Clear ESP-IDF Search Results Clear results from ESP Explorer Documentation Search Results
Clear Saved ESP-IDF Setups Clear existing esp-idf setups saved by the extension.
Configure ESP-IDF extension Open a window with a setup wizard to install ESP-IDF, IDF Tools and python virtual environment.
Configure Project SDKConfig for Coverage Set required values in your project SDKConfig to enable Code Coverage
Create project from Extension Template Create ESP-IDF using one of the extension template projects. ⌘ I C Ctrl E C
Create New ESP-IDF Component Create a new component in the current directory based on ESP-IDF component template
Dispose Current SDK Configuration Editor Server Process If you already executed the SDK Configuration editor, a cache process will remain in the background for faster re opening. 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.
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
Execute Custom Task User can define a command line command or script in idf.customTask which can be executed with this command. ⌘ I J Ctrl E J
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
Full Clean Project Delete the current ESP-IDF project build directory. ⌘ I X Ctrl E X
Get eFuse Summary Get list of eFuse and values from currently serial port chip.
Get HTML Coverage Report for project Parse your project GCOV Code coverage files to generate a HTML coverage report.
Import ESP-IDF Project Import an existing ESP-IDF project and add .vscode and .devcontainer files to a new location and also able to rename the project.
Install ESP-ADF Clone ESP-ADF inside the selected directory and set idf.espAdfPath (idf.espAdfPathWin in Windows) configuration setting.
Install ESP-IDF Python Packages (DEPRECATION NOTICE) Install extension python packages. Deprecated will be removed soon.
Install ESP-MDF Clone ESP-MDF inside the selected directory and set idf.espMdfPath (idf.espMdfPathWin in Windows) configuration setting.
Install ESP-Matter Clone ESP-Matter and set idf.espMatterPath. The ESP-IDF: Set ESP-MATTER Device Path (ESP_MATTER_DEVICE_PATH) is used to define the device path for ESP-Matter. ESP-Matter is not supported in Windows.
Install ESP-Rainmaker Clone ESP-Rainmaker and set idf.espRainmakerPath (idf.espRainmakerPathWin in Windows) configuration setting.
Install ESP-HomeKit-SDK Clone ESP-HomeKit-SDK inside the selected directory and set idf.espHomeKitSdkPath (idf.espHomeKitSdkPathWin in Windows) configuration setting.
Launch IDF Monitor for CoreDump / 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.
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 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
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.
New Project Launch UI with a ESP-IDF project creation wizard using examples templates from ESP-IDF and additional frameworks configured in the extension. ⌘ I N Ctrl E N
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
NVS Partition Editor Launch UI to create a CSV file for ESP_IDF Non Volatile Storage
Partition Table Editor Launch UI to manage custom partition table as described in ESP_IDF Partition Table
Pick a workspace folder when using a Visual Studio Code workspace with multiple workspace folders, this command allow you to select which workspace folder to use for this extension commands. More information in working with multiple projects.
Remove Editor coverage Remove editor colored lines from Add Editor coverage command
Run idf.py reconfigure task This command will execute idf.py reconfigure (CMake configure task). Useful when you need to generate compile_commands.json for the C/C++ language support.
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.
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
Search in documentation... Select some text from your source code file and search in ESP-IDF documentation with results right in the vscode 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.
Select Flash Method Select which flash method to use for Flash your project command. It can be DFU, JTAG or UART.
Select port to use Select which serial port to use for ESP-IDF tasks like flashing or monitor your device. ⌘ I P Ctrl E P
Select OpenOCD Board Configuration Select the openOCD configuration files that match your Espressif device target. For example if you are using DevKitC or ESP-Wrover-Kit. This is necessary for flashing with JTAG or debugging your device.
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.
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, show output, both or none of them.
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.
Set ESP-MATTER Device Path (ESP_MATTER_DEVICE_PATH) The ESP-IDF: Set ESP-MATTER Device Path (ESP_MATTER_DEVICE_PATH) is used to define the device path for ESP-Matter. ESP-Matter is not supported in Windows.
Show Examples Projects Launch UI to show examples from selected framework and allow you to create a project from them. This command will show frameworks already configured in the extension so if you want to see ESP-Rainmaker examples you need to run the Install ESP-Rainmaker first (or set the equivalent setting idf.espRainmakerPath) and then execute this command to see the examples.
Show Ninja Build Summary Execute the Chromium ninja-build-summary.py
Size analysis of the binaries Launch UI with the ESP-IDF project binaries size information. ⌘ I S Ctrl E S
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
Unit Test: Install ESP-IDF PyTest requirements Install the ESP-IDF Pytest requirements packages to be able to execute ESP-IDF Unit tests. More information in

Arduino as ESP-IDF Component

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.

Build

ESP-IDF: Build your Project is provided by this extension to 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.

Debugging

Click F5 to start debugging. To configure the debug behaviour, please review DEBUGGING.

NOTE For correct debug experience, first define the correct idf.customExtraPaths paths and idf.customExtraVars using SETUP, build your project, choose the right serial port, flash the program to your device.

CMakeLists.txt Editor

THIS WILL OVERRIDE ANY EXISTING CODE IN THE FILE WITH THE ONE GENERATED IN THE EDITOR. IF YOU HAVE ANY CODE NOT INCLUDED IN THE SCHEMA (OR SINGLE LINE COMMENTS) USE A REGULAR TEXT EDITOR INSTEAD

On CMakeLists.txt file right click this extension provides a custom CMakeLists.txt Editor to fill an ESP-IDF Project and Component registration as specified in ESP-IDF Project CMakeLists.txt and ESP-IDF Component CMakeLists.txt files. You need to choose which kind of CMakeLists.txt file (project or component) to edit. There is 2 types of input, one is a simple string and another is an array of strings, such as Component Sources (SRCS). All inputs are described in the CMakeLists.txt Schema (${this_repository}/src/cmake/cmakeListsSchema.json).

NOTE This editor doesn't support all CMake functions and syntaxes. This editor should only be used for simple CMakeLists.txt options such as component registration (using idf_component_register) and basic project elements. If you need more customization or advanced CMakeLists.txt, consider reviewing ESP-IDF Build System. Also review CMakeLists.txt Editor Schema for a list of supported code.

Custom Tasks

There are couple of custom tasks that you can implement by using one of these configuration settings:

  1. Set idf.customTask to define a custom task to be executed with ESP-IDF: Execute Custom Task command or the activity bar icon.
  2. Set idf.preBuildTask to define a custom task to be executed before ESP-IDF: Build your Project command task.
  3. Set idf.postBuildTask to define a custom task to be executed after ESP-IDF: Build your Project command task.
  4. Set idf.preFlashTask to define a custom task to be executed before Flash commands.
  5. Set idf.postFlashTask to define a custom task to be executed after Flash commands.

Flash

The commands Select Flash Method and Flash, Flash (With JTag) using OpenOCD and JTAG or Flash (UART) your Project using the ESP-IDF esptool.py as explained in ESP-IDF Build System Flash Arguments, are provided by this extension to flash your project. This command depends on the ${YOUR_PROJECT_DIR}/build/flasher_args.json file generated by Build and the idf.flashBaudRate configuration setting.

Kconfig Files Editor

When you open a Kconfig, Kconfig.projbuild or Kconfig.in file we provide syntax highlighting. If idf.useIDFKconfigStyle is enabled, we also provide ESP-IDF Kconfig style syntax validation such as indent validation and not closing blocks found (Example: menu-endmenu). Please review Kconfig Formatting Rules and Kconfig Language for further details about the ESP-IDF Kconfig formatting rules and Kconfig language in general.

Log & Heap Tracing

We support Log and Heap Tracing out of the box, which enables users to perform log/heap tracing with just few button clicks and present the results of tracing data with UI.

You can follow this quick step-by-step guide for Heap Tracing.

Monitor

ESP-IDF: Monitor Device is provided by this extension to start idf.py monitor terminal program in Visual Studio Code. Please take a look at the IDF Monitor Documentation.

In Visual Studio Code, for ESP-IDF: Monitor Device we use the shell executable given in vscode.env.shell which is override by terminal.integrated.shell.* in your Visual Studio Code Settings when using the Terminal: Select Default Shell command to update the shell or updating terminal.integrated.shell.windows for Windows, terminal.integrated.shell.osx for MacOS and terminal.integrated.shell.linux for Linux in VSCode Settings Preference menu (F1 -> Preferences: Open Settings (JSON)).

OpenOCD Server

you can start or stop the OpenOCD from Visual Studio Code using the ESP-IDF: OpenOCD Manager command or from the OpenOCD Server (Running | Stopped) button in the Visual Studio Code status bar. The output is shown in menu View -> Output -> OpenOCD. By default it will be launched using localhost, port 4444 for Telnet communication, port 6666 for TCL communication and port 3333 for Gdb.

Before using the OpenOCD server, you need to set the proper values for OpenOCD Configuration files in the idf.openOCDConfigs configuration setting. You can choose a specific board listed in OpenOCD using ESP-IDF: Select OpenOCD Board Configuration.

NOTE: you can modify openocd.tcl.host and openocd.tcl.port configuration settings to modify these values. Please review ESP-IDF Settings to see how to modify these configuration settings.

The resulting OpenOCD server launch command looks like this: openocd -d${idf.openOcdDebugLevel} -f ${idf.openOcdConfigs} ${idf.openOcdLaunchArgs}. The idf.openOcdDebugLevel is a number used to define the OpenOCD Log Level (0-4) and idf.openOcdLaunchArgs is a string array of any custom openOCD launch arguments you wants to use.

Partition Table Tree

Click theESP-IDF Explorer in the Activity Bar. On the Device Partition Explorer section, click the Refresh Partition Table icon or the ESP-IDF: Refresh Partition Table command in the Command Palette. This will get a list of the partitions listed in the Partition Table of your connected device and show them in the Device Partition Explorer section. When you can any partition, you can choose to either open the Partition Table Editor (only when custom partition table is enabled) or choose a binary (.bin) file to flash on the selected partition. You can also right click any .bin file and choose the partition in device to flash this partition.

SDK Configuration Editor

This extension includes a GUI Menuconfig using the ESP-IDF: SDK Configuration Editor command that reads your current project folder's sdkconfig file (if available, otherwise it would take default values) and start the ESP-IDF JSON Configuration Server process (confserver.py in ${IDF_PATH}/tools) that enables you to redefine ESP-IDF project and board configuration.

When you modify a parameter value, the value is send to the confserver.py process, which return the new value and other values modified to GUI Menuconfig and then update the values in the UI.

Values are not automatically saved to the SDKConfig file until you click save changes. You can cancel any changes and load the values from the SDKConfig file by clicking cancel changes. If you click set default the current SDKConfig file is replaced by a template SDKConfig file and then loaded into the GUI Menuconfig rendered values.

The search functionality allows to find a parameter by description, i.e the name that appears in the SDKConfig file.

An IDF GUI Menuconfig log in ESP-IDF Output (Menu View -> Output) is created to print all communications with ${idf.espIdfPath}\tools\confserver.py. It can be be used to track any errors.

NOTE: The ESP-IDF JSON Configuration Server is built from the project's build/config/kconfig_menus.json which is generated by the build system from ESP-IDF and user defined components Kconfig files on the first run of SDK Configuration Editor. This process takes a bit of time so we keep the process running in the background to speed things up. If you are making changes to any Kconfig files or you want to re-run the SDK Configuration Editor from scratch, you need to dispose the current process with the ESP-IDF: Dispose Current SDK Configuration Editor Server Process and run the ESP-IDF: SDK Configuration Editor again.

Set Espressif Device Target

The ESP-IDF: Set Espressif Device Target allows you to choose among Espressif different chips based on idf.py set-target.

When you use this command, the following files are set:

  • Choosing esp32 as IDF_TARGET will set idf.openOCDConfigs to ["interface/ftdi/esp32_devkitj_v1.cfg", "target/esp32.cfg"]
  • Choosing esp32s2 as IDF_TARGET will set idf.openOCDConfigs to ["interface/ftdi/esp32_devkitj_v1.cfg", "target/esp32s2.cfg"]
  • Choosing esp32s3 as IDF_TARGET will set idf.openOCDConfigs to ["interface/ftdi/esp32_devkitj_v1.cfg", "target/esp32s3.cfg"]
  • Choosing esp32c3 as IDF_TARGET will set idf.openOCDConfigs to ["board/esp32c3-builtin.cfg"] if using built-in usb jtag or ["board/esp32c3-ftdi.cfg"] if using ESP-PROG-JTAG.

System View Tracing Viewer

We have provide a System View Tracing Viewer inside the VS Code Extension which will enable you to view the traces along with other relevant details.