ESP32 - DEBUGGING your ESP-IDF code using JTAG [VS CODE]

Introduction

This tutorial will guide you through the process of debugging your ESP32 IDF application using JTAG in Visual Studio Code. By using an external debugger like the ESP-PROG, you can effectively identify and solve issues in your code, enhancing your development skills and productivity.

Step 1: Set Up Your Environment

Before you begin debugging, ensure that you have the necessary hardware and software set up.

Requirements

• Hardware: ESP-PROG or a compatible JTAG debugger (FT2232H).
• Software:
  • Visual Studio Code
  • ESP-IDF (Espressif IoT Development Framework)
  • OpenOCD (Open On-Chip Debugger)

Practical Tips

• Ensure your ESP32 board is compatible with the JTAG debugger you choose.
• Check for the latest versions of all software tools.

Step 2: Connect the Hardware

Properly connect your ESP-PROG to your ESP32 board.

Connection Steps

1. Connect the ESP-PROG to your computer via USB.
2. Use jumper wires to connect the ESP-PROG to the ESP32 board:
   • TMS to TMS
   • TCK to TCK
   • TDI to TDI
   • TDO to TDO
   • GND to GND

Common Pitfalls

• Ensure all connections are secure to avoid communication issues.
• Double-check wiring against the ESP-PROG documentation.

Step 3: Update JTAG Drivers

Make sure your system has the latest drivers for the JTAG debugger.

Driver Update Process

1. Visit the manufacturer’s website for the latest driver.
2. Download and install the driver on your system.
3. Restart your computer to apply the changes.

Step 4: Install and Configure OpenOCD

OpenOCD is essential for communicating with the ESP32 through JTAG.

Installation Steps

• Install OpenOCD via your package manager or download it from the official website.

Configuration Steps

1. Create a configuration file for your debugger, typically named openocd.cfg.
2. Include the following lines:

   interface ft2232
   ft2232_device_desc "FT2232D"
   ft2232_layout "jtagkey"
   ft2232_vid_pid 0x0403 0x6015
   

3. Save the configuration file in your project directory.

Step 5: Set Up GDB

GDB (GNU Debugger) is essential for debugging your application.

Setup Steps

1. Open Visual Studio Code.
2. Install the C/C++ extension from Microsoft.
3. Configure your launch.json file for GDB:

   {
     "version": "0.2.0",
     "configurations": [
       {
         "name": "ESP32 Debug",
         "type": "cppdbg",
         "request": "launch",
         "program": "${workspaceFolder}/build/your_project.elf",
         "cwd": "${workspaceFolder}",
         "executable": "${workspaceFolder}/build/your_project.elf",
         "setupCommands": [
           {
             "text": "target remote localhost:3333",
             "description": "Connect to the target"
           }
         ],
         "stopAtEntry": false,
         "miDebuggerPath": "path/to/xtensa-esp32-elf-gdb"
       }
     ]
   }
   

Practical Advice

• Replace your_project.elf with the actual name of your ELF file.
• Ensure the path to xtensa-esp32-elf-gdb is correct.

Step 6: Test the Debugger

Run a quick test to ensure everything is functioning correctly.

Testing Steps

1. Open a terminal and run OpenOCD:

   openocd -f interface/ftdi/esp32.cfg -f target/esp32.cfg
   

2. In another terminal, launch GDB with your ELF file:

   xtensa-esp32-elf-gdb build/your_project.elf
   

3. Issue the command target remote localhost:3333 in GDB.

Important Notes

• If you encounter connection issues, verify your OpenOCD configuration.
• Ensure no other processes are using the same port.

Step 7: Automate OpenOCD

To streamline your workflow, automate the OpenOCD launch process.

Automation Steps

1. Create a script to start OpenOCD and GDB together.
2. Use the following code in your script:

   #!/bin/bash
   openocd -f interface/ftdi/esp32.cfg -f target/esp32.cfg &
   sleep 2
   xtensa-esp32-elf-gdb build/your_project.elf -ex "target remote localhost:3333"
   

Step 8: Debugging Your Code

Now you can start debugging your application.

Debugging Steps

1. Set breakpoints in your code within Visual Studio Code.
2. Use GDB commands to step through your code:
   • break function_name to set a breakpoint.
   • continue to run the program until the next breakpoint.
   • step to execute the next line of code.

Bug Identification

• Analyze output and variable states to identify issues.
• Use the print command in GDB to inspect variables.

Conclusion

In this tutorial, you learned how to set up and use JTAG debugging for your ESP32 applications in Visual Studio Code. By following these steps, you can effectively troubleshoot your code, enhance your programming skills, and improve your development workflow. For further learning, explore advanced GDB commands and debugging techniques to deepen your understanding.