How to debug an ESP8266 Arduino project with GDBStub

The ESP8266 has only supported the vMicro Software debugger, as it lacks support for JTAG.

Since the release of the 2.5.0 toolchain from Espressif, a GDB Stub has been added, allowing you to debug in a similar way to the Hardware debugging, without the hardware....

This can now be used out of the box in vMicro in a few simple steps, with no additional hardware

This is also available on Instructables and YouTube for the Uno - read the below page for differences.

Debugger Connections

Simply connect your ESP8266 to your PC via the USB>TTL adapter as normal

Software Setup

Ensure you have Visual Studio and the vMicro Extension Installed

Open your Sketch, and select the options from vMicro > Debugging as shown below:

NOTE - as the debugger uses the Serial interface of the ESP, you will have to remove all calls to Serial from your code. This can be done using a define as seen in the screenshot below.

You will need to add a couple of additions to your sketch (also in output window on debugger select), a skeleton example is below:

// Check we are using GDB Debugging and include the additional code
#ifdef VM_DEBUG_GDB
#include "GDBStub.h"
#endif

void setup(){
#ifdef VM_DEBUG_GDB
  gdbstub_init();
  // Add/extend the below delay if you want to debug the setup code
  // delay(3000);
#endif
}

void loop(){
}

1. Ensure you have the Debug Configuration selected from the Configuration Manager Window
2. Include the GDBStub.h file at the top of your sketch
3. Add the gdbstub_init() call to your setup()
4. If you know where you want the first breakpoint in your code, add it now
5. To start the debugging process, you can either:
   • "Debug > Attach to Process" button if your code has already been uploaded to the STM32 board
   • "Debug > Start Debugging" if your code has not been uploaded

 Tip:

If you want to jump into code at the start of setup(), add delay(3000); as the first line of code after gdbstub_init(); to allow the debugger to connect before your code begins executing.

Congratulations - you should have the debugger running, and further windows can be opened from the "Debug > Windows" menu once you have started debugging

See our GDB Debugging in Brief guide, or our detailed GDB Debugging Tutorial for Arduino to learn more about using the debugging interface.