Tutorials docs (#332)

* add step by step setup

* add setup basic use tutorial

* add additional frameworks tutorial

* add debug tutorial

* add core dump gdb in debug tutorial

* add partition table editor tutorial

* code coverage

* update code coverage tutorial

* add nvs partition editor tutorial

* add heap tracing system view tutorial

* mv images out of vsix

* add cmakelists editor

* add efuse rainmaker tutorial

* add doc fixes

* add tutorials links in readme

* smaller debug screenshots

* smaller app tracing screenshots

* basic use small blink example

* update width height tutorial

* add conditional breakpoint

.vscodeignore

@@ -27,3 +27,5 @@ gulpfile.js
 .yarnrc
 report.txt
 report.json
+media/screenshots
+media/tutorials

README.md

@@ -9,7 +9,7 @@
 ![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)
 
-Develop, [build](./docs/FEATURES.md), [flash](./docs/FEATURES.md), [monitor](./docs/FEATURES.md), [debug](./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](./docs/DEBUGGING.md) and [more](./docs/FEATURES.md) with Espressif chips using Espressif IoT Development Framework [(ESP-IDF)](https://github.com/espressif/esp-idf)
 
 <a href="https://youtu.be/Lc6ausiKvQM">
   <p align="center">
@@ -19,14 +19,30 @@ Develop, [build](./docs/FEATURES.md), [flash](./docs/FEATURES.md), [monitor](./d
 
 # Table of content
 
-1. [Quick links](#Quick-links)
-2. [Prerequisites](#Prerequisites)
-3. [How to use](#How-to-use)
-4. [Available commands](#Available-commands)
-5. [Commands for tasks.json and launch.json](#Commands-for-tasks.json-and-launch.json)
-6. [Available Tasks in tasks.json](#Available-Tasks-in-tasks.json)
-7. [Code of Conduct](#Code-of-Conduct)
-8. [License](#License)
+1. [Tutorials](#Tutorials)
+2. [Quick links](#Quick-links)
+3. [Prerequisites](#Prerequisites)
+4. [How to use](#How-to-use)
+5. [Available commands](#Available-commands)
+6. [Commands for tasks.json and launch.json](#Commands-for-tasks.json-and-launch.json)
+7. [Available Tasks in tasks.json](#Available-Tasks-in-tasks.json)
+8. [Code of Conduct](#Code-of-Conduct)
+9. [License](#License)
+
+## Tutorials
+
+1. [Install](./docs/tutorial/install.md) the extension and dependencies.
+2. [Basic usage](./docs/tutorial/basic_use.md)
+3. [Debug](./docs/tutorial/debugging.md)
+4. [Code coverage](./docs/tutorial/code_coverage.md)
+5. [Application tracing](./docs/tutorial/app_tracing.md)
+6. [Heap tracing and SystemView tracing](./docs/tutorial/heap_tracing.md)
+7. [Partition table editor](./docs/tutorial/partition_editor.md)
+8. [NVS Partition editor](./docs/tutorial/nvs_partition_editor.md)
+9. [CMakeLists.txt editor](./docs/tutorial/cmakelists_editor.md)
+10. [ESP-ADF, ESP-MDF and other frameworks](./docs/tutorial/additional_frameworks.md)
+11. [eFuse Explorer](./docs/tutorial/efuse.md)
+12. [Rainmaker](./docs/tutorial/rainmaker.md)
 
 ## Quick links
 
@@ -38,8 +54,9 @@ Develop, [build](./docs/FEATURES.md), [flash](./docs/FEATURES.md), [monitor](./d
 - [Github Repository](https://github.com/espressif/vscode-esp-idf-extension)
 - [Github issues](https://github.com/espressif/vscode-esp-idf-extension/issues)
 - [How to use](#How-to-use)
-- [**See all features**](./docs/FEATURES.md)
+- [See all features](./docs/FEATURES.md)
 - [Setup process](./docs/SETUP.md)
+- [Tutorials](./docs/tutorial/toc.md)
 - [Releases](https://github.com/espressif/vscode-esp-idf-extension/releases)
 - [Working with multiple projects](./docs/MULTI_PROJECTS.md)
 
@@ -77,6 +94,7 @@ All the other dependencies like ESP-IDF and ESP-IDF Tools can be installed using
 
 - Do some coding!
 - Check you set the correct port of your device by pressing <kbd>F1</kbd>, 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.
 - When you are ready, build your project. Then flash to your device by pressing <kbd>F1</kbd> and typing **ESP-IDF: Flash your device** then selecting Flash allows you to flash the device.
 - You can later start a monitor by pressing <kbd>F1</kbd> and typing **ESP-IDF: Monitor your device** which will log the activity in a Visual Studio Code terminal.
 - 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). To make sure you can debug your device, set the proper `idf.openOcdConfigs` settings in your settings.json or by pressing <kbd>F1</kbd> and typing **ESP-IDF: Device configuration**.
@@ -105,6 +123,7 @@ Click <kbd>F1</kbd> to show Visual studio code actions, then type **ESP-IDF** to
 | Install ESP-ADF                                         |                                        |                                           |
 | Install ESP-IDF Python Packages                         |                                        |                                           |
 | Install ESP-MDF                                         |                                        |                                           |
+| Launch IDF Monitor for CoreDump / GDB-Stub Mode         |                                        |                                           |
 | Monitor your device                                     | <kbd>⌘</kbd> <kbd>E</kbd> <kbd>M</kbd> | <kbd>Ctrl</kbd> <kbd>E</kbd> <kbd>M</kbd> |
 | New Project                                             | <kbd>⌘</kbd> <kbd>E</kbd> <kbd>N</kbd> | <kbd>Ctrl</kbd> <kbd>E</kbd> <kbd>N</kbd> |
 | Open ESP-IDF Terminal                                   | <kbd>⌘</kbd> <kbd>E</kbd> <kbd>T</kbd> | <kbd>Ctrl</kbd> <kbd>E</kbd> <kbd>T</kbd> |
@@ -121,7 +140,9 @@ Click <kbd>F1</kbd> to show Visual studio code actions, then type **ESP-IDF** to
 | Size analysis of the binaries                           | <kbd>⌘</kbd> <kbd>E</kbd> <kbd>S</kbd> | <kbd>Ctrl</kbd> <kbd>E</kbd> <kbd>S</kbd> |
 | Remove Editor coverage                                  |                                        |                                           |
 
-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`). 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.
+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`). 
+
+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](https://github.com/espressif/arduino-esp32) to see if your ESP-IDF version is compatible.
 
@@ -143,15 +164,14 @@ as shown in the [debugging documentation](./DEBUGGING.md).
 
 - `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.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`.
 
 ## Available Tasks in tasks.json
 
-There is also some tasks defined in Tasks.json, which can be executed by running <kbd>F1</kbd> and writing `Tasks: Run task` and selecting one of
-the following:
+There is also some tasks defined in Tasks.json, which can be executed by running <kbd>F1</kbd> and writing `Tasks: Run task` and selecting one of the following:
 
 1. `Build` - Build Project
 2. `Set Target to esp32`
@@ -162,7 +182,7 @@ the following:
 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.
+Note that for OpenOCD tasks you need to define `OPENOCD_SCRIPTS` in your system environment variables with openocd scripts folder path.
 
 ## Code of Conduct
 

docs/COVERAGE.md

@@ -1,32 +1,35 @@
 # Using **gcov** and **gcovr** to provide code coverage
 
+Source code coverage is data indicating the count and frequency of every program execution path that has been taken within a program’s runtime. [Gcov](https://en.wikipedia.org/wiki/Gcov) is a GCC tool that, when used in concert with the compiler, can generate log files indicating the execution count of each line of a source code. The [Gcovr](https://gcovr.com/) tool is utility for managing Gcov and generating summarized code coverage results.
+
+Please read [GCOV Code coverage](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/app_trace.html#gcov-source-code-coverage) to learn more about code coverage with gcov in ESP-IDf projects.
+
 ## Requirements
 
-Your ESP-IDF project should be configured to generate gcda/gcno coverage files using gcov. Please take a look at the [ESP-IDF gcov example](https://github.com/espressif/esp-idf/tree/master/examples/system/gcov) to see how to set up your project.
+Your ESP-IDF project should be configured to generate gcda/gcno coverage files using gcov as shown in [GCOV Code coverage](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/app_trace.html#gcov-source-code-coverage). Please take a look at the [ESP-IDF gcov example](https://github.com/espressif/esp-idf/tree/master/examples/system/gcov) as example project.
 
-This extension also requires `gcovr` to generate JSON and HTML reports from generated files. This is installed as part of this extension ESP-IDF Debug Adapter Python requirements when following the **ESP-IDF: Configure ESP-IDF extension** command.
-Please take a look at [SETUP](./SETUP.md) for more information.
+This extension requires `gcovr` to generate JSON and HTML reports from generated files. This is installed as part of this extension [SETUP](./SETUP.md).
 
-Make sure you had properly configure xtensa toolchain in `idf.customExtraPaths` or in your environment variable PATH since the gcov executable used is `xtensa-esp32-elf-gcov` and `gcovr` exists in the same directory as your `${idf.pythonBinPath}` path.
+Make sure you had properly configure the toolchain in `idf.customExtraPaths` or in your environment variable PATH since the gcov executable used is `{TOOLCHAIN_PREFIX}-gcov` (replacing TOOLCHAIN_PREFIX for your IDF_TARGET toolchain prefix) and `gcovr` exists in the same directory as your `${idf.pythonBinPath}` path.
 
 ## Editor Coverage
 
-For the text editor highlighting, we use execute a child process with `gcovr -r . --gcov-executable {TOOLCHAIN_PREFIX}-gcov --json`.
+For the text editor highlighting, the **ESP-IDF: Add Editor coverage** command execute a child process with `gcovr -r . --gcov-executable {TOOLCHAIN_PREFIX}-gcov --json`. You can remove the coverage highlight with **ESP-IDF; Remove Editor coverage**.
 
 > **NOTE:** This assumes you had configure your extension with Xtensa toolchain in `idf.customExtraPaths` and installed the `gcovr` from Debug adapter's python requirements.
 
 For the text editor, we use the json object generated by the previous command to highlight each line if it is covered or if it is not. We don't highlight noncode lines.
 
-You can customize highlight color using the extension settings. Visual Studio code support `"red"`, `rgb(255,0,120)` or `rgba(120,0,0,0.1)`.
+You can customize highlight color using the extension settings. Visual Studio code support `"red"`, `rgb(255,0,120)` or `rgba(120,0,0,0.1)` values.
 
 - Covered lines use `idf.coveredLightTheme` for light themes and `idf.coveredDarkTheme` for dark themes.
 - Partially covered lines use `idf.partialLightTheme` for light themes and `idf.partialDarkTheme` for dark themes.
 - Non-covered lines use `idf.uncoveredLightTheme` for light themes and `idf.uncoveredDarkTheme` for dark themes.
 
 ## HTML report
 
-We execute a child process with command `gcovr -r . --gcov-executable {TOOLCHAIN_PREFIX}-gcov --html` for the HTML report.
+The **ESP-IDF: Get HTML Coverage Report for project** execute a child process with command `gcovr -r . --gcov-executable {TOOLCHAIN_PREFIX}-gcov --html` for the HTML report.
 
 > **NOTE:** This assumes you had configure your extension with Xtensa toolchain in `idf.customExtraPaths` and installed the `gcovr` from Debug adapter's python requirements.
 
-With the generated HTML, we generate a Webview Panel with report from `gcovr`.
+With the generated HTML from `gcovr`, a Webview Panel is launched to show the gcov html report.

docs/FEATURES.md

@@ -8,7 +8,7 @@ This extension provides many features to ease development of ESP-IDF Projects.
 - GUI [SDK Configuration editor](#SDK-Configuration-editor) to configure your ESP-IDF project (esp-idf menuconfig).
 - [Partition table editor](./PARTITION_TABLE_EDITOR.md)
 - [NVS Partition editor](./NVS_PARTITION_EDITOR.md)
-- Easily [Build](#Build), [Flash](#Flash) and [Monitor](#Monitor) your code for ESP32 and ESP32 S2 chips.
+- Easily [Build](#Build), [Flash](#Flash) and [Monitor](#Monitor) your code with Espressif chips.
 - OpenOCD server within Visual Studio Code.
 - [DEBUGGING](./DEBUGGING.md) with [ESP-IDF Debug Adapter](https://github.com/espressif/esp-debug-adapter).
 - Size analysis of binaries with **ESP-IDF: Size analysis of the binaries**.
@@ -37,7 +37,7 @@ The **Add Arduino-ESP32 as ESP-IDF Component** command will add [Arduino-ESP32](
 
 Click <kbd>F5</kbd> to start debugging. To configure the debug behaviour, please review [DEBUGGING](./DEBUGGING.md).
 
-> **NOTE** For correct debug experience, first `build` your project, choose the right serial port, `flash` your device and define the correct `idf.customExtraPaths` paths and `idf.customExtraVars` using [SETUP](./SETUP.md).
+> **NOTE** For correct debug experience, first define the correct `idf.customExtraPaths` paths and `idf.customExtraVars` using [SETUP](./SETUP.md), `build` your project, choose the right serial port, `flash` the program to your device.
 
 ## CMakeLists.txt Editor
 
@@ -67,13 +67,17 @@ You can follow [this](./HEAP_TRACING.md) quick step-by-step guide for heap traci
 
 In Visual Studio Code, for **ESP-IDF: Monitor your 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)).
 
-## SDK Configuration editor
+## OpenOCD Server
+
+The user 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** or use **ESP-IDF: Device configuration** to manually set any value you desire.
 
-### Prerequisites
+> **NOTE:** The user can modify `openocd.tcl.host` and `openocd.tcl.port` configuration settings to modify these values. Please review [ESP-IDF Settings](../SETTINGS.md) to see how to modify these configuration settings.
 
-- ESP-IDF `>=v4.x`
+## SDK Configuration editor
 
-This plugin includes a GUI menuconfig 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](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/build-system.html?highlight=confserver#json-configuration-server) process (confserver.py in **\${ESP-IDF-DIRECTORYPATH}**/tools) that enables the user to redefine ESP-IDF project and board configuration.
+This extension includes a GUI menuconfig 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](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/build-system.html?highlight=confserver#json-configuration-server) process (confserver.py in **\${IDF_PATH}**/tools) that enables the user to redefine ESP-IDF project and board configuration.
 
 When the user 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.
 
@@ -87,6 +91,13 @@ An IDF GUI Menuconfig log in Output (Menu View -> Output) is created to print al
 
 The **ESP-IDF: Set Espressif device target** allows the user to choose among Espressif different chips based on [idf.py set-target](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/build-system.html?highlight=target#selecting-idf-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](./SYS_VIEW_TRACING_VIEWER.md) inside the vscode extension which will enable you to view the traces along with other relevant details.

docs/NVS_PARTITION_EDITOR.md

@@ -9,7 +9,7 @@ key1,data,u8,1
 key2,file,string,/path/to/file
 ```
 
-This is based on ESP-IDF [NVS Partition Generator Utility](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/storage/nvs_partition_gen.html). Make sure `espIdfPath` configuration setting is defined for this to properly work.
+This is based on ESP-IDF [NVS Partition Generator Utility](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/storage/nvs_partition_gen.html). Make sure `idf.espIdfPath` configuration setting is defined for this to work properly.
 
 ## Prerequisites