avr-stub

avr-stub is a source level debugger based on GDB stub mechanism. It works with ATmega328 and Arduino Mega microcontrollers without an external programmer. The official reference can be found here.

Configuration

In a nutshell, avr-stub is a piece of software (stub) that is added to your application and communicates with PlatformIO when a debug session is running. It requires several additional configuration steps in order to use it as a debug tool. To use avr-stub, the following settings in “platformio.ini” (Project Configuration File):

[env:myenv]
platform = atmelavr
board = ...

debug_tool = avr-stub
debug_port = SERIAL_PORT

; GDB stub implementation
lib_deps =
    jdolinay/avr-debugger @ ~1.1

Where the value in debug_port is a serial port connected to your board and jdolinay/avr-debugger is a special library that implements the GDB stub.

In order to enable the GDB stub in your application, a call to the special function debug_init must be added at the beginning of your application. For example, with the Arduino framework it might look like this:

#include "Arduino.h"
#include "avr8-stub.h"

void setup()
{
  // initialize GDB stub
  debug_init();
  pinMode(LED_BUILTIN, OUTPUT);
}

void loop()
{
  digitalWrite(LED_BUILTIN, HIGH);
  delay(1000);
  digitalWrite(LED_BUILTIN, LOW);
  delay(1000);
}

Warning

If your program doesn’t stop on a breakpoint, try specifying an explicit breakpoint directly in the code using the breakpoint function:

...

void loop()
{
  breakpoint();
  digitalWrite(LED_BUILTIN, HIGH);
  delay(300);
  digitalWrite(LED_BUILTIN, LOW);
  delay(100);
}

...

Breakpoint modes

The avr-stub tool supports the following three breakpoint modes:

Description AVR8_BREAKPOINT_MODE
FLASH breakpoint mode, which works only with atmega328 based boards and requires a special bootloader 0
RAM breakpoint mode, the default mode which works out of the box with all atmega328, atmega1280, and atmega2560 based boards 1
FLASH breakpoint mode through Optiboot, which works with all atmega328, atmega1280, and atmega2560 based boards and requires the version 8 of the bootloader. 2

To switch between modes, specify a special macro definition AVR8_BREAKPOINT_MODE with the appropriate value from the table above, for example:

[env:myenv]
platform = atmelavr
board = uno

; Set breakpoint mode
build_flags =
  -DAVR8_BREAKPOINT_MODE=2

debug_tool = avr-stub
debug_port = SERIAL_PORT

lib_deps =
    jdolinay/avr-debugger @ ~1.1

Debugger limitations

  • One external interrupt pin must be reserved for the debugger.
  • Any part of your application that uses the UART module (e.g. Arduino Serial class) cannot be used in your program together with the debugger.
  • When using flash breakpoints the watchdog cannot be used.

More detailed information can be found in the Important limitations of the debugger section in the official documentation.

Platforms

Name Description
Atmel AVR Atmel AVR 8-bit MCUs deliver a unique combination of performance, power efficiency and design flexibility. Optimized to speed time to market-and easily adapt to new ones-they are based on the industry’s most code-efficient architecture for C and assembly programming

Frameworks

Name Description
Arduino Arduino Wiring-based Framework allows writing cross-platform software to control devices attached to a wide range of Arduino boards to create all kinds of creative coding, interactive objects, spaces or physical experiences
Simba Simba is an RTOS and build framework with aims to make embedded programming easy and portable

Boards

Note

For more detailed board information please scroll tables below by horizontal.

Name Platform Debug MCU Frequency Flash RAM
ATmega1280 Atmel AVR On-board ATMEGA1280 16MHz 127KB 8KB
ATmega2560 Atmel AVR On-board ATMEGA2560 16MHz 255KB 8KB
ATmega328 Atmel AVR On-board ATMEGA328 16MHz 31.50KB 2KB
ATmega328P/PA Atmel AVR On-board ATMEGA328P 16MHz 31.50KB 2KB
Adafruit Feather 328P Atmel AVR On-board ATMEGA328P 8MHz 31.50KB 2KB
Adafruit Metro Atmel AVR On-board ATMEGA328P 16MHz 31.50KB 2KB
Adafruit Pro Trinket 3V/12MHz (FTDI) Atmel AVR On-board ATMEGA328P 12MHz 28KB 2KB
Adafruit Pro Trinket 5V/16MHz (FTDI) Atmel AVR On-board ATMEGA328P 16MHz 28KB 2KB
Alorium Hinj Atmel AVR On-board ATMEGA328P 16MHz 31.50KB 2KB
Alorium Sno Atmel AVR On-board ATMEGA328P 16MHz 31.50KB 2KB
Alorium XLR8 Atmel AVR On-board ATMEGA328P 16MHz 31.50KB 2KB
Anarduino MiniWireless Atmel AVR On-board ATMEGA328P 16MHz 31.50KB 2KB
Arduino BT ATmega328 Atmel AVR On-board ATMEGA328P 16MHz 28KB 2KB
Arduino Duemilanove or Diecimila ATmega328 Atmel AVR On-board ATMEGA328P 16MHz 30KB 2KB
Arduino Ethernet Atmel AVR On-board ATMEGA328P 16MHz 31.50KB 2KB
Arduino Fio Atmel AVR On-board ATMEGA328P 8MHz 30KB 2KB
Arduino LilyPad ATmega328 Atmel AVR On-board ATMEGA328P 8MHz 30KB 2KB
Arduino Mega ADK Atmel AVR On-board ATMEGA2560 16MHz 248KB 8KB
Arduino Mega or Mega 2560 ATmega1280 Atmel AVR On-board ATMEGA1280 16MHz 124KB 8KB
Arduino Mega or Mega 2560 ATmega2560 (Mega 2560) Atmel AVR On-board ATMEGA2560 16MHz 248KB 8KB
Arduino Mini ATmega328 Atmel AVR On-board ATMEGA328P 16MHz 28KB 2KB
Arduino Nano ATmega328 Atmel AVR On-board ATMEGA328P 16MHz 30KB 2KB
Arduino Nano ATmega328 (New Bootloader) Atmel AVR On-board ATMEGA328P 16MHz 30KB 2KB
Arduino Pro or Pro Mini ATmega328 (3.3V, 8 MHz) Atmel AVR On-board ATMEGA328P 8MHz 30KB 2KB
Arduino Pro or Pro Mini ATmega328 (5V, 16 MHz) Atmel AVR On-board ATMEGA328P 16MHz 30KB 2KB
Arduino Uno Atmel AVR On-board ATMEGA328P 16MHz 31.50KB 2KB
BQ ZUM BT-328 Atmel AVR On-board ATMEGA328P 16MHz 28KB 2KB
BitWizard Raspduino Atmel AVR On-board ATMEGA328P 16MHz 30KB 2KB
Controllino Maxi Atmel AVR On-board ATMEGA2560 16MHz 248KB 8KB
Controllino Maxi Automation Atmel AVR On-board ATMEGA2560 16MHz 248KB 8KB
Controllino Mega Atmel AVR On-board ATMEGA2560 16MHz 248KB 8KB
Controllino Mini Atmel AVR On-board ATMEGA328P 16MHz 31.50KB 2KB
FYSETC F6 V1.3 Atmel AVR On-board ATMEGA2560 16MHz 252KB 8KB
LightBlue Bean Atmel AVR On-board ATMEGA328P 8MHz 31.50KB 2KB
LightBlue Bean+ Atmel AVR On-board ATMEGA328P 16MHz 31.50KB 2KB
LowPowerLab MightyHat Atmel AVR On-board ATMEGA328P 16MHz 31KB 2KB
LowPowerLab Moteino Atmel AVR On-board ATMEGA328P 16MHz 31.50KB 2KB
LowPowerLab Moteino (8Mhz) Atmel AVR On-board ATMEGA328P 8MHz 31.50KB 2KB
Microduino Core (Atmega328P@16M,5V) Atmel AVR On-board ATMEGA328P 16MHz 31.50KB 2KB
Microduino Core (Atmega328P@8M,3.3V) Atmel AVR On-board ATMEGA328P 8MHz 31.50KB 2KB
OpenEnergyMonitor emonPi Atmel AVR On-board ATMEGA328P 16MHz 30KB 2KB
PanStamp AVR Atmel AVR On-board ATMEGA328P 8MHz 31.50KB 2KB
Prusa RAMBo Atmel AVR On-board ATMEGA2560 16MHz 252KB 8KB
RepRap RAMBo Atmel AVR On-board ATMEGA2560 16MHz 252KB 8KB
SODAQ Moja Atmel AVR On-board ATMEGA328P 8MHz 31.50KB 2KB
Seeeduino Atmel AVR On-board ATMEGA328P 16MHz 31.50KB 2KB
SparkFun Digital Sandbox Atmel AVR On-board ATMEGA328P 8MHz 31.50KB 2KB
SparkFun Mega Pro 3.3V/8MHz Atmel AVR On-board ATMEGA2560 8MHz 252KB 8KB
SparkFun Mega Pro 5V/16MHz Atmel AVR On-board ATMEGA2560 16MHz 248KB 8KB
SparkFun Mega Pro Mini 3.3V Atmel AVR On-board ATMEGA2560 8MHz 252KB 8KB
SparkFun MicroView Atmel AVR On-board ATMEGA328P 16MHz 31.50KB 2KB
SparkFun RedBoard Atmel AVR On-board ATMEGA328P 16MHz 31.50KB 2KB
SparkFun Serial 7-Segment Display Atmel AVR On-board ATMEGA328P 8MHz 31.50KB 2KB
SpellFoundry Sleepy Pi 2 Atmel AVR On-board ATMEGA328P 8MHz 30KB 2KB
Talk2 Whisper Node Atmel AVR On-board ATMEGA328P 16MHz 31.50KB 2KB
TinyCircuits TinyDuino Processor Board Atmel AVR On-board ATMEGA328P 8MHz 30KB 2KB
TinyCircuits TinyLily Mini Processor Atmel AVR On-board ATMEGA328P 8MHz 30KB 2KB
ubIQio Ardhat Atmel AVR On-board ATMEGA328P 16MHz 31.50KB 2KB