How to debug an ESP32S3 via JTAG with an Arduino project and GDB?

× Not what you are looking for? Did you want USB/WiFi debug, trace and performance monitoring instead?
FAQ    |    USB Drivers

The ESP32SS3 Modules are being adopted many boards, all of which can now be debugged using an External Hardware debugger, directly in Visual Studio, with vMicro!

This page applies to all ESP32S3 Modules. See these pages for the ESP32S2, ESP32S3 via USB, ESP32C3 via JTAG and ESP32C3 via USB.

Note Icon Note:

If you are using ESP32 Core v2.0.0 - 2.0.2 there is an issue with the GDB.exe reported here.  Update to v2.0.3 onwards which have the issue resolved.

If you are using "Upload via Programmer", ensure you do not use v2.0.4 as this has an issue with bootloaders.

 

External Debug Interface: USB (Default)

If you are looking to use USB to debug this board please see the seperate page here.

To see a list of all debuggers currently supported within vMicro please click here.

NOTE: If using External JTAG debugging any SDCard functionality will need to be removed as this conflicts with the JTAG pin assignments.
           All boards support the vMicro Software Debugger which only requires the Serial interface to work

 

JTAG External Debugger Connections

Note Icon Note:

You will need to set a Fuse bit to enable JTAG! This operation is irreversible, so be sure you want to do this before burning the fuse.

 

Check Fuse Bits

Download the full ESPTOOL from GitHub: https://github.com/espressif/esptool/releases/download/v3.3/esptool-v3.3-win64.zip

Extract it to a folder on your PC.

Open a command line and navigate to the esptool folder you created above.

cd %USERPROFILE%\Downloads\esptool-v3.3-win64

 

Run the script to show the current fuse summary:

espefuse.exe --port COM5 summary

You will see output similar to below:

Note Icon Note:

The above output is from a ESP32-C3-DevKitC-02 which does not have the STRAP_JTAG_SEL fuse available.



  1. The STRAP_JTAG_SEL needs to be set, which allows GPIO3 to be pulled LOW at boot to enable the JTAG Pins. If not pulled LOW then the USB-JTAG functionality is available.
  2. If STRAP_JTAG_SEL is not present, you will need to set the DIS_USB_JTAG Fuse, which PERMANENTLY disables USB debugging on this board, and cannot be undone.

Burning the Fuse


This is a one-time (irreversible) operation, full eFuse.exe documentation is available at Espressif.

espefuse.exe --port COM5 burn_efuse STRAP_JTAG_SEL

 

If you do not have the fuse you will see this output:

JTAG Fuse Burn Fail (Fuse Doesn't Exist)

 

If you do have the fuse, you may have to type in "BURN" to continue burning the fuse, as shown below:

Fuse Burn Success

Once complete run the summary command again:

espefuse.exe --port COM5 summary

Check the STRAP_JTAG_SEL or DIS_USB_JTAG is set to True in the output depending on which fuse you burned.

 

JTAG Wiring Connections

NOTE: If you have set the JTAG_SEL_ENABLE Fuse above you will also need to connect IO3 to GND when resetting the board.

To connect your JTAG debugger to the ESP32S3 board you will need to connect the below pins:

ESPC3 JTAG Connections

 

Specific Probe Wiring Diagrams

ESP-PROG Wiring Diagram

FT2232H Dual 

FT2232 Mini Module

TODO: ESP-DEVKIT Wiring Diagram

Then you will also need to connect your Debugger to the PC on one USB port, and the ESP32 on another USB Port

 

Software Setup

Note Icon Note:

  • This is only reliable from vMicro Version 2022.0429.02 onwards.
  • This currenly requires a Local board.txt to function at its best:
    debug.toolingsystem=gdbscript
# Very Latest OpenOCD needed for ESP32S3
tools.openocd.debug.path={runtime.tools.openocd-esp32-0.10.1-2021.11.11.path}
tools.openocd.program.path={runtime.tools.openocd-esp32-0.10.1-2021.11.11.path}
tools.openocd.upload.path={runtime.tools.openocd-esp32-0.10.1-2021.11.11.path}

 

There is also a video guide to the software and driver setup described below

Ensure you have Visual Studio and the vMicro Extension Installed

Open your Sketch and select the Debug > Hardware, and the relevant Debugger you have available

Visual Studio Toolbar Selections for ESP32

NOTE - The vMicro > Debugger > Compiler Optimization MUST be set to "No Optimization" for this board to function with the debugger

You may need to install an additional USB Driver on Interface 0 of your debugger to allow it to function with this software - check in the debugger list here

Remember - If you have installed a new driver, you may have to do it again if you connect the debugger to a different USB port next time.....

 

Start Debugger

  1. Ensure you have the Debug Configuration selected from the Configuration Manager Window
  2. If you know where you want the first breakpoint in your code, add it now
  3. To start the debugging process, you can either:
    • "Debug > Attach to Process" button if your code has already been uploaded to the ESP32 board
    • "Debug > Start Debugging" if your code has not been uploaded
ESP32 Debugging in vMicro and Visual Studio

Congratulations - you should have the debugger running, and further windows can be opened from the "Debug > Windows" menu once you have started debugging

 

See our GDB Debugging in Brief guide, or our detailed GDB Debugging Tutorial for Arduino to learn more about using the debugging interface.

 

There is also a video guide on this below: