How to debug an ESP8266 Arduino project with GDBStub

× Not what you are looking for? Did you want USB/WiFi debug, trace and performance monitoring instead?

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:

ESP8266 Debug Toolbar Settings


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):

  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

Note Icon 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.

ESP8266 Debugging in vMicro and Visual Studio

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