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.4

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"
#include "app_api.h" // only needed with flash breakpoints

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.4

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.

Boards

Note

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

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