Introducing esp-gdbstub: debug your ESP8266 code over the serial port using GDB

[ESP_Sprite]

While programming for the ESP8266 is easy, with many available options provided both by Espressif and the awesome community of people centered around our chip, support for actually debugging applications has been somewhat lacking, limited mostly to inserting printf statements in critical places.

In order to remedy this, Espressif has developed a so-called GDB stub. This GDB stub is a bit of code you can link into your program. It then allows attaching GDB or another compatible debugger to the serial port the ESP8266 is connected to. GDB then will allow you to set breakpoints, read and write variables, break on memory access etcetera.

The GDB stub we present here is open-source (licensed under the Espressif MIT license) and pretty capable. It can run under the non-OS or the FreeRTOS stack, supports interrupting execution using Ctrl-C, supports exception catching, can make use of the hardware debugging features the ESP8266 Xtensa core has and has configurable options like the redirection of printf to GDB and switching to a private stack on invocation.

Apart from using the standard, command line based GDB, it's also possible to use a GUI to debug your ESP8266 applications. Specifically, we've been co-operating with Sysprogs, and their VisualGDB product fully supports esp-gdbstub, as you can see in the tutorial they wrote.

You can download esp-gdbstub by cloning the repository on Espressifs Github page. We hope esp-gdbstub provides a useful tool that makes programming for the ESP8266 a bit easier. If you have any remarks, bugs to report, patches or feature requests, please don't hesitate to report them on Github.