diff --git a/.vscode/settings.json b/.vscode/settings.json index d9952f78f..dfa4f547b 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -34,5 +34,6 @@ } ], "typescript.updateImportsOnFileMove.enabled": "always", - "workbench.editor.enablePreview": true + "workbench.editor.enablePreview": true, + "iis.configDir": "" } diff --git a/media/walkthrough/commands-section.png b/media/walkthrough/commands-section.png new file mode 100644 index 000000000..17e217fe6 Binary files /dev/null and b/media/walkthrough/commands-section.png differ diff --git a/media/walkthrough/create-project.png b/media/walkthrough/create-project.png new file mode 100644 index 000000000..a2975fb96 Binary files /dev/null and b/media/walkthrough/create-project.png differ diff --git a/media/walkthrough/esp-idf-explorer.png b/media/walkthrough/esp-idf-explorer.png new file mode 100644 index 000000000..cb97462fb Binary files /dev/null and b/media/walkthrough/esp-idf-explorer.png differ diff --git a/media/walkthrough/examples-list.png b/media/walkthrough/examples-list.png new file mode 100644 index 000000000..f8e1c5080 Binary files /dev/null and b/media/walkthrough/examples-list.png differ diff --git a/media/walkthrough/express-setup.png b/media/walkthrough/express-setup.png new file mode 100644 index 000000000..a73abfef3 Binary files /dev/null and b/media/walkthrough/express-setup.png differ diff --git a/media/walkthrough/gifs/configure-jtag-h2.gif b/media/walkthrough/gifs/configure-jtag-h2.gif new file mode 100644 index 000000000..bc6f4ebc7 Binary files /dev/null and b/media/walkthrough/gifs/configure-jtag-h2.gif differ diff --git a/media/walkthrough/gifs/create-example-from-component.gif b/media/walkthrough/gifs/create-example-from-component.gif new file mode 100644 index 000000000..7acb931ea Binary files /dev/null and b/media/walkthrough/gifs/create-example-from-component.gif differ diff --git a/media/walkthrough/gifs/debug.gif b/media/walkthrough/gifs/debug.gif new file mode 100644 index 000000000..76b97c503 Binary files /dev/null and b/media/walkthrough/gifs/debug.gif differ diff --git a/media/walkthrough/gifs/install-component.gif b/media/walkthrough/gifs/install-component.gif new file mode 100644 index 000000000..1b513e199 Binary files /dev/null and b/media/walkthrough/gifs/install-component.gif differ diff --git a/media/walkthrough/gifs/partition-table.gif b/media/walkthrough/gifs/partition-table.gif new file mode 100644 index 000000000..d6f23f8d5 Binary files /dev/null and b/media/walkthrough/gifs/partition-table.gif differ diff --git a/media/walkthrough/gifs/size-analysis-gui.gif b/media/walkthrough/gifs/size-analysis-gui.gif new file mode 100644 index 000000000..b427bf9b9 Binary files /dev/null and b/media/walkthrough/gifs/size-analysis-gui.gif differ diff --git a/media/walkthrough/gifs/unit-testing.gif b/media/walkthrough/gifs/unit-testing.gif new file mode 100644 index 000000000..5790826f5 Binary files /dev/null and b/media/walkthrough/gifs/unit-testing.gif differ diff --git a/media/walkthrough/hints-viewer.png b/media/walkthrough/hints-viewer.png new file mode 100644 index 000000000..508b02f79 Binary files /dev/null and b/media/walkthrough/hints-viewer.png differ diff --git a/media/walkthrough/icons/build-flash-monitor.png b/media/walkthrough/icons/build-flash-monitor.png new file mode 100644 index 000000000..7870177e5 Binary files /dev/null and b/media/walkthrough/icons/build-flash-monitor.png differ diff --git a/media/walkthrough/icons/build.png b/media/walkthrough/icons/build.png new file mode 100644 index 000000000..a49674ac0 Binary files /dev/null and b/media/walkthrough/icons/build.png differ diff --git a/media/walkthrough/icons/debug.png b/media/walkthrough/icons/debug.png new file mode 100644 index 000000000..da91ba708 Binary files /dev/null and b/media/walkthrough/icons/debug.png differ diff --git a/media/walkthrough/icons/device-target.png b/media/walkthrough/icons/device-target.png new file mode 100644 index 000000000..110f6d452 Binary files /dev/null and b/media/walkthrough/icons/device-target.png differ diff --git a/media/walkthrough/icons/flash-method.png b/media/walkthrough/icons/flash-method.png new file mode 100644 index 000000000..3cfb5bb39 Binary files /dev/null and b/media/walkthrough/icons/flash-method.png differ diff --git a/media/walkthrough/icons/flash.png b/media/walkthrough/icons/flash.png new file mode 100644 index 000000000..99d783774 Binary files /dev/null and b/media/walkthrough/icons/flash.png differ diff --git a/media/walkthrough/icons/monitor.png b/media/walkthrough/icons/monitor.png new file mode 100644 index 000000000..2c87bdb79 Binary files /dev/null and b/media/walkthrough/icons/monitor.png differ diff --git a/media/walkthrough/icons/port.png b/media/walkthrough/icons/port.png new file mode 100644 index 000000000..339fe730d Binary files /dev/null and b/media/walkthrough/icons/port.png differ diff --git a/media/walkthrough/icons/run-and-debug.png b/media/walkthrough/icons/run-and-debug.png new file mode 100644 index 000000000..5486ef04a Binary files /dev/null and b/media/walkthrough/icons/run-and-debug.png differ diff --git a/media/walkthrough/icons/sdkconfig.png b/media/walkthrough/icons/sdkconfig.png new file mode 100644 index 000000000..155193033 Binary files /dev/null and b/media/walkthrough/icons/sdkconfig.png differ diff --git a/media/walkthrough/idf-version.png b/media/walkthrough/idf-version.png new file mode 100644 index 000000000..ea07af008 Binary files /dev/null and b/media/walkthrough/idf-version.png differ diff --git a/media/walkthrough/install-btn.png b/media/walkthrough/install-btn.png new file mode 100644 index 000000000..24bac1a41 Binary files /dev/null and b/media/walkthrough/install-btn.png differ diff --git a/media/walkthrough/peripheral-viewer.png b/media/walkthrough/peripheral-viewer.png new file mode 100644 index 000000000..08dcd8742 Binary files /dev/null and b/media/walkthrough/peripheral-viewer.png differ diff --git a/media/walkthrough/project-components.png b/media/walkthrough/project-components.png new file mode 100644 index 000000000..542151441 Binary files /dev/null and b/media/walkthrough/project-components.png differ diff --git a/media/walkthrough/python-selection.png b/media/walkthrough/python-selection.png new file mode 100644 index 000000000..487445722 Binary files /dev/null and b/media/walkthrough/python-selection.png differ diff --git a/media/walkthrough/size-analysis.png b/media/walkthrough/size-analysis.png new file mode 100644 index 000000000..ae597043e Binary files /dev/null and b/media/walkthrough/size-analysis.png differ diff --git a/media/walkthrough/status-bar.png b/media/walkthrough/status-bar.png new file mode 100644 index 000000000..481ad48ea Binary files /dev/null and b/media/walkthrough/status-bar.png differ diff --git a/package.json b/package.json index 6a6557dd9..70ef35af2 100644 --- a/package.json +++ b/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\nAlternatively, access this command via the Command Palette by typing 'ESP-IDF: Configure ESP-IDF extension'", + "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\nAlternatively, you can open the Command Palette and type 'ESP-IDF: Show Examples Projects'.\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)\n\nAlternatively, access individual commands through the ESP-IDF Explorer view or Command Palette.", + "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 Walkthrough](command:workbench.action.openWalkthrough?%22espressif.esp-idf-extension%23espIdf.walkthrough.advanceds%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", + "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", + "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", + "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:espIdf.componentRegistry)", + "media": { + "markdown": "walkthroughs/advanced/component-installation.md" + } + }, + { + "id": "app-size-analysis", + "title": "Application Size Analysis", + "description": "Learn how to analyze and optimize your application's memory usage using the Size Analysis tool.\n\n- Understand memory section usage\n- Identify large components\n- Optimize code size\n\n[Open Size Analysis](command:espIdf.sizeAnalysis)", + "media": { + "markdown": "walkthroughs/advanced/app-size-analysis.md" + } + }, + { + "id": "partition-table", + "title": "Partition Table Configuration", + "description": "Master the Partition Table Editor to configure your device's flash memory layout.\n\n- Create and modify partitions\n- Set up OTA updates\n- Configure storage partitions\n\n[Open Partition Editor](command:espIdf.partitionTableEditor)", + "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[Start Unit Testing](command:espIdf.unitTest)", + "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.\n\n- Set up multi-project workspace\n- Configure project-specific settings\n- Manage multiple devices\n\n[Add Folder to Workspace](command:workbench.action.addRootFolder)", + "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", @@ -217,6 +361,13 @@ } ], "menus": { + "extension/context": [ + { + "command": "espIdf.openWalkthrough", + "when": "extension =~ /^espressif.esp-idf-extension$/ && extensionStatus == installed", + "group": "zzz" + } + ], "editor/title": [ { "command": "espIdf.searchError", @@ -625,6 +776,12 @@ "scope": "window", "description": "%param.showOnboardingOnInit%" }, + "idf.hasWalkthroughBeenShown": { + "type": "boolean", + "default": false, + "scope": "application", + "description": "%param.hasWalkthroughBeenShown%" + }, "trace.poll_period": { "type": "string", "default": "1", @@ -976,6 +1133,10 @@ } ], "commands": [ + { + "command": "espIdf.openWalkthrough", + "title": "ESP-IDF: Open Get Started Walkthrough" + }, { "command": "espIdf.searchError", "title": "%espIdf.searchError.title%" diff --git a/package.nls.es.json b/package.nls.es.json index 3fd06b0ce..efa43be58 100644 --- a/package.nls.es.json +++ b/package.nls.es.json @@ -162,6 +162,7 @@ "param.uncoveredLightTheme": "Color de fondo para líneas no cubiertas en tema claro para Cobertura de ESP-IDF.", "param.useIDFKConfigStyle": "Habilitar/Deshabilitar validación de estilo ESP-IDF para archivos Kconfig", "param.hintsViewer.title": "Ruta al archivo de sugerencias.", + "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", diff --git a/package.nls.json b/package.nls.json index fd970c107..39058b7dc 100644 --- a/package.nls.json +++ b/package.nls.json @@ -162,6 +162,7 @@ "param.uncoveredLightTheme": "Background color for uncovered lines in Light theme for ESP-IDF Coverage.", "param.useIDFKConfigStyle": "Enable/Disable ESP-IDF style validation for Kconfig files", "param.hintsViewer.title": "Path to the hints file.", + "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", diff --git a/package.nls.pt.json b/package.nls.pt.json index b2a29b9d3..453b336d8 100644 --- a/package.nls.pt.json +++ b/package.nls.pt.json @@ -160,6 +160,7 @@ "param.uncoveredDarkTheme": "Cor de fundo para linhas descobertas no tema Dark para cobertura ESP-IDF.", "param.uncoveredLightTheme": "Cor de fundo para linhas descobertas no tema Light para cobertura ESP-IDF.", "param.useIDFKConfigStyle": "Habilitar/desabilitar validação de estilo ESP-IDF para arquivos Kconfig", + "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", diff --git a/package.nls.ru.json b/package.nls.ru.json index ac942a6c3..9497f33dd 100644 --- a/package.nls.ru.json +++ b/package.nls.ru.json @@ -162,6 +162,7 @@ "param.uncoveredLightTheme": "Цвет фона для непокрытых линий в светлой теме для покрытия ESP-IDF.", "param.useIDFKConfigStyle": "Включить/отключить проверку стиля ESP-IDF для файлов Kconfig.", "param.hintsViewer.title": "Путь к файлу подсказок", + "param.hasWalkthroughBeenShown": "Показывать ли руководство по настройке ESP-IDF при первом запуске.", "trace.poll_period.description": "poll_ period будет установлен для apptrace", "trace.skip_size.description": "Skip_size будет установлен для трассировки приложения.", "trace.stop_tmo.description": "stop_tmo будет установлен для apptrace", diff --git a/package.nls.zh-CN.json b/package.nls.zh-CN.json index 9e895f576..46b6a97f7 100644 --- a/package.nls.zh-CN.json +++ b/package.nls.zh-CN.json @@ -162,6 +162,7 @@ "param.uncoveredLightTheme": "在 ESP-IDF 覆盖率的浅色主题中未覆盖的行的背景颜色。", "param.useIDFKConfigStyle": "启用/禁用 Kconfig 文件的 ESP-IDF 样式验证", "param.hintsViewer.title": "提示文件的路径", + "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", diff --git a/src/extension.ts b/src/extension.ts index 10241e3fb..c8c351f16 100644 --- a/src/extension.ts +++ b/src/extension.ts @@ -3493,6 +3493,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); diff --git a/walkthroughs/advanced/advanced-conclusion.md b/walkthroughs/advanced/advanced-conclusion.md new file mode 100644 index 000000000..454ccc29e --- /dev/null +++ b/walkthroughs/advanced/advanced-conclusion.md @@ -0,0 +1,24 @@ +# Congratulations on Completing the Advanced Guide! 🎉 + +You've been introduced to essential advanced features that will enhance your ESP-IDF development workflow. + + +### Additional Tools 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! \ No newline at end of file diff --git a/walkthroughs/advanced/advanced-intro.md b/walkthroughs/advanced/advanced-intro.md new file mode 100644 index 000000000..6f5d5bf1d --- /dev/null +++ b/walkthroughs/advanced/advanced-intro.md @@ -0,0 +1,34 @@ +# Welcome to ESP-IDF Advanced Features + +This guide will introduce you to powerful features that will enhance your ESP-IDF development workflow. You'll learn about: + +- Troubleshooting Guide +- Project configuration using menuconfig +- Installing ESP-IDF components +- Debugging capabilities +- Analyze your application's memory usage in detail +- Configure your device's flash memory layout visually +- Set up a testing environment for your projects +- Work with multiple projects in one workspace + +## Prerequisites +- Completed the Basic Usage Guide +- Basic familiarity with ESP-IDF concepts +- Have a working ESP-IDF setup +- Have your development board ready +- JTAG debugging hardware (for debugging features) + + +## Using This Guide +- Each section builds on basic concepts +- Features can be explored independently +- Look for 💡 tips and ❗important notes + +## Navigation Tips + +- Each section can be followed independently +- Look for 💡 tips throughout the guide +- Use Command Palette (F1 / Ctrl+Shift+P / Cmd+Shift+P) to access features +- Check troubleshooting tips in each section or the "Troubleshooting Guide" step from this guide + +Ready to enhance your ESP-IDF development experience? Let's begin with SDK Configuration! \ No newline at end of file diff --git a/walkthroughs/advanced/app-size-analysis.md b/walkthroughs/advanced/app-size-analysis.md new file mode 100644 index 000000000..43118e2f6 --- /dev/null +++ b/walkthroughs/advanced/app-size-analysis.md @@ -0,0 +1,22 @@ +# Analyze Your Application Size + +ESP-IDF Extension provides powerful tools to analyze your application's memory usage, helping you optimize storage allocation. You can visualize size information in two convenient ways: + +## Visual Analysis +Get a detailed graphical breakdown of your application's memory usage: + +1. Run the command "ESP-IDF: Size Analysis of the Binaries" +2. Press Enter to see a visual representation of memory usage + +![Gif of Size Analysis](../../media/walkthrough/gifs/size-analysis-gui.gif) + +## CLI Analysis +View detailed size information in the terminal after each build: + +1. Build your project using the Command "ESP-IDF: Build your Project" +2. The size analysis will automatically appear in the terminal after the build + +![Screenshot of Size Analysis in the terminal](../../media/walkthrough/size-analysis.png) + +## Resources +- [Application Size Analysis Documentation](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/additionalfeatures/application-size-analysis.html) \ No newline at end of file diff --git a/walkthroughs/advanced/component-installation.md b/walkthroughs/advanced/component-installation.md new file mode 100644 index 000000000..85802850a --- /dev/null +++ b/walkthroughs/advanced/component-installation.md @@ -0,0 +1,29 @@ +# Install ESP-IDF Components + +## Overview +The ESP-IDF extension allows you to browse, install, and manage ESP components directly from the VS Code interface, making it easier to enhance your ESP-IDF projects with additional functionality. + +## Features +- Browse the ESP Component Registry within VS Code +- Install components directly to your project +- Create new projects from component examples +- Special support for Arduino-ESP32 as a component + +### Browse and Install Components +1. Run "ESP-IDF: ESP Component Registry" command +2. Use the search bar to find components +3. Click on a component to view details +4. Click the "Install" button to add it to your project + +![GIF of Component Installation](../../media/walkthrough/gifs/install-component.gif) + +### Create Projects from Examples +1. Find a component with examples +2. Click "Create project from this template" +3. Choose your project location +4. The extension will set up a new project with the component pre-configured + +![GIF for Using Component Example](../../media/walkthrough/gifs/create-example-from-component.gif) + +## Resources +- [Install ESP-IDF Components Documnetation](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/additionalfeatures/install-esp-components.html) \ No newline at end of file diff --git a/walkthroughs/advanced/debug-project.md b/walkthroughs/advanced/debug-project.md new file mode 100644 index 000000000..af8f46252 --- /dev/null +++ b/walkthroughs/advanced/debug-project.md @@ -0,0 +1,46 @@ +# Debug Your ESP Project + +Debug ESP projects in VS Code with breakpoints, variable inspection, and more. + +## Prerequisites + +Before starting: +- Verify your board supports JTAG debugging +- Configure JTAG following the ESP-IDF documentation for your specific target + > Navigate to the correct JTAG setup guide: + > 1. Visit [ESP-IDF Programming Guide](https://docs.espressif.com/projects/esp-idf/en/latest/) + > 2. Select your target (e.g., ESP32, ESP32-H2) + > 3. Go to API Guides → JTAG Debugging -> Configuring `` Target + +> 💡 **Windows Users**: Install required USB drivers via ESP-IDF Tools Installer v2.8+ or follow target-specific documentation. + +![Navigate to JTAG Configuration](../../media/walkthrough/gifs/configure_jtag_h2.gif) + +## Setup Steps + +1. Configure Debug Connection: + - `ESP-IDF: Select Port to Use` + - `ESP-IDF: Select OpenOCD Board Configuration` + +2. Launch Debugger: + - Press `F5` or use Run → Start Debugging + - Program halts at entry point + +![Debug Example](../../media/walkthrough/gifs/debug.gif) + +## Debug Features + +- Set breakpoints: Click line number margin +- Inspect variables: Use Watch window +- Navigation: + - Step Over (F10) + - Step Into (F11) + +> 💡 **Note**: ESP32 is limited to 2 hardware breakpoints - use strategically! + +For aditional debugging features, check out the [VS Code Extension Debug Guide](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/debugproject.html) + +## 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) \ No newline at end of file diff --git a/walkthroughs/advanced/multi-project.md b/walkthroughs/advanced/multi-project.md new file mode 100644 index 000000000..2385b0e44 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/walkthroughs/advanced/partition-table.md b/walkthroughs/advanced/partition-table.md new file mode 100644 index 000000000..f8bdfb437 --- /dev/null +++ b/walkthroughs/advanced/partition-table.md @@ -0,0 +1,24 @@ +# Customize Your ESP32's Memory Layout with Partition Table Editor + +## Description +The Partition Table Editor provides a user-friendly interface to define and modify your ESP32's flash memory layout. You can create custom partitions for your application, data, and bootloader with just a few clicks. + +## Features +- Visual partition table editing interface +- Automatic CSV file generation and management +- Direct integration with ESP-IDF build system +- Real-time validation of partition configurations + +![GIF of Partition Table](../../media/walkthrough/gifs/partition-table.gif) + +## Try it yourself +1. Run the command`ESP-IDF: SDK Configuration Editor` +2. Open editor by running the command `ESP-IDF: Open Partition Table Editor UI` +3. If you haven't enabled custom partition table, you will be asked if you want to. + +## Did you know? +💡 The editor automatically validates your partition layout to ensure it meets ESP32 requirements and prevents common configuration mistakes. + +## 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) \ No newline at end of file diff --git a/walkthroughs/advanced/sdk-configuration.md b/walkthroughs/advanced/sdk-configuration.md new file mode 100644 index 000000000..700ecf267 --- /dev/null +++ b/walkthroughs/advanced/sdk-configuration.md @@ -0,0 +1,34 @@ +# Configuring Your Project with menuconfig + +## Opening SDK Configuration +![Menuconfig Interface](../media/walkthrough/menuconfig.gif) + +1. Click the menuconfig icon in status bar + - Or use Command Palette: "ESP-IDF: SDK Configuration Editor" + +## Key Features + +### Common Configurations +- Component configuration +- Compiler options +- Flash and partition settings +- Serial port parameters + +💡 **Tip**: Use search bar to quickly find settings + +## Troubleshooting + +1. **Editor Won't Open** + - Check Python installation + - Verify ESP-IDF environment + - Run [Doctor Command](command:espIdf.doctorCommand) + +2. **Changes Not Saving** + - Save before closing + - Check write permissions + - Verify sdkconfig file location + +Need help? Check: +- [Configure Your Project](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/configureproject.html) +- [Project Configuration Editor](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/additionalfeatures/project-configuration.html) +- [ESP-IDF Configuration documentation](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/kconfig-reference.html) \ No newline at end of file diff --git a/walkthroughs/advanced/troubleshooting.md b/walkthroughs/advanced/troubleshooting.md new file mode 100644 index 000000000..367f72494 --- /dev/null +++ b/walkthroughs/advanced/troubleshooting.md @@ -0,0 +1,77 @@ +# Troubleshooting ESP-IDF Projects + +Learn how to diagnose and resolve common issues with ESP-IDF development in VS Code. + +### Debug Logging Configuration + +1. **OpenOCD Debug Level:** + - Open VS Code settings + - Set `idf.openOcdDebugLevel` to 4 or higher + - Reveals detailed OpenOCD server output + +2. **Debug Adapter Logging:** + - Open project's `.vscode/launch.json` + - Set `logLevel` to 3 or higher + - Provides additional debug adapter information + +### Diagnostic Tools + +1. **ESP-IDF Output Panel:** + - View > Output > ESP-IDF + - Shows real-time extension activity + - Useful for tracking command execution + +2. **Doctor Command:** + - Run "ESP-IDF: Doctor Command" from Command Palette + - Generates environment configuration report + - Automatically copies to clipboard + +3. **Extension Logs:** + + Windows location: + + >%USERPROFILE%.vscode\extensions\espressif.esp-idf-extension-VERSION\esp_idf_vsc_ext.log + + MacOS/Linux location: + + >$HOME/.vscode/extensions/espressif.esp-idf-extension-VERSION/esp_idf_vsc_ext.log + +### Common Issues + +1. **Settings Hierarchy:** +- Check settings at all levels: + - Global (User Settings) + - Workspace + - Workspace Folder +- Doctor Command shows active settings + +2. **Python Package Issues:** +- Use "ESP-IDF: Install ESP-IDF Extension Python Packages" + - Reinstalls required packages + - Updates both ESP-IDF and extension packages + +3. **Windows-Specific:** +- Enable Developer Mode for symlink issues + - Helps with ESP-IDF git cloning + - Resolves permission-related errors + +### Getting Help + +1. **OpenOCD Issues:** +- Review [OpenOCD troubleshooting FAQ](https://github.com/espressif/openocd-esp32/wiki/Troubleshooting-FAQ) +- Check application tracing +- Verify debug configuration + +2. **Developer Tools:** +- Help > Toggle Developer Tools +- Check Console tab for errors +- Copy relevant error messages + +3. **Community Support:** +- Search [existing issues](http://github.com/espressif/vscode-esp-idf-extension/issues) +- Open [new issue](https://github.com/espressif/vscode-esp-idf-extension/issues/new/choose) +- Include Doctor Command output + +## Related Resources + +- [Troubleshooting documentation](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/troubleshooting.html) \ No newline at end of file diff --git a/walkthroughs/advanced/unit-testing.md b/walkthroughs/advanced/unit-testing.md new file mode 100644 index 000000000..35cd816db --- /dev/null +++ b/walkthroughs/advanced/unit-testing.md @@ -0,0 +1,39 @@ +# Unit Testing with ESP-IDF + +Learn how to use Unity-based unit testing in your ESP-IDF projects directly from VS Code. + +## Features +- Automatic test discovery from your project's components +- Visual test runner integration in VS Code's Testing tab +- PyTest-based test execution with detailed results +- Support for both CMake and legacy Make build systems + +![GIF about Unit Testing](../../media/walkthrough/gifs/unit-testing.gif) + +## Try it yourself + +1. Install the testing requirements: + - Open Command Palette (Ctrl+Shift+P) + - Type "ESP-IDF Unit Test: Install ESP-IDF PyTest requirements" + - Wait for the installation to complete + +2. Add tests to your component: + - Create a `test` directory in your component folder + - Add test files following the pattern `test_*.c` + - Use the Unity test framework: + ```c + TEST_CASE("my test name", "[my_component]") + { + // Your test code here + } + ``` + +3. Run your tests: + - Open the Testing tab in the Activity Bar + - Click the Run Test button next to any test + - View results directly in VS Code + +## Related Resources +- [Unit Testing with Unity Documentation](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/additionalfeatures/unit-testing.html) +- [ESP-IDF Unit Testing in ESP32 Documentation](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/unit-tests.html) +- Example: ESP-IDF unit_test project \ No newline at end of file diff --git a/walkthroughs/basic/additional-resources.md b/walkthroughs/basic/additional-resources.md new file mode 100644 index 000000000..cb55c4b53 --- /dev/null +++ b/walkthroughs/basic/additional-resources.md @@ -0,0 +1,28 @@ +# Additional Resources and User Interface (UI) Exploration for ESP-IDF Development + +Now that you have completed the ESP-IDF Basic Usage Walkthrough, enhance your development skills with the ESP-IDF by using the VS Code extension. Explore the additional resources below to learn more about the extension’s features. + +## ESP-IDF VS Code Extension Resources + +1. [GitHub Repository](https://github.com/espressif/vscode-esp-idf-extension): Explore the VS Code extension source code and issue tracking. +2. [Documentation](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/#): Comprehensive guides and troubleshooting for the ESP-IDF VS Code extension. + +## ESP-IDF Official Documentation + +3. [ESP-IDF Programming Guide](https://docs.espressif.com/projects/esp-idf/en/latest/): The ESP-IDF programming guide for all the ESP32 series. + +## Community and Support + +4. [ESP32 Forum](https://esp32.com/): The official community forum for the ESP32. +5. [Espressif on Youtube](https://www.youtube.com/c/EspressifSystems): Official YouTube channel with product information, webinars and talks. +6. [Developer Portal](https://developer.espressif.com/): The developer resources portal with tutorials, articles, workshops, and news. + +## Explore the ESP-IDF Extension User Interface + +For a comprehensive overview of the ESP-IDF extension’s features, we recommend taking the User Interface (UI) Walkthrough. This interactive guide will introduce you to all the UI elements included in the extension.To start the UI Walkthrough, click the link below: + +[Start Advanced Walkthrough](command:workbench.action.openWalkthrough?%22espressif.esp-idf-extension%23espIdf.walkthrough.advanced%22) + +By exploring these resources and completing the Advanced Walkthrough, you'll be well-prepared to tackle more advanced ESP-IDF projects, mastering ESP-IDF development using the VS Code Extension. + +Happy coding! \ No newline at end of file diff --git a/walkthroughs/basic/basic-usage-intro.md b/walkthroughs/basic/basic-usage-intro.md new file mode 100644 index 000000000..e1e80d124 --- /dev/null +++ b/walkthroughs/basic/basic-usage-intro.md @@ -0,0 +1,17 @@ +# Welcome to ESP-IDF Extension Basic Usage Guide + +Learn how to use the ESP-IDF extension for Visual Studio Code effectively. This guide covers: + +* Extension configuration +* Creating projects from ESP-IDF examples +* Building, flashing, and monitoring ESP projects + +**Quick Tip**: Access the Command Palette using: +- Windows/Linux: `F1` or `Ctrl+Shift+P` +- macOS: `F1` or `Cmd+Shift+P` + +The guide is suitable for both newcomers and experienced developers transitioning to VS Code for ESP-IDF development. + +> 💡 **Need Help?** If you encounter any issues while going through the walkthrough, consult our [troubleshooting documentation](https://github.com/espressif/vscode-esp-idf-extension/blob/master/docs/TROUBLESHOOTING.md). + +Ready to begin configuring your environment? \ No newline at end of file diff --git a/walkthroughs/basic/build-flash-monitor.md b/walkthroughs/basic/build-flash-monitor.md new file mode 100644 index 000000000..14e27a1d1 --- /dev/null +++ b/walkthroughs/basic/build-flash-monitor.md @@ -0,0 +1,81 @@ +# Building, Flashing, and Monitoring Your ESP-IDF Project + +Learn how to compile your code, flash it to your device, and monitor the output. You can perform these operations individually or all at once. + +### Building Your Project + +1. **Build Options:** + - Click the "Build Project" icon from the status bar + + !["Build Project"](../../media/walkthrough/icons/build.png) + + - Use Command Palette: "ESP-IDF: Build your Project" + - Use keyboard shortcut (if configured) + +2. **Build Process:** + - The extension will compile your code + - Output appears in the terminal + +### Flashing to Device + +1. **Prerequisites:** + - Ensure device is connected + - Correct port is selected + +2. **Flash Options:** + - Click "Flash Device" icon from the status bar + + !["Flash Device"](../../media/walkthrough/icons/flash.png) + + - Use Command Palette: "ESP-IDF: Flash (UART) your Project" + +### Monitoring Output + +1. **Monitor Options:** + - Click "Monitor Device" icon from the status bar + + !["Monitor Device"](../../media/walkthrough/icons/monitor.png) + + - Use Command Palette: "ESP-IDF: Monitor Device" + +2. **Monitor Features:** + - View device output in real-time + - Send commands through UART + +### All-in-One Operation + +The most convenient way is using "Build, Flash and Monitor": +1. Click the "Build, Flash and Monitor" icon from the status bar + + !["Build, Flash and Monitor"](../../media/walkthrough/icons/build-flash-monitor.png) + +2. Or use Command Palette: "ESP-IDF: Build, Flash and Start a Monitor on your Device" +3. The extension will: + - Build your project + - Flash the binary + - Start the monitor automatically + +### Common Issues + +- **Build Failures:** + - Check error messages in terminal + +- **Flash Issues:** + - Verify correct port selection + - Check device connection + - Ensure device is in correct mode + +- **Monitor Problems:** + - Ensure no other program is using the port + +## Next Steps + +For more in depth information about building, flashing and monitoring check out our documentation: +- [Build the Project](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/buildproject.html) +- [Flash onto the Device](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/flashdevice.html) +- [Monitor the Output](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/monitoroutput.html) + +After successfully building, flashing, and monitoring your project: +- Experiment with project's code and re-build and re-flash the project +- Debug your application if needed +- Explore more advanced features \ No newline at end of file diff --git a/walkthroughs/basic/configuration.md b/walkthroughs/basic/configuration.md new file mode 100644 index 000000000..c9bd8ef67 --- /dev/null +++ b/walkthroughs/basic/configuration.md @@ -0,0 +1,38 @@ +# Configure the ESP-IDF VS Code Extension + +### 1. Install Prerequisites (macOS and Linux only) +Follow the steps in our [ESP-IDF installation documentation](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/linux-macos-setup.html#step-1-install-prerequisites) for a quick and simple process. + +### 2. Select Setup Mode +Choose the Express setup mode (recommended). +![Express Setup Mode selection](../../media/walkthrough/express-setup.png) + +### 3. Choose ESP-IDF Version +Expend dropdown menu and select an ESP-IDF version. + +![ESP-IDF Version selection](../../media/walkthrough/idf-version.png) + +### 4. Set Python Path (macOS and Linux only) +Choose the appropriate Python path from the dropdown. + +![Python Path selection](../../media/walkthrough/python-selection.png) + +### 5. Install +Click the Install button to begin the installation process. + +![Start Installation](../../media/walkthrough/install-btn.png) + +### 6. Post-Installation Step (Linux only) +After installation, run the following command in your preferred terminal: +``` +sudo cp --update=none /home/hmp/.espressif/tools/openocd-esp32/v0.12.0-esp32-20240318/openocd-esp32/share/openocd/contrib/60-openocd.rules /etc/udev/rules.d +``` + +## Next Steps + +In case you get stuck, you can always follow the in depth [Installation](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/installation.html) documentation. + +Once configuration is complete, you're ready to start developing with ESP-IDF in VS Code. You can now: +- Create a new project +- Open an existing ESP-IDF project +- Build, flash, and monitor your ESP device directly from VS Code \ No newline at end of file diff --git a/walkthroughs/basic/create-project.md b/walkthroughs/basic/create-project.md new file mode 100644 index 000000000..2dc52b088 --- /dev/null +++ b/walkthroughs/basic/create-project.md @@ -0,0 +1,21 @@ +# Create a Project Using an ESP-IDF Example + +### 1. Select an Example Project +Choose an example project from the list provided. For beginners, we recommend starting with the Blink example. + +![Example project selection](../../media/walkthrough/examples-list.png) + +### 2. Create the Project +Click the "Create project using example blink" button to proceed. + +![Create project button](../../media/walkthrough/create-project.png) + +After clicking the button, you'll be prompted to choose a location where the project will be created. + +## Next Steps + +For more information, you can check our [Start a ESP-IDF Project](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/startproject.html) documentation. + +Once you've created your project: +- Explore the project structure in VS Code +- Review the example code to understand its functionality \ No newline at end of file diff --git a/walkthroughs/basic/setup-project.md b/walkthroughs/basic/setup-project.md new file mode 100644 index 000000000..245b67c9a --- /dev/null +++ b/walkthroughs/basic/setup-project.md @@ -0,0 +1,54 @@ +# Setting Up Your ESP-IDF Project + +Before you can build and flash your project, you'll need to configure several important settings. Follow these steps to properly set up your development environment. + +### 1. Set Target Device +First, specify which ESP chip you're developing for: + +1. Click the "Set Espressif Device Target" icon from the status bar or use the "ESP-IDF: Set Espressif Device Target" command from Command Palette + + !["Set Espressif Device Target"](../../media/walkthrough/icons/device-target.png) + +2. Choose your target (e.g., esp32, esp32s2, esp32c3) from the list of targets +3. The extension will automatically adjust settings for your selected target + +### 2. Configure Project Settings (not needed in our example) +Next, configure your project-specific settings: + +1. Open ESP-IDF Configuration editor (menuconfig): + - Use the "ESP-IDF: SDK Configuration Editor(Menuconfig)" command from Command Palette + - Or click the "SDK Configuration editor" icon from the status bar + + !["SDK Configuration editor"](../../media/walkthrough/icons/sdkconfig.png) + +> 💡 **Tip**: For a comprehensive list of available configuration options, check the [ESP-IDF Configuration Options Reference](https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-reference/kconfig.html#configuration-options-reference) + +### 3. Serial Port Setup +Configure your serial connection: + +1. Connect your ESP device to your computer +2. Select the correct serial port: + - Click the "Select Port to Use" icon from VS Code's status bar + + !["Select Port to Use"](../../media/walkthrough/icons/port.png) + + - Or use "ESP-IDF: Select Port to Use" command from Command Palette + +### 4. Set Flashing Method (UART recommended for simplicity) +Finally, select the flashing method you want to use: + +- Use the "ESP-IDF: Select Flash Method" command from Command Palette +- Or click the "Select Flash Method" icon from the status bar + + !["Select Flash Method"](../../media/walkthrough/icons/flash-method.png) + +## Next Steps + +For more in depth information about connecting your device and setting up the project, check out our documentation: +- [Connect Your Device](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/connectdevice.html) +- [Configure Your Project](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/configureproject.html) + +Once you've completed these setup steps, you're ready to: +- Build your project +- Flash it to your device +- Monitor the device output \ No newline at end of file