From e04b341d1b334bfc3ee28f5396f2f0792a762168 Mon Sep 17 00:00:00 2001 From: AndriiFilippov Date: Wed, 21 Oct 2026 23:00:01 +0200 Subject: [PATCH 1/2] docs: move migration guide to published documentation --- MIGRATION_GUIDE.md | 400 --------------- README.md | 2 +- .../_static}/migration/01_open_project.gif | Bin .../_static}/migration/02_set_target.gif | Bin .../migration/03_set_flash_method.gif | Bin .../_static}/migration/04_set_port.gif | Bin .../_static}/migration/05_full_clean.gif | Bin .../_static}/migration/06_build_project.gif | Bin .../_static}/migration/07_menuconfig.gif | Bin .../_static}/migration/08_flash_project.gif | Bin .../_static}/migration/09_monitor.gif | Bin .../_static}/migration/10_debug.gif | Bin .../_static}/migration/10_debug_focus.gif | Bin .../_static}/migration/eclipse_toolbar.png | Bin .../_static}/migration/vscode_status_bar.png | Bin docs/en/index.rst | 1 + docs/en/migration-guide.rst | 485 ++++++++++++++++++ {docs_readme => docs/en}/migration/AGENTS.md | 0 18 files changed, 487 insertions(+), 401 deletions(-) delete mode 100644 MIGRATION_GUIDE.md rename {docs_readme/images => docs/_static}/migration/01_open_project.gif (100%) rename {docs_readme/images => docs/_static}/migration/02_set_target.gif (100%) rename {docs_readme/images => docs/_static}/migration/03_set_flash_method.gif (100%) rename {docs_readme/images => docs/_static}/migration/04_set_port.gif (100%) rename {docs_readme/images => docs/_static}/migration/05_full_clean.gif (100%) rename {docs_readme/images => docs/_static}/migration/06_build_project.gif (100%) rename {docs_readme/images => docs/_static}/migration/07_menuconfig.gif (100%) rename {docs_readme/images => docs/_static}/migration/08_flash_project.gif (100%) rename {docs_readme/images => docs/_static}/migration/09_monitor.gif (100%) rename {docs_readme/images => docs/_static}/migration/10_debug.gif (100%) rename {docs_readme/images => docs/_static}/migration/10_debug_focus.gif (100%) rename {docs_readme/images => docs/_static}/migration/eclipse_toolbar.png (100%) rename {docs_readme/images => docs/_static}/migration/vscode_status_bar.png (100%) create mode 100644 docs/en/migration-guide.rst rename {docs_readme => docs/en}/migration/AGENTS.md (100%) diff --git a/MIGRATION_GUIDE.md b/MIGRATION_GUIDE.md deleted file mode 100644 index cafe121cd..000000000 --- a/MIGRATION_GUIDE.md +++ /dev/null @@ -1,400 +0,0 @@ -# Migrating from Espressif-IDE to the ESP-IDF VS Code Extension - -> A practical migration guide for existing Espressif-IDE / ESP-IDF Eclipse Plugin users. - -Espressif-IDE 4.5.0 is the final feature release of Espressif-IDE and the ESP-IDF Eclipse plugin. Existing users can continue to maintain current projects, but new projects are encouraged to use the ESP-IDF VS Code Extension. - -This guide shows how to open an existing ESP-IDF project in VS Code and reproduce the workflows you already know from Espressif-IDE: configure, build, flash, monitor, and debug. - -## What to expect - -You do **not** need to recreate your ESP-IDF project. - -Most project-level ESP-IDF configuration is portable and can be reused directly in VS Code. The parts that may need manual attention are mainly IDE-specific settings stored by Eclipse outside the project itself. - -### Usually reusable without changes - -- Source code and `CMakeLists.txt` -- `sdkconfig` and `sdkconfig.defaults*` -- `dependencies.lock` -- `idf_component.yml` -- Managed components -- Local/custom components - -### May require manual setup - -- Custom build directory -- JTAG / OpenOCD board configuration -- Adapter-specific settings -- VS Code debug configuration (`.vscode/launch.json`) -- Custom debug values from Eclipse `.launch` files -- Environment-specific build cache - -> [!IMPORTANT] -> Keep the original Eclipse workspace, including its `.metadata` directory, until Build, Flash, Monitor, and Debug have all been verified in VS Code. Some Eclipse-specific settings are stored in the workspace rather than in the project directory. - ---- - -## Eclipse to VS Code: quick reference - -| Task | Espressif-IDE / Eclipse Plugin | ESP-IDF VS Code Extension | -|---|---|---| -| Open project | Import/open project in an Eclipse workspace | **File → Open Folder...** | -| Select target | Project/toolbar target configuration | ESP-IDF target/device selection from the status bar or Command Palette | -| Select flash method | Eclipse launch/flash configuration | Select **UART** or **JTAG** in the ESP-IDF status bar/settings | -| Select port | Serial configuration | Select the device port from the ESP-IDF status bar | -| Full Clean | Clean/reconfigure project | **ESP-IDF: Full Clean** | -| Build | Build toolbar / CDT Build | **ESP-IDF: Build your project** | -| Menuconfig | ESP-IDF SDK Configuration Editor | **ESP-IDF: SDK Configuration Editor (Menuconfig)** | -| Flash | Serial/JTAG flash action | **ESP-IDF: Flash your project** | -| Monitor | Serial Monitor | **ESP-IDF: Monitor your device** | -| Debug | Eclipse `.launch` configuration | Generate `.vscode` config if needed, then start Debug | - -### Familiar controls, different locations - -Espressif-IDE provides common project actions through the Eclipse toolbar: - -![Espressif-IDE toolbar](docs_readme/images/migration/eclipse_toolbar.png) - -In VS Code, equivalent actions are available through the **ESP-IDF status bar**, **Command Palette**, and **Run and Debug** view: - -![VS Code ESP-IDF status bar](docs_readme/images/migration/vscode_status_bar.png) - ---- - -## Optional: AI-assisted migration - -If your AI coding agent supports `AGENTS.md`, download the -[migration `AGENTS.md`](docs_readme/migration/AGENTS.md) -and place it in the root of your ESP-IDF project. - -It provides migration-specific instructions for inspecting the existing project -and Eclipse workspace metadata, then migrating supported build, JTAG/OpenOCD, -and debug settings to their VS Code equivalents. - -You can start with a simple prompt: - -```text -Migrate this existing Espressif-IDE project to the ESP-IDF VS Code Extension. -``` - -The agent should apply settings automatically when the mapping is unambiguous -and report only what still requires manual review. Actions that modify a -connected device, such as flashing firmware, should require user confirmation. - -# Migration walkthrough - -## 1. Open the existing project - -In VS Code, use **File → Open Folder...** and select the root directory of your existing ESP-IDF project. - -![Open existing project](docs_readme/images/migration/01_open_project.gif) - -You do not need to create a new VS Code project or copy your source files into a new template. - -After opening the folder, verify that the project still contains its normal ESP-IDF files, for example: - -```text -project/ -├── CMakeLists.txt -├── main/ -├── sdkconfig -├── sdkconfig.defaults -├── dependencies.lock -├── managed_components/ -└── ... -``` - ---- - -## 2. Verify the ESP-IDF setup - -Make sure VS Code is using the ESP-IDF installation/version expected by the project. - -If you already have the required ESP-IDF version installed, select that existing setup in the ESP-IDF extension rather than reinstalling the framework. - -> [!TIP] -> Using the same ESP-IDF version first makes migration easier to validate. Upgrade the project separately after the IDE migration is complete. - ---- - -## 3. Select the target and board - -Select the ESP-IDF target used by the project and, when applicable, the exact board/device configuration. - -![Set target and board](docs_readme/images/migration/02_set_target.gif) - -> [!IMPORTANT] -> For JTAG users, explicitly select the board/device even if the chip target already appears correct. A correct `IDF_TARGET` does not necessarily mean the corresponding OpenOCD board configuration has been initialized. - -For example, a project may correctly report `esp32c6` while VS Code still has an unrelated OpenOCD configuration from an older project. Re-selecting the target/board refreshes the project-specific hardware configuration. - ---- - -## 4. Select the flash method - -Choose the flash method that matches your existing workflow. - -![Set flash method](docs_readme/images/migration/03_set_flash_method.gif) - -Typical choices are: - -- **UART** for serial flashing -- **JTAG** when flashing through OpenOCD/JTAG - -If you are migrating a JTAG-based workflow, verify this setting before troubleshooting OpenOCD or Debug. - ---- - -## 5. Select the serial port - -For UART flashing and Serial Monitor, select the device port. - -![Set serial port](docs_readme/images/migration/04_set_port.gif) - -The exact port name is platform-dependent, for example: - -```text -macOS: /dev/tty.usbserial-... -Linux: /dev/ttyUSB0 or /dev/ttyACM0 -Windows: COM3, COM4, ... -``` - ---- - -## 6. Run Full Clean only if needed - -Do not clean the project automatically unless it is necessary. First try to use the existing project normally. - -If Menuconfig or project configuration fails because of stale or environment-specific build cache, run: - -**ESP-IDF: Full Clean** - -![Full Clean](docs_readme/images/migration/05_full_clean.gif) - -> [!NOTE] -> A full project Build is not required just to recover Menuconfig. Full Clean followed by reopening the SDK Configuration Editor can be enough. - ---- - -## 7. Build the project - -Run: - -**ESP-IDF: Build your project** - -![Build project](docs_readme/images/migration/06_build_project.gif) - -The following project-level state should continue to work without IDE-specific conversion: - -- custom CMake configuration -- `sdkconfig` -- `sdkconfig.defaults*` -- managed components -- local/custom components -- dependency lock files - -If Build succeeds, this is a strong indication that the ESP-IDF project itself migrated correctly. - ---- - -## 8. Open SDK Configuration Editor / Menuconfig - -Run: - -**ESP-IDF: SDK Configuration Editor (Menuconfig)** - -![SDK Configuration Editor](docs_readme/images/migration/07_menuconfig.gif) - -Verify that important existing values are still present. - -Examples include: - -- target-specific configuration -- flash size -- partition table selection -- compiler optimization -- application-specific Kconfig values - -If the editor reports that the project must be cleaned because of an incompatible build cache, return to **Step 6**. - ---- - -## 9. Validate Flash - -After the project builds successfully, validate the hardware workflows you normally use. - -If Flash is part of your workflow, make sure the target, flash method, and port/board are correct, then run: - -**ESP-IDF: Flash your project** - -![Flash project](docs_readme/images/migration/08_flash_project.gif) - -### UART users - -UART flashing normally works once the correct serial port and target are configured. - -### JTAG users - -If JTAG Flash fails with an OpenOCD adapter/device error: - -1. Re-select the target and exact board/device configuration. -2. Confirm the flash method is JTAG. -3. Verify the intended adapter when multiple devices are connected. - ---- - -## 10. Validate Serial Monitor - -If Serial Monitor is part of your workflow, run: - -**ESP-IDF: Monitor your device** - -![Serial Monitor](docs_readme/images/migration/09_monitor.gif) - -Verify normal application output and confirm that the expected firmware is running. - -This is also a convenient point to validate custom/local components because their runtime output can confirm that they were compiled, linked, flashed, and executed correctly. - ---- - -## 11. Configure and validate Debug - -Existing Espressif-IDE projects do not necessarily contain a VS Code debug configuration. - -If `.vscode/launch.json` is missing, run: - -**ESP-IDF: Add VS Code Configuration Folder** - -Then start Debug from the VS Code **Run and Debug** view. - -![Debug workflow](docs_readme/images/migration/10_debug_focus.gif) - -Default debugging works after the VS Code configuration folder is generated. - -> [!WARNING] -> `Add VS Code Configuration Folder` creates VS Code defaults. It does **not** convert your existing Eclipse `.launch` file. If your Eclipse debug setup contained custom ports, semihosting, reset behavior, custom GDB commands, or other non-default settings, review them manually after default Debug is working. - ---- - -# Advanced migration cases - -## Custom build directory - -A custom build directory used by Espressif-IDE may be stored in the Eclipse launch configuration rather than in the portable project files. - -For example: - -```xml - -``` - -VS Code supports a custom build directory, but this value is not currently imported automatically. - -If your project depends on a custom build path: - -1. Configure the equivalent build directory in VS Code using the - [`idf.buildPath`](https://github.com/espressif/vscode-esp-idf-extension/blob/master/docs_espressif/en/settings.rst#build) - setting. - - For example: - - ```json - { - "idf.buildPath": "${workspaceFolder}/custom-build" - } - ``` -2. Reconfigure or clean generated state if necessary. -3. Verify Menuconfig. -4. Verify Build. -5. Verify Flash if it is part of your workflow. -6. Verify Debug if it is part of your workflow. - -This matters not only for compilation. External scripts and Clangd may also depend on files such as `compile_commands.json` generated inside the active build directory. - ---- - -## JTAG / OpenOCD settings - -JTAG board and adapter settings are IDE-specific and may need to be selected again in VS Code. - -If JTAG Flash does not work after migration: - -1. Verify the ESP-IDF target and re-select the exact board/device. -2. Confirm JTAG is selected as the flash method. -3. Verify the intended adapter when multiple devices are connected. - ---- - -## Custom Eclipse debug configuration - -Espressif-IDE debug settings are not automatically converted into VS Code debug settings. - -Review the old Eclipse `.launch` configuration if your workflow uses custom values such as: - -- GDB, TCL, or Telnet ports -- `stopAt=app_main` -- semihosting -- flash-before-debug behavior -- reset/start behavior -- custom GDB commands, arguments, or timeouts - -Start from the standard VS Code Debug configuration, then migrate or recreate only the custom behavior your project actually requires. - -> [!CAUTION] -> Eclipse workspace metadata can contain stale or duplicated values. Do not blindly copy every target-related value into VS Code. Prefer the actual ESP-IDF project configuration when resolving conflicts. - ---- - - -## C/C++ code navigation and IntelliSense - -Espressif-IDE uses clangd for C/C++ code navigation, diagnostics, and header resolution. - -In VS Code, the default ESP-IDF setup uses the Microsoft C/C++ extension. - -If you prefer to continue using clangd, install the clangd extension and run: - -**ESP-IDF: Configure project for ESP-Clang** - -See the [ESP-IDF VS Code Extension documentation](https://github.com/espressif/vscode-esp-idf-extension/blob/master/docs_espressif/en/configureproject.rst#c-and-c-code-navigation-and-syntax-highlighting) for more details. - ---- - -# Troubleshooting - -| Symptom | Likely cause | Recommended action | -|---|---|---| -| SDK Configuration Editor asks for `fullclean` | Existing CMake cache references another Python/environment | Run **ESP-IDF: Full Clean**, then reopen the editor. | -| JTAG Flash reports an FTDI/OpenOCD device error | Board/OpenOCD setup was not restored | Re-select target + exact board/device configuration. | -| Target appears correct but JTAG still fails | Chip target and board/OpenOCD state are separate | Explicitly select the board/device again. | -| Debug reports `.vscode/launch.json` is missing | Existing project has no VS Code debug config | Run **ESP-IDF: Add VS Code Configuration Folder**. | -| Default Debug works but behavior differs from Eclipse | Custom Eclipse `.launch` values were not converted | Review and migrate/recreate the required custom debug settings. | -| VS Code creates `project/build` instead of the old build path | Eclipse custom build path was not imported | Configure the custom build directory manually. | -| Doctor reports unrelated configuration errors | Stale user/global extension settings | Check whether the reported setting is relevant to the current project. | - ---- - -# Final migration checklist - -Before considering the migration complete: - -- [ ] Project opens and builds with the expected ESP-IDF version and target. -- [ ] Menuconfig opens and existing configuration values are preserved. -- [ ] Board/OpenOCD, flash method, and serial port are correct for the workflows you use. -- [ ] Flash / Monitor work if they are part of your workflow. -- [ ] Custom build directory is restored if required. -- [ ] Debug starts successfully and required custom Eclipse debug settings have been reviewed. - ---- - - -## Related resources - -- [Espressif-IDE support status](README.md#support-status) -- [Espressif-IDE support policy](SUPPORT_POLICY.md) -- [ESP-IDF VS Code Extension](https://github.com/espressif/vscode-esp-idf-extension) -- [ESP-IDF Programming Guide](https://docs.espressif.com/projects/esp-idf/en/latest/) - diff --git a/README.md b/README.md index ffed799d7..f49060914 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ Espressif-IDE is a standalone, customized IDE built on Eclipse CDT for developin Espressif-IDE 4.5.0, released on 14 October 2026, is the final feature release of Espressif-IDE and the ESP-IDF Eclipse plugin. Maintenance for high-severity bugs and security fixes continues until 14 October 2027. It is not recommended for new projects. See [SUPPORT_POLICY.md](SUPPORT_POLICY.md). -Existing Espressif-IDE users can follow the [migration guide](MIGRATION_GUIDE.md) +Existing Espressif-IDE users can follow the [migration guide](docs/en/migration-guide.rst) to move an existing ESP-IDF project to the ESP-IDF VS Code Extension. ## Key Features diff --git a/docs_readme/images/migration/01_open_project.gif b/docs/_static/migration/01_open_project.gif similarity index 100% rename from docs_readme/images/migration/01_open_project.gif rename to docs/_static/migration/01_open_project.gif diff --git a/docs_readme/images/migration/02_set_target.gif b/docs/_static/migration/02_set_target.gif similarity index 100% rename from docs_readme/images/migration/02_set_target.gif rename to docs/_static/migration/02_set_target.gif diff --git a/docs_readme/images/migration/03_set_flash_method.gif b/docs/_static/migration/03_set_flash_method.gif similarity index 100% rename from docs_readme/images/migration/03_set_flash_method.gif rename to docs/_static/migration/03_set_flash_method.gif diff --git a/docs_readme/images/migration/04_set_port.gif b/docs/_static/migration/04_set_port.gif similarity index 100% rename from docs_readme/images/migration/04_set_port.gif rename to docs/_static/migration/04_set_port.gif diff --git a/docs_readme/images/migration/05_full_clean.gif b/docs/_static/migration/05_full_clean.gif similarity index 100% rename from docs_readme/images/migration/05_full_clean.gif rename to docs/_static/migration/05_full_clean.gif diff --git a/docs_readme/images/migration/06_build_project.gif b/docs/_static/migration/06_build_project.gif similarity index 100% rename from docs_readme/images/migration/06_build_project.gif rename to docs/_static/migration/06_build_project.gif diff --git a/docs_readme/images/migration/07_menuconfig.gif b/docs/_static/migration/07_menuconfig.gif similarity index 100% rename from docs_readme/images/migration/07_menuconfig.gif rename to docs/_static/migration/07_menuconfig.gif diff --git a/docs_readme/images/migration/08_flash_project.gif b/docs/_static/migration/08_flash_project.gif similarity index 100% rename from docs_readme/images/migration/08_flash_project.gif rename to docs/_static/migration/08_flash_project.gif diff --git a/docs_readme/images/migration/09_monitor.gif b/docs/_static/migration/09_monitor.gif similarity index 100% rename from docs_readme/images/migration/09_monitor.gif rename to docs/_static/migration/09_monitor.gif diff --git a/docs_readme/images/migration/10_debug.gif b/docs/_static/migration/10_debug.gif similarity index 100% rename from docs_readme/images/migration/10_debug.gif rename to docs/_static/migration/10_debug.gif diff --git a/docs_readme/images/migration/10_debug_focus.gif b/docs/_static/migration/10_debug_focus.gif similarity index 100% rename from docs_readme/images/migration/10_debug_focus.gif rename to docs/_static/migration/10_debug_focus.gif diff --git a/docs_readme/images/migration/eclipse_toolbar.png b/docs/_static/migration/eclipse_toolbar.png similarity index 100% rename from docs_readme/images/migration/eclipse_toolbar.png rename to docs/_static/migration/eclipse_toolbar.png diff --git a/docs_readme/images/migration/vscode_status_bar.png b/docs/_static/migration/vscode_status_bar.png similarity index 100% rename from docs_readme/images/migration/vscode_status_bar.png rename to docs/_static/migration/vscode_status_bar.png diff --git a/docs/en/index.rst b/docs/en/index.rst index 704c7f60c..48871bff1 100644 --- a/docs/en/index.rst +++ b/docs/en/index.rst @@ -49,6 +49,7 @@ Contents :maxdepth: 1 Support Policy + Migration to VS Code Extension Prerequisites Installation Start Your Project diff --git a/docs/en/migration-guide.rst b/docs/en/migration-guide.rst new file mode 100644 index 000000000..93ae7b06a --- /dev/null +++ b/docs/en/migration-guide.rst @@ -0,0 +1,485 @@ +Migrating from Espressif-IDE to the ESP-IDF VS Code Extension +============================================================= + + A practical migration guide for existing Espressif-IDE / ESP-IDF Eclipse Plugin users. + +Espressif-IDE 4.5.0 is the final feature release of Espressif-IDE and the ESP-IDF Eclipse plugin. Existing users can continue to maintain current projects, but new projects are encouraged to use the ESP-IDF VS Code Extension. + +This guide shows how to open an existing ESP-IDF project in VS Code and reproduce the workflows you already know from Espressif-IDE: configure, build, flash, monitor, and debug. + +What to expect +-------------- + +You do **not** need to recreate your ESP-IDF project. + +Most project-level ESP-IDF configuration is portable and can be reused directly in VS Code. The parts that may need manual attention are mainly IDE-specific settings stored by Eclipse outside the project itself. + +Usually reusable without changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Source code and ``CMakeLists.txt`` +- ``sdkconfig`` and ``sdkconfig.defaults*`` +- ``dependencies.lock`` +- ``idf_component.yml`` +- Managed components +- Local/custom components + +May require manual setup +~~~~~~~~~~~~~~~~~~~~~~~~ + +- Custom build directory +- JTAG / OpenOCD board configuration +- Adapter-specific settings +- VS Code debug configuration (``.vscode/launch.json``) +- Custom debug values from Eclipse ``.launch`` files +- Environment-specific build cache + +.. important:: + + Keep the original Eclipse workspace, including its ``.metadata`` directory, until Build, Flash, Monitor, and Debug have all been verified in VS Code. Some Eclipse-specific settings are stored in the workspace rather than in the project directory. + +-------------- + +Eclipse to VS Code: quick reference +----------------------------------- + ++---------------------+---------------------------------------------+------------------------------------------------------------------------+ +| Task | Espressif-IDE / Eclipse Plugin | ESP-IDF VS Code Extension | ++=====================+=============================================+========================================================================+ +| Open project | Import/open project in an Eclipse workspace | **File → Open Folder...** | ++---------------------+---------------------------------------------+------------------------------------------------------------------------+ +| Select target | Project/toolbar target configuration | ESP-IDF target/device selection from the status bar or Command Palette | ++---------------------+---------------------------------------------+------------------------------------------------------------------------+ +| Select flash method | Eclipse launch/flash configuration | Select **UART** or **JTAG** in the ESP-IDF status bar/settings | ++---------------------+---------------------------------------------+------------------------------------------------------------------------+ +| Select port | Serial configuration | Select the device port from the ESP-IDF status bar | ++---------------------+---------------------------------------------+------------------------------------------------------------------------+ +| Full Clean | Clean/reconfigure project | **ESP-IDF: Full Clean** | ++---------------------+---------------------------------------------+------------------------------------------------------------------------+ +| Build | Build toolbar / CDT Build | **ESP-IDF: Build your project** | ++---------------------+---------------------------------------------+------------------------------------------------------------------------+ +| Menuconfig | ESP-IDF SDK Configuration Editor | **ESP-IDF: SDK Configuration Editor (Menuconfig)** | ++---------------------+---------------------------------------------+------------------------------------------------------------------------+ +| Flash | Serial/JTAG flash action | **ESP-IDF: Flash your project** | ++---------------------+---------------------------------------------+------------------------------------------------------------------------+ +| Monitor | Serial Monitor | **ESP-IDF: Monitor your device** | ++---------------------+---------------------------------------------+------------------------------------------------------------------------+ +| Debug | Eclipse ``.launch`` configuration | Generate ``.vscode`` config if needed, then start Debug | ++---------------------+---------------------------------------------+------------------------------------------------------------------------+ + +Familiar controls, different locations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Espressif-IDE provides common project actions through the Eclipse toolbar: + +|Espressif-IDE toolbar| + +In VS Code, equivalent actions are available through the **ESP-IDF status bar**, **Command Palette**, and **Run and Debug** view: + +|VS Code ESP-IDF status bar| + +-------------- + +Optional: AI-assisted migration +------------------------------- + +If your AI coding agent supports ``AGENTS.md``, download the :download:`migration AGENTS.md ` and place it in the root of your ESP-IDF project. + +It provides migration-specific instructions for inspecting the existing project and Eclipse workspace metadata, then migrating supported build, JTAG/OpenOCD, and debug settings to their VS Code equivalents. + +You can start with a simple prompt: + +.. code:: text + + Migrate this existing Espressif-IDE project to the ESP-IDF VS Code Extension. + +The agent should apply settings automatically when the mapping is unambiguous and report only what still requires manual review. Actions that modify a connected device, such as flashing firmware, should require user confirmation. + +Migration walkthrough +===================== + +.. _1-open-the-existing-project: + +1. Open the existing project +---------------------------- + +In VS Code, use **File → Open Folder...** and select the root directory of your existing ESP-IDF project. + +|Open existing project| + +You do not need to create a new VS Code project or copy your source files into a new template. + +After opening the folder, verify that the project still contains its normal ESP-IDF files, for example: + +.. code:: text + + project/ + ├── CMakeLists.txt + ├── main/ + ├── sdkconfig + ├── sdkconfig.defaults + ├── dependencies.lock + ├── managed_components/ + └── ... + +-------------- + +.. _2-verify-the-esp-idf-setup: + +2. Verify the ESP-IDF setup +--------------------------- + +Make sure VS Code is using the ESP-IDF installation/version expected by the project. + +If you already have the required ESP-IDF version installed, select that existing setup in the ESP-IDF extension rather than reinstalling the framework. + +.. tip:: + + Using the same ESP-IDF version first makes migration easier to validate. Upgrade the project separately after the IDE migration is complete. + +-------------- + +.. _3-select-the-target-and-board: + +3. Select the target and board +------------------------------ + +Select the ESP-IDF target used by the project and, when applicable, the exact board/device configuration. + +|Set target and board| + +.. important:: + + For JTAG users, explicitly select the board/device even if the chip target already appears correct. A correct ``IDF_TARGET`` does not necessarily mean the corresponding OpenOCD board configuration has been initialized. + +For example, a project may correctly report ``esp32c6`` while VS Code still has an unrelated OpenOCD configuration from an older project. Re-selecting the target/board refreshes the project-specific hardware configuration. + +-------------- + +.. _4-select-the-flash-method: + +4. Select the flash method +-------------------------- + +Choose the flash method that matches your existing workflow. + +|Set flash method| + +Typical choices are: + +- **UART** for serial flashing +- **JTAG** when flashing through OpenOCD/JTAG + +If you are migrating a JTAG-based workflow, verify this setting before troubleshooting OpenOCD or Debug. + +-------------- + +.. _5-select-the-serial-port: + +5. Select the serial port +------------------------- + +For UART flashing and Serial Monitor, select the device port. + +|Set serial port| + +The exact port name is platform-dependent, for example: + +.. code:: text + + macOS: /dev/tty.usbserial-... + Linux: /dev/ttyUSB0 or /dev/ttyACM0 + Windows: COM3, COM4, ... + +-------------- + +.. _6-run-full-clean-only-if-needed: + +6. Run Full Clean only if needed +-------------------------------- + +Do not clean the project automatically unless it is necessary. First try to use the existing project normally. + +If Menuconfig or project configuration fails because of stale or environment-specific build cache, run: + +**ESP-IDF: Full Clean** + +|Full Clean| + +.. note:: + + A full project Build is not required just to recover Menuconfig. Full Clean followed by reopening the SDK Configuration Editor can be enough. + +-------------- + +.. _7-build-the-project: + +7. Build the project +-------------------- + +Run: + +**ESP-IDF: Build your project** + +|Build project| + +The following project-level state should continue to work without IDE-specific conversion: + +- custom CMake configuration +- ``sdkconfig`` +- ``sdkconfig.defaults*`` +- managed components +- local/custom components +- dependency lock files + +If Build succeeds, this is a strong indication that the ESP-IDF project itself migrated correctly. + +-------------- + +.. _8-open-sdk-configuration-editor--menuconfig: + +8. Open SDK Configuration Editor / Menuconfig +--------------------------------------------- + +Run: + +**ESP-IDF: SDK Configuration Editor (Menuconfig)** + +|SDK Configuration Editor| + +Verify that important existing values are still present. + +Examples include: + +- target-specific configuration +- flash size +- partition table selection +- compiler optimization +- application-specific Kconfig values + +If the editor reports that the project must be cleaned because of an incompatible build cache, return to **Step 6**. + +-------------- + +.. _9-validate-flash: + +9. Validate Flash +----------------- + +After the project builds successfully, validate the hardware workflows you normally use. + +If Flash is part of your workflow, make sure the target, flash method, and port/board are correct, then run: + +**ESP-IDF: Flash your project** + +|Flash project| + +UART users +~~~~~~~~~~ + +UART flashing normally works once the correct serial port and target are configured. + +JTAG users +~~~~~~~~~~ + +If JTAG Flash fails with an OpenOCD adapter/device error: + +1. Re-select the target and exact board/device configuration. +2. Confirm the flash method is JTAG. +3. Verify the intended adapter when multiple devices are connected. + +-------------- + +.. _10-validate-serial-monitor: + +10. Validate Serial Monitor +--------------------------- + +If Serial Monitor is part of your workflow, run: + +**ESP-IDF: Monitor your device** + +|Serial Monitor| + +Verify normal application output and confirm that the expected firmware is running. + +This is also a convenient point to validate custom/local components because their runtime output can confirm that they were compiled, linked, flashed, and executed correctly. + +-------------- + +.. _11-configure-and-validate-debug: + +11. Configure and validate Debug +-------------------------------- + +Existing Espressif-IDE projects do not necessarily contain a VS Code debug configuration. + +If ``.vscode/launch.json`` is missing, run: + +**ESP-IDF: Add VS Code Configuration Folder** + +Then start Debug from the VS Code **Run and Debug** view. + +|Debug workflow| + +Default debugging works after the VS Code configuration folder is generated. + +.. warning:: + + ``Add VS Code Configuration Folder`` creates VS Code defaults. It does **not** convert your existing Eclipse ``.launch`` file. If your Eclipse debug setup contained custom ports, semihosting, reset behavior, custom GDB commands, or other non-default settings, review them manually after default Debug is working. + +-------------- + +Advanced migration cases +======================== + +Custom build directory +---------------------- + +A custom build directory used by Espressif-IDE may be stored in the Eclipse launch configuration rather than in the portable project files. + +For example: + +.. code:: xml + + + +VS Code supports a custom build directory, but this value is not currently imported automatically. + +If your project depends on a custom build path: + +1. Configure the equivalent build directory in VS Code using the ``idf.buildPath`` setting (see `VS Code extension settings `__). + + For example: + + .. code:: json + + { + "idf.buildPath": "${workspaceFolder}/custom-build" + } + +2. Reconfigure or clean generated state if necessary. + +3. Verify Menuconfig. + +4. Verify Build. + +5. Verify Flash if it is part of your workflow. + +6. Verify Debug if it is part of your workflow. + +This matters not only for compilation. External scripts and Clangd may also depend on files such as ``compile_commands.json`` generated inside the active build directory. + +-------------- + +.. _jtag--openocd-settings: + +JTAG / OpenOCD settings +----------------------- + +JTAG board and adapter settings are IDE-specific and may need to be selected again in VS Code. + +If JTAG Flash does not work after migration: + +1. Verify the ESP-IDF target and re-select the exact board/device. +2. Confirm JTAG is selected as the flash method. +3. Verify the intended adapter when multiple devices are connected. + +-------------- + +Custom Eclipse debug configuration +---------------------------------- + +Espressif-IDE debug settings are not automatically converted into VS Code debug settings. + +Review the old Eclipse ``.launch`` configuration if your workflow uses custom values such as: + +- GDB, TCL, or Telnet ports +- ``stopAt=app_main`` +- semihosting +- flash-before-debug behavior +- reset/start behavior +- custom GDB commands, arguments, or timeouts + +Start from the standard VS Code Debug configuration, then migrate or recreate only the custom behavior your project actually requires. + +.. caution:: + + Eclipse workspace metadata can contain stale or duplicated values. Do not blindly copy every target-related value into VS Code. Prefer the actual ESP-IDF project configuration when resolving conflicts. + +-------------- + +C/C++ code navigation and IntelliSense +-------------------------------------- + +Espressif-IDE uses clangd for C/C++ code navigation, diagnostics, and header resolution. + +In VS Code, the default ESP-IDF setup uses the Microsoft C/C++ extension. + +If you prefer to continue using clangd, install the clangd extension and run: + +**ESP-IDF: Configure project for ESP-Clang** + +See the `ESP-IDF VS Code Extension documentation `__ for more details. + +-------------- + +Troubleshooting +=============== + ++-----------------------------------------------------------------+------------------------------------------------------------+------------------------------------------------------------------------+ +| Symptom | Likely cause | Recommended action | ++=================================================================+============================================================+========================================================================+ +| SDK Configuration Editor asks for ``fullclean`` | Existing CMake cache references another Python/environment | Run **ESP-IDF: Full Clean**, then reopen the editor. | ++-----------------------------------------------------------------+------------------------------------------------------------+------------------------------------------------------------------------+ +| JTAG Flash reports an FTDI/OpenOCD device error | Board/OpenOCD setup was not restored | Re-select target + exact board/device configuration. | ++-----------------------------------------------------------------+------------------------------------------------------------+------------------------------------------------------------------------+ +| Target appears correct but JTAG still fails | Chip target and board/OpenOCD state are separate | Explicitly select the board/device again. | ++-----------------------------------------------------------------+------------------------------------------------------------+------------------------------------------------------------------------+ +| Debug reports ``.vscode/launch.json`` is missing | Existing project has no VS Code debug config | Run **ESP-IDF: Add VS Code Configuration Folder**. | ++-----------------------------------------------------------------+------------------------------------------------------------+------------------------------------------------------------------------+ +| Default Debug works but behavior differs from Eclipse | Custom Eclipse ``.launch`` values were not converted | Review and migrate/recreate the required custom debug settings. | ++-----------------------------------------------------------------+------------------------------------------------------------+------------------------------------------------------------------------+ +| VS Code creates ``project/build`` instead of the old build path | Eclipse custom build path was not imported | Configure the custom build directory manually. | ++-----------------------------------------------------------------+------------------------------------------------------------+------------------------------------------------------------------------+ +| Doctor reports unrelated configuration errors | Stale user/global extension settings | Check whether the reported setting is relevant to the current project. | ++-----------------------------------------------------------------+------------------------------------------------------------+------------------------------------------------------------------------+ + +-------------- + +Final migration checklist +========================= + +Before considering the migration complete: + +- ☐ Project opens and builds with the expected ESP-IDF version and target. +- ☐ Menuconfig opens and existing configuration values are preserved. +- ☐ Board/OpenOCD, flash method, and serial port are correct for the workflows you use. +- ☐ Flash / Monitor work if they are part of your workflow. +- ☐ Custom build directory is restored if required. +- ☐ Debug starts successfully and required custom Eclipse debug settings have been reviewed. + +-------------- + +Related resources +----------------- + +- `Espressif-IDE support status `__ +- `Espressif-IDE support policy `__ +- `ESP-IDF VS Code Extension `__ +- `ESP-IDF Programming Guide `__ + +.. |Espressif-IDE toolbar| image:: ../_static/migration/eclipse_toolbar.png +.. |VS Code ESP-IDF status bar| image:: ../_static/migration/vscode_status_bar.png +.. |Open existing project| image:: ../_static/migration/01_open_project.gif +.. |Set target and board| image:: ../_static/migration/02_set_target.gif +.. |Set flash method| image:: ../_static/migration/03_set_flash_method.gif +.. |Set serial port| image:: ../_static/migration/04_set_port.gif +.. |Full Clean| image:: ../_static/migration/05_full_clean.gif +.. |Build project| image:: ../_static/migration/06_build_project.gif +.. |SDK Configuration Editor| image:: ../_static/migration/07_menuconfig.gif +.. |Flash project| image:: ../_static/migration/08_flash_project.gif +.. |Serial Monitor| image:: ../_static/migration/09_monitor.gif +.. |Debug workflow| image:: ../_static/migration/10_debug_focus.gif diff --git a/docs_readme/migration/AGENTS.md b/docs/en/migration/AGENTS.md similarity index 100% rename from docs_readme/migration/AGENTS.md rename to docs/en/migration/AGENTS.md From a5aaaadffd1142bfb9fa5d792b26f36fb8e8d19e Mon Sep 17 00:00:00 2001 From: AndriiFilippov Date: Wed, 21 Oct 2026 23:20:05 +0200 Subject: [PATCH 2/2] docs: exclude migration AGENTS.md from Sphinx build --- docs/en/conf.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/en/conf.py b/docs/en/conf.py index 8f17605c5..1a2dd70eb 100644 --- a/docs/en/conf.py +++ b/docs/en/conf.py @@ -23,3 +23,7 @@ # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. language = 'en' + +# Keep the AI migration instructions downloadable, but do not build them as a documentation page. +exclude_patterns = list(globals().get("exclude_patterns", [])) +exclude_patterns.append("migration/AGENTS.md")