Note to self – Debugging the Wemos D1 Mini ESP32

General

Yes, this board is generally debugable, but : Only via JTAG!

Debugging Hardware

I am using the original Espressif ESP-Prog board. It supports the JTAG interface as well as two 3,3V and 5V programming voltages.

The relevant Pins on the D1 Mini Board are printed on the underside of the board. If not, refer to the layout of the particular board. The following pins are required:

  • TMS
  • TCK
  • TDI
  • TDO

Also the VJtag voltage should be selected and connected appropriately. For example, if the ESP-Prog jumper for the JTAG connector voltage is set 3.3V, connect the VJtag Pin to 3.3V on the D1 Mini board.

Software

For development I am using VS Code with the PlatformIO extension in Windows OS.

Setup

Package

To make this work with PlatformIO, the openocd for ESP32 debug package must be installed. To enforce this, the package should be explicitly installed. Open “PlatformIO Core CLI” via the PlatformIO menu. Execute the following command:

pio pkg install -g -t "tool-openocd-esp32"

Configuration

In the platformIO.ini file some cruicial configurations need to be made, or even not be made!

  • Do not use additional compiler flags! Especially any “-g*” flag caused debugging to always fail
  • Any path to the openocd package must be absolute! This goes especially for the “-f” launch options
  • The order of the command flags “-c” is cruicial. “init” must appear before “reset halt” or reset will be reported as an unknown command!
  • Debug speed must most likely be adjusted. I could not make anything work higher than 10MHz

As a result, the cruicial configuration is as follows:

[env:ESP32D1Mini-DBG]
extends = env:ESP32D1Mini
build_type = debug
build_flags =
    ${env.build_flags}
    -DDEBUG

debug_tool = esp-prog
debug_server =
  ${platformio.packages_dir}/tool-openocd-esp32/bin/openocd
  -f ${platformio.packages_dir}/tool-openocd-esp32/share/openocd/scripts/interface/ftdi/esp32_devkitj_v1.cfg
  -f ${platformio.packages_dir}/tool-openocd-esp32/share/openocd/scripts/target/esp32.cfg 
  -c "adapter speed 10000" 
  -c "init" 
  -c "reset halt"