How to best configure ESP32 + Arduino + VS Code Debug

[simonerom]

Hi all,
I decided to start experimenting with Embedded devices and my choice for the device is the ESP32 + Arduino
Since my C++ skills are quite rusty, my first step is to get a good development environment that includes a working debug system. After several hours of work, I could get a decent configuration that can debug the Blink example, but it is not perfect and I would appreciate some advices to improve the development experience (see my issues at the bottom). Here is my configuration:

HARDWARE:

• ESP32 DEV KIT (V1)
• FT232H (Single channel) Module
• MacBook Pro 13 (BigSur OS)

SOFTWARE

• Arduino IDE
• VS Code
• OpenOCD v0.10.0-esp32-20200709

My debug board is a cheap one, it has non standard FTDI product id (0x6014 instead of 6x010) but I had no issues with macOS BigSur, which does not load any driver for it yet it is recognised by openOCD, only I had to run it with:

openocd -f board/esp32-wrover-kit-3.3v.cfg -c 'ftdi_vid_pid 0x0403 0x6014'

Next, I could make GDB run with the following launch.json file in VS Code:

{
"version": "0.2.0",
"configurations": [
{
"name": "GDB",
"type": "gdb",
"request": "launch",
"cwd": "${workspaceRoot}",
"target": "/var/folders/93/kwmr2pgn1m7g0jrv1mw1d1vc0000gn/T/arduino_build_980648/blink.ino.elf",
"gdbpath" : "/Users/simone/.espressif/tools/xtensa-esp32-elf/esp-2020r3-8.4.0/xtensa-esp32-elf/bin/xtensa-esp32-elf-gdb",
"autorun": [
"target remote localhost:3333",
]
}
]
}

So here are the issues I have that I would like to fix:

1. When I start the debug, I can see the value of local variables if I hover the mouse over it, but I cannot see them listed in the left Variables panel of VS Code (which also means I cannot change the value). Any idea why they are not showing up?

2. in launch.json I'm supposed to enter the target elf file, I installed the Arduino extension for VS Code which seems to call Arduino behind scenes to build my sketch. The problem is that I have no idea where the elf file is after each compilation. The best I could do is to show detailed build output in arduino IDE, build there, look at where the elf file is generated and put it in launch.json. This works but each time I build the path of the elf file changes (it contains a folder that changes with the build number or something) which forces me to reopen Arduino ide each time I need to rebuild, and edit the launch.json to update the target pat: not ideal!

3. Any suggestions on how to get autocomplete for arduino libraries in VS Code? Is there any pre-filled file with paths to include or something that I can just put in my .vscode folder?

Please feel free to suggest any improvements to the launch.json or any other advice to increase productivity is very welcome!

Thanks!

1. ===
   Adding my own first improvement here:
   Open VS Code settings and change change the setting of the C++ extension as below to get rid of the "symbol undefined" red underline for standard arduino functions like pinMode and digitalWrite!

"C_Cpp.intelliSenseEngine": "Tag Parser"

[pert]

simonerom:

1. When I start the debug, I can see the value of local variables if I hover the mouse over it, but I cannot see them listed in the left Variables panel of VS Code (which also means I cannot change the value). Any idea why they are not showing up?

First of all, I should say that I have no experience with the VS Code Arduino extension, nor with debugging ESP32. However, I do have some experience with debugging SAMD boards via Arduino Pro IDE.

It might be purely a coincidence, but I had this same problem with Arduino Pro IDE. I realized I had forgotten to check the Sketch > Optimize for Debugging. Of course, VS Code doesn't have this option, but the important part is that what this option does is changes the compilation command by changing the "-Os" flag to "-Og -g3":

arduino/ArduinoCore-samd/blob/1.8.11/platform.txt#L37-L38

The high level of optimization that is very useful when trying to fit a large program into a small amount of memory has a harmful effect on the debuggability of the program. For this reason, Arduino added this option to reduce the optimization when you are debugging.

So you might be able to adjust the ESP32 platform's compilation commands accordingly to help out the debugger. For example, here you can see the optimization flags for C++:

espressif/arduino-esp32/blob/1.0.5/platform.txt#L31

simonerom:
2. in launch.json I'm supposed to enter the target elf file, I installed the Arduino extension for VS Code which seems to call Arduino behind scenes to build my sketch. The problem is that I have no idea where the elf file is after each compilation. The best I could do is to show detailed build output in arduino IDE, build there, look at where the elf file is generated and put it in launch.json. This works but each time I build the path of the elf file changes (it contains a folder that changes with the build number or something) which forces me to reopen Arduino ide each time I need to rebuild, and edit the launch.json to update the target pat: not ideal!

The Arduino IDE does have a preferences property for this:

arduino/Arduino/blob/master/build/shared/manpage.adoc#preferences

build.path
The path to use for building. This is where things like the preprocessed .cpp file, compiled .o files and the final .hex file go.

If set, this directory should already exist before running the arduino command.

If this preference is not set (which is normally the case), a new temporary build folder is created on every run and deleted again when the application is closed.

In addition to the command line, you can set that preference directly in the Arduino IDE's preferences.txt file. you can find the location of that file in the Arduino IDE's File > Preferences dialog at the link following the line "More preferences can be edited directly in the file".

If you like command line tools, you might also be interested in Arduino CLI. arduino-cli compile has flags to allow you to set the location of the compilation output:
https://arduino.github.io/arduino-cli/latest/commands/arduino-cli_compile/

simonerom:
3. Any suggestions on how to get autocomplete for arduino libraries in VS Code? Is there any pre-filled file with paths to include or something that I can just put in my .vscode folder?

It looks like you have this sorted, but I'll mention for others who might be interested that this does work in Arduino Pro IDE. Arduino has created a language server for Arduino sketches. Under the hood, this is using the professional grade clangd C++ language server, but the Arduino Programming language is a superset of C++, which is preprocessed into valid C++ by the Arduino build system, so clangd needs a little bit of help to interact with the Arduino build system to get the C++ and then apply those results back to the Arduino sketch, which doesn't exactly match the code clangd was looking at.