vscode-esp-idf-extension

# ESP-IDF Extension for VS Code [中文](./README_CN.md) 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 t