PyAvrOCD installation & configuration

Both, installation and configuration of PyAvrOCD are straightforward.

Installation

A note for Linux users

Note that Linux users may need to add a few udev rules after having installed PyAvrOCD. This can be accomplished by invoking PyAvrOCD once as root with the option --install-udev-rules (assuming that pyavrocd has been stored somewhere on the PATH):

> sudo pyavrocd --install-udev-rules

Alternatively, one can add the udev rules manually, following the instructions in the pyedbglib README.

Arduino IDE 2

If you want to use PyAvrOCD as part of Arduino IDE 2, you do not need to install it explicitly. It is sufficient to add an "additional boards manager URL" and install the respective core. It will then be installed as a tool for this core. As a Linux user, you may also need to set some permissions and provide udev rules as described above.

If you want to use PyAvrOCD stand-alone or as part of another IDE, you need to install the PyAvrOCD package explicitly, as described below.

Downloading binaries

Go to the GitHub page, select the latest release (located on the right-hand side of the page), download the archive containing the binary for your architecture, and then untar the archive. It includes the executable pyavrocd (or pyavrocd.exe), a folder pyavrocd-util, and additionally avr-gdb or (avr-gdb.exe), the GDB debugger for AVR chips. Store pyavrocd (or pyavrocd.exe) and pyavrocd-util somewhere in the same folder and include this folder in your PATH variable. The avr-gdb debugger has version 16.3, which is relatively recent, and has been compiled for your architecture with only a minimal amount of references to dynamic libraries. It is up to you to decide whether you want to use this version or the one that is already installed on your system.

Apple Users: On a Mac, files downloaded through a browser or from an email are marked as potentially dangerous, and the system may not allow them to be executed. In this case, use the command

xattr -d com.apple.quarantine FILE

in order to remove the extended attribute com.apple.quarantine from the binary executable FILE.

Since the binaries were generated on very recent versions of the respective operating systems (Windows 11, macOS 15.4, Ubuntu 24.04), it can happen that the binary is not compatible with your operating system. In this case, use one of the methods below.

PyPI

I assume you already installed a recent Python version (>=3.10).

It is possible to install PyAvrOCD using pip. However, it is recommended to use pipx instead. Pipx installs packages in a way such that they are entirely isolated from the rest of your Python installation and can be invoked as an ordinary binary executable. So, if you haven't done so already, install pipx following the instructions on the pipx website. Then proceed as follows.

> pipx install pyavrocd
> pipx ensurepath

After restarting the shell, you should be able to start the GDB server. The binary is stored under ~/.local/bin/.

GitHub

Alternatively, you can download or clone the GitHub repository. Additionally, you need to install the Python package manager Poetry:

> pipx install poetry

With that, you can start executing the script inside the downloaded folder as follows:

> poetry install
> poetry run pyavrocd ...

Furthermore, you can create a binary standalone package as follows:

> poetry run pyinstaller pyavrocd.spec

As a result, you find an executable pyavrocd (or pyavrocd.exe) in the directory dist/pyavrocd/ together with the folder pyavrocd-util. You can copy those to a place in your PATH.

Configuration

It is not necessary to set up any configuration file before you can use PyAvrOCD.

However, sometimes, it may be convenient to store some options in a file so that you do not have to type them every time you invoke PyAvrOCD. Or, you may want to override options that are set in an IDE. For this purpose, the @ notation is very helpful. If you place the string @file.ext on the command line, then arguments are read from file.ext and spliced into the command line. These arguments are read line by line.

Let us assume, file.ext contains the following lines:

--manage
eesave
--prog=3000
--to
atmelice
--veri=e

When you now invoke PyAvrOCD with pyavrocd -d attiny13 -t dwlink @file.ext, then this is expanded into

pyavrocd -d attiny13 -t dwlink --manage eesave --prog=3000 --to atmelice --veri=e

With the usual abbreviation rules, the fact that the equal sign can simply be substituted by space, and the rule that later arguments override earlier ones, this is equivalent to

pyavrocd --device attiny13 --manage eesave --prog-clock 3000 --tool atmelice --verify enable

Note that implicitly @pyavrocd.options is added to the end of the command line. This means that even if you cannot change the command line that invokes PyAvrOCD, because, e.g., PyAvrOCD is invoked by an IDE, you still can specify arguments that have precedence by using the configuration file pyavrocd.options.