Skip to content

Debugging with the ESP-IDF

2024-02-28

Debugging with the ESP-IDF Framework can be a bit of a struggle, since it's not just clicking a button, so this tutorial tries to bring some light into the darkness.

1. Installing and setting up the ESP-IDF Framework

1.1 Via the command line

You can install the ESP-IDF easily with some command line commands. It is very well documented in the official documentation.

1.2 Via Visual Studio Code

If you want to take the easy route or just don't feel comfortable with the command line, you can just get the ESP-IDF Extension for VS Code, which will install the extension and take you through the steps of installing the ESP-IDF. Just download VS Code, go to extensions, and download the ESP-IDF extension. This is the recommended way, since there is almost no way of doing it wrong. The VS Code extension also let's you easily upload and configure your projects.

2. Prerequisites

From JTAG Debugging from the official ESP-IDF documentation.

After running the export.sh script, located in the esp-idf github folder, your terminal is set up to run the esp-idf tools.

Note: On Linux, you need to execute the export.sh script on every new terminal you want to use the esp-idf on. On Windows, the ESP-IDF Tools Installer creates an "ESP-IDF Command Prompt" shortcut in the Start Menu. This shortcut opens the Command Prompt and sets up all the required environment variables.

2.1 Flash the ESP32

Before you debug, you have to upload your project to the ESP32. There are 2 ways to do that.

With idf.py via UART

If you flash your ESP via UART, you just have to connect the UART port to your computer. On development boards that is usually a USB connector, since those boards usually have a USB to UART bridge controller already installed.

idf.py -p /dev/ttyUSB1 flash

Note: flash automatically also builds your project.

Note: The argument after -p is the port your ESP is connected to. On Linus it has a /dev/* and on windows it looks something like COM*

With OpenOCD via JTAG

If you wan to flash your ESP via JTAG, you have to connect it to a debugger, and the debugger to your computer.

openocd -f board/esp32-wrover-kit-3.3v.cfg -c "program_esp filename.bin 0x10000 verify exit"

The program_esp command has the following format:

program_esp <image_file> <offset> [verify] [reset] [exit]
  • image_file - Path to program image file.
  • offset - Offset in flash bank to write image.
  • verify - Optional. Verify flash contents after writing.
  • reset - Optional. Reset target after programming.
  • exit - Optional. Exit OpenOCD after command has run.

2.2 OpenOCD

After you connected your OpenOCD compatible debugger, start OpenOCD with this command, in a terminal with the environment variables set:

openocd -f board/esp32-wrover-kit-3.3v.cfg

Note: The argument after -f is board specific, in this case for ESP-WROVER-KIT with ESP32-WROOM-32 module. You may need to specify another file depending on your hardware. For more info, see Configuration of OpenOCD for specific target.

After you started OpenOCD, open another terminal where the environment variables are set (Referred to as an esp-idf terminal from now on) and switch to your project folder, if not already done.

3. Debugging with ESP-IDF

From Using Debugger from the official ESP-IDF documentation.

3.1 Initialization

Before you can launch the debugger, you will need to provide couple of configuration parameters and commands. Instead of entering them one by one in command line, create a configuration file and name it gdbinit:

target remote :3333
set remote hardware-watchpoint-limit 2
mon reset halt
flushregs
thb app_main
c

Save this file in the project directory.

For more details about the gdbinit file, see What is the meaning of debugger’s startup commands?

3.2 Debugging

Now that OpenOCD is running in another terminal, and we set up the gdbinit file, we can start the debugger.

xtensa-esp32-elf-gdb -x gdbinit build/blink.elf

Note: If the command isn't found, make sure you are in a esp-idf terminal, where the environment variables are set.

blink.elf is the program file compiled by the ESP-IDF. Look in the build folder in your project directory what name your .elf file has, if you're not sure.

GDB will start up, stop at the beginning of the main function, and you are ready to debug.

TUI mode

In the gdb terminal, you can activate the TUI (Terminal User Interface) mode by pressing CTRL+x CTRL+a or by typing TUI enable, or TUI disable respectively.