How to debug an ESP32C3 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?

The ESP32SC3 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 ESP32C3 Modules. See these pages for the ESP32S2 and ESP32S3, and ESP32C3 via USB.

Note Icon Note:

NOTE: If you are using ESP32 Core v2.0.1 or 2.0.2 there is an issue with the GDB.exe reported here.  Roll Back to v2.0.0 to ensure this is reliable, or use v2.0.3 onwards which have the issue resolved.

 

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 JTAG_SEL_ENABLE fuse available.

We have not burned the DIS_USB_JTAG fuse on our board to test the below procedure currently.



  1. 1) The JTAG_SEL_ENABLE needs to be set to False, which allows GPIO10 to be pulled LOW at boot to enable the JTAG Pins.
  2. 2) If JTAG_SEL_ENABLE 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 JTAG_SEL_ENABLE

 

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.

Once complete run the summary command again:

espefuse.exe --port COM5 summary

Check the JTAG_SEL_ENABLE 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 IO10 to GND when resetting the board.

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

ESPC3 JTAG Connections

 

Specific Probe Wiring Diagrams

TODO: Jlink Wiring Diagram

TODO: ESP-PROG Wiring Diagram

TODO: FT2232H Dual 

TODO: FT2232 Mini Module

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
    # Most stable OpenOCD Version for newer ESP32 Boards 
    tools.openocd.debug.path={runtime.tools.openocd-esp32-0.10.1-2021.07.21.path}
    # Very Latest OpenOCD (seems less stable than the above)
    # tools.openocd.debug.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

 

There is also a video guide on this below: