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 | 128KB | 8KB |
| ATmega2560 | Atmel AVR | On-board | ATMEGA2560 | 16MHz | 256KB | 8KB |
| ATmega328 | Atmel AVR | On-board | ATMEGA328 | 16MHz | 32KB | 2KB |
| ATmega328P/PA | Atmel AVR | On-board | ATMEGA328P | 16MHz | 32KB | 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 |