Installing & configuring the debugging software

The GDB server PyAvrOCD provides an interface to the hardware debug probe. In addition to that, you need an IDE, a debug GUI, or the stand-alone GDB client.

Arduino IDE 2

Arduino IDE 2 is probably the most straightforward option. After having installed it, you can extend the IDE's capabilities by adding third-party platforms in the Additional Board Manager URLs field of the Preferences dialog. The set of available debug-enabled cores and how to install them is covered in the section on Arduino cores.

PlatformIO and Visual Studio Code

PlatformIO is a cross-platform, cross-architecture, multiple framework professional tool for embedded systems engineers. Installed as an extension to the popular Visual Studio Code, it provides a powerful IDE for embedded programming and debugging. Using the platformio.ini file, integrating an external debugging framework is very easy.

[platformio]
default_envs = debug

[env:atmega328p]
platform = atmelavr
framework = arduino
board = ATmega328P
board_build.mcu = atmega328p
board_build.f_cpu = 16000000L
board_hardware.oscillator = external
build_unflags = -flto              ;; this makes sure we can watch the global vars

[env:debug]
extends = env:atmega328p          ;; <--- substitute the right board here
build_type = debug
debug_tool = custom
debug_server = /path/to/pyavrocd  ;; <-- specify path to gdbserver
    --port=3333
    --device=${this.board_build.mcu}
    --manage=all
debug_init_cmds =
    define pio_reset_halt_target
         monitor reset
    end
    define pio_reset_run_target
         monitor reset
         disconnect
    end
    target remote $DEBUG_PORT
    monitor debugwire enable
    $LOAD_CMDS
    $INIT_BREAK
debug_build_flags =
    -Og
    -ggdb3
    -DDEBUG
debug_svd_path = /path/to/svd-file ;; <-- specify path to SVD file

Recently, PyAvrOCD has been extended to deal with System View Description files, which enable the IDE to view and manipulate I/O registers in a very comfortable way. In order to use this feature, you need to download the set of SVD files from the latest release of PyAvrOCD and copy the appropriate SVD file to the PlatformIO project folder, or you can also access it in the pyavrocd-util folder, which is stored alongside pyavrocd. The SVD files are all stored in the directory pyavrocd-util/svd.

I noticed that the avr-gdb debugger in the PlatformIO toolchain is quite dated and does not start (e.g., under Ubuntu 24.04 and macOS 15.5). Simply replace it with a more recent version from your system or, better yet, use the version shipped with the PyAvrOCD binary, which contains some important patches. The location where PlatformIO stores its copy of avr-gdb is ~/.platformio/packages/toolchain-atmelavr/, where the tilde symbol signifies the home directory of the user.

Other IDEs

There are a few other possible options for IDEs. I believe it should be possible to integrate PyAvrOCD into CLion and Eclipse. How to integrate an AVR-GDB server into CLion is, for example, described here. Integration into Visual Studio Code and Eclipse Theia should be straightforward because one could make use of the Visual Studio Code extension cortex-debug that is also used in the Arduino IDE 2.

If you have a clear description of how to integrate PyAvrOCD in an IDE, I'd be happy to add it here.

A debug GUI: Gede

Gede is a lean and clean GUI for GDB. It can be built and run on almost all Linux distros, FreeBSD, and macOS. You need an AVR-GDB client with a version of 10.2 or higher. If you have installed Gede somewhere in your PATH, PyAvrOCD will start Gede in the background if you specify the option --start gede when invoking PyAvrOCD. Configuring Gede is done when you start the GUI.

CLI debugging

The most basic option is simply to install avr-gdb, the GDB debugger for AVR chips. You can use the version shipped with the PyAvrOCD binaries, which contains a few important patches for AVR MCUs.

It is not necessary to configure anything when you use avr-gdb. However, I find it very helpful to have the few commands in the global initialization file .gdbinit.

define hook-quit
    set confirm off
end
set history save on
set history size 10000
set history filename ~/.gdb_history
set logging overwrite 1

A software simulator: simavr

The software simulator simavr is included in the Arduino IDE 2 tools and in the binary package. If you have installed PyAvrOCD differently, you need to install the simulator first. While the package managers under macOS and Linux offer the stable version 1.7, this release unfortunately does not play well with PyAvrOCD. You can either download a binary from the latest Github Actions CI or you can build it from source.

make install DESTDIR=~/.local/

brew tap osx-cross/avr
brew install --HEAD simavr