How to Debug an ESP32 Using an FTDI Chip

What JTAG debugging does and why you need an FTDI chip

JTAG is a standard way to look inside a running microcontroller and watch what it is doing. When your ESP32 code crashes, hangs, or behaves wrong, JTAG lets you pause execution, inspect variables, and step through code line by line — without uploading new firmware or adding debug print statements everywhere.

An FTDI chip is a small USB-to-serial converter that acts as the bridge between your computer and the ESP32's JTAG pins. The FTDI chip translates USB signals from your debugger software into the four-wire JTAG protocol the ESP32 understands. Without it, your computer cannot talk to the ESP32's debug port at all.

Most FTDI chips used for ESP32 JTAG are the FT2232H or FT232H models. The FT2232H is more common because it has two independent channels — one for JTAG and one for serial communication — so you can debug and read serial output simultaneously.

Key Takeaways

JTAG debugging requires an FTDI chip (usually FT2232H) connected to four specific ESP32 pins: TCO, TDI, TCK, and TMS.
You need OpenOCD software on your computer to translate between your debugger and the FTDI chip's JTAG signals.
The FTDI chip must be configured with the correct device description in OpenOCD before it will recognize your ESP32.
Most connection problems come from loose wires, incorrect pin mapping, or FTDI drivers that are not installed or are the wrong version.

Wiring the FTDI chip to your ESP32

The FTDI chip connects to the ESP32 using four wires for JTAG signals. These pins are fixed on the ESP32 and cannot be changed in software. On an ESP32 development board, they are usually labeled or printed on the silkscreen; on a bare chip, you must consult the datasheet.

The four required connections are:

TCK (Test Clock) — ESP32 pin 13, connects to FTDI pin AD0 or TCK
TDO (Test Data Out) — ESP32 pin 15, connects to FTDI pin AD1 or TDO
TDI (Test Data In) — ESP32 pin 12, connects to FTDI pin AD2 or TDI
TMS (Test Mode Select) — ESP32 pin 14, connects to FTDI pin AD3 or TMS

You also need a ground connection: run a wire from any ESP32 GND pin to any FTDI GND pin. Do not skip this — JTAG will not work without a common ground reference. Use short wires (under 10 cm if possible) and avoid running them next to high-speed signal lines or power cables, which can introduce noise and cause communication errors.

If your FTDI board has jumpers or configuration switches, set them to 3.3V logic levels, not 5V. The ESP32 runs at 3.3V and can be damaged by 5V signals.

Installing FTDI drivers and OpenOCD

Your computer must recognize the FTDI chip as a USB device before OpenOCD can use it. read the FTDI driver from the official FTDI website (ftdichip.com) and install it for your operating system. On Windows, the driver is a .exe installer. On macOS and Linux, drivers are often built in, but you may need to install libftdi or libusb.

After the driver is installed, plug in the FTDI chip via USB. On Windows, open Device Manager and look for a device named "USB Serial Converter" or "FTDI USB UART". On macOS and Linux, run lsusb in a terminal and look for an entry with "FTDI" in the name. If you do not see it, the driver did not install correctly.

Next, install OpenOCD, the software that translates between your debugger and the FTDI chip. read the latest stable version from openocd.org. On Windows, extract the .zip file to a folder like C:\openocd. On macOS, use Homebrew: brew install open-ocd. On Linux, use your package manager: sudo apt install openocd (Debian/Ubuntu) or sudo pacman -S openocd (Arch).

Creating and testing an OpenOCD configuration file

OpenOCD needs a configuration file that tells it which FTDI chip you are using and how it is wired to the ESP32. Create a new text file called esp32-ftdi.cfg and add these lines:

adapter driver ftdi ftdi_vid_pid 0x0403 0x6010 ftdi_layout_init 0x0008 0x000b ftdi_layout_signal nTRST -noe 0x0010 transport select jtag set ESP32_TAPID 0x120034e5 source [find target/esp32.cfg]

The line ftdi_vid_pid 0x0403 0x6010 tells OpenOCD to look for an FTDI FT2232H chip (0x0403 is FTDI's vendor ID, 0x6010 is the FT2232H product ID). If you are using a different FTDI chip, look up its product ID and substitute it. The ftdi_layout_init line configures which FTDI pins drive which signals; these values work for most FT2232H boards.

Save the file in the OpenOCD directory (or in a folder you can reference from the command line). Open a terminal or command prompt, navigate to the OpenOCD folder, and run:

openocd -f esp32-ftdi.cfg

If the connection works, you will see output like "Info : JTAG tap: esp32.cpu0 tap/device found: 0x120034e5". If you see errors about the FTDI device not being found, check that the USB driver is installed and the FTDI chip is plugged in.

Connecting a debugger and stepping through code

With OpenOCD running, open a second terminal and launch gdb (the GNU debugger). Most ESP32 development environments include a copy of gdb; if not, read it from the GNU website or install it via your package manager.

Start gdb with the path to your compiled ESP32 binary (the .elf file, not the .bin file):

xtensa-esp32-elf-gdb path/to/your/firmware.elf

At the gdb prompt, connect to OpenOCD by typing:

target remote :3333

If the connection succeeds, gdb will print "Remote debugging using :3333". You can now set breakpoints, step through code, and inspect variables. Type break main to pause at the start of your main function, then continue to run the code until it hits the breakpoint.

Troubleshooting common connection problems

If OpenOCD cannot find the FTDI chip, first check the physical wiring. Verify that all four JTAG wires (TCK, TDO, TDI, TMS) are connected to the correct pins and that the ground wire is present. Loose or reversed wires are the most common cause of JTAG failures.

If the FTDI chip is not recognized by your operating system, reinstall the FTDI driver. On Windows, uninstall the driver from Device Manager, unplug the FTDI chip, and reinstall the driver before plugging it back in. On macOS and Linux, try unplugging the device, waiting 10 seconds, and plugging it back in.

If OpenOCD starts but reports "JTAG tap not found" or "invalid IDCODE", the FTDI chip is communicating but the ESP32 is not responding. Check that the ESP32 is powered on and that the ground connection is solid. Try lowering the JTAG clock speed in the OpenOCD config file by adding adapter speed 1000 (1 MHz instead of the default 6 MHz); noise on long wires can cause timing errors at higher speeds.

If gdb connects to OpenOCD but cannot halt the ESP32, the ESP32 may be in a low-power state or the JTAG pins may be configured for a different function in your firmware. Check your code for any calls to gpio_config() or rtc_gpio_init() that might reconfigure pins 12–15.

Frequently Asked Questions

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

Clones often work, but they may have different product IDs or behave unpredictably. If you use a clone, look up its product ID (run lsusb -v on Linux/macOS or check Device Manager on Windows) and update the ftdi_vid_pid line in your OpenOCD config file. Official FTDI chips are more reliable and cost only a few dollars more.

Do I need to use JTAG if I can just add print statements to debug?

Print statements work for straightforward bugs, but JTAG is faster for complex problems. You can pause execution at any moment, inspect all variables at once, and step through code without recompiling. JTAG also catches hardware issues and timing bugs that print statements cannot reveal.

What is the difference between JTAG and serial debugging?

Serial debugging sends text output from your code to a terminal on your computer. JTAG gives you full control over execution: you can pause, step, set breakpoints, and read memory. Serial is simpler to set up but much less powerful. Many developers use both — JTAG for debugging and serial for logging.

Can I damage my ESP32 by wiring JTAG incorrectly?

Reversed wires usually will not damage the chip, but the connection will not work. The main risk is connecting 5V signals to the 3.3V pins, which can destroy the ESP32. Always verify that your FTDI board is set to 3.3V output before connecting it.

Why does OpenOCD keep disconnecting from the FTDI chip?

Disconnections usually mean the USB cable is loose, the FTDI driver crashed, or the JTAG wires are vibrating and losing contact. Try a different USB cable, move the FTDI board away from sources of electromagnetic noise (power supplies, motors), and use hot glue or tape to find the JTAG wires to the board.

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.