How to debug an AVR Arduino project with GDB Stub?

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 https://github.com/jdolinay/avr_debug)

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

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:

// Include the additional code for GDB Debugging
#include "avr8-stub.h"

void setup(){
  debug_init();
}

void loop(){
  breakpoint();
}

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

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.

 AVR Core 1.8.3:

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