diff --git a/.github/workflows/pr-comment.yml b/.github/workflows/pr-comment.yml index b428b71f8..150f48898 100644 --- a/.github/workflows/pr-comment.yml +++ b/.github/workflows/pr-comment.yml @@ -49,6 +49,7 @@ jobs: return core.error(`No artifacts found`); } let body = `Download the artifacts for this pull request:\n`; + body += `You can test these changes by installing this VSIX by click menu `View` -> `Command Palette...`, type `Install from VSIX` and then select downloaded `esp-idf-extension.vsix` file to install the extension.`; for (const art of artifacts) { body += `\n* [${art.name}.zip](https://nightly.link/${owner}/${repo}/actions/artifacts/${art.id}.zip)`; } @@ -56,7 +57,7 @@ jobs: core.info("Review thread message body:", body); for (const pr of pull_requests) { - body += `\n [Espressif docs preview](https://preview-docs.espressif.com/projects/vscode-esp-idf-extension/en/${pr.number}-merge/index.html)`; + body += `\n [Espressif documentation preview](https://preview-docs.espressif.com/projects/vscode-esp-idf-extension/en/${pr.number}-merge/index.html)`; await upsertComment(owner, repo, pr.number, "nightly-link", body); } diff --git a/README.md b/README.md index 0e217c429..897dbcd2c 100644 --- a/README.md +++ b/README.md @@ -2,128 +2,123 @@ espressif logo -# ESP-IDF Visual Studio Code Extension +# ESP-IDF Extension for VSCode [![Tutorials](https://img.shields.io/badge/-Tutorials-red)](./docs/tutorial/toc.md) -[![Documentation](https://img.shields.io/badge/Documentation-blue)](./docs/ONBOARDING.md) +[![Espressif Documentation](https://img.shields.io/badge/Documentation-red)](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/) [![Troubleshooting](https://img.shields.io/badge/Troubleshooting-red)](./README.md#Troubleshooting) [![ESP32](https://img.shields.io/badge/Supported%20Chips-red)](./docs/HARDWARE_SUPPORT.md) ![Version](https://img.shields.io/github/package-json/v/espressif/vscode-esp-idf-extension) [![Releases](https://img.shields.io/badge/Github-Releases-blue)](https://github.com/espressif/vscode-esp-idf-extension/releases) [![Forum](https://img.shields.io/badge/Forum-esp32.com-blue)](https://esp32.com/viewforum.php?f=40) -Develop, build, flash, monitor, [debug](./docs/DEBUGGING.md) and [more](./docs/FEATURES.md) with Espressif chips using Espressif IoT Development Framework [(ESP-IDF)](https://github.com/espressif/esp-idf) +Develop, build, flash, monitor, debug and [more](./docs/FEATURES.md) with Espressif chips using Espressif IoT Development Framework [(ESP-IDF)](https://github.com/espressif/esp-idf). -**Nightly builds** 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. +**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 [documentation](./docs/ONBOARDING.md) first to properly use the extension. +Make sure to review our [Espressif documentation](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/) or [Github documentation](./docs/ONBOARDING.md) 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 requirements for your operating system: +2. Install ESP-IDF system prerequisites for your operating system: -- For Windows the [C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools) might be required. -- Requirements for [MacOS](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/macos-setup.html#install-prerequisites) -- Requirements for [Linux](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/linux-setup.html#install-prerequisites) +- Prerequisites for [MacOS](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/macos-setup.html#install-prerequisites) +- Prerequisites for [Linux](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/linux-setup.html#install-prerequisites) +- 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: 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. - -6. (OPTIONAL) Press F1 and type **ESP-IDF: Select where to Save Configuration Settings**, which can be User Settings (global), Workspace Settings or Workspace Folder Settings. Default is User settings. +5. Install the extension. After you install the extension, the ![Espressif icon](./media/readme/espressifIcon.png) 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 the basic commands provided by this extension. - > **NOTE:** Please take a look at [Working with multiple projects](./docs/MULTI_PROJECTS.md) for more information. +

+ Commands list +

-7. In Visual Studio Code, select menu "View" and "Command Palette" and type `Configure ESP-IDF Extension`. After, choose the **ESP-IDF: Configure ESP-IDF Extension** option. +6. From the command list select **Configure ESP-IDF Extension** or press F1 and type `Configure ESP-IDF Extension`. After, choose the **ESP-IDF: Configure ESP-IDF Extension** option. > **NOTE:** For versions of ESP-IDF < 5.0, spaces are not supported inside configured paths.

- Select ESP-IDF + Select ESP-IDF

-8. Choose **Express** and select the download server: +7. Choose **Express** and select the download server: - Espressif: Faster speed in China using Espressif Download servers links. - Github: Using github releases links. -9. Pick an ESP-IDF version to download or the `find ESP-IDF in your system` option to search for existing ESP-IDF directory. +8. Pick an ESP-IDF version to download or the `Find ESP-IDF in your system` option to search for existing ESP-IDF directory. -10. Choose the location for ESP-IDF Tools (also known as `IDF_TOOLS_PATH`) which is `$HOME\.espressif` on MacOS/Linux and `%USERPROFILE%\.espressif` on Windows by default. +9. Choose the location for ESP-IDF Tools (also known as `IDF_TOOLS_PATH`) which is `$HOME\.espressif` on MacOS/Linux and `%USERPROFILE%\.espressif` on Windows by default. -11. If your operating system is MacOS/Linux, choose the python executable to create ESP-IDF virtual environment. +10. If your operating system is MacOS/Linux, choose the system python executable to create ESP-IDF virtual environment inside ESP-IDF Tools and install ESP-IDF python package there. - > **NOTE:** Windows users don't need to select a python executable since it is part of the setup. - > **NOTE:** Make sure that `IDF_TOOLS_PATH` doesn't have any spaces to avoid any build issues. Also make sure that `IDF_TOOLS_PATH` is not the same directory as `IDF_PATH`. + > **NOTE:** Windows users don't need to select a python executable since it is going to be installed by this setup. + +11. Make sure that `IDF_TOOLS_PATH` doesn't have any spaces to avoid any build issues. Also make sure that `IDF_TOOLS_PATH` is not the same directory as `IDF_PATH`. 12. You will see a page showing the setup progress status showing ESP-IDF download progress, ESP-IDF Tools download and install progress as well as the creation of a python virtual environment. -13. If everything is installed correctly, you will see a message that all settings have been configured. You can start using the extension. Otherwise check the [Troubleshooting](#Troubleshooting) section if you have any issues. +13. 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 VSCode + +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. -14. Press F1 and type **ESP-IDF: Show Examples Projects** to create a new project from ESP-IDF examples. Select ESP-IDF and choose an example to create a new project from. +

+ Status bar +

-15. (OPTIONAL) Configure the `.vscode/c_cpp_properties.json` as explained in [C/C++ Configuration](./docs/C_CPP_CONFIGURATION.md). +These icons will be used in the steps below showing common ESP-IDF use cases: -> **Note:** For code navigation the [Microsoft C/C++ Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) or [Clangd extension](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd) can be used for C/C++ language support. By default, projects created with **ESP-IDF: Create Project from Extension Template** or **ESP-IDF: Show Examples Projects** include a template for Microsoft C/C++ extension `c_cpp_properties.json` configuration file and doesn't need to be configured. Run **ESP-IDF: Run idf.py reconfigure task** to generate the compile_commands.json file so language support works. +1. Press F1 and type **ESP-IDF: Show Examples Projects** to create a new project from ESP-IDF examples. Select ESP-IDF and choose an example to create a new project from. -16. Set the serial port of your device by pressing F1, typing **ESP-IDF: Select Port to Use:** and choosing the serial port your device is connected. +2. Once the project is created and opened in VS Code, Set the serial port of your device by pressing status bar icon ![serial port](./media/readme/serialport.png) or F1, typing **ESP-IDF: Select Port to Use:** and choosing the serial port your device is connected. -17. Select an Espressif target (esp32, esp32s2, etc.) with the **ESP-IDF: Set Espressif Device Target** command. +3. Select an Espressif target (esp32, esp32s2, etc.) by pressing status bar icon ![IDF Target](./media/readme/target.png) or F1 and type **ESP-IDF: Set Espressif Device Target** command. -18. Use the **ESP-IDF: Select OpenOCD Board Configuration** to choose the OpenOCD configuration files for the extension OpenOCD server. +4. Next configure your ESP-IDF project by pressing status bar icon ![sdkconfig editor](./media/readme/sdkconfig.png) 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. -19. Next configure your ESP-IDF project by pressing 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. +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](./docs/C_CPP_CONFIGURATION.md) documentation. -20. When you are ready, build your project by pressing F1 and typing **ESP-IDF: Build your Project**. +6. At this point you can modify the code and when the project is completed, build your project by pressing status bar icon ![build](./media/readme/build.png) or press F1 and typing **ESP-IDF: Build your Project**. -21. Flash to your device by pressing F1 and typing **ESP-IDF: Select Flash Method** to select either `UART`, `DFU` or `JTAG` depending on your serial connection. +7. Flash to your device by pressing status bar icon ![flash](./media/readme/flash.png) or F1 and typing **ESP-IDF: Flash your project** to select either `UART`, `DFU` or `JTAG` depending on your serial connection, and start flashing the application to your device. -> **NOTE:** You can also use the **ESP-IDF: Flash (UART) your Project** or **ESP-IDF: Flash (with JTag)** directly. +8. Change the flash method pressing status bar icon ![flash method](./media/readme/flashmethod.png) or F1 and typing **ESP-IDF: Select Flash Method** to select either `UART`, `DFU` or `JTAG`. You can alternatively use the **ESP-IDF: Flash (UART) your Project**, **ESP-IDF: Flash (with JTag)** or **ESP-IDF: Flash (DFU) your project**. -22. Start a monitor by pressing F1 and typing **ESP-IDF: Monitor Device** which will log the device activity in a Visual Studio Code terminal. +9. Start a monitor by pressing status bar icon ![monitor](./media/readme/monitor.png) or F1 and typing **ESP-IDF: Monitor Device** which will log the device activity in a Visual Studio Code terminal. -23. To make sure you can debug your device, select your board configuration by pressing F1 and typing **ESP-IDF: Select OpenOCD Board Configuration**. You can test the connection by 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. +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, select the device OpenOCD board configuration files by pressing F1 and typing **ESP-IDF: Select OpenOCD Board Configuration**. You can test the connection by pressing status bar icon ![openocd](./media/readme/openocd.png) or 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 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. -24. If you want to start a debug session, just press `F5` (make sure you had at least build, flash and OpenOCD is connecting correctly so the debugger works correctly). +12. If you want to start a debug session, just press `F5` (make sure you had at least build, flash and OpenOCD is connecting correctly so the debugger works correctly). The debug session output can be seen in the menu `View` -> `Debug Console`. Check the [Troubleshooting](#Troubleshooting) section if you have any issues. -# Tutorials - -1. [Install and setup the extension](./docs/tutorial/install.md). -2. [Create a project from ESP-IDF examples, Build, flash and monitor](./docs/tutorial/basic_use.md). -3. [Debugging](./docs/tutorial/debugging.md) with steps to configure OpenOCD and debug adapter. -4. [Heap tracing](./docs/tutorial/heap_tracing.md) -5. [Code coverage](./docs/tutorial/code_coverage.md) -6. [Developing on Docker Container](./docs/tutorial/using-docker-container.md) -7. [Developing on WSL](./docs/tutorial/wsl.md) +# Further reading -Check all the tutorials [here](./docs/tutorial/toc.md). +You can find a list of tutorials, commands and documentation about all features in depth below. -# Table of content +- Check the extension [Espressif documentation](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/). -- [ESP-IDF Visual Studio Code Extension](./README.md#esp-idf-visual-studio-code-extension) -- [Tutorials](./README.md#tutorials) -- [Table of content](./README.md#table-of-content) -- [How to use](./README.md#how-to-use) -- [Available commands](./README.md#available-commands) -- [About commands](./README.md#about-commands) -- [Commands for tasks.json and launch.json](./README.md#commands-for-tasksjson-and-launchjson) -- [Available Tasks in tasks.json](./README.md#available-tasks-in-tasksjson) -- [Troubleshooting](./README.md#troubleshooting) -- [Code of Conduct](./README.md#code-of-conduct) -- [License](./README.md#license) +- Check all the extension [tutorials](./docs/tutorial/toc.md). -Check all the [documentation](./docs/ONBOARDING.md). +- Check all the extension [github documentation](./docs/ONBOARDING.md). -# Available commands +## All Available commands -Click F1 to show Visual studio code actions, then type **ESP-IDF** to see all possible actions. +Click F1 or click menu `View` -> `Command Palette...` to show Visual studio code commands, then type **ESP-IDF** to see all possible extension commands. @@ -137,14 +132,7 @@ Click F1 to show Visual studio code actions, then type **ESP-IDF** to - - - - - - - - + @@ -562,25 +550,7 @@ Click F1 to show Visual studio code actions, then type **ESP-IDF** to
ConfigurationAdd OpenOCD rules file (For Linux users)Add OpenOCD permissions to /etc/udev/rules.d to allow OpenOCD execution.
Add Docker Container ConfigurationAdd 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
-# About commands - -1. The **Add Arduino-ESP32 as ESP-IDF Component** command will add [Arduino-ESP32](https://github.com/espressif/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](https://github.com/espressif/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-Matter** will clone ESP-Matter inside the selected directory and set `idf.espMatterPath` configuration setting. 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**. Make sure to install Matter system prerequisites first. - -5. The **Install ESP-MDF** will clone ESP-MDF inside the selected directory and set `idf.espMdfPath` (`idf.espMdfPathWin` in Windows) configuration setting. - -6. The **Install ESP-HomeKit-SDK** will clone ESP-HomeKit-SDK inside the selected directory and set `idf.espHomeKitSdkPath` (`idf.espHomeKitSdkPathWin` in Windows) configuration setting. - -7. The **Show Examples Projects** command allows you create a new project using one of the examples in ESP-IDF, ESP-ADF, ESP-Matter, ESP-HomeKit-SDK or ESP-MDF directory if related configuration settings are correctly defined. - -# Commands for tasks.json and launch.json +## 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: @@ -597,7 +567,7 @@ We have implemented some utilities commands that can be used in tasks.json and l See an example in the [debugging](./docs/DEBUGGING.md) documentation. -# Available Tasks in tasks.json +## 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: @@ -621,7 +591,7 @@ If something is not working please check for any error on one of these: > **NOTE:** Use `logLevel` in your /.vscode/launch.json to 3 or more to show more 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. +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` @@ -633,7 +603,9 @@ If something is not working please check for any error on one of these: 6. Review the [OpenOCD troubleshooting FAQ](https://github.com/espressif/OpenOCD-esp32/wiki/Troubleshooting-FAQ) related to the `OpenOCD` output, for application tracing, debug or any OpenOCD related issues. -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. Please consider that this extension install ESP-IDF, this extension's and ESP-IDF Debug Adapter python packages when running the **ESP-IDF: Configure ESP-IDF Extension** setup wizard. +7. In some cases that 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 build flash and monitor. 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: Install ESP-IDF Python Packages** command or running the setup again with the **ESP-IDF: Configure ESP-IDF Extension** command. > **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. diff --git a/docs/C_CPP_CONFIGURATION.md b/docs/C_CPP_CONFIGURATION.md index 82a24087a..ab64da34e 100644 --- a/docs/C_CPP_CONFIGURATION.md +++ b/docs/C_CPP_CONFIGURATION.md @@ -1,3 +1,7 @@ +For code navigation the [Microsoft C/C++ Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) or [Clangd extension](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd) can be used for C/C++ language support. By default, projects created with **ESP-IDF: Create Project from Extension Template** or **ESP-IDF: Show Examples Projects** include a template for Microsoft C/C++ extension `c_cpp_properties.json` configuration file and doesn't need to be configured. + +Run **ESP-IDF: Run idf.py reconfigure task** to generate the **compile_commands.json** file so language support works. + # Configuration of c_cpp_properties.json File The [C/C++ Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) can be used to provide C and C++ syntax highlight, code navigation and Go to declaration/definition within C and C++ files. diff --git a/docs/DEBUGGING.md b/docs/DEBUGGING.md index 589d7bc03..144bfced6 100644 --- a/docs/DEBUGGING.md +++ b/docs/DEBUGGING.md @@ -2,6 +2,8 @@ > **NOTE:** 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. +> **NOTE:** For Linux users, make sure to copy the [udev rules files](https://github.com/espressif/openocd-esp32/blob/master/contrib/60-openocd.rules) into the `/etc/udev/rules.d` directory. + > **NOTE:** Please take a look first at [ESP-IDF JTAG Debugging](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/index.html#how-it-works). > OpenOCD typically uses port 4444 for Telnet communication, port 6666 for TCL communication and port 3333 for gdb. @@ -13,6 +15,31 @@ Our extension implements a `ESP-IDF: Peripheral View` tree view in the `Run and If `initCommands`, `gdbinitFile` or `initGdbCommands` are defined in launch.json, make sure to include the following commands for debug session to properly work as shown in [JTAG Debugging with command line](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/using-debugger.html#command-line). +# Setting a custom application image offset + +If you modify the application image offset you need to modify openOCD launch arguments to update the application image offset. This can happens if OpenOCD output (Menu View -> Output -> `ESP-IDF`) shows an error like this: + +``` + Failed to get flash maps (-6)!\n❌ Error: Failed to get flash maps (-6)!\nWarn : Application image is invalid! Check configured binary flash offset 'appimage_offset'. +``` + +To update openOCD launch arguments, open the project's `settings.json` and add or modify: + +```json +{ + "idf.openOcdLaunchArgs": [ + "-c", + "init", + "-c", + "reset halt", + "-c", + "esp appimage_offset 0x20000" + ] +} +``` + +where `0x20000` is your application image offset used in the partition table. + ## Using the Eclipse CDT GDB Debug Adapter The Eclipse CDT team have published a GDB debug adapter as NPM package which we include in our extension dependencies. For more information about the debug adapter please review [CDT-GDB-Adapter Github Repository](https://github.com/eclipse-cdt-cloud/cdt-gdb-adapter). diff --git a/docs/FEATURES.md b/docs/FEATURES.md index f76addadb..8f4ac9925 100644 --- a/docs/FEATURES.md +++ b/docs/FEATURES.md @@ -60,12 +60,6 @@ Here's the complete HTML table that combines the given information: - - 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. diff --git a/docs/HARDWARE_SUPPORT.md b/docs/HARDWARE_SUPPORT.md index 84e62b125..b3ad1bd14 100644 --- a/docs/HARDWARE_SUPPORT.md +++ b/docs/HARDWARE_SUPPORT.md @@ -1,14 +1,5 @@ # Current Chips Supported in this Extension -[ESP32](https://www.espressif.com/en/products/socs/esp32) -[ESP32-C2](https://www.espressif.com/en/products/socs/esp32-c2) -[ESP32-C3](https://www.espressif.com/en/products/socs/esp32-c3) -[ESP32-C6](https://www.espressif.com/en/products/socs/esp32-c6) -[ESP32-S2](https://www.espressif.com/en/products/socs/esp32-s2) -[ESP32-S3](https://www.espressif.com/en/products/socs/esp32-s3) -[ESP32-H2](https://www.espressif.com/en/products/socs/esp32-h2) -[ESP32-P4](https://www.espressif.com/en/products/socs/esp32-p4) - The chips supported in the extension are directly dependent on the ESP-IDF and OpenOCD version you are using: - The list of OpenOCD configuration boards is obtained from `$OPENOCD_SCRIPTS/esp-config.json` where `$OPENOCD_SCRIPTS` is your OpenOCD Scripts path. diff --git a/docs/tutorial/debugging.md b/docs/tutorial/debugging.md index 62af1f37a..83e4ebc07 100644 --- a/docs/tutorial/debugging.md +++ b/docs/tutorial/debugging.md @@ -9,6 +9,8 @@ This tutorial shows you how to debug ESP-IDF projects using the Visual Studio Co > **NOTE:** Please take a look at [Configuring of OpenOCD for specific target](https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-guides/jtag-debugging/tips-and-quirks.html#configuration-of-openocd-for-specific-target) for more information about these configuration files. +> **NOTE:** For Linux users, make sure to copy the [udev rules files](https://github.com/espressif/openocd-esp32/blob/master/contrib/60-openocd.rules) into the `/etc/udev/rules.d` directory. + 3. With the blink example folder open in your visual studio code window, press F5. Several steps will be automatically done for you but explained for clarity. You can skip to step 6 to continue the debug tutorial part. @@ -27,6 +29,31 @@ Several steps will be automatically done for you but explained for clarity. You Initial halted

+# Setting a custom application image offset + +If you modify the application image offset you need to modify openOCD launch arguments to update the application image offset. This can happens if OpenOCD output (Menu View -> Output -> `ESP-IDF`) shows an error like this: + +``` + Failed to get flash maps (-6)!\n❌ Error: Failed to get flash maps (-6)!\nWarn : Application image is invalid! Check configured binary flash offset 'appimage_offset'. +``` + +To update openOCD launch arguments, open the project's `settings.json` and add or modify: + +```json +{ + "idf.openOcdLaunchArgs": [ + "-c", + "init", + "-c", + "reset halt", + "-c", + "esp appimage_offset 0x20000" + ] +} +``` + +where `0x20000` is your application image offset used in the partition table. + # Navigating Through the Code, Call Stack and Threads 7. When the target is halted, the editor will show the line of code where the program halted and the list of threads in the `Call Stack` sub-window `(a)` on the `Run` icon in the Activity Bar on the side of Visual Studio Code. The first line of call stack under main `(b)` contains the last called function `app_main()`, which in turned was called from `main_task()` as shown in the previous image. Each line of the stack also contains the file name and line number `(c)` where the function was called. By clicking on each of the stack entries, you will see the file opened. diff --git a/docs/tutorial/install.md b/docs/tutorial/install.md index aa084dc4b..7680cb179 100644 --- a/docs/tutorial/install.md +++ b/docs/tutorial/install.md @@ -76,7 +76,7 @@ To install the nightly build follow the instructions below. Nightly builds are available for Visual Studio Code or OpenVSX. - Open VS Code -- Go to Extensions +- Click menu `View` and then `Extensions` - Click on the `...` from the top and choose `Install from VSIX...` - Browse to the VSIX file you downloaded - Wait for the extension to install diff --git a/docs/tutorial/using-docker-container.md b/docs/tutorial/using-docker-container.md index 630c67773..358b0136d 100644 --- a/docs/tutorial/using-docker-container.md +++ b/docs/tutorial/using-docker-container.md @@ -251,7 +251,7 @@ the interface is the same as [Internal USB-serial](#internal-usb-serial), that i ### Additional steps for debugging -Make sure to run `ESP-IDF: Add OpenOCD rules file (For Linux users)` command to add OpenOCD rules in the docker container before running OpenOCD and starting a debug session. +Make sure to copy the [OpenOCD udev rules files](https://github.com/espressif/openocd-esp32/blob/master/contrib/60-openocd.rules) into the `/etc/udev/rules.d` directory before running OpenOCD and starting a debug session. ## Debugging diff --git a/docs/tutorial/wsl.md b/docs/tutorial/wsl.md index 77cfbadea..0c09d4db9 100644 --- a/docs/tutorial/wsl.md +++ b/docs/tutorial/wsl.md @@ -190,7 +190,7 @@ the interface is the same as [Internal USB-serial](#internal-usb-serial), that i ### Additional steps for debugging -Make sure to run `ESP-IDF: Add OpenOCD rules file (For Linux users)` command to add OpenOCD rules in the WSL before running OpenOCD and starting a debug session. +Make sure to copy the [OpenOCD udev rules files](https://github.com/espressif/openocd-esp32/blob/master/contrib/60-openocd.rules) into the `/etc/udev/rules.d` directory before running OpenOCD and starting a debug session. ## Debugging diff --git a/docs_espressif/en/additionalfeatures/docker-container.rst b/docs_espressif/en/additionalfeatures/docker-container.rst index 33ec7a590..e39a1afa8 100644 --- a/docs_espressif/en/additionalfeatures/docker-container.rst +++ b/docs_espressif/en/additionalfeatures/docker-container.rst @@ -285,7 +285,7 @@ USB-JTAG for Docker container Debugging in Docker Container ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- Make sure to run **ESP-IDF: Add OpenOCD rules file (For Linux users)** command to add OpenOCD rules in the docker container before running OpenOCD and starting a debug session. +- Make sure to copy the `OpenOCD udev rules files `_ into the ``/etc/udev/rules.d`` directory before running OpenOCD and starting a debug session. - After following `USB-JTAG for Docker container`_, press ``F5`` to start to debug: diff --git a/docs_espressif/en/additionalfeatures/wsl.rst b/docs_espressif/en/additionalfeatures/wsl.rst index 3235f45f8..eb95573ec 100644 --- a/docs_espressif/en/additionalfeatures/wsl.rst +++ b/docs_espressif/en/additionalfeatures/wsl.rst @@ -198,14 +198,14 @@ Same as `External USB-Serial`_ and `Internal USB-serial`_, but it needs to confi .. image:: ../../../media/tutorials/using_docker_container/extra_parameters.png -the interface is the same as [Internal USB-serial](#internal-usb-serial), that is ``ttyACMx``: +the interface is the same as `Internal USB-serial`_, that is ``ttyACMx``: .. image:: ../../../media/tutorials/using_docker_container/container_flash_jtag.gif Additional steps for debugging ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Make sure to run **ESP-IDF: Add OpenOCD rules file (For Linux users)** command to add OpenOCD rules in the docker container before running OpenOCD and starting a debug session. +Make sure to copy the `OpenOCD udev rules files `_ into the ``/etc/udev/rules.d`` directory before running OpenOCD and starting a debug session. Debugging ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs_espressif/en/commands.rst b/docs_espressif/en/commands.rst index 97d807771..e1991656d 100644 --- a/docs_espressif/en/commands.rst +++ b/docs_espressif/en/commands.rst @@ -13,9 +13,7 @@ All commands start with ``ESP-IDF:``. * - 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. + - Parse your project `GCOV Code coverage `_ files to add color lines representing code coverage on currently opened source code file. * - 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 diff --git a/docs_espressif/en/debugproject.rst b/docs_espressif/en/debugproject.rst index ee65a5794..0f2bf1b3d 100644 --- a/docs_espressif/en/debugproject.rst +++ b/docs_espressif/en/debugproject.rst @@ -8,27 +8,29 @@ Table of Content (ToC) 2. :ref:`What happens in the background?` -3. :ref:`Navigating Through the Code, Call Stack and Threads` +3. :ref:`Setting a custom application image offset` -4. :ref:`Setting and Clearing Breakpoints` +4. :ref:`Navigating Through the Code, Call Stack and Threads` -5. :ref:`Halting the Target Manually` +5. :ref:`Setting and Clearing Breakpoints` -6. :ref:`Stepping Through the Code` +6. :ref:`Halting the Target Manually` -7. :ref:`Watching and Setting Program Variables` +7. :ref:`Stepping Through the Code` -8. :ref:`Setting Conditional Breakpoint` +8. :ref:`Watching and Setting Program Variables` -9. :ref:`Disassembly view` +9. :ref:`Setting Conditional Breakpoint` -10. :ref:`Watchpoints (Data Breakpoints)` +10. :ref:`Disassembly view` -11. :ref:`Send commands to GDB` +11. :ref:`Watchpoints (Data Breakpoints)` -12. :ref:`ESP-IDF: Peripheral View` +12. :ref:`Send commands to GDB` -13. :ref:`Post-mortem debug use cases` +13. :ref:`ESP-IDF: Peripheral View` + +14. :ref:`Post-mortem debug use cases` Start a debug session @@ -52,6 +54,8 @@ Before debbugging the project, you needs to specify the serial port of the devic * Please review `Configuration of OpenOCD for Specific Target `_ to understand which board or configuration to use for your specific hardware. * Make sure to configure your drivers as mentioned in ESP-IDF `Configure JTAG Interface `_ documentation. +- (Linux users) Make sure to copy the `OpenOCD udev rules files `_ into the ``/etc/udev/rules.d`` directory before running OpenOCD and starting a debug session. + To start debugging select menu **Run** and **Start Debugging** or just press F5. .. image:: ../../media/tutorials/debug/init_halted.png @@ -78,6 +82,34 @@ By default it will be launched using localhost, port ``4444`` for Telnet communi This adapter is a middle man between Visual Studio Code, configured toolchain GDB and OpenOCD server. You can see how `Espressif chips debugging works `_ and how Visual Studio Code use `Debug adapters `_ to communicate with many debug tools. +Setting a custom application image offset +------------------------------------------------------------- + +If you modify the application image offset you need to modify openOCD launch arguments to update the application image offset. This can happens if OpenOCD output (Menu View -> Output -> `ESP-IDF`) shows an error like this: + +.. code-block:: + + Failed to get flash maps (-6)! + ❌ Error: Failed to get flash maps (-6)! + Warn : Application image is invalid! Check configured binary flash offset 'appimage_offset'. + +To update openOCD launch arguments, open the project's ``.vscode/settings.json`` and add or modify: + +.. code-block:: JSON + + { + "idf.openOcdLaunchArgs": [ + "-c", + "init", + "-c", + "reset halt", + "-c", + "esp appimage_offset 0x20000" + ] + } + +where ``0x20000`` is your application image offset used in the partition table. + Navigating Through the Code, Call Stack and Threads ------------------------------------------------------- diff --git a/media/readme/build.png b/media/readme/build.png new file mode 100644 index 000000000..12ef41baf Binary files /dev/null and b/media/readme/build.png differ diff --git a/media/readme/commandsList.png b/media/readme/commandsList.png new file mode 100644 index 000000000..8d534c0de Binary files /dev/null and b/media/readme/commandsList.png differ diff --git a/media/readme/espressifIcon.png b/media/readme/espressifIcon.png new file mode 100644 index 000000000..337746a10 Binary files /dev/null and b/media/readme/espressifIcon.png differ diff --git a/media/readme/flash.png b/media/readme/flash.png new file mode 100644 index 000000000..eecff7a6f Binary files /dev/null and b/media/readme/flash.png differ diff --git a/media/readme/flashmethod.png b/media/readme/flashmethod.png new file mode 100644 index 000000000..b59489d79 Binary files /dev/null and b/media/readme/flashmethod.png differ diff --git a/media/readme/monitor.png b/media/readme/monitor.png new file mode 100644 index 000000000..a18889e94 Binary files /dev/null and b/media/readme/monitor.png differ diff --git a/media/readme/openocd.png b/media/readme/openocd.png new file mode 100644 index 000000000..4407a5aaa Binary files /dev/null and b/media/readme/openocd.png differ diff --git a/media/readme/sdkconfig.png b/media/readme/sdkconfig.png new file mode 100644 index 000000000..3cb5581e7 Binary files /dev/null and b/media/readme/sdkconfig.png differ diff --git a/media/readme/serialport.png b/media/readme/serialport.png new file mode 100644 index 000000000..1efe06e2d Binary files /dev/null and b/media/readme/serialport.png differ diff --git a/media/readme/setup.png b/media/readme/setup.png new file mode 100644 index 000000000..38e04fe62 Binary files /dev/null and b/media/readme/setup.png differ diff --git a/media/readme/statusBar.png b/media/readme/statusBar.png new file mode 100644 index 000000000..1721d5171 Binary files /dev/null and b/media/readme/statusBar.png differ diff --git a/media/readme/target.png b/media/readme/target.png new file mode 100644 index 000000000..1d01238d9 Binary files /dev/null and b/media/readme/target.png differ diff --git a/media/youtube_tutorial_preview.png b/media/youtube_tutorial_preview.png deleted file mode 100644 index da3aed652..000000000 Binary files a/media/youtube_tutorial_preview.png and /dev/null differ