It is possible to use a true step-and-memory debugger using OpenOCD - you will need an external debugger like a JLink or FT2232 JTAG adapter

You can use an OpenOCD compatible debugging probe such as J-Link for source level debugging of C and C++ code on the Adafruit Metro ESP32-S2. (However, I had more luck with a J-link BASE than a J-Link EDU Mini and more consistent behavior with the built in debugger of the Kaluga devkit than either)

Doing some serious development on any ARM-based platform, and tired of 'printf' plus an LED to debug? A proper JTAG/SWD HW debugger can make debugging more of a pleasure and...
$19.95
In Stock

Metro ESP32S2

First you'll need to solder on an SWD connector at the indicated location on the Metro ESP32-S2 PCB. Note that the "key" of the box header must be on the same side as the "pin 1" arrow. These are very fine pitch headers and can be difficult to solder. Any solder bridges between the pins will prevent the connection from working.

This 1.27mm pitch, 2x5 male SMT Box Header is the same one used on our SWD Cable Breakout Board. The header...
$1.50
In Stock
We've carrying a new 1.27mm pitch 2x5 Mini SWD 0.05" Pitch Connector. It's a tinier, bite-sized version of the
Out of Stock

OpenOCD Setup

Next, you'll need the version of the Open On-Chip Debugger (OpenOCD) updated with ESP32-S2 support by Espressif.  If you have a CircuitPython build environment available, just use the export.sh from your CircuitPython source directory.  Otherwise, you'll want to follow the official installation instructions from Espressif.

Verify that you have Espressif's version of OpenOCD--just look for "esp32" in the version number, and make sure the date is at least as new as this one:

$ openocd --version
Open On-Chip Debugger v0.10.0-esp32-20200709 (2020-07-09-08:54)

You also need the correct debugger program, xtensa-esp32s2-elf-gdb, this version or newer:

$ xtensa-esp32s2-elf-gdb --version
GNU gdb (crosstool-NG esp-2020r3) 8.1.0.20180627-git

In one terminal, start OpenOCD:
openocd -f 'interface/jlink.cfg' -f 'target/esp32s2.cfg' -c 'adapter_khz 2000'

In another terminal, start gdb and connect to OpenOCD:

$ xtensa-esp32s2-elf-gdb build-adafruit_metro_esp32s2/firmware.elf
(gdb) target remote :3333
Remote debugging using :3333
0x4001b800 in ?? ()

I have not had success programming the chip using gdb commands like load or OpenOCD commands like program_esp.  It's inconvenient but I still use esptool when reprogramming the chip.

This guide was first published on Nov 04, 2020. It was last updated on 2021-05-19 16:48:25 -0400.

This page (Debugging with OpenOCD) was last updated on Jun 23, 2021.

Text editor powered by tinymce.