Debugging the ESP32 in PlatformIO (using JTAG)
When Serial.printf(); is not enough
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
Linux + macOS
Write down your VID and PID (in my case 0x0403, 0x6011) and change ftdi_device_desc, ftdi_device_desc, and ftdi_layout_init in
Now add the JTAG interface to your projects platformio.ini:
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!