[VSC-1258] feature/walkthrough

.vscode/settings.json

@@ -34,5 +34,6 @@
     }
   ],
   "typescript.updateImportsOnFileMove.enabled": "always",
-  "workbench.editor.enablePreview": true
+  "workbench.editor.enablePreview": true,
+  "iis.configDir": ""
 }

package.json

@@ -117,6 +117,150 @@
   "main": "./dist/extension",
   "l10n": "./l10n",
   "contributes": {
+    "walkthroughs": [
+      {
+        "id": "espIdf.walkthrough.basic-usage",
+        "title": "ESP-IDF Basic Usage Guide",
+        "description": "Learn how to configure the ESP-IDF extension and use its basic features in VS Code",
+        "steps": [
+          {
+            "id": "introduction",
+            "title": "Introduction to ESP-IDF in VS Code",
+            "description": "This walkthrough will guide you through configuring the ESP-IDF extension and demonstrate its basic usage in Visual Studio Code.",
+            "media": {
+              "markdown": "walkthroughs/basic/basic-usage-intro.md"
+            }
+          },
+          {
+            "id": "extension-configuration",
+            "title": "Configuring the ESP-IDF Extension",
+            "description": "❗**Linux and MacOS users:** Please install prerequisites first. The process is quick and simple - follow the steps in our [ESP-IDF install documentation](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/linux-macos-setup.html#step-1-install-prerequisites).\n\nOnce ready, let's configure the ESP-IDF extension:\n\n[Configure ESP-IDF Extension](command:espIdf.setup.start)\n\n",
+            "media": {
+              "markdown": "walkthroughs/basic/configuration.md"
+            }
+          },
+          {
+            "id": "create-example-project",
+            "title": "Creating an Example Project",
+            "description": "Now, let's create a new project from ESP-IDF examples:\n\n[Show Example Projects](command:espIdf.examples.start)\n\n💡 Explore different examples to find one that suits your needs.",
+            "media": {
+              "markdown": "walkthroughs/basic/create-project.md"
+            }
+          },
+          {
+            "id": "setup-project",
+            "title": "Setting Up Your Project",
+            "description": "Before building your project, you'll need to configure some essential settings:\n\n1. Configure your target device\n\n[Set Espressif Device Target](command:espIdf.setTarget)\n2. Set up project-specific configurations (not needed in our example)\n3. Select serial port \n\n[Select Port to Use](command:espIdf.selectPort)\n4. Select flashing method \n\n[Select Flash Method](command:espIdf.selectFlashMethodAndFlash)",
+            "media": {
+              "markdown": "walkthroughs/basic/setup-project.md"
+            }
+          },
+          {
+            "id": "build-flash-monitor",
+            "title": "Building, Flashing, and Monitoring",
+            "description": "Now that your project is configured, let's build the code, flash it to your device, and monitor the output.\n\nYou can perform these operations individually or all at once using the 'Build, Flash and Monitor' command.\n\n[Build, Flash and Monitor](command:espIdf.buildFlashMonitor)",
+            "media": {
+              "markdown": "walkthroughs/basic/build-flash-monitor.md"
+            }
+          },
+          {
+            "id": "additional-resources-and-ui",
+            "title": "Additional Resources and UI Exploration",
+            "description": "As a next step, we recommend that you go through the Advanced Walkthrough as well.\n\n[Start Advanced Features Guide Walkthrough](command:workbench.action.openWalkthrough?%22espressif.esp-idf-extension%23espIdf.walkthrough.advanced%22)",
+            "media": {
+              "markdown": "walkthroughs/basic/additional-resources.md"
+            }
+          }
+        ]
+      },
+      {
+        "id": "espIdf.walkthrough.advanced",
+        "title": "ESP-IDF Advanced Features Guide",
+        "description": "Explore advanced features and tools for ESP-IDF development in VS Code",
+        "steps": [
+          {
+            "id": "advanced-introduction",
+            "title": "Introduction to Advanced Features",
+            "description": "Overview of advanced ESP-IDF development capabilities.\n\n**Prerequisites:**\n - Completed the Basic Usage Guide\n - Basic familiarity with ESP-IDF concepts\n - Have a working ESP-IDF setup\n - Have your development board ready\n - JTAG debugging hardware (for debugging features)",
+            "media": {
+              "markdown": "walkthroughs/advanced/advanced-intro.md"
+            }
+          },
+          {
+            "id": "troubleshooting",
+            "title": "Troubleshooting Guide",
+            "description": "Learn about common troubleshooting techniques and how to get help when you need it.\n\nKey features:\n- Debug logging configuration\n- Environment diagnostics\n- Log file locations\n- Common issues and solutions\n\n[Run Doctor Command](command:espIdf.doctorCommand)",
+            "media": {
+              "markdown": "walkthroughs/advanced/troubleshooting.md"
+            }
+          },
+          {
+            "id": "sdk-configuration",
+            "title": "SDK Configuration (menuconfig)",
+            "description": "Learn how to customize your project's configuration using menuconfig\nKey features:\n- Component configuration\n- Compiler options\n- Flash and partition settings\n- Serial port parameters\n\n💡 Tip: Use search bar to quickly find settings",
+            "media": {
+              "markdown": "walkthroughs/advanced/sdk-configuration.md"
+            }
+          },
+          {
+            "id": "debugging",
+            "title": "Debugging Your Application",
+            "description": "Learn how to debug your ESP-IDF applications using VS Code\n\nKey features:\n- Conditional breakpoints\n- Navigating through the code, call stack and threads\n- Halting the target manually\n- Watching and setting program variables\n- Disassembly view\n- Sending GDB Commands\n- Peripheral Viewer",
+            "media": {
+              "markdown": "walkthroughs/advanced/debug-project.md"
+            }
+          },
+          {
+            "id": "component-installation",
+            "title": "Installing ESP-IDF Components",
+            "description": "Learn how to enhance your project with ESP Component Registry and Arduino-ESP32 integration.\n\n- Browse and install ESP components\n- Add Arduino-ESP32 as a component\n- Create projects from component examples\n\n[Open ESP Component Registry](command:esp.component-manager.ui.show)",
+            "media": {
+              "markdown": "walkthroughs/advanced/component-installation.md"
+            }
+          },
+          {
+            "id": "app-size-analysis",
+            "title": "Application Size Analysis",
+            "description": "ESP-IDF Extension provides powerful tools to analyze your application's memory usage, helping you optimize storage allocation. \n\n[Open Size Analysis](command:espIdf.size)",
+            "media": {
+              "markdown": "walkthroughs/advanced/app-size-analysis.md"
+            }
+          },
+          {
+            "id": "partition-table",
+            "title": "Partition Table Configuration",
+            "description": "The Partition Table Editor provides a user-friendly interface to define and modify your ESP32's flash memory layout.\nKey features\n- Visual partition table editing interface\n- Automatic CSV file generation and management\n- Direct integration with ESP-IDF build systemReal-time validation of partition configurations\n\n[Open Partition Editor](command:esp.webview.open.partition-table)",
+            "media": {
+              "markdown": "walkthroughs/advanced/partition-table.md"
+            }
+          },
+          {
+            "id": "unit-testing",
+            "title": "Unit Testing",
+            "description": "Set up and run unit tests for your ESP-IDF projects.\n\n- Configure test environment\n- Write and run tests\n- Analyze test results\n\n[Open Testing View](command:testing.viewExplorer)",
+            "media": {
+              "markdown": "walkthroughs/advanced/unit-testing.md"
+            }
+          },
+          {
+            "id": "multi-project",
+            "title": "Multi-Project Management",
+            "description": "Learn to efficiently manage multiple ESP-IDF projects in a single workspace.",
+            "media": {
+              "markdown": "walkthroughs/advanced/multi-project.md"
+            }
+          },
+          {
+            "id": "conclusion",
+            "title": "Next Steps",
+            "description": "Congratulations! You've learned about essential advanced features of ESP-IDF development.\n\nNext steps:\n- Explore additional tools in ESP-IDF documentation\n- Join the ESP32 community forum\n- Check out example projects\n\n[Visit Our Documentation](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/additionalfeatures.html)",
+            "media": {
+              "markdown": "walkthroughs/advanced/advanced-conclusion.md"
+            }
+          }
+        ]
+      }
+    ],
     "problemMatchers": [
       {
         "name": "espIdf",
@@ -232,6 +376,13 @@
       }
     ],
     "menus": {
+      "extension/context": [
+        {
+          "command": "espIdf.openWalkthrough",
+          "when": "extension =~ /^espressif.esp-idf-extension$/ && extensionStatus == installed",
+          "group": "zzz"
+        }
+      ],
       "editor/title": [
         {
           "command": "espIdf.searchError",
@@ -611,6 +762,12 @@
             "scope": "window",
             "description": "%param.showOnboardingOnInit%"
           },
+          "idf.hasWalkthroughBeenShown": {
+            "type": "boolean",
+            "default": false,
+            "scope": "application",
+            "description": "%param.hasWalkthroughBeenShown%"
+          },
           "trace.poll_period": {
             "type": "number",
             "default": 1,
@@ -1033,6 +1190,10 @@
       }
     ],
     "commands": [
+      {
+        "command": "espIdf.openWalkthrough",
+        "title": "ESP-IDF: Open Get Started Walkthrough"
+      },
       {
         "command": "espIdf.searchError",
         "title": "%espIdf.searchError.title%"

package.nls.es.json

@@ -166,6 +166,7 @@
 	"param.usbSerialPortFilters.title": "Lista de USB productID y de USB vendorID para filtrar",
   "param.usbSerialPortFilters.vendorId": "Número hexadecimal del USB vendorID como texto.",
   "param.usbSerialPortFilters.productId": "Número hexadecimal del USB productID como texto.",
+	"param.hasWalkthroughBeenShown": "Indica si se ha mostrado el recorrido de bienvenida",
 	"trace.poll_period.description": "poll_period se establecerá para el rastreo de la aplicación",
 	"trace.skip_size.description": "skip_size se establecerá para el rastreo de la aplicación",
 	"trace.stop_tmo.description": "stop_tmo se establecerá para el rastreo de la aplicación",

package.nls.json

@@ -166,6 +166,7 @@
   "param.usbSerialPortFilters.title": "USB serial port productID and vendorID list to filter",
   "param.usbSerialPortFilters.vendorId": "USB Vendor ID hex number as string. Format is 0x0403",
   "param.usbSerialPortFilters.productId": "USB Product ID hex number as string. Format is 0x6010",
+  "param.hasWalkthroughBeenShown": "Has the walkthrough been shown",
   "trace.poll_period.description": "poll_period will be set for the apptrace",
   "trace.skip_size.description": "skip_size will be set for the apptrace",
   "trace.stop_tmo.description": "stop_tmo will be set for the apptrace",

package.nls.pt.json

@@ -164,6 +164,7 @@
 	"param.usbSerialPortFilters.title": "Lista de productID e vendorID da porta serial USB para filtrar",
   "param.usbSerialPortFilters.vendorId": "Número hexadecimal do USB vendorID como string.",
   "param.usbSerialPortFilters.productId": "Número hexadecimal de USB productID como string.",
+	"param.hasWalkthroughBeenShown": "Mostrar o guia de introdução na inicialização da extensão",
 	"trace.poll_period.description": "poll_period será definido para o apptrace",
 	"trace.skip_size.description": "skip_size será definido para o apptrace",
 	"trace.stop_tmo.description": "stop_tmo será definido para o apptrace",

package.nls.ru.json

@@ -166,6 +166,7 @@
 	"param.usbSerialPortFilters.title": "Список идентификаторов продуктов и идентификаторов поставщиков для последовательного порта USB для фильтрации",
   "param.usbSerialPortFilters.vendorId": "Шестнадцатеричный номер USB VendorID в виде строки. ",
   "param.usbSerialPortFilters.productId": "Шестнадцатеричный номер USB ProductID в виде строки. ",
+	"param.hasWalkthroughBeenShown": "Показывать ли руководство по настройке ESP-IDF при первом запуске.",
 	"trace.poll_period.description": "poll_ period будет установлен для apptrace",
 	"trace.skip_size.description": "Skip_size будет установлен для трассировки приложения.",
 	"trace.stop_tmo.description": "stop_tmo будет установлен для apptrace",

package.nls.zh-CN.json

@@ -166,6 +166,7 @@
 	"param.usbSerialPortFilters.title": "USB串口productID和vendorID列表进行过滤",
 	"param.usbSerialPortFilters.vendorId": "USB VendorID 十六进制数字作为字符串。",
   "param.usbSerialPortFilters.productId": "USB ProductID 十六进制数字作为字符串。",
+	"param.hasWalkthroughBeenShown": "是否显示了 ESP-IDF 配置窗口的漫游",
 	"trace.poll_period.description": "将为 apptrace 设置 poll_period",
 	"trace.skip_size.description": "将为 apptrace 设置 skip_size",
 	"trace.stop_tmo.description": "将为 apptrace 设置 stop_tmo",

src/checkExtensionSettings.ts

@@ -36,7 +36,7 @@ export async function checkExtensionSettings(
   try {
     const isExtensionConfigured = await isCurrentInstallValid(workspace);
     if (isExtensionConfigured) {
-      vscode.commands.executeCommand("espIdf.welcome.start");
+      await vscode.commands.executeCommand("espIdf.welcome.start");
       return;
     }
   } catch (error) {

src/extension.ts

@@ -3636,6 +3636,35 @@ export async function activate(context: vscode.ExtensionContext) {
     statusBarItems["currentIdfVersion"]
   );
 
+  // WALK-THROUGH
+  let disposable = vscode.commands.registerCommand(
+    "espIdf.openWalkthrough",
+    () => {
+      vscode.commands.executeCommand(
+        "workbench.action.openWalkthrough",
+        "espressif.esp-idf-extension#espIdf.walkthrough.basic-usage"
+      );
+    }
+  );
+
+  context.subscriptions.push(disposable);
+
+  const hasWalkthroughBeenShown = await idfConf.readParameter(
+    "idf.hasWalkthroughBeenShown"
+  );
+
+  if (!hasWalkthroughBeenShown) {
+    await idfConf.writeParameter(
+      "idf.hasWalkthroughBeenShown",
+      true,
+      vscode.ConfigurationTarget.Global
+    );
+    vscode.commands.executeCommand(
+      "workbench.action.openWalkthrough",
+      "espressif.esp-idf-extension#espIdf.walkthrough.basic-usage"
+    );
+  }
+
   // Hints Viewer
 
   const treeDataProvider = new ErrorHintProvider(context);

walkthroughs/advanced/advanced-conclusion.md

@@ -0,0 +1,21 @@
+# Congratulations on Completing the Advanced Guide! 🎉
+
+### Additional Extension Features to Explore
+
+- Application Tracing
+- CMakeLists Editor
+- Code coverage
+- DFU Flashing
+- Docker container
+- ESP-IDF Terminal
+- EFuse Explorer
+- Heap Tracing
+- Hints viewer
+- NVS Partition Table Editor
+- QEMU
+- Rainmaker
+- WSL
+
+[Explore our documentation](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/additionalfeatures.html) to find out more about them.
+
+Happy coding!

walkthroughs/advanced/advanced-intro.md

@@ -0,0 +1,12 @@
+# Welcome to ESP-IDF Advanced Features Guide
+
+This guide will introduce you to powerful features that will enhance your ESP-IDF development workflow. Each feature has it's own dedicated step.
+
+## Using This Guide
+- Each section builds on basic concepts
+- Features can be explored independently
+- Look for 💡 tips and ❗important notes
+- Check troubleshooting tips in each section or the "Troubleshooting Guide" step from this guide
+
+
+Ready to enhance your ESP-IDF development experience?

walkthroughs/advanced/app-size-analysis.md

@@ -0,0 +1,11 @@
+# Analyze Your Application Size
+
+## Visual Analysis
+
+![Gif of Size Analysis](../../media/walkthrough/gifs/size-analysis-gui.gif)
+
+## CLI Analysis
+![Screenshot of Size Analysis in the terminal](../../media/walkthrough/size-analysis.png)
+
+## Related Resources
+- [Application Size Analysis Documentation](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/additionalfeatures/application-size-analysis.html)

walkthroughs/advanced/component-installation.md

@@ -0,0 +1,12 @@
+# Install ESP-IDF Components
+
+### Browse and Install Components
+
+![GIF of Component Installation](../../media/walkthrough/gifs/install-component.gif)
+
+### Create Projects from Examples
+
+![GIF for Using Component Example](../../media/walkthrough/gifs/create-example-from-component.gif)
+
+## Related Resources
+- [Install ESP-IDF Components Documnetation](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/additionalfeatures/install-esp-components.html)

walkthroughs/advanced/debug-project.md

@@ -0,0 +1,10 @@
+# Debug Your ESP Project
+
+Debug ESP projects in VS Code with breakpoints, variable inspection, and more.
+
+![Debug Example](../../media/walkthrough/gifs/debug.gif)
+
+## Related Resources
+
+- [VS Code Extension Debug Documentation](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/debugproject.html)
+- [ESP-IDF Debug Documentation](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/index.html)

walkthroughs/advanced/multi-project.md

@@ -0,0 +1,8 @@
+# Work with Multiple ESP-IDF Projects
+
+These powerful features are available and fully documented in our [Working with Multiple Projects Documentation](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/additionalfeatures/multiple-projects.html):
+- Manage multiple projects in one VS Code window
+- Use different ESP-IDF versions per project
+- Create multiple build configurations
+- Switch projects via status bar
+- Configure project-specific settings

walkthroughs/advanced/partition-table.md

@@ -0,0 +1,8 @@
+# Customize Your ESP32's Memory Layout with Partition Table Editor
+
+
+![GIF of Partition Table](../../media/walkthrough/gifs/partition-table.gif)
+
+## Related Resources
+- [Partition Table Editor Documentation](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/additionalfeatures/partition-table-editor.html)
+- [ESP-IDF Partition Tables documentation](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/partition-tables.html)