add tutorial links

.github/ISSUE_TEMPLATE/bug_report.md

@@ -31,16 +31,20 @@ If applicable, add screenshots to help explain your problem.
 - ESP-IDF Version: [e.g. v3.2.2]
 - Python Version: [e.g. 2.7.10]
 
-> **NOTE**: You can use the `ESP-IDF: Doctor command` to generate a report of your configuration.
+> **NOTE**: You can use the `ESP-IDF: Doctor command` to generate a report of your configuration in your clipboard which you can copy here.
 
 **Output**
 
-Click the menu `View` and select `Output`. This extension uses several output channels: ESP-IDF, ESP-IDF Debug Adapter, Heap Trace, OpenOCD and SDK Configuration Editor.
+In Visual Studio Code select menu `View` -> `Output` -> ESP-IDF, ESP-IDF Debug Adapter, Heap Trace, OpenOCD and SDK Configuration Editor.
 
-Please share the output of the channel related to your issue. For example ESP-IDF is used mostly for the extension setup process.
+> **NOTE:** Use `idf.openOcdDebugLevel` configuration setting to 3 or more to show debug logging in OpenOCD server output.
+
+> **NOTE:** Use `logLevel` in your <project-directory>/.vscode/launch.json to 3 or more to show more debug adapter output.
+
+Please share the output of the channel related to your issue. For example ESP-IDF is used mostly for the extension setup process output.
 
 **Logs**
-If applicable, please share the log file which can be obtained from
+Please share the log file which can be obtained from:
 
 - Windows: `%USERPROFILE%\.vscode\extensions\espressif.esp-idf-extension-VERSION\esp_idf_vsc_ext.log`
 - Linux & MacOSX: `$HOME/.vscode/extensions/espressif.esp-idf-extension-VERSION/esp_idf_vsc_ext.log`

README.md

@@ -4,8 +4,9 @@
 
 # ESP-IDF VS Code Extension
 
+[![Tutorials](https://img.shields.io/badge/-Tutorials-red)](./docs/tutorial/toc.md)
 [![Documentation](https://img.shields.io/badge/Documentation-blue)](./docs/ONBOARDING.md)
-[![ESP32](https://img.shields.io/badge/Supported%20Chip-ESP32%20ESP32--S2%20ESP32--S3%20ESP32--C3-green)](./docs/HARDWARE_SUPPORT.md)
+[![ESP32](https://img.shields.io/badge/Supported%20Chip-ESP32%20ESP32--S2%20ESP32--S3%20ESP32--C3-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)
@@ -20,6 +21,16 @@ Make sure to review our [documentation](./docs/ONBOARDING.md) first to properly
   </p>
 </a>
 
+# Tutorials
+
+1. [Install and setup the extension](./docs/tutorial/install.md).
+2. [Create a project from example, Build, flash and monitor](./docs/tutorial/install.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)
+
+Check all the tutorials [here](./docs/tutorial/toc.md).
+
 # Table of content
 
 1. [Prerequisites](#Prerequisites)
@@ -31,6 +42,8 @@ Make sure to review our [documentation](./docs/ONBOARDING.md) first to properly
 7. [Code of Conduct](#Code-of-Conduct)
 8. [License](#License)
 
+Check all the [documentation](./docs/ONBOARDING.md).
+
 # Prerequisites
 
 There are few dependencies required in your system and available in environment variable PATH before installing this extension. Please review [ESP-IDF Prerequisites](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/index.html#step-1-install-prerequisites) documentation.
@@ -53,16 +66,18 @@ All the other dependencies like ESP-IDF and ESP-IDF Tools can be installed using
   - Run `code ${YOUR_PROJECT_DIR}` from the command line.
 - Check you have installed the [Prerequisites](#Prerequisites)
 - (OPTIONAL) Press <kbd>F1</kbd> and type **ESP-IDF: Select where to save configuration settings**, which can be User settings, Workspace settings or workspace folder settings. Please take a look at [Working with multiple projects](./docs/MULTI_PROJECTS.md) for more information. Default is User settings.
-- On the first time using the extension, press <kbd>F1</kbd> and type **ESP-IDF: Configure ESP-IDF extension** to open the extension configuration wizard. This will install ESP-IDF and tools and configure the extension.
+- On the first time using the extension, press <kbd>F1</kbd> and type **ESP-IDF: Configure ESP-IDF extension** to open the extension configuration wizard. This will install ESP-IDF, ESP-IDF tools, create a virtual python environment with ESP-IDF and this extension python packages and configure the extension settings with these values.
 
-  > **NOTE:** Please take a look at [SETUP](./docs/SETUP.md) documentation or the [Install](./docs/tutorial/install.md) tutorial for details about extension configuration.
+  > **NOTE:** Please take a look at [SETUP](./docs/SETUP.md) documentation or the [Install](./docs/tutorial/install.md) tutorial for details about extension setup and configuration.
 
 - Press <kbd>F1</kbd> and type **ESP-IDF: Show Examples Projects** to create a new project from ESP-IDF examples.
 
-- Configure the `.vscode/c_cpp_properties.json` as explained in [C/C++ Configuration](./docs/C_CPP_CONFIGURATION.md). There is a default configuration that should work but you might want to modify it to your needs.
+- Configure the `.vscode/c_cpp_properties.json` as explained in [C/C++ Configuration](./docs/C_CPP_CONFIGURATION.md). There is a default configuration that should work when you create a new project with the extension commands but you might want to modify it to your needs.
 
   > **Note:** If you want to get code navigation and ESP-IDF function references, the [Microsoft C/C++ Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) can be used to resolve header/source links. By default, projects created with **ESP-IDF: Create project from extension template** or **ESP-IDF: Show Examples Projects** tries to resolve headers by manually recursing ESP-IDF directory sources with the `Tag Parser` engine. This can be optimized by building the project first and configure your project to use `build/compile_commands.json` as explained in [C/C++ Configuration](./docs/C_CPP_CONFIGURATION.md).
 
+  > **NOTE:** You should set `"C_Cpp.intelliSenseEngine": "Tag Parser"` in your settings.json if you are not using the compile_commands.json approach.
+
 - 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. If you are using one of our boards, use the **ESP-IDF: Select OpenOCD Board Configuration** to choose the openOCD configuration files for the extension openOCD server.
@@ -176,9 +191,11 @@ Note that for OpenOCD tasks you need to define `OPENOCD_SCRIPTS` in your system
 
 If something is not working please check for any error on one of these:
 
-> **NOTE:** Use `idf.openOcdDebugLevel` to 3 or more to show debug logging in OpenOCD server output.
+> **NOTE:** Use `idf.openOcdDebugLevel` configuration setting to 3 or more to show debug logging in OpenOCD server output.
+
+> **NOTE:** Use `logLevel` in your <project-directory>/.vscode/launch.json to 3 or more to show more debug adapter output.
 
-1. In Visual Studio Code select menu "View" -> Output -> ESP-IDF, ESP-IDF Debug Adapter, Heap Trace, OpenOCD and SDK Configuration Editor.
+1. In Visual Studio Code select menu "View" -> Output -> ESP-IDF, ESP-IDF Debug Adapter, Heap Trace, OpenOCD and SDK Configuration Editor. This output information is useful to know what is happening in each tool.
 2. Use the `ESP-IDF: Doctor command` to generate a report of your configuration and it will be copied in your clipboard to paste anywhere.
 3. Check log file which can be obtained from:
 
@@ -187,11 +204,11 @@ If something is not working please check for any error on one of these:
 
 4. In Visual Studio Code, select menu "Help" -> `Toggle Developer Tools` and copy any error in the Console tab related to this extension.
 
-5. Make sure that your extension is properly configured as described in [JSON Manual Configuration](./docs/SETUP.md#JSON-Manual-Configuration). Visual Studio Code allows the user to configure settings at different levels: Global (User Settings), Workspace and WorkspaceFolder. The doctor command might give the values from user settings instead of the workspace folder settings.
+5. Make sure that your extension is properly configured as described in [JSON Manual Configuration](./docs/SETUP.md#JSON-Manual-Configuration). Visual Studio Code allows the user to configure settings at different levels: Global (User Settings), Workspace and WorkspaceFolder so make sure your project has the right settings. The doctor command might give the values from user settings instead of the workspace folder settings.
 
 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.
+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.
 
 If the user can't resolve the error, please search in the [github repository issues](http://github.com/espressif/vscode-esp-idf-extension/issues) for existing errors or open a new issue [here](https://github.com/espressif/vscode-esp-idf-extension/issues/new/choose).
 

docs/C_CPP_CONFIGURATION.md

@@ -10,7 +10,7 @@ To enable Code Navigation, auto-complete and other language support features on
 ## Default configuration
 
 With this configuration file, the IntelliSense engine of the C/C++ extension will include all header files found by performing a recursive search of the `${config:idf.espIdfPath}/components` folder.
-For this configuration to work, you need to set you C/C++ Extension IntelliSense engine to **Tag Parser**.
+For this configuration to work, you need to set you C/C++ Extension IntelliSense engine to **Tag Parser** by using `C_Cpp.intelliSenseEngine": "Tag Parser"` in your settings.json.
 
 An example configuration that should work with most projects is shown below.
 

docs/DEBUGGING.md

@@ -11,6 +11,8 @@ We recommend using our ESP-IDF Debug Adapter to debug your ESP-IDF projects, but
 
 ## Use the ESP-IDF Debug Adapter
 
+> **NOTE:** Currently the python package `pygdbmi` used by the debug adapter still depends on some Python 2.7 libraries (libpython2.7.so.1.0) so make sure that the Python executable you use in `idf.pythonBinPath` contains these libraries. This will be dropped in later versions of ESP-IDF.
+
 This extension includes the [ESP-IDF Debug Adapter](https://github.com/espressif/esp-debug-adapter) which implement the debug adapter protocol (DAP) to communicate Xtensa's Toolchain and OpenOCD with Visual Studio Code allowing the user to easily debug ESP-IDF applications. Visual Studio Code will:
 
 1. Launch the debug adapter server in port `debugPort` given in launch.json if `mode` is `auto` or

docs/INSTALL.md

@@ -33,7 +33,7 @@ To install from `.vsix` file:
 ## Configure the extension
 
 - (OPTIONAL) Press <kbd>F1</kbd> and type **ESP-IDF: Select where to save configuration settings**, which can be User settings, Workspace settings or workspace folder settings. Please take a look at [Working with multiple projects](./MULTI_PROJECTS.md) for more information. Default is User settings.
-- Please take a look at [SETUP](./SETUP.md) for details about extension configuration.
+- Please take a look at [SETUP](./SETUP.md) documentation or the [Install](./docs/tutorial/install.md) tutorial for details about the extension configuration.
 
 ## Uninstalling the plugin
 

docs/SETUP.md

@@ -46,7 +46,16 @@ Setup wizard provides 3 choices:
 - **Use existing setup**: This option will use an existing setup if:
   1. `esp-idf.json` is found in the current `idf.toolsPath` (MacOS/Linux users) or `idf.toolsPathWin` (Windows users). This file is generated when you install ESP-IDF with the [IDF Windows installer](https://github.com/espressif/idf-installer) or using [IDF-ENV](https://github.com/espressif/idf-env).
   2. ESP-IDF is found in `idf.espIdfPath` or `idf.espIdfPathWin`, `IDF_PATH` environment variable, `$HOME/esp/esp-idf` on MacOS/Linux and `%USERPROFILE%\esp\esp-idf` or `%USERPROFILE%\Desktop\esp-idf` in Windows.
-  3. ESP-IDF Tools and ESP-IDF Python virtual environment for the previos ESP-IDF are found in `idf.toolsPath` or `idf.toolsPathWin`, `IDF_TOOLS_PATH` environment variable, `$HOME\.espressif` on MacOS/Linux and `%USERPROFILE%\.espressif` on Windows.
+  3. ESP-IDF Tools and ESP-IDF Python virtual environment for the previous ESP-IDF are found in `idf.toolsPath` or `idf.toolsPathWin`, `IDF_TOOLS_PATH` environment variable, `$HOME\.espressif` on MacOS/Linux and `%USERPROFILE%\.espressif` on Windows.
+
+> **NOTE:** When running any of these choices, the setup wizard will install ESP-IDF Python packages, this extension (`EXTENSION_PATH`/requirements.txt and ESP-IDF debug adapter (`EXTENSION_PATH`/esp_debug_adapter/requirements.txt) python packages where `EXTENSION_PATH` is:
+
+- Windows: `%USERPROFILE%\.vscode\extensions\espressif.esp-idf-extension-VERSION`
+- Linux & MacOSX: `$HOME/.vscode/extensions/espressif.esp-idf-extension-VERSION`
+
+so make sure that if using an existing python virtual environment that installing these packages doesn't affect your virtual environment.
+
+> **NOTE:** Currently the python package `pygdbmi` used by the debug adapter still depends on some Python 2.7 libraries (libpython2.7.so.1.0) so make sure that the Python executable in `idf.pythonBinPath` you use contains these libraries. This will be dropped in later versions of ESP-IDF.
 
 > **NOTE:** Make sure that `IDF_PATH` and `IDF_TOOLS_PATH` doesn't have any spaces to avoid any build issues.
 

docs/tutorial/debugging.md

@@ -6,6 +6,8 @@ This tutorial shows the user how to debug ESP-IDF projects using the Visual Stud
 
 > **NOTE:** 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.
 
+> **NOTE:** Currently the python package `pygdbmi` used by the debug adapter still depends on some Python 2.7 libraries (libpython2.7.so.1.0) so make sure that the Python executable in `idf.pythonBinPath` you use contains these libraries. This will be dropped in later versions of ESP-IDF.
+
 1. Configure, build and flash your project as explained in [Basic use tutorial](./basic_use.md).
 2. 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.
 

docs/tutorial/install.md

@@ -1,6 +1,6 @@
 # Installation
 
-  > **NOTE:** [troubleshooting](../../README.md#Troubleshooting)
+> **NOTE:** [troubleshooting](../../README.md#Troubleshooting)
 
 1. Download and install [Visual Studio Code](https://code.visualstudio.com/).
 2. 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 <kbd>⇧</kbd> <kbd>⌘</kbd> <kbd>X</kbd>.
@@ -30,7 +30,7 @@
 10. If you choose **Express** setup mode:
     - Pick an ESP-IDF version to download (or find ESP-IDF in your system) and the python executable to create the virtual environment.
     - Choose the location for ESP-IDF Tools and python virtual environment (also known as `IDF_TOOLS_PATH`) which is `$HOME\.espressif` on MacOS/Linux and `%USERPROFILE%\.espressif` on Windows by default.
-    > **NOTE:** Windows users don't need to select a python executable since it is part of the setup.
+      > **NOTE:** Windows users don't need to select a python executable since it is part of the setup.
 
 > **NOTE:** Make sure that `IDF_PATH` and `IDF_TOOLS_PATH` doesn't have any spaces to avoid any build issues.
 
@@ -65,8 +65,13 @@
   <img src="../../media/tutorials/setup/install-complete.png" alt="Install complete">
 </p>
 
-> **NOTE**: The advance mode allows the user to choose to use existing ESP-IDF tools by manually entering each ESP-IDF tool absolute path. Make sure each  ESP-IDF tool path doesn't have any spaces.
+> **NOTE**: The advance mode allows the user to choose to use existing ESP-IDF tools by manually entering each ESP-IDF tool absolute path. Make sure each ESP-IDF tool path doesn't have any spaces.
 
 15. Now that the extension setup is finally done, check the [basic use](./basic_use.md) to learn how to use the SDK Configuration editor, build, flash and monitor your Espressif device.
 
-  > **NOTE**: Visual Studio Code has many places where to set configuration settings. This extension uses the `idf.saveScope` configuration setting to determine where to save settings, Global (User Settings), Workspace and WorkspaceFolder. Please review [vscode settings precedence](https://code.visualstudio.com/docs/getstarted/settings#_settings-precedence).
+> **NOTE**: Visual Studio Code has many places where to set configuration settings. This extension uses the `idf.saveScope` configuration setting to determine where to save settings, Global (User Settings), Workspace and WorkspaceFolder. Please review [vscode settings precedence](https://code.visualstudio.com/docs/getstarted/settings#_settings-precedence).
+
+> **NOTE:** the setup wizard will install ESP-IDF Python packages, this extension (`EXTENSION_PATH`/requirements.txt) and ESP-IDF debug adapter (`EXTENSION_PATH`/esp_debug_adapter/requirements.txt) python packages. Make sure that if using an existing python virtual environment that installing these packages doesn't affect your virtual environment. The `EXTENSION_PATH` is:
+
+- Windows: `%USERPROFILE%\.vscode\extensions\espressif.esp-idf-extension-VERSION`
+- Linux & MacOSX: `$HOME/.vscode/extensions/espressif.esp-idf-extension-VERSION`