PyAvrOCD installation & configuration

Both the installation and configuration of PyAvrOCD are straightforward on Windows, macOS, and Linux machines (see supported platforms). Mac and Linux users should be aware of some idiosyncrasies, however.

Installation

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. Together with PyAvrOCD, you will also get the GDB client avr-gdb and the simulator (for some AVR chips) simavr.

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, click on the label Latest below the section title Releases (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 folder tools, which in turn contains the executable pyavrocd (or pyavrocd.exe), a folder pyavrocd-util, avr-gdb (or avr-gdb.exe), the GDB debugger for AVR chips, and additionally simavr (or simavr.exe), a software simulator of some of the AVR chips.

Store all of it somewhere in the same folder and preferably include this folder in your PATH variable. My preference for such a folder is ~/.local/bin , which will be used throughout this document. So, in order to store everything there, use the following shell commands (PowerShell on Windows):

mv tools/* ~/.local/bin

The avr-gdb debugger has version 17.1, which is relatively recent, and has been compiled for your architecture with only a minimal amount of references to dynamic libraries. It is strongly advised to use this version since it contains a few patches.

Since the binaries were generated on very recent versions of the respective operating systems, 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). Then PyPI will bring you the most recent version of PyAvrOCD to your computer.

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

Note that the folder with SVD files is not part of the PyPI installation. If you want to use SVD files, they have to be downloaded separately from the release page of the GitHub repo. The release asset is called svd.tar.gz.

GitHub

Alternatively, you can download or clone the GitHub repository. Additionally, you need to install a Python package manager, for instance, 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 two 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.

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