How to Set Up JTAG Debugging on an ESP32 Using an FTDI Chip

What you need to debug an ESP32 with FTDI hardware

JTAG debugging on an ESP32 requires an FTDI chip that supports JTAG protocol — typically an FT2232H, FT4232H, or FT232H. The FTDI chip acts as a bridge between your computer and the ESP32's JTAG pins, letting your debugger step through code, set breakpoints, and inspect variables in real time. You'll also need OpenOCD (Open On-Chip Debugger) running on your computer and a GDB client to interact with the debugger.

The physical connection uses four wires: TCO (test clock output), TDI (test data in), TDO (test data out), and TMS (test mode select). Some setups also connect ground and a reset line. The exact pins on your ESP32 depend on which model you have — the ESP32-WROOM and ESP32-PICO-D4 use different pin assignments than the ESP32-S3 or ESP32-C3.

Key Takeaways

An FT2232H or FT4232H FTDI chip connects to your ESP32's JTAG pins (TCO, TDI, TDO, TMS) and your computer via USB.
OpenOCD runs on your computer and communicates with the FTDI chip to control the ESP32 debugger.
You must configure OpenOCD with the correct board file and FTDI interface settings before debugging starts.
GDB connects to OpenOCD's TCP port to let you set breakpoints, step through code, and inspect memory.
The ESP32 firmware must be built with debugging symbols enabled, usually by setting the optimization level to -Og or lower.

Wiring the FTDI chip to your ESP32

The four JTAG signal wires must connect from the FTDI chip to the correct pins on your ESP32. For the standard ESP32-WROOM, TCO connects to GPIO13, TDI to GPIO12, TDO to GPIO15, and TMS to GPIO14. The ESP32-S3 uses GPIO39 for TCO, GPIO40 for TDI, GPIO41 for TDO, and GPIO42 for TMS. Check your specific board's datasheet or pinout diagram before soldering or breadboarding.

Connect ground from the FTDI chip to a ground pin on the ESP32 — this is essential for signal integrity. Many setups also wire the FTDI's reset output to the ESP32's EN (enable) pin so OpenOCD can reset the chip during debugging. Use short wires, ideally under 10 centimeters, to reduce noise on the JTAG signals. If you are using a breadboard, press the wires firmly into the holes to avoid loose connections that cause intermittent failures.

The FTDI chip itself connects to your computer via USB. Most FTDI breakout boards include a micro-USB or USB-C connector. Plug it in and verify your operating system recognizes it — on Linux, run lsusb and look for "Future Devices" or "FTDI". On Windows, check Device Manager for a USB Serial Device or FTDI device. On macOS, the system usually loads the FTDI driver automatically.

Installing and configuring OpenOCD

OpenOCD is the software that talks to the FTDI chip and controls the ESP32's debug hardware. Download a prebuilt binary from the OpenOCD project website or install it through your package manager — on Ubuntu, apt install openocd works; on macOS with Homebrew, use brew install open-ocd. On Windows, download the installer from the official OpenOCD site.

After installation, create a configuration file that tells OpenOCD how to communicate with your FTDI chip and ESP32. A minimal config file looks like this: it specifies the FTDI interface (FT2232H or FT4232H), the channel on the FTDI chip (usually channel 0 for JTAG), the ESP32 target, and the JTAG clock speed. Save this as esp32-ftdi.cfg in your working directory.

The configuration must match your hardware exactly. If you are using an FT4232H, the interface line changes to interface ftdi with ftdi_device_desc "Quad RS232-HS". If your JTAG signals are on a different channel, update the ftdi_channel line. The JTAG clock speed (adapter_khz) should start at 1000 kHz; you can increase it to 5000 or 10000 kHz once debugging works, but slower speeds are more reliable over longer wires.

Building your ESP32 firmware with debug symbols

For the debugger to show you source code and variable names, your firmware must include debug symbols. In the ESP-IDF build system, this happens automatically when you set the optimization level to -Og or -O0. Open your project's sdkconfig file or run idf.py menuconfig, navigate to Compiler Options, and set Optimization Level to Debug (-Og). This keeps the code reasonably fast while preserving all symbol information.

Rebuild your project with idf.py build. The resulting ELF file (usually in build/your_project.elf) contains the debug symbols. This ELF file is what you pass to GDB, not the binary you flash to the chip. Flash the binary to the ESP32 as usual with idf.py flash, but keep the ELF file on your computer for debugging.

Starting OpenOCD and connecting GDB

Open a terminal and run OpenOCD with your configuration file: openocd -f esp32-ftdi.cfg. If the connection succeeds, you will see output like "Info : JTAG tap: esp32.cpu0 tap/device found" and "Info : Listening on port 3333 for gdb connections". If you see errors about the FTDI device not being found, check that the USB cable is plugged in, the FTDI driver is loaded, and the configuration file specifies the correct interface and channel.

In a second terminal, start GDB with your ELF file: xtensa-esp32-elf-gdb build/your_project.elf (or riscv32-esp-elf-gdb for ESP32-C3 and ESP32-S3). At the GDB prompt, connect to OpenOCD by typing target remote :3333. GDB will connect to OpenOCD's TCP port and halt the ESP32. You can now set breakpoints with break main, resume execution with continue, and step through code with step or next.

Common problems and fixes

If OpenOCD says "Error: unable to open ftdi device", the FTDI chip is not recognized. On Linux, you may need to add a udev rule so your user can access the USB device without root. Create a file /etc/udev/rules.d/99-ftdi.rules with the line ATTRS{idVendor}=="0403", MODE="0666", then reload with udevadm control --reload. On Windows, reinstall the FTDI driver from the manufacturer's website. On macOS, unplug the device, restart your computer, and plug it back in.

If GDB connects but the ESP32 does not halt, or if breakpoints do not work, check that the JTAG wires are connected to the correct pins and that ground is connected. Loose breadboard connections are a common culprit — try pressing the wires in again or moving to a different set of holes. If the JTAG clock speed is too high, lower adapter_khz to 500 kHz and try again.

If you see "Error: JTAG scan chain interrogation failed", the FTDI chip is communicating but the ESP32 is not responding. This usually means the ESP32 is in deep sleep or the reset line is not connected. Try pressing the ESP32's reset button manually, or add the reset line from the FTDI chip to the ESP32's EN pin in your configuration file.

Frequently Asked Questions

Can I use a cheaper FTDI clone instead of an official chip?

Clones often work but may have driver issues or unreliable JTAG timing. Official FTDI chips from Digi-Key or Mouser are inexpensive (under $15) and come with reliable drivers. If you already have a clone, try it — if JTAG fails, the official chip is worth the upgrade.

What is the difference between FT2232H and FT4232H?

The FT4232H has four channels instead of two, so you can run JTAG on one channel and a serial port on another without conflicts. For simple debugging, either works. The FT2232H is cheaper and more common in hobbyist boards.

Do I need to disconnect the serial port when debugging?

If your FTDI chip has two channels and you are using one for JTAG and one for serial, you can keep both connected. If you are using a single-channel chip or both channels for JTAG, close any serial monitor before starting OpenOCD to avoid port conflicts.

Why is my breakpoint not stopping the code?

The most common cause is that the firmware was built without debug symbols. Rebuild with optimization level -Og, reflash the binary, and restart GDB. Also verify that the breakpoint address matches the code — use info line main in GDB to check.

Can I debug over a longer cable or through a USB hub?

JTAG is sensitive to cable length and signal quality. Cables over 2 meters often cause timing errors. USB hubs add latency and can cause connection drops. Use a direct USB connection and keep JTAG wires short and twisted together to reduce noise.

This guide is for general information only and is not medical, financial, legal, or other professional advice. For decisions specific to your situation, consult a qualified professional. See our Editorial Policy.