The USC Andrew and Erna Viterbi School of Engineering USC Ming Hsieh Department of Electrical Engineering University of Southern California

EE 459Lx - Embedded System Design Laboratory

AVR Toolchain for Linux

by
Allan Weber

USC Dept. of Electrical and Computer Engineering
Last edited: February 10, 2023

This web page describes a way to install a working AVR 64-bit toolchain ("avr-gcc") based on using the Arduino IDE software. The Arduino IDE is normally used with a graphical user interface (GUI) to write programs in the Arduino style, but all the avr-gcc command line programs are inside the IDE, and with a little work you can run them from the command line. Since Arduino appears to be periodically releasing new versions of their IDE, and this includes updated versions of the AVR toolchain, you can take advantage of this and use the toolchain software from within the Arduino IDE from the command line.

If you don't want to go through these steps to make use of the IDE's programs, there is a simpler way to do it, but the avr-gcc software that ends up being installed is quite a bit older than what Ardiuno provides and there may be issues related to that. Scroll to the bottom of this page, or click here to see these instructios.

Important: The information below assumes you are at least moderately familiar with using the command line interface, and with basic Unix-type commands for moving around the file system and doing simple operations. The program that runs in the command line program to accept typed commands and then does something is called the "shell" program. You can display the value of the "SHELL" variable to see what shell program you are using. For example,

    $ printenv SHELL
    /bin/bash

shows that the "bash" shell is being used. You need to know which shell program is being used since that affects some of the steps below.

Warning: Some of the steps below require administrator or "root" privileges. When using the command line this is done with the "sudo" command to run single command as the adminstrator. The first time the "sudo" is typed, the system will ask for your password, meaning the password you use to login to the system. Subsequent uses of "sudo" may not ask for the password if done shortly after the first one was done.

Step 1: Install the Arduino IDE

Download and install version 1.8.19 of the Arduino IDE. On the Arduino software web page, you will have to scroll down to find this listed as "Legacy IDE" but this is the one you want to get. Do not download any version that starts with "2" or says it's a "release candidate" or "hourly build" since these are configured differently and will not work with our setup.

The downloaded file may have a name like "arduino-1.8.19-linux64.tar.xz". The extracted files can be placed anywhere, but in this example we'll put them in the "/usr/local" directory. Assuming the downloaded file is in your home directory, do the following steps.

    $ unxz arduino-1.8.19-linux64.tar.xz
    $ cd /usr/local
    $ sudo tar xf ~/arduino-1.8.19-linux64.tar
    $ sudo ln -s arduino-1.8.19 arduino

This has installed the Arduino IDE files in /usr/local and they can be reached from the command line in /usr/local/arduino.

Step 2: Find the AVR Toolchain

Using the command line, you'll need to find the AVR toolchain that is inside the Arduino IDE. First use the "cd" command to go to /usr/local and then do another "cd" to get inside the Arduino IDE package. Assuming you installed it in /usr/local as described above do something like this.

    $ cd /usr/local/
    $ cd arduino

Now dig deeper into the directory struction to find the AVR toolchain.

    $ cd hardware/tools/avr

This was the path to it as of the time this web page was written but it may change so be prepared to hunt for it if the above paths are no longer correct.

Doing an "ls" at this point should show that you are in the AVR toolchain directory and "ls bin" will show the subdirectory with the compiler, linker, downloader, etc.

    $ ls
    avr  builtin_tools_versions.txt  include  libexec
    bin  etc                         lib      x86_64-pc-linux-gnu
    
    $ ls bin
    arduinoOTA     avr-cpp        avr-gcc-ar      avr-gprof    avr-objdump
    avr-addr2line  avrdude        avr-gcc-nm      avr-ld       avr-ranlib
    avr-ar         avr-elfedit    avr-gcc-ranlib  avr-ld.bfd   avr-readelf
    avr-as         avr-g++        avr-gcov        avr-man      avr-size
    avr-c++        avr-gcc        avr-gcov-dump   avr-nm       avr-strings
    avr-c++filt    avr-gcc-7.3.0  avr-gcov-tool   avr-objcopy  avr-strip

Now that you have found the AVR toolchain files, get the full path to the AVR toolchain with the "pwd -P".

    $ pwd -P
    /usr/local/arduino-1.8.19/hardware/tools/avr

Since you previously installed symbolic link so /usr/local/arduino-1.8.19 can be found using /usr/local/arduino, the actual path you will want to use is

    /usr/local/arduino/hardware/tools/avr

Make a note of the path since you will need that for the next step.

Step 3: Install Link to AVR Toolchain

Put a link to the above AVR toolchain directory someplace where you can add it to the executable search path. A recommended place is in the "/usr/local" directory. Move to the /usr/local directory and make a symbolic link using the path to the AVR toolchain that you copied above. In the example below we also create a "/usr/local/bin" directory since we'll need that later.

    $ cd /usr/local
    $ sudo ln -s arduino/hardware/tools/avr avr
    $ sudo mkdir bin
    $ cd $HOME

You now have a "/usr/local/avr" directory with the toolchain programs. The last command above ("cd $HOME") does a "cd" back to your home directory.

Step 4: Adjust PATH Variable

The environment variable "PATH" contains a list of directories (separated by colons - ":") that the system will search through when you tell it to execute a program. It starts by searching the first directory listed for the program, and goes down the list until if find the program in one of them and runs it. To make the Arduino avr-gcc toolchain work properly it's very important the the PATH variable be set properly. The default value of the PATH variable is set by the system, but often modified by user-written commands that get run when the shell starts up.

You will need to modify the executable search path to add a couple directories (/usr/local/bin and /usr/local/avr/bin) to the path. The easiest way to do this is to edit one of the shell start-up files in your home directory to add a command that adds the correct directories to the start of the search path. Unfortunately, the choice of which file to edit depends on the the shell your command line program is using, as found at the top of this web page from the SHELL variable.

Edit the file and add this line to it.

    export PATH=/usr/local/bin:/usr/local/avr/bin:$PATH

This adds the /usr/local/bin and /usr/local/avr/bin directories to the start of the executable search path. To make this take effect it is necessary to kill the current command line window and open up a new one. To confirm that the path is now correct you can print it out.

    $ printenv PATH
    /usr/local/bin:/usr/local/avr/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin

It should show /usr/local/bin as the first directory, and /usr/local/avr/bin after it. If the /usr/local/bin directory shows up twice like in the example above you can ignore this since it won't affect things.

Step 5: Install the "avrdude" Program

The "avrdude" program for downloading code to the AVR microcontroller that comes with the Arduino IDE works when used directly from a command line but it needs to be told where the "avrdude.conf" configuration file is located. The simplest fix for this is to create an "avrdude" shell script that invokes the Arduino IDE's "avrdude" program and supplies the path to the configuration file as an argument on the command line.

You can put this shell script anywhere but it needs to be in a directory in your search path that is ahead of the /usr/local/avr/bin directory where the real "avrdude" program is located. In step 3 above we created a "/usr/local/bin" directory, and in step 4 we put that directory ahead of the /usr/local/avr/bin directory in the PATH variable, so that would be the preferred place to put the script.

Use your text editor to create a file containing the three lines below, and then save it with the filename "avrdude".

    #!/bin/bash
    AVRDIR="/usr/local/avr"
    exec -a "$0" "$AVRDIR/bin/avrdude" "-C" "$AVRDIR/etc/avrdude.conf" "$@"

Once the file has been created, change the protection mode on the file so it's executable and move it to the /usr/local/bin directory.

    $ chmod +x avrdude
    $ sudo mv avrdude /usr/local/bin/

Once the above is done, when you run "avrdude", it will cause the three line "avrdude" file you created to execute the real "avrdude" program in the Arduino IDE and supply the correct arguments to it. Since it's not in the Arduino IDE software collection, it's not affected by updating to a newer Arduino IDE and should work with any newer version.

If you try typing the commmand avrdude at this point, it may display some lines about options available when invoking the program, or it may display an error messages about no programming device specified. In either case this shows the program is being executed and you can move to the next step.

Important: The above will only work if your PATH variable is such that the copy of avrdude you just created is found before the one in /usr/local/avr/bin. If you followed the instructions in step 4 above this should be the case. Otherwise you may have to make adjustments to the PATH, or put avrdude someplace else to make it all work.

Step 6: Install the "make" Program

Linux installations may already have the "make" program installed. You can check with the "which" command to find out if it's installed.

    $ which make
    /usr/bin/make

If the "which" command doesn't show an installed "make", you should install it with the command.

    $ sudo apt-get install make

Step 7 (Optional): Enable Arduino Downloading

If you want to use the avr-gcc software to download to an Arduino board rather than just to bare ATmega microcontrollers using one of the programming modules provided in the EE459 toolkit, the following step may be required.

The step below allows you to program an Arduino board as your normal user rather than doing it as "root" (generally a good idea). To do this you need to add yourself to the Linux group that controls the programming module when it's attached. The programming module is usually in the "dailout" group so you need to be added to that group.

    $  sudo usermod -a -G dialout your_username

where "your_username" is whatever username you use when logging in to the system.

Step 8: Test Installation

At this point all the command line operations for compiling and downloading AVR software should be working. You might have to kill and re-open the command line window you used to install the software for some of it to work but after that it should work normally. First use the "which" command to confirm which program execute when you type the command. It will print out the program that will execute and check to make sure they are the ones in either /usr/local/bin or /usr/local/avr/bin. You can skip the test for the "make" program if you didn't install a new one in the section above.

    $ which make
    /usr/bin/make

    $ which avr-gcc
    /usr/local/avr/bin/avr-gcc

    $ which avrdude
    /usr/local/bin/avrdude

Next, you should be able to test running each program and have it print out their version numbers.

    $ make --version
    GNU Make 4.2.1
    Built for x86_64-pc-linux-gnu

    $ avr-gcc --version
    avr-gcc (GCC) 7.3.0

    $ avrdude --help
    (this prints lots of stuff but at the end...)
    avrdude version 6.3-20190619, URL: ....

At this point the only thing left to do is to try compiling and downloading a program.

Using Linux Packages for avr-gcc Installation

This section describes another way to install the avr-gcc software that is easier to do, but seems to install a relatively older version of the programs.

The easiest way to install a working toolchain for doing command line compiling and downloading of programs to AVR microcontrollers appears to be by installing some package that are available in most Linux distributions.

For Debian and Ubuntu Linux the following packages need to be installed.

The installation can be done with the command

    sudo apt-get install gcc-avr binutils-avr gdb-avr avr-libc avrdude

This may also cause several other packages to be installed. Check to see if the "make" program is present on the system. If not also do "sudo apt-get install make" to install it.