Installing & configuring the debugging software

The GDB server PyAvrOCD provides an interface to the debug probe on one side and to the symbolic debugger on the host on the other side. That means that in addition to PyAvrOCD, you need to install a symbolic debugger, which in our case means avr-gdb. However, perhaps you want more than that.

Below, we will cover a number of cases ranging from CLI to IDEs. Installation of the software is usually straightforward when you follow the instructions on the respective webpages, where you can download the software. A bit more space is dedicated to configuring the software.

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 or the version already installed on your system. If avr-gdb is not installed, use your preferred package manager on Linux, Homebrew on macOS, or download a version from Zak's avr-gcc-build repository. This is particularly useful when you want to run debugging software on a 32-bit system.

It is not necessary to configure anything when you use avr-gdb. However, I find it very helpful to have the following commands in the global initialization file .gdbinit, which has to be stored in the user directory:

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

If you are not a fan of a command-line interface, then an integrated development environment (IDE) or a simple graphical user interface (GUI) for avr-gdb is called for.

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. This is done by adding additional Board Manager URLs in the preferences dialog, installing a platform, and selecting a board in the Board Manager. For example, adding the following Board Manager URLs enables debugging of the ATtiny MCUs and all Arduino AVR Boards:

https://felias-fogg.github.io/package_debugging_index.json

After that, you must install the respective platform(s):

  • Arduino AVR Boards (Debug enabled)
  • ATTinyCore (Debug enabled), and/or
  • Atmel AVR Xplained-minis (Debug enabled).

You can then choose from all the classic Arduino AVR Boards and the ATtinys. And this is all! Now, you can press the debug button and start debugging. Well, before you can do that, you must probably modify the target board, and you need to connect the debug probe to the target board, except for the last platform. The Xplained Mini boards already contain a debugger/programmer. So, you simply connect the board to a host, and can start uploading and debugging.

There will be more Board Manager URLs in the future that will extend the range of debuggable MCUs. In particular, the cores by MCUdude covering all ATmegaX8s and all classic JTAG mega chips will have a debug option.

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. If you want to debug a program on an ATmega328P, the platformio.ini file could look as follows (see also the examples folder)

[platformio]
default_envs = debug

[env:atmega328p]
platform = atmelavr
framework = arduino
board = ATmega328P
board_build.f_cpu = 16000000L
board_hardware.oscillator = external

[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=${env:debug.board}
debug_init_cmds =
    define pio_reset_halt_target
         monitor reset
    end
    define pio_reset_run_target
         monitor reset
         continue
    end
    target remote $DEBUG_PORT
    monitor debugwire enable
    $LOAD_CMDS
    $INIT_BREAK
debug_build_flags =
    -Og
    -ggdb3

Note that the debug environment should be the default one. It should be the first if no default environment has been declared.

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 copy the right SVD file from the SVD folder of the GitHub repo to the PlatformIO project folder. In addition, the following entry needs to be added to the platformio.ini file (using again the example of the ATmega328P):

debug_svd_path = atmega328p.svd

Instead of copying the SVD file into your project folder, you can also access it in the pyavrocd-util folder. 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 use the version shipped with the PyAvrOCD binary. 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.

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.

Other options

There are a few other possible options. The most crucial point is that remote debugging and the specification of alternative debuggers are supported. 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.