\nProject Structure<\/a>
\nBuild Systems<\/a>
\nDebugging ESP32 Boards<\/a>
\nConfiguration<\/a>
\nUnit Tests<\/a>
\nHeader Files<\/a>
\nTroubleshooting Build Problems<\/a>
\nTroubleshooting ESP-IDF\/Toolchain Problems<\/a>
\nInstalling Multiple Toolchains<\/a>
\nResetting Python environment<\/a>
\nESP-ADF Structure<\/a>
\nESP-IDF 5.5<\/a><\/p>\n
<\/a>ESP-IDF and Toolchains<\/h2>\nESP32 projects are based on ESP-IDF – an open-source framework from Espressif. You can find documentation on ESP-IDF here<\/a>, or a list of official releases on the Espressif’s Github Repository<\/a>.<\/p>\nVisualGDB ESP-IDF-based projects are specifically designed as to work as a thin wrapper on top of the ESP-IDF build system. While VisualGDB provides convenient GUI for many common ESP-IDF tasks, it does not introduce any changes to the underlying build process. This ensures that:
\n<\/strong><\/p>\n\n- The projects edited with VisualGDB can still be built via command-line ESP-IDF tools, producing exactly<\/strong> the same results.<\/li>\n
- Any project that can be built via ESP-IDF tools, can also be built with VisualGDB.<\/li>\n
- Any extensions or examples that that work with the original ESP-IDF, will also work with VisualGDB-based projects.<\/li>\n<\/ul>\n
Update:<\/strong><\/span> VisualGDB 6.1 and later now understands the the same IDF and tool layout that is used by the Espressif’s VS Code extension. You no longer need to download a separate toolchain from us, and can use the latest tools from Espressif, producing the same results as VS Code. See this page<\/a> for details.<\/p>\n<\/a>Project Structure<\/h2>\nA typical ESP-IDF-based project consists of the following components:<\/p>\n
\n- The main component containing the app_main()<\/strong> function.<\/li>\n
- Zero or more additional project-specific components.<\/li>\n
- Multiple ESP-IDF-specific components.<\/li>\n
- Zero or more unit test components.<\/li>\n<\/ol>\n
![\"\"](\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2020\/05\/idfstruct.png\")
<\/a>The contents of the main component are shown directly under the project’s node, while other components can be found under the Components<\/strong> node.<\/p>\nEach component is internally defined as a static library. The final firmware build by the project is obtained by linking all of the project’s components together.<\/p>\n
Each component can define its own properties (e.g. include directories or preprocessor macros) via the regular VS Properties dialogs:![\"\"](\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2020\/05\/props.png\")
<\/a>You can create new components in arbitrary locations, or reference existing component directories via the context menu on the Components<\/strong> node in Solution Explorer.<\/p>\n<\/a>Build Systems<\/h2>\nESP-IDF projects are built using CMake scripts included in the ESP-IDF. If you encounter problems building the project, see the build problem troubleshooting<\/a> section.<\/p>\n<\/a>Debugging ESP32 Boards<\/h2>\nESP32 devices can be debugged via JTAG (this includes the ESP32 Arduino core). Generally, we advise using the ESP32-WROVER-KIT module<\/a>, as it includes an on-board JTAG debugger and can be debugged out-of-the-box. Many other boards do not include a JTAG connector and require soldering in order get debugging to work. You can find example schematics for popular boards in our ESP32 tutorials<\/a>.<\/p>\nIf you do not have a JTAG debugger, you can still program the FLASH memory of the ESP32 module via the COM port by right-clicking on the project in Solution Explorer and selecting “Program FLASH Memory<\/strong>“.<\/p>\n<\/a>Configuration<\/h2>\nYou can configure various parameters of the ESP32 projects via VisualGDB Project Properties -> ESP-IDF Project -> ESP-IDF Configuration:![\"\"](\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2020\/05\/cfg.png\")
<\/a>The configuration will be saved in the sdkconfig<\/strong> file that is used by the ESP-IDF build system when building the project.<\/p>\n<\/a>Unit Tests<\/h2>\nYou can create and run unit tests on the ESP32 devices, as long as you have a JTAG debugger. See this tutorial<\/a> for detailed step-by-step instructions.<\/p>\n<\/a>Header Files<\/h2>\nBecause the ESP-IDF framework does not explicitly reference header files in the component definitions, VisualGDB tries to discover them dynamically based on the component’s source directory. Unless the automatic discovery of header files is disabled, adding existing headers to Solution Explorer will have no effect if the headers are not located in a place where they can be automatically discovered.<\/p>\n
You can change the way VisualGDB discovers the headers for each target via per-target properties in Solution Explorer:\u00a0![\"\"](\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2020\/05\/headers-1.png\")
<\/a>Note that unlike the regular Advanced CMake projects, header settings for ESP-IDF project node (1) will only affect the main component (<Project Directory>\\main<\/strong>).<\/p>\nIf you set the Header File Search Mode<\/strong> to Disabled<\/strong>, adding headers to a target explicitly add them to the idf_component_register()<\/strong> statement together with the sources.<\/p>\n<\/a>Troubleshooting Build Problems<\/h2>\nAs the ESP32 projects are built by ESP-IDF itself, rather than by VisualGDB, many build issues are caused by incompatible configuration settings, missing external dependencies or unsupported combinations of ESP-IDF and toolchain (see this section<\/a>). VisualGDB can help you narrow down the issue by exporting the exact build command line used by it, as we will show below.<\/p>\nBefore you begin troubleshooting a build issue, make sure you understand whether it happens during the configuration phase<\/strong>, or build phase<\/strong>. The configuration phase<\/strong> happens when you just load the project. If it fails, the project will have an error icon in Solution Explorer. If this happens, try reloading the project (or doing a clean reload) via the context menu:![\"\"](\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2020\/05\/reload.png\")
<\/a>The build phase happens when you actually build the project via the Build Solution<\/strong> command.<\/p>\nConfiguration problems are often caused by errors in CMake scripts or corrupt toolchain\/ESP-IDF environments. Build problems are typically triggered by errors in the source code, or when trying to build a project created for an older ESP-IDF version. For both build and configuration, you can find out the exact command line used by VisualGDB to launch the ESP-IDF tools in the VisualGDB Build window:![\"\"](\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2020\/05\/log.png\")
<\/a>You can dump the command line to a batch file using the context menu. The file will include the working directory and any environment variables, so you will be able to reproduce the problem outside VisualGDB. Note that the same build log can contain multiple command lines. Each command line that can be dumped into a batch file is shown in cyan<\/span>.<\/p>\nIf you determine that the build or configuration fails due to missing environment variables, you can specify them via VisualGDB Project Properties -> CMake Build Settings<\/strong>:![\"\"](\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2020\/05\/vars.png\")
<\/a><\/p>\n<\/a>Troubleshooting ESP-IDF\/Toolchain Compatibility<\/h2>\nUpdate:<\/strong> VisualGDB 6.1 or later directly supports the same tool layout as used by Espressif’s VS Code extension. This simplifies troubleshooting and eliminates the need to download extra toolchains. Read more about it here<\/a>.<\/p>\nIf you encounter issues with an older version of the toolchain, please follow the steps below to ensure your ESP-IDF checkout and the toolchain are compatible:<\/p>\n
\n- Delete all existing ESP32 toolchains via Tools->VisualGDB->Manage VisualGDB Packages:
![\"\"](\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2020\/05\/pkg.png\")
<\/a><\/li>\n- Start the ESP-IDF project wizard and download a new toolchain using it (see this page<\/a> for a full list of toolchains and compatible ESP-IDF versions). Make sure you use the ESP-IDF checkout shipped with the toolchain and DO NOT<\/strong> install one from Github or from elsewhere:
![\"\"](\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2020\/05\/checkouts.png\")
<\/a><\/li>\n- Clone the “Blink” project sample and ensure it builds correctly.<\/li>\n
- If the newly created project works, while your existing project doesn’t, the ESP-IDF version you are using may not be backward-compatible with your project. If this is the case, try downloading older ESP32 toolchains<\/a> and building the project with them.<\/li>\n
- Unless you are prepared to troubleshoot the ESP32 toolchain\/IDF compatibility, DO NOT <\/strong>use the “Clone an SDK release from GitHub” or “Locate and existing SDK checkout” buttons in the VisualGDB GUI.<\/li>\n<\/ol>\n
If it still doesn’t help, see the Resetting Python Environment section<\/strong> below.<\/p>\nIf you would like to try a pre-release ESP-IDF version (e.g. v4.1 or later) that is not yet shipped with our toolchains, please make sure you use VisualGDB 5.5 Preview 6 or later and the esp32-gcc8.2.0-r3.exe<\/strong> toolchain (or later), as the older toolchains use a layout that is incompatible with newer ESP-IDF versions. It may still not work as expected, so unless you are prepared to troubleshoot toolchain\/Python issues, please consider using\u00a0 stable ESP-IDF release shipped with our toolchains.<\/p>\n<\/a>Installing Multiple Toolchains<\/h2>\nVisualGDB distinguishes different toolchain versions by comparing the following parameters:<\/p>\n
\n- GCC version<\/li>\n
- GDB version<\/li>\n
- Toolchain revision<\/li>\n<\/ul>\n
Normally, the toolchain revision increases for bugfix releases that completely supersede the prior ones, however this is not the case for ESP32 toolchains, where multiple different revisions may be needed at the same time.<\/p>\n
You can configure VisualGDB to recognize multiple ESP32 toolchains with the same GCC\/GDB versions using one of the 2 methods below:<\/p>\n
\n- Manually add another entry in registry to HKEY_CURRENT_USER\\SOFTWARE\\Sysprogs\\GNUToolchains<\/strong>. The value name should start with SysGCC-<\/strong>, but otherwise can be arbitrary. The value should point to the toolchain directory.<\/li>\n
- In the VisualGDB toolchain selector, click “Select a third party toolchain by locating gdb.exe<\/strong>“, change the filter from GDB executables<\/strong> to Toolchain Definition Files<\/strong> and point it to the toolchain.xml<\/strong> file in the toolchain directory.<\/li>\n<\/ol>\n
Note that automatically managing multiple toolchain\/BSP versions is supported starting from the Custom edition. If you are using a lower edition, consider manually changing the toolchain ID in the toolchain.xml<\/strong> file, so that VisualGDB will consider it a separate toolchain.<\/p>\n<\/a>Resetting Python Environment<\/h2>\nUpdate:<\/strong> VisualGDB 6.1 or later directly supports the same tool layout<\/a> as used by Espressif’s VS Code extension, eliminating the need for troubleshooting steps below.<\/p>\nIf you are using the ESP32 toolchain\u00a0 v8.2.0r3<\/strong> or later, the Python environment would not be a part of the toolchain and would not be reset by reinstalling the toolchain. If you encounter Python-related problems, follow the steps below to reset the Python environment:<\/p>\n\n- Clear the Tools->Options->VisualGDB->General->Python Directory<\/strong> setting:
![\"\"](\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2020\/05\/python.png\")
<\/a>See this page<\/a> for more information about VisualGDB-managed Python installations.<\/li>\n- Delete the %LOCALAPPDATA%\\VisualGDB\\Python*<\/strong> directories<\/li>\n
- Delete\/rename the %USERPROFILE%\\.espressif<\/strong> folder that contains virtual Python environments<\/li>\n
- Launch the ESP-IDF project wizard and let VisualGDB install the Python 3.x package:
![\"\"](\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2020\/05\/getpython.png\")
<\/a>Unless you are prepared to troubleshoot Python issues, do not use any other Python environment.<\/li>\n<\/ol>\n<\/a>ESP-ADF Structure<\/h2>\nYou can use VisualGDB to create projects based on the ESP-ADF<\/a> framework as well. In order to do so, you can check out the ESP-ADF repository into your ESP32 toolchain: ![\"\"](\"https:\/\/visualgdb.com\/w\/wp-content\/uploads\/2020\/05\/clone.png\")
<\/a>Note that ESP-ADF<\/strong> includes a separate copy of ESP-IDF<\/strong> as a Git submodule. However, there is a difference between the way it is handled by VisualGDB vs. the command-line Espressif tools:<\/p>\n\n- The Espressif’s command-line environment sets the IDF_PATH<\/strong> environment variable to the location of your ESP-IDF<\/strong> installation, that is separate from ESP-ADF<\/strong>. This effectively overrides<\/a> the copy of ESP-IDF<\/strong> contained inside ESP-ADF<\/strong>. Updating your ESP-IDF<\/strong> later will implicitly affect the projects built with ESP-ADF<\/strong>, potentially causing problems after the update.<\/li>\n
- VisualGDB sets the IDF_PATH <\/strong>variable based on the SDK version selected in the project properties. When building the ESP-ADF<\/strong> projects, it uses the ESP-IDF<\/strong> copy referenced by the selected ESP-ADF<\/strong> checkout (esp-adf\\<version>\\esp-idf).<\/strong> This allows having multiple ESP-ADF<\/strong> and ESP-IDF<\/strong> checkouts completely separated from each other. There are no implicit dependencies between them, and updating your ESP-IDF<\/strong> installations will not break ESP-ADF<\/strong> projects or vice versa.<\/li>\n<\/ul>\n
As of ESP-ADF<\/strong> 2.3, the version of ESP-IDF<\/strong> referenced as a Git submodule is very old and may not work with some projects. To work around it, you need to manually go to the c:\\SysGCC\\esp32\\esp-adf\\<version>\\esp-idf<\/strong> directory and run the following commands there:<\/p>\ngit checkout <ESP-IDF tag name>\r\ngit submodule update --recursive<\/pre>\nYou can find out the exact tag name by running “git describe \u2013tags<\/strong>” in your ESP-IDF checkout.<\/p>\nNote that not all versions of ESP-IDF<\/strong> and ESP-ADF<\/strong> are compatible. You can find out the ESP-IDF versions compatible with a specific ESP-ADF release by checking the <esp-adf>\\docs\\en\\get-started\\index.rst<\/strong> file (search for “ESP-IDF versions”).<\/p>\n<\/a>ESP-IDF 5.5<\/h2>\n
VisualGDB ESP-IDF-based projects are specifically designed as to work as a thin wrapper on top of the ESP-IDF build system. While VisualGDB provides convenient GUI for many common ESP-IDF tasks, it does not introduce any changes to the underlying build process. This ensures that: Update:<\/strong><\/span> VisualGDB 6.1 and later now understands the the same IDF and tool layout that is used by the Espressif’s VS Code extension. You no longer need to download a separate toolchain from us, and can use the latest tools from Espressif, producing the same results as VS Code. See this page<\/a> for details.<\/p>\n A typical ESP-IDF-based project consists of the following components:<\/p>\n Each component is internally defined as a static library. The final firmware build by the project is obtained by linking all of the project’s components together.<\/p>\n Each component can define its own properties (e.g. include directories or preprocessor macros) via the regular VS Properties dialogs: ESP-IDF projects are built using CMake scripts included in the ESP-IDF. If you encounter problems building the project, see the build problem troubleshooting<\/a> section.<\/p>\n ESP32 devices can be debugged via JTAG (this includes the ESP32 Arduino core). Generally, we advise using the ESP32-WROVER-KIT module<\/a>, as it includes an on-board JTAG debugger and can be debugged out-of-the-box. Many other boards do not include a JTAG connector and require soldering in order get debugging to work. You can find example schematics for popular boards in our ESP32 tutorials<\/a>.<\/p>\n If you do not have a JTAG debugger, you can still program the FLASH memory of the ESP32 module via the COM port by right-clicking on the project in Solution Explorer and selecting “Program FLASH Memory<\/strong>“.<\/p>\n You can configure various parameters of the ESP32 projects via VisualGDB Project Properties -> ESP-IDF Project -> ESP-IDF Configuration: You can create and run unit tests on the ESP32 devices, as long as you have a JTAG debugger. See this tutorial<\/a> for detailed step-by-step instructions.<\/p>\n Because the ESP-IDF framework does not explicitly reference header files in the component definitions, VisualGDB tries to discover them dynamically based on the component’s source directory. Unless the automatic discovery of header files is disabled, adding existing headers to Solution Explorer will have no effect if the headers are not located in a place where they can be automatically discovered.<\/p>\n You can change the way VisualGDB discovers the headers for each target via per-target properties in Solution Explorer:\u00a0 If you set the Header File Search Mode<\/strong> to Disabled<\/strong>, adding headers to a target explicitly add them to the idf_component_register()<\/strong> statement together with the sources.<\/p>\n As the ESP32 projects are built by ESP-IDF itself, rather than by VisualGDB, many build issues are caused by incompatible configuration settings, missing external dependencies or unsupported combinations of ESP-IDF and toolchain (see this section<\/a>). VisualGDB can help you narrow down the issue by exporting the exact build command line used by it, as we will show below.<\/p>\n Before you begin troubleshooting a build issue, make sure you understand whether it happens during the configuration phase<\/strong>, or build phase<\/strong>. The configuration phase<\/strong> happens when you just load the project. If it fails, the project will have an error icon in Solution Explorer. If this happens, try reloading the project (or doing a clean reload) via the context menu: Configuration problems are often caused by errors in CMake scripts or corrupt toolchain\/ESP-IDF environments. Build problems are typically triggered by errors in the source code, or when trying to build a project created for an older ESP-IDF version. For both build and configuration, you can find out the exact command line used by VisualGDB to launch the ESP-IDF tools in the VisualGDB Build window: If you determine that the build or configuration fails due to missing environment variables, you can specify them via VisualGDB Project Properties -> CMake Build Settings<\/strong>: Update:<\/strong> VisualGDB 6.1 or later directly supports the same tool layout as used by Espressif’s VS Code extension. This simplifies troubleshooting and eliminates the need to download extra toolchains. Read more about it here<\/a>.<\/p>\n If you encounter issues with an older version of the toolchain, please follow the steps below to ensure your ESP-IDF checkout and the toolchain are compatible:<\/p>\n If it still doesn’t help, see the Resetting Python Environment section<\/strong> below.<\/p>\n If you would like to try a pre-release ESP-IDF version (e.g. v4.1 or later) that is not yet shipped with our toolchains, please make sure you use VisualGDB 5.5 Preview 6 or later and the esp32-gcc8.2.0-r3.exe<\/strong> toolchain (or later), as the older toolchains use a layout that is incompatible with newer ESP-IDF versions. It may still not work as expected, so unless you are prepared to troubleshoot toolchain\/Python issues, please consider using\u00a0 stable ESP-IDF release shipped with our toolchains.<\/p>\n VisualGDB distinguishes different toolchain versions by comparing the following parameters:<\/p>\n Normally, the toolchain revision increases for bugfix releases that completely supersede the prior ones, however this is not the case for ESP32 toolchains, where multiple different revisions may be needed at the same time.<\/p>\n You can configure VisualGDB to recognize multiple ESP32 toolchains with the same GCC\/GDB versions using one of the 2 methods below:<\/p>\n Note that automatically managing multiple toolchain\/BSP versions is supported starting from the Custom edition. If you are using a lower edition, consider manually changing the toolchain ID in the toolchain.xml<\/strong> file, so that VisualGDB will consider it a separate toolchain.<\/p>\n Update:<\/strong> VisualGDB 6.1 or later directly supports the same tool layout<\/a> as used by Espressif’s VS Code extension, eliminating the need for troubleshooting steps below.<\/p>\n If you are using the ESP32 toolchain\u00a0 v8.2.0r3<\/strong> or later, the Python environment would not be a part of the toolchain and would not be reset by reinstalling the toolchain. If you encounter Python-related problems, follow the steps below to reset the Python environment:<\/p>\n You can use VisualGDB to create projects based on the ESP-ADF<\/a> framework as well. In order to do so, you can check out the ESP-ADF repository into your ESP32 toolchain: As of ESP-ADF<\/strong> 2.3, the version of ESP-IDF<\/strong> referenced as a Git submodule is very old and may not work with some projects. To work around it, you need to manually go to the c:\\SysGCC\\esp32\\esp-adf\\<version>\\esp-idf<\/strong> directory and run the following commands there:<\/p>\n You can find out the exact tag name by running “git describe \u2013tags<\/strong>” in your ESP-IDF checkout.<\/p>\n Note that not all versions of ESP-IDF<\/strong> and ESP-ADF<\/strong> are compatible. You can find out the ESP-IDF versions compatible with a specific ESP-ADF release by checking the <esp-adf>\\docs\\en\\get-started\\index.rst<\/strong> file (search for “ESP-IDF versions”).<\/p>\n
\n<\/strong><\/p>\n\n
<\/a>Project Structure<\/h2>\n
\n
<\/a>The contents of the main component are shown directly under the project’s node, while other components can be found under the Components<\/strong> node.<\/p>\n<\/a>You can create new components in arbitrary locations, or reference existing component directories via the context menu on the Components<\/strong> node in Solution Explorer.<\/p>\n<\/a>Build Systems<\/h2>\n
<\/a>Debugging ESP32 Boards<\/h2>\n
<\/a>Configuration<\/h2>\n
<\/a>The configuration will be saved in the sdkconfig<\/strong> file that is used by the ESP-IDF build system when building the project.<\/p>\n<\/a>Unit Tests<\/h2>\n
<\/a>Header Files<\/h2>\n
<\/a>Note that unlike the regular Advanced CMake projects, header settings for ESP-IDF project node (1) will only affect the main component (<Project Directory>\\main<\/strong>).<\/p>\n<\/a>Troubleshooting Build Problems<\/h2>\n
<\/a>The build phase happens when you actually build the project via the Build Solution<\/strong> command.<\/p>\n<\/a>You can dump the command line to a batch file using the context menu. The file will include the working directory and any environment variables, so you will be able to reproduce the problem outside VisualGDB. Note that the same build log can contain multiple command lines. Each command line that can be dumped into a batch file is shown in cyan<\/span>.<\/p>\n<\/a><\/p>\n<\/a>Troubleshooting ESP-IDF\/Toolchain Compatibility<\/h2>\n
\n
<\/a><\/li>\n<\/a><\/li>\n<\/a>Installing Multiple Toolchains<\/h2>\n
\n
\n
<\/a>Resetting Python Environment<\/h2>\n
\n
<\/a>See this page<\/a> for more information about VisualGDB-managed Python installations.<\/li>\n<\/a>Unless you are prepared to troubleshoot Python issues, do not use any other Python environment.<\/li>\n<\/ol>\n<\/a>ESP-ADF Structure<\/h2>\n
<\/a>Note that ESP-ADF<\/strong> includes a separate copy of ESP-IDF<\/strong> as a Git submodule. However, there is a difference between the way it is handled by VisualGDB vs. the command-line Espressif tools:<\/p>\n\n
git checkout <ESP-IDF tag name>\r\ngit submodule update --recursive<\/pre>\n
<\/a>ESP-IDF 5.5<\/h2>\n