Project tutorial
Arduino Uno Debugging

Arduino Uno Debugging © GPL3+

Try GDB debugging on your Arduino Uno without an external debugger, so you can solve those bugs and get your project released!

  • 5 respects

Components and supplies

Necessary tools and machines

09507 01
Soldering iron (generic)
Only IF needed for Breakout Board
Solder Wire, Lead Free
Only IF needed for Breakout Board

Apps and online services

About this project

When you can't quite figure out what is going on with your project at run time, Debugging Tools can save you a lot of headaches, but you have to find a hardware debugger first....

GDBStub allows us to use the GDB debugging system directly on our Arduino Uno board (or other AVR target), without having to purchase and wire up a Hardware Debugger.

The only downside is it consumes our Serial interface, so we will also connect SoftwareSerial so we can keep our custom Serial print commands, alongside hardware debugging.

Hardware Setup

Simply attach the USB lead to your Uno and your PC as normal.

If you don't need the additional Serial interface, you can skip the rest of this section.

Wire your Uno to your USB TTL Serial breakout board as shown below

(Rx/Tx can be changed in software so allocate to other pins if in use)

Software Setup

Open the project you wish to debug.

Then we can configure our Visual Micro IDE for debugging by selecting the options shown below:-

Installing the GDBStub Library

You can install the GDBStub library manually, or by using the Visual Micro Library Manager:

  • vMicro > Add Library > Download and Install Arduino Library > Manage Libraries Tab
  • Enter "gdb" as the Search term
  • For the Uno we can use the "avr-debugger by Jan Dolinay"
  • Left click to install the library (see more about libraries here)
  • Click the Rescan button at the top when the install has completed
  • Now close the Visual Micro Explorer

Adding the Code for GDBStub

To harness the GDBStub we will need to add a few lines of code:

  • Include the avr8-stub.h
  • Add debug_init() to your setup() routine
  • Add breakpoint() to the top of loop()

Updating the Code for Serial Issues

If you are not using the Serial Breakout then you can just comment out all Serial Code for now (wrap with a #define to make it easy to switch on and off).

NOTE - Visual Micro provides _DEBUG automatically if you enable the Project Setting ""Configuration Define _DEBUG" and set its value to 1. When you change to "Release" Configuration this code will deactivate.

To wrap all of your code to be compatible with SoftwareSerial and Serial we suggest you:-

  • Include the Software Serial Library from vMicro > Add Library > Current Platform
  • Add a #define for the Serial Object in use e.g. USE_SERIAL
  • Change all references from Serial to USE_SERIAL
  • Add the SoftwareSerial object with the Rx/Tx pins you wish to use

That's all that's needed, and you can switch back to Serial by changing the USE_SERIAL define now.

Setup Additional Serial Monitor

So we can view the additional SoftwareSerial port whilst debugging we will need to make it visible.

Open vMicro > General > Monitor Alternative, and select the USB Port for your TTL Serial Device, a new Serial Monitor Window should appear connected to this port, without changing your upload port.

Set a Breakpoint

Add a break point to your sketch by clicking in the left hand margin.

You can add more than one, and up to 4 at any one time.

Start Debugging

Ensure the correct COM port is set for upload.

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

Now you can debug in Visual Micro as normal on your Arduino Uno, without an external hardware debugger.

NOTE - you may need to re-open the alternative serial monitor again after debugging begins the first time. After this it will be remembered as part of your Visual Studio Window Layout.

The below Videos go through this process in two steps (1) GDBStub Setup, (2) Software Serial Setup (enable captions on these videos)

Part 1 - GDB Stub (Enable Subtitles / Captions)

Part 2 - Software Serial adaptations (Enable Subtitles / Captions)

AVR GDBStub in Visual Micro

ESP8266 GDBStub in Visual Micro

vMicro Debugging Walkthrough

Youtube Channel

Visual Micro Website


Main GDBStub Sketch Example used in this tutorial
#ifdef _DEBUG
#include <SoftwareSerial.h>
#include <avr8-stub.h>
#include <app_api.h>

	#define USE_SERIAL SWSerial
	SoftwareSerial SWSerial(2, 3);
	#define USE_SERIAL Serial

double currentSinVal = 0.0;
double currentCosVal = 0.0; 
int randomVal = 0;

void setup() {
#ifdef _DEBUG



void loop() {
#ifdef _DEBUG
	currentSinVal = getSinValue(millis());
	currentCosVal = getCosValue(millis());
	randomVal += random(0, 100);


Secondary code file used in examples
double getSinValue(unsigned long millis) {
	double newSin = 1+ sin(millis / 200);
	return newSin * 90;

double getCosValue(unsigned long millis) {
	double newCos = cos(millis / 200);
	return newCos * 90;


Uno to USB Serial Breakout Wiring
Shows how to wire a USB Serial converter to the Uno for this example.
Connections itscxviy4w


Similar projects you might like

Arduino Nano 33 IoT Debugging

Project tutorial by visualmicro

  • 12 respects

Arduino Nano 33 BLE/IoT Custom Debugging

Project tutorial by visualmicro

  • 4 respects

Control Arduino Uno Using ESP8266 WiFi Module and Blynk App

Project tutorial by Adithya TG

  • 46 respects

Multicolor Knight Rider with RGB PL9823 LED + Arduino UNO

Project tutorial by Giovanni Gentile

  • 16 respects

Simple Arduino Uno - ESP 8266 Integration

Project tutorial by team

  • 96 respects

Christmas Card PCB

Project tutorial by visualmicro

  • 2 respects
Add projectSign up / Login