Importing ESP32 projects built with ESP-IDF into VisualGDB

This tutorial shows how to use the Sysprogs ESP32 toolchain to build the sample projects from ESP-IDF directly on Windows and import them into VisualGDB for easier editing and debugging. Unlike the MSBuild-based ESP32 workflow, VisualGDB will not be controlling the build process. Instead, it will launch the esp-idf build tools to do the actual build, that will allow the use of the menu-based configuration options and auxiliary Python scripts included in the IDF.

Before you begin, install our latest ESP32 toolchain on your computer.

We will not build the basic “Blinking LED” sample from ESP-IDF and show how to use VisualGDB to edit and debug it.

  1. Open the Cygwin shell by running “<toolchain directory>\bin\mintty.exe -” (note the dash at the end of the command line) and go to the $IDF_PATH/examples/get-started/blink directory:01-cdNote that the ESP-IDF compatible with command-line builds is installed in the <toolchain>\esp-idf.orig directory. If you run mintty.exe (or bash.exe ‐‐login), the $IDF_PATH variable will automatically point to its location. Note the double dash before ‘login’.
  2. Run “make menuconfig” in the example directory. You will see the menu-based configuration interface provided by the ESP-IDF:02-menuconfig
  3. Exit the configuration interface and run “make” to build the sample project:03-built
  4. Before we import the project into VisualGDB, ensure that you can program it. Connect your ESP32 board to the computer and locate its COM port in Device Manager:04-usbser
  5. The Cygwin path for this port will be /dev/ttyS<COM port number minus 1>. E.g. for COM9 it is /dev/ttyS8. You can list all COM ports visible to Cygwin by typing ls /dev/tty in the command prompt and pressing <TAB>:05-ttys8
  6. Go back to the configuration interface (by running “make menuconfig” in the Cygwin terminal) and set “Serial flasher config -> Default Serial Port” to the Cygwin port path:06-setting
  7. Save the settings and run “make flash” to program the firmware into the FLASH memory:07-makeflashEnsure that the LED on the board is blinking. If not, try resetting it manually by pressing the reset button.
  8. Now we will import the project into VisualGDB so that we can edit and debug it more conveniently. Start Visual Studio and open VisualGDB Embedded Project Wizard:08-blink
  9. Select “Import a project built with command-line tools -> Specify a build command line manually”:09-cmdline
  10. Select your ESP32 toolchain and the basic ESP32 device:10-esp32
  11. Enter the sample directory on the “Import Source” page: 11-dir
  12. On the “Import Build/Debug” page specify the following command to build the project:
    Setting Value
    Command <SysGCC>\esp32\bin\bash.exe
    Arguments ‐‐loginlogin -c “make -C $(BuildDir.forwardslashes)”

    Warning: copying the ‘arguments’ field from your browser may result in invalid characters. If you get strange build errors, delete the 2 dashes before the ‘login’ argument and type them manually.12-build

  13. Enter the path to the ELF file built with ESP-IDF in the “Executable file to debug” field:13-elf
  14. On the Debug Method page select the same debug settings that you use for regular ESP32 projects:14-debug
  15. Press “Finish” to generate the project. Now you can build it via Build->Build Solution (or Ctrl-Shift-B). VisualGDB will automatically invoke the ESP-IDF build script and display the error messages from it in the Errors pane:15-buildvs
  16. Note that as VisualGDB does not control the build, it does not know the include directories used by the compiler and will not be able to locate some of the header files. If you are using VisualGDB 5.2 or later, it will automatically search the source directories for the missing headers and suggest adding them to IntelliSense settings. Note that the nvs_flash/test_nvs_host directory contains a wrong version of sdk_config.h and should be skipped by pressing the “X” button:16-suggest
  17. Ensure that the skipped directory is replaced with the <sample project name>/build/include directory and click “Add now” to permanently adjust the IntelliSense settings:17-suggest-good
  18. Note how the IntelliSense errors will disappear:18-fixed
  19. Press F5 to begin debugging. VisualGDB will automatically program the FLASH memory via JTAG:19-program
  20. Once the programming is complete, ensure that the LED is blinking and try setting a breakpoint in the main source file. It will not work due to special path naming rules used by esp-idf. Click the “Diagnose breakpoint problems” button to fix this automatically:20-nobp
  21. VisualGDB will detect that the problem is caused by an extra slash and dot at the end of the file path and will suggest creating a rule to work around this. Proceed with the mapping rule:21-map
  22. Now you should be able to debug the project as if it was a regular esp32 project built by VisualGDB (note the various debugging limitations of ESP32):22-bkpt
  23. As ESP-IDF is controlling the build, changing VisualGDB/Visual Studio project properties won’t affect the build. Instead, you would need to edit the Makefiles in your project directory and the ESP-IDF directories to change various build settings:23-make
  24. Locate the sdkconfig.h file under your project’s build directory. This file contains all build settings selected via the menu-based configuration interface:24-sdkconfIf you want to transfer the settings from a project built with ESP-IDF to a MSBuild-based project, simply copy the sdkconfig.file to the MSBuild project directory.