Introduction to Zephyr Part 7: Debugging with OpenOCD and GDB | DigiKey

Debugging embedded systems can be challenging, but it's essential for identifying and resolving issues in both software and hardware. In this tutorial, we demonstrate how to debug an ESP32 running the Zephyr RTOS using OpenOCD and GDB. OpenOCD acts as the interface between your ESP32's JTAG hardware and debugging tools, while GDB provides a powerful command-line interface for stepping through code, inspecting variables, and analyzing system behavior. This guide walks you through the setup and use of these tools to streamline your debugging workflow. You can find a written version of this tutorial here: https://www.digikey.com/en/maker/tutorials/2025/introduction-to-zephyr-part-7-debugging-with-openocd-and-gdb The GitHub repository for this course (including solutions to the challenges) can be found here: https://github.com/ShawnHymel/introduction-to-zephyr/tree/main The hardware setup leverages the ESP32-S3-DevKitC, which features a built-in hardware debugger connected via USB for JTAG debugging. The tutorial also explains how to configure your host computer to communicate with the board, including tips for Windows users who may need to install USB drivers using Zadig. On the software side, we cover installing OpenOCD, ensuring you have the right version with ESP32 support, and running it to connect to the debugging hardware. Using the blink demo from the first episode, we demonstrate how to compile and flash the firmware to the ESP32. Although GDB and OpenOCD can flash binaries directly, the tutorial explains why flashing via the host computer is more practical when working within a containerized development environment. This ensures you can efficiently load and debug your applications without unnecessary complications. GDB is a robust debugging tool that lets you set breakpoints, inspect memory, and step through code interactively. We explain how to launch GDB in the Docker container, connect it to OpenOCD, and use essential commands like break, step, and print for real-time debugging. For those using VS Code, the tutorial also details how to configure launch.json to enable a graphical debugging experience, making it easier to visualize variable values and control execution flow. With the proper launch.json configuration, debugging becomes even more intuitive using VS Code's graphical interface. We show how to connect to the debugger, set breakpoints, and use interactive features to analyze your program's execution. This section highlights the powerful integration between GDB, OpenOCD, and VS Code, making it easier for developers to troubleshoot their Zephyr-based ESP32 applications. Official Zephyr documentation: https://docs.zephyrproject.org/latest/index.html Introduction to RTOS: https://www.youtube.com/watch?v=F321087yYy4&list=PLEBQazB0HUyQ4hAPU1cJED6t3DU0h34bz ESP32-S3-DevKitC: https://www.digikey.com/en/products/detail/espressif-systems/ESP32-S3-DEVKITC-1-N32R8V/15970965 Maker.io - https://www.digikey.com/en/maker DigiKey’s Blog – TheCircuit https://www.digikey.com/en/blog Connect with DigiKey on Facebook https://www.facebook.com/digikey.electronics/ And follow us on X: https://x.com/digikey 0:00 Intro 0:53 OpenOCD and GDB Overview 4:09 Installing and Running OpenOCD Server 11:27 Running GDB in a Docker Container 14:47 GDB Basic Commands for Debugging 26:58 Connecting GDB to VS Code 29:21 Debugging with VS Code 33:09 Challenge: Printing from USB Port 34:14 Conclusion