Using AVR Microprocessors Under OS/X

Matt Wright, July 4, 2005

This document explains how to install Mac OS/X versions of avr-gcc, avr-libc, uisp, Pascal Stang's avrlib, and the other tools necessary to write programs and load (aka "flash") them onto AVR microprocessors. This is intended for people who have used these tools on the Planet CCRMA Linux environment (e.g., in the context of CCRMA's 250a class or Human-Computer Interaction summer workshop), but it may also be useful to others.

Contents

Easy install

At the end of the day you need to have about 58 Mb of compiler tools, libraries, and documentation in /usr/local/avr, and about another 2.4 Mb of Pascal Stang's avrlib ("AVR Library") in ~/avrlib. If you're lucky you can just download my versions, unpack them, put them in the right places, and be done with it.

  1. You need the gnumake program, and you also need a symbolic link to it called make. There are two options:
    1. Apple's developer tools include gnumake and much, much, much more. If you want to develop OSX applications you probably want these anyway. They have a fancy easy-to-use installer.
    2. Alternately, you could just download my copy of gnumake (63K), unstuff it, and install the resulting file like this:
      3. sudo mv gnumake /usr/bin
sudo ln -s /usr/bin/gnumake /usr/bin/make
  2. Download and un-stuff these files:
  3. The contents of avrlib.sit is a folder named avrlib - put this folder at the top level of your home directory.
  4. The contents of usr-local-avr.sit is a folder named avr - put this folder in your /usr/local directory. (You may first need to make yourself a /usr/local directory and maybe even a /usr directory.) You will probably need to do this as an administrator, like this:
    sudo mv avr /usr/local
  5. Add /usr/local/avr/bin to your Unix path, define the shell variable AVR to be /usr/local/avr and define the shell variable AVRLib to be ~/avrlib For example, if you use the tcsh shell, add these three lines to the file .cshrc in your home directory: 
    set path=($path /usr/local/avr/bin)
setenv AVR /usr/local/avr
setenv AVRLIB ~/avrlib

If you use the bash shell, add these six lines to the .bashrc file in your home directory:

    PATH=$PATH:/usr/local/avr/bin
    export PATH
AVR=/usr/local/avr
export AVR
AVRLIB=~/avrlib
export AVRLIB

Why those particular directories?

It's a good idea to put the AVR tools in /usr/local/avr because they're updated frequently, so it's nice to have them all in a single location. Plus, that makes it easier to install my versions from the Stuffit archives above.

It's a convention at CCRMA that avrlib lives in each user's home directory, so if you put avrlib in your OSX home directory, you have less to change when you copy over AVR projects from your CCRMA Linux account.

Medium-hard install

If you want to compile everything for yourself, here are the downloads I used:

These are the instructions I followed:

These websites are also helpful, with additional explanations, alternate suggestions, etc.:

Here are the Terminal commands I typed to get started on the compilation/installation process (as suggested by the nongnu.org link above):

sudo mkdir /usr/local/avr
bash
PREFIX=/usr/local/avr
export PREFIX
PATH=$PATH:$PREFIX/bin
export PATH

Hard install

If you're even more brave, you can go to http://www.nongnu.org/avr-libc/user-manual/install_tools.html and follow the links to the latest versions of binutils, gcc, avr-libc, and uisp. The versions listed above (namely, binutils-2.15, gcc-3.4.3, avr-libc-1.2.3, and uisp-20050207) were the most recent as of April 2005 when I downloaded and compiled everything, and they seem to be mutually-compatible as far as I can tell. But by all means, if you like to be on the bleeding edge and enjoy running configure scripts and building software, go got it. Please let me know [matt at CCRMA] of your experiences with this.

USB-to-Serial Converters

Modern Apple Macintosh computers do not come with serial ports, so you will have to use a USB-to-Serial adapter. I've personally had success with the Keyspan UPR-112 and the Keyspan USA-19 devices, and a lack of success with an unlabeled generic device known as "Prolific" or "BF". I've heard that in general these tools work only with Keyspan hardware; please let me know [matt at CCRMA] of your experiences with other hardware. If you're physically at CCRMA in spring of 2005, you're welcome to borrow one or both of my serial to USB devices.

All of these USB devices require drivers, which generally come on a CD when you buy the device, but are also available for download from the manufacturer's website (for example, http://www.keyspan.com/downloads/macosx).

Once you install the driver and plug in the USB device, it will appear as a Unix tty device. For example, my Keyspan US-19 appears as /dev/tty.USA19W1b1P1.1 and my Keyspan UPR-112 appears as /dev/tty.UPSH112I3b13P1.1

It's easy to look for these files with ls from a Terminal window:

ls /dev/tty.*

You'll need to add the name of this ersatz serial port to a makefile, for example, like this:

UISP_PORT=/dev/tty.UPSH112I3b13P1.1

Building CCRMA's Example Programs

CCRMA's example AVR programs rely on the following to compile and load:

CBI and SBI Macros

Many of CCRMA's example programs use macros including CBI and SBI to clear and set individual bits of I/O ports. These old macros are now no longer supported by avr-libc, so if you've got a recent enough version of avr-libc to not include those macros, make sure you have a recent enough version of Pascal Stang's avrlib (March 2005 or later) that does include them.

The silver lining is that the AVR toolchain now supports this programming style for reading and writing individual bits from I/O ports, which I personally prefer:

PORTA = 0x01;
PORTB |= 0x02;
PORTC &= ~0x04;
var = PIND;

Other Issues

LCD

The LCD implementation has changed, so CCRMA's old lcdconf.h files (which are in each project directory) need to be replaced with the one in avrlib/conf:

mv lcdconf.h lcdconf.h.old
cp ~/avrlib/conf/lcdconf.h .

Even so, the writing on the LCD will be garbled unless you set LCD_LINES and LCD_LINE_LENGTH to the actual number and length of the lines (in characters) on your LCD. For CCRMA's development boards, we use a 2x40 LCD, so your lcdconf.h should include these two lines:

#define LCD_LINES 2 // visible lines
#define LCD_LINE_LENGTH 40 // line length (in characters)

The new avrlib also includes a macro LCD_DELAY that represents enough NOP ("No Operation") instructions to cause the AVR processor to do nothing for long enough for a character to be written safely to the LCD. It's worked for me consistently with 12 nop instructions, like this: 

#define LCD_DELAY asm volatile ("nop\n nop\n nop\n nop\n " \
                                "nop\n nop\n nop\n nop\n " \
                                "nop\n nop\n nop\n nop\n");

Encoder

My version of avrlib/encoder.h includes an extra definition, of GIMSK, which is necessary to make CCRMA's encoder demos work:

#define GIMSK GICR // Kludge until Pascal fixes this in avrlib (MW 050524)

OpenSoundControl

For projects that use OpenSoundControl (to get data from the AVR over a serial port to Pd), the makefile has to include $(AVRLIB)/ccrma/OSC-client.c in the list of files in the SRC variable. Basically, anywhere you see

$(AVRLIB)/ccrma/osc.c

in a makefile, make it say

$(AVRLIB)/ccrma/osc.c $(AVRLIB)/ccrma/OSC-client.c

Where to go from here

To get the AVRmini to talk to Pd on your OSX machine via OSC over Serial over USB (!), see Jesse Fox's excellent instructions:

http://ccrma.stanford.edu/~jrobfox/OSC_PD_OSX.html

Somebody should replicate the functionality of the dumpOSCSerial object for Max/MSP.