Skip to content

Commit

Permalink
Simplify walkthroughs
Browse files Browse the repository at this point in the history
  • Loading branch information
radurentea committed Nov 20, 2024
1 parent 18bc782 commit c8b0bb2
Show file tree
Hide file tree
Showing 16 changed files with 51 additions and 287 deletions.
24 changes: 12 additions & 12 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -134,15 +134,15 @@
{
"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'",
"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\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.",
"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"
}
Expand All @@ -158,15 +158,15 @@
{
"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.",
"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 Walkthrough](command:workbench.action.openWalkthrough?%22espressif.esp-idf-extension%23espIdf.walkthrough.advanceds%22)",
"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"
}
Expand All @@ -181,7 +181,7 @@
{
"id": "advanced-introduction",
"title": "Introduction to Advanced Features",
"description": "Overview of advanced ESP-IDF development capabilities",
"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"
}
Expand All @@ -197,55 +197,55 @@
{
"id": "sdk-configuration",
"title": "SDK Configuration (menuconfig)",
"description": "Learn how to customize your project's configuration using 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",
"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:espIdf.componentRegistry)",
"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": "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)",
"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": "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)",
"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[Start Unit Testing](command:espIdf.unitTest)",
"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.\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)",
"description": "Learn to efficiently manage multiple ESP-IDF projects in a single workspace.",
"media": {
"markdown": "walkthroughs/advanced/multi-project.md"
}
Expand Down
5 changes: 1 addition & 4 deletions walkthroughs/advanced/advanced-conclusion.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,6 @@
# 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
### Additional Extension Features to Explore

- Application Tracing
- CMakeLists Editor
Expand Down
30 changes: 4 additions & 26 deletions walkthroughs/advanced/advanced-intro.md
Original file line number Diff line number Diff line change
@@ -1,34 +1,12 @@
# 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)
# 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

## 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!

Ready to enhance your ESP-IDF development experience?
13 changes: 1 addition & 12 deletions walkthroughs/advanced/app-size-analysis.md
Original file line number Diff line number Diff line change
@@ -1,22 +1,11 @@
# 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
## Related Resources
- [Application Size Analysis Documentation](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/additionalfeatures/application-size-analysis.html)
19 changes: 1 addition & 18 deletions walkthroughs/advanced/component-installation.md
Original file line number Diff line number Diff line change
@@ -1,29 +1,12 @@
# 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
## Related Resources
- [Install ESP-IDF Components Documnetation](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/additionalfeatures/install-esp-components.html)
38 changes: 1 addition & 37 deletions walkthroughs/advanced/debug-project.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,45 +2,9 @@

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 `<YOUR TARGET>` 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
## 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)
18 changes: 1 addition & 17 deletions walkthroughs/advanced/partition-table.md
Original file line number Diff line number Diff line change
@@ -1,24 +1,8 @@
# 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
## 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)
12 changes: 1 addition & 11 deletions walkthroughs/advanced/sdk-configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,16 +6,6 @@
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**
Expand All @@ -28,7 +18,7 @@
- Check write permissions
- Verify sdkconfig file location

Need help? Check:
## Related Resources
- [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)
2 changes: 0 additions & 2 deletions walkthroughs/advanced/troubleshooting.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,5 @@
# 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:**
Expand Down
31 changes: 0 additions & 31 deletions walkthroughs/advanced/unit-testing.md
Original file line number Diff line number Diff line change
@@ -1,38 +1,7 @@
# 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)
Expand Down
Loading

0 comments on commit c8b0bb2

Please sign in to comment.