Debugging the ESP32 in PlatformIO (using JTAG)

Sometimes you need to dig deeper if a peripheral or function on the ESP32 doesn’t work. The underlying FreeRTOS components and internals of the ESP32 can make it impossible to debug via a serial port.

In that case, you can utilise the ESP32’s JTAG interface. This allows you to monitor processes, memory allocation, variables and look at the call stack and even do test driven development.

If you have FTDI FT4232H module, you can use it as a JTAG interface when used in MPSSE mode, instead of quad serial mode.

I recommend the FTDI FT4232H Mini Module.

Wiring up JTAG

You’ll require the following connections (FT4232 Mini Module to ESP32):

• ADBUS0 (CN2.7) — TCK
• ADBUS1 (CN2.10) — TDI
• ADBUS2 (CN2.9) — TDO
• ADBUS3 (CN2.12) — TMS
• #RESET (CN2.8) — RESET or EN
• GND (CN2.2) — GND
• VBUS to VCC (CN3.1 — CN3.2)
• VIO (CN2.3) — TARGET 3.3V
• CN2.1 — CN2.11

Enabling JTAG Debug Support in PlatformIO

Find the USB device

Change OpenOCD configuration

Write down your VID and PID (in my case 0x0403, 0x6011) and change ftdi_device_desc, ftdi_device_desc, and ftdi_layout_init in

# .platformio/packages/tool-openocd-esp32/share/openocd/scripts/interface/ftdi/minimodule.cfg
interface ftdi
ftdi_device_desc "Quad RS232-HS"
ftdi_vid_pid 0x0403 0x6011
ftdi_channel 0
# Every pin set as high impedance except TCK, TDI, TDO and TMS
# ftdi_layout_init 0x0000 0x001b
ftdi_layout_init 0x0008 0x000b
# nSRST defined on pin CN2–13 of the MiniModule (pin ADBUS5 [AD5] on the FT2232H chip)
# This choice is arbitrary. Use other GPIO pin if desired.
ftdi_layout_signal nSRST -data 0x0020 -oe 0x0020

Now add the JTAG interface to your projects platformio.ini:

debug_tool = minimodule
upload_protocol = minimodule // If you want to upload using JTAG instead of Serial
debug_build_flags = -O0 -ggdb3 -g3

FTDI Serial Driver Blacklisting / Unloading

You’ll also need to blacklist / move the FTDI serial driver from your Operating System. FTDI has a tool for it, but unfortunately on my macOS it didn’t work.

sudo kextunload /Library/Extensions/FTDIUSBSerialDriver.kext

Now you have a succesfully working in-system debuger!