How to debug an AVR Arduino project with GDB Stub?

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

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

A number of GDB Stubs have been created by others, 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, and an external Library of your choice

NOTE - vMicro only starts GDB, so alternative GDB Stubs can be used, the below is just an example. Depending on which stub library you choose will vary the boards supported.


This is also available on Instructables and YouTube, and on the Arduino project Hub

Debugger Connections

Simply connect your AVR to your PC via the USB cable as normal

Software Setup

Ensure you have Visual Studio and the vMicro Extension Installed

Ensure you have your GDBStub library installed (e.g. an example is

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

Arduino Uno Debug Toolbar Settings


NOTE - as the debugger uses the Serial interface of the AVR, 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
#include "avr8-stub.h"

void setup(){

void loop(){
  1. Ensure you have the Debug Configuration selected from the Configuration Manager Window
  2. Review the examples in your library for code additions:
  3. Include the relevant stub.h file at the top of your sketch [from the library above "avr8-stub.h"]
  4. Add the relevant init() call to your setup() [from the library above debug_init()]
  5. Add any other calls required [from the library above add breakpoint() at top of loop()]
  6. If you know where you want the first breakpoint in your code, add it now
  7. To start the debugging process, you can either:
    • "Debug > Attach to Process" button if your code has already been uploaded to the board
    • "Debug > Start Debugging" if your code has not been uploaded
AVR 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

Note Icon AVR Core 1.8.3:

If you get an error starting the Debugger stating "Unable to start debugging. The value of miDebuggerPath is invalid", follow the work around below:

  1. Install v1.8.6 of "Arduino megaAVR Boards" from the Micro Explorer window this will add the toolset, and press ReScan when installation has completed.
  2. Then if you right click on the project > Add > Local Board.txt
  3. And add the below entry to the file, and change the MyUsername to match your setup:
  4. tools.gdbstub.path=C:\Users\MyUsername\AppData\Local\Arduino15\packages\arduino\tools\avr-gcc\7.3.0-atmel3.6.1-arduino5/bin
  5. Save the file, and try Attaching the Debugger again, it should now work as expected.

(v1.8.3 of the AVR Core is supplied without the GDB.exe needed)

There is also a video guide for setting up the debugger below: