Make the readme easy to follow (#1295)

* update readme documentation * add note for debug custom app img offset * update debugging doc * review changes * rm add openocd udev rules non existing cmd from doc
espressif · Sep 30, 2024 · 209f7a4 · 209f7a4
1 parent eef0677
commit 209f7a4
Show file tree

Hide file tree

Showing 27 changed files with 172 additions and 126 deletions.
diff --git a/.github/workflows/pr-comment.yml b/.github/workflows/pr-comment.yml
@@ -49,14 +49,15 @@ 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)`;
             }
 
             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
diff --git 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
@@ -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
@@ -60,12 +60,6 @@ Here's the complete HTML table that combines the given information:
             <td></td>
             <td></td>
         </tr>
-        <tr>
-            <td>Add OpenOCD rules file (For Linux users)</td>
-            <td>Add OpenOCD permissions to /etc/udev/rules.d to allow OpenOCD execution.</td>
-            <td></td>
-            <td></td>
-        </tr>
         <tr>
             <td>Add vscode configuration folder</td>
             <td>Add <strong>.vscode</strong> files to the currently opened project directory. These include launch.json (for debugging), settings.json and c_cpp_properties.json for syntax highlight.</td>

diff --git 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
@@ -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
   <img src="../../media/tutorials/debug/init_halted.png" alt="Initial halted" height="500">
 </p>
 
+# 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
@@ -76,7 +76,7 @@ To install the nightly build follow the instructions below.
 Nightly builds are available for <a href="https://nightly.link/espressif/vscode-esp-idf-extension/workflows/ci/master/esp-idf-extension.vsix.zip">Visual Studio Code</a> or <a href="https://nightly.link/espressif/vscode-esp-idf-extension/workflows/ci/master/esp-idf-extension-open.vsix.zip">OpenVSX</a>.
 
 - 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
@@ -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
@@ -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
@@ -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 <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.
 
 - 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
@@ -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 <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/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 <https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers>`_ extension
    * - Add Editor coverage
-     - Parse your project `GCOV Code coverage <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/app_trace.html#gcov-source-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 <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/app_trace.html#gcov-source-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
@@ -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 <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/tips-and-quirks.html#jtag-debugging-tip-openocd-configure-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 <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/configure-ft2232h-jtag.html>`_ documentation.
 
+- (Linux users) 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.
+
 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 <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/index.html#how-it-works>`_ and how Visual Studio Code use `Debug adapters <https://microsoft.github.io/debug-adapter-protocol/overview>`_ 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
diff --git a/media/readme/commandsList.png b/media/readme/commandsList.png
diff --git a/media/readme/espressifIcon.png b/media/readme/espressifIcon.png
diff --git a/media/readme/flash.png b/media/readme/flash.png
diff --git a/media/readme/flashmethod.png b/media/readme/flashmethod.png
diff --git a/media/readme/monitor.png b/media/readme/monitor.png
diff --git a/media/readme/openocd.png b/media/readme/openocd.png
diff --git a/media/readme/sdkconfig.png b/media/readme/sdkconfig.png
diff --git a/media/readme/serialport.png b/media/readme/serialport.png
diff --git a/media/readme/setup.png b/media/readme/setup.png
diff --git a/media/readme/statusBar.png b/media/readme/statusBar.png
diff --git a/media/readme/target.png b/media/readme/target.png
diff --git a/media/youtube_tutorial_preview.png b/media/youtube_tutorial_preview.png