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.

FTDI FT4232H Mini Module

Wiring up JTAG

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

FT4232 Overview — Pinout
  • 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

macOS

macOS USB Device Listing showing FT4232H MiniModule with its USB PID and VID
Linux lsusb showing FT4232H MiniModule with its USB PID and VID

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!

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store