Difference between revisions of "AVR"

From CCRMA Wiki
Jump to: navigation, search
(Mac OS X: The Easy Way)
 
(36 intermediate revisions by 3 users not shown)
Line 3: Line 3:
  
 
==AVR Hardware at CCRMA==
 
==AVR Hardware at CCRMA==
===ATMega32===
+
===ATMega644===
We currently use the ATMega 32 ([http://www.atmel.com/dyn/products/product_card.asp?part_id=2014 Product Page]). It features:
+
We currently use the ATMega 644 ([http://www.atmel.com/dyn/products/product_card.asp?part_id=3694 Product Page]). It features:
*32 Kbyte self-programming Flash Program Memory  
+
*64 Kbyte self-programming Flash Program Memory  
*2 Kbyte SRAM
+
*4 Kbyte SRAM
*1 Kbyte EEPROM  
+
*2 Kbyte EEPROM  
 
*8-Channel 10-bit A/D-converter  
 
*8-Channel 10-bit A/D-converter  
*Up to 16 Mhz clock
+
*Up to 20 Mhz clock
 
*I<sup>2</sup>C, SPI interfaces
 
*I<sup>2</sup>C, SPI interfaces
 
*1 USART, 2-channels PWM, 2 ext. interrupts
 
*1 USART, 2-channels PWM, 2 ext. interrupts
  
ATMega 32 Documentation:
+
ATMega 3644 Documentation:
*[http://www.atmel.com/dyn/resources/prod_documents/2503S.pdf ATmega32 Summary]
+
*[http://www.atmel.com/dyn/resources/prod_documents/2593S.pdf ATmega644 Summary]
*[http://www.atmel.com/dyn/resources/prod_documents/doc2503.pdf ATMega32 Complete Datasheet]
+
*[http://www.atmel.com/dyn/resources/prod_documents/doc2593.pdf ATMega644 Complete Datasheet]
  
 
=== AVRmini Development Board===
 
=== AVRmini Development Board===
Line 60: Line 60:
  
 
* global.h
 
* global.h
The global.h file is required by the [[#avrlib]]. In most cases, it simply defines the clock speed of the AVR microcontroller that you are using. The general philosophy of the [[avrlib]] is that the library should remain general-purpose, and able to support a range of projects for different microcontrollers and hardware without modification. So, since you may have different projects on your computer for different AVR devices at different clock speeds, there is a global.h in every project directory (rather than keeping a common one in the [[#avrlib]] directory).  
+
The global.h file is required by the [[#avrlib]]. In most cases, it simply defines the clock speed of the AVR microcontroller that you are using. The general philosophy of the [[#avrlib]] is that the library should remain general-purpose, and able to support a range of projects for different microcontrollers and hardware without modification. So, since you may have different projects on your computer for different AVR devices at different clock speeds, there is a global.h in every project directory (rather than keeping a common one in the [[#avrlib]] directory).  
  
 
* makefile
 
* makefile
Line 66: Line 66:
  
  
There is one other type of file that is present in some of the avrlib-demos directories that you may need in your projects. These are configuration files that contain settings for specific avrlib modules. For example, in the lcdtest directory, you will see a file called lcdconf.h. lcdconf.h contains settings relevant to the lcd display you are using, such as the number of lines and columns. As described above, you may have different projects using different lcd displays, so rather than change a global configuration file each time you compile your code, the avrlib requires that you put a different configuration file in each project directory.  
+
There is one other type of file that is present in some of the avrlib-demos directories that you may need in your projects. These are configuration files that contain settings for specific avrlib modules. For example, in the lcdtest directory, you will see a file called lcdconf.h. lcdconf.h contains settings relevant to the lcd display you are using, such as the number of lines and columns. As described above, you may have different projects using different lcd displays, so rather than change a global configuration file each time you compile your code, the avrlib requires that you put a different configuration file in each project directory.
  
 
====avr-gcc====
 
====avr-gcc====
 
avr-gcc is actual compiler that generates AVR byte code from the c files that you compile. We don't invoke avr-gcc directly, rather it is called from the makefile. At the end of a successful compilation, the compiler will generate a .hex file that must be loaded onto the microcontroller. See below for instructions on installing avr-gcc on your own computer.
 
avr-gcc is actual compiler that generates AVR byte code from the c files that you compile. We don't invoke avr-gcc directly, rather it is called from the makefile. At the end of a successful compilation, the compiler will generate a .hex file that must be loaded onto the microcontroller. See below for instructions on installing avr-gcc on your own computer.
 
  
 
----
 
----
 +
 
===Downloading Compiled Programs to the AVR===
 
===Downloading Compiled Programs to the AVR===
After the compiler has generated a .hex file, it must be loaded onto the microcontroller. There are a variety of ways of doing this, using different programming hardware and/or protocols for transmitting the data. We use an option that requires no additional programming hardware and uses freely-available software. The avrmini v4 also supports programming by external programming hardware, such as the STK500 development board and the AVRISP programmer. Use of these programmers is not covered here.
+
After the compiler has generated a .hex file, it must be loaded onto the microcontroller. There are a variety of ways of doing this, using different programming hardware and/or protocols for transmitting the data. We use an option that requires no additional programming hardware (other than the FTDI FT232R chip that is on the AVRmini v4), and uses freely-available software.  
 +
 
 +
====Programming Hardware====
 +
The AVRmini v4 also supports programming by external programming hardware, such as the [http://www.atmel.com/dyn/products/tools_card.asp?family_id=607&family_name=AVR+8%2DBit+RISC+&tool_id=2735 STK500] development board, the low-cost [http://www.atmel.com/dyn/products/tools_card.asp?family_id=607&family_name=AVR+8%2DBit+RISC+&tool_id=3808 AVRISP mkII], and a variety of [http://en.wikipedia.org/wiki/Bit-banging bit-banging] hardware options. The AVRISP and bit-banging programmers interface to the AVR microcontroller and carry the programming instructions via the SPI serial interface.
 +
 
 +
=====AVRISP=====
 +
The [http://www.atmel.com/dyn/products/tools_card.asp?family_id=607&family_name=AVR+8%2DBit+RISC+&tool_id=3808 AVRISP mkII] (Around $35 at [http://www.digikey.com Digikey], [http://www.digikey.com/scripts/DkSearch/dksus.dll?Detail?Ref=366605&Row=467656&Site=US P/N ATAVRISP2-ND]), is a simple external programmer that connects to your computer's USB port, and has a 10-pin connector that plugs into the "AVR ISP" header on an AVRmini. The older AVRISP connects to the PC via an RS232 serial port. The AVRISP interfaces to the AVR microcontroller and carries the programming instructions via the SPI serial interface. You can to use [[#uisp]] or [[#avrdude]] to program the AVR with an AVRISP. On Windows, you can also use [[#AVRStudio]].
 +
 
 +
=====STK500=====
 +
The [http://www.atmel.com/dyn/products/tools_card.asp?family_id=607&family_name=AVR+8%2DBit+RISC+&tool_id=2735 STK500] is a development kit for AVR microcontrollers from Atmel. It is similar to, but much more expensive than the [[#AVRmini]]. Among its advantages, however, is that it has its own communication protocol that may be used to program a variety of microcontrollers. The STK500 can function similar to the AVRISP as an external SPI programmer (connected to an AVRmini's AVR ISP header, for example), or can be used to program AVR devices on the STK500 itself via the UART.
 +
 
 +
=====Bit-Banging Programmers=====
 +
[http://en.wikipedia.org/wiki/Bit-banging bit-banging] methods emulate the behavior of real serial communication devices without an actual UART or serial device. Bit-banging programmers are significantly slower than real serial programmers like the AVR ISP, but can be built quite cheaply using only a few components. One of the most popular bit-banging methods for microcontroller programming is associated with the [http://www.lancos.com/prog.html PonyProg] software and its SI-Prog hardware. The SI-Prog hardware is very simple, and the circuit can be copied on a breadboard or assembled on a piece of perf board. The programmer can connect to the 10-pin AVR ISP header on an AVRmini v4. Like the AVRISP, bit-banging programmers interface to the AVR and carry the programming instructions via the SPI serial interface. If you have an AVRmini v2, v3, or v3.1, the SI-Prog hardware is built into the board. These boards have a second DB9 serial connector for programming via this interface. To use this method, your computer must have an RS232 serial port. USB-Serial adapters generally don't work for this application. There are many other bit-banging programmer schematics, specifications, and devices that can be found on the web.
 +
 
 +
----
  
 
====Bootloaders====
 
====Bootloaders====
At CCRMA, we install a bootloader on the ATMega32 microcontroller. The bootloader takes advantage of the AVR's self-programming feature. Residing in a special section of program memory, the bootloader is a small program that is executed as soon as the AVR is reset. For a certain amount of time, it looks for incoming programming instructions on the serial port, which it uses to load a new application program into memory, overwriting the rest of the Flash. If no programming instructions are received, the bootloader times out and branches to the beginning of the main program memory, running whatever application program was previously there. The serial data may come from the DB9 serial connector on the avrmini connected to a real serial port on a PC using the RS232 protocol, or via USB through the FT232R chip that can appear as a serial port both to applications on a PC and to the AVR chip, emulating RS232 communication.
+
Bootloaders are another way to program microcontrollers that requires minimal external hardware. At CCRMA, we install a bootloader on the ATMega644 microcontroller that takes advantage of the AVR's self-programming feature. Residing in a special section of program memory, the bootloader is a small program that is executed as soon as the AVR is reset. For a certain amount of time, it looks for incoming programming instructions on the microcontroller's serial UART which it uses to load a new application program into memory, overwriting the rest of the Flash. If no programming instructions are received, the bootloader times out and branches to the beginning of the main program memory, running whatever application program was previously there. The serial data may come from the DB9 serial connector on the AVRmini connected to a real serial port on a PC using the RS232 protocol, or via USB through the FT232R chip that can appear as a serial port both to applications on a PC and to the AVR chip, emulating RS232 communication. The bootloader we use implements the STK500's serial programming protocol (Version 1). You can download the bootloader and get more information here: [http://hubbard.engr.scu.edu/embedded/avr/bootloader/index.html http://hubbard.engr.scu.edu/embedded/avr/bootloader/index.html].
  
The bootloader we use emulates the STK500 (firmware version 1), an AVR development board from Atmel. You can download the bootloader and get more information here: [http://hubbard.engr.scu.edu/embedded/avr/bootloader/index.html http://hubbard.engr.scu.edu/embedded/avr/bootloader/index.html].
+
If you have an AVR development kit that you got from CCRMA, you probably have a bootloader installed. If you didn't, you may want to install a bootloader (see below) or use an alternate programming method, such as [[#ftisp]].  
  
If you have an AVR development kit that you got from CCRMA, you probably have a bootloader installed. If you didn't, you may want to install a bootloader or use an alternate programming method, such as [[#ftisp]].  
+
----
 +
 
 +
====Programming Software====
 +
All of the above hardware programming methods require software on the PC to send the compiled program data to the microcontroller, via an external programmer or an RS232 serial connection.
  
 
====avrdude====
 
====avrdude====
Line 94: Line 111:
 
====ftisp====
 
====ftisp====
 
[http://hubbard.engr.scu.edu/embedded/avr/ftisp/index.html ftisp] is utility program that allows direct ISP programming of AVR processors via a USB connection without a bootloader. Ftisp uses the fast synchronous [bit-bang features found in the FT2232 and FT232R USB interface chips from FTDI (www.ftidchip.com).
 
[http://hubbard.engr.scu.edu/embedded/avr/ftisp/index.html ftisp] is utility program that allows direct ISP programming of AVR processors via a USB connection without a bootloader. Ftisp uses the fast synchronous [bit-bang features found in the FT2232 and FT232R USB interface chips from FTDI (www.ftidchip.com).
 +
 +
====AVRStudio====
 +
[http://www.atmel.com/dyn/products/tools_card.asp?family_id=607&family_name=AVR+8%2DBit+RISC+&tool_id=2725 AVR Studio] is a free IDE for developing AVR applications on Windows. In addition to an editor, it has its own programming/downloading application for writing programs to the AVR.
  
 
==Setting up your Computer to do AVRLib / CCRMA-Style AVR Development==
 
==Setting up your Computer to do AVRLib / CCRMA-Style AVR Development==
Line 117: Line 137:
 
The avrlib-demos can reside anywhere, but they assume that the avrlib is in your home directory.
 
The avrlib-demos can reside anywhere, but they assume that the avrlib is in your home directory.
  
 
+
----
  
 
===Linux Machines at CCRMA===
 
===Linux Machines at CCRMA===
Line 128: Line 148:
  
 
<pre>
 
<pre>
~> svn checkout file:///usr/ccrma/group/pid/avr/svn/avrlib ./avrlib
+
~> svn checkout file:///usr/ccrma/group/pid/svn/avr/avrlib ./avrlib
 
</pre>
 
</pre>
  
Line 140: Line 160:
 
To get the avrlib-demos with subversion:
 
To get the avrlib-demos with subversion:
 
<pre>
 
<pre>
~/somewhere> svn checkout file:///usr/ccrma/group/pid/avr/svn/avrlib-demos ./avrlib-demos
+
~/somewhere> svn checkout file:///usr/ccrma/group/pid/svn/avr/avrlib-demos ./avrlib-demos
 
</pre>
 
</pre>
 
You can update them with <tt>svn update</tt> as well. The avrlib-demos can reside anywhere, but they assume that the avrlib is in your home directory.
 
You can update them with <tt>svn update</tt> as well. The avrlib-demos can reside anywhere, but they assume that the avrlib is in your home directory.
Line 146: Line 166:
  
 
----
 
----
 +
 
===PlanetCCRMA Linux on your own PC===
 
===PlanetCCRMA Linux on your own PC===
  
Line 172: Line 193:
 
For Intel: [http://ccrma.stanford.edu/courses/250a/avr/osx-gnumake_intel.tar.gz osx-gnumake_intel.tar.gz]
 
For Intel: [http://ccrma.stanford.edu/courses/250a/avr/osx-gnumake_intel.tar.gz osx-gnumake_intel.tar.gz]
  
Then, unstuff it, and install the resulting file like this:
+
Then, unstuff it and install the resulting file with these commands in terminal:
 
<pre>
 
<pre>
~> tar xzf osc-gnumake_<platform>.tar.gz
+
~> tar xvf osx-gnumake_<platform>.tar.gz
 
~> sudo mv gnumake /usr/bin
 
~> sudo mv gnumake /usr/bin
 
~> sudo ln -s /usr/bin/gnumake /usr/bin/make
 
~> sudo ln -s /usr/bin/gnumake /usr/bin/make
 
</pre>
 
</pre>
 +
*where "<platform>" is either "intel" or "ppc"
  
 
2. Download, un-stuff this archive and put the resulting <tt>avr</tt> directory in /usr/local, which you may need to create if it doesn't exist:
 
2. Download, un-stuff this archive and put the resulting <tt>avr</tt> directory in /usr/local, which you may need to create if it doesn't exist:
Line 186: Line 208:
 
You will probably need to do this as administrator, i.e.
 
You will probably need to do this as administrator, i.e.
 
<pre>
 
<pre>
~> tar xzf usr-local-avr_ppc.tar.gz
+
~> tar xvf usr-local-avr_ppc.tar.gz
 
~> sudo mv avr /usr/local
 
~> sudo mv avr /usr/local
 
</pre>
 
</pre>
Line 203: Line 225:
 
====Linux / Mac OS X (the not-so easy way)====
 
====Linux / Mac OS X (the not-so easy way)====
 
This requires compiling the tools from source. It is not too difficult, but may take some time, depending on your bandwidth and CPU speed. On a Mac, this assumes you have the [http://developer.apple.com/tools Apple's developer tools] installed. On Linux, it assumes you have gcc and a basic operational build setup.
 
This requires compiling the tools from source. It is not too difficult, but may take some time, depending on your bandwidth and CPU speed. On a Mac, this assumes you have the [http://developer.apple.com/tools Apple's developer tools] installed. On Linux, it assumes you have gcc and a basic operational build setup.
 
  
 
First, you need to download the following sources (either .tar.gz or .tar.bz2):
 
First, you need to download the following sources (either .tar.gz or .tar.bz2):
Line 304: Line 325:
 
~> sudo make install
 
~> sudo make install
 
</pre>
 
</pre>
 
  
 
=====avr-libc=====
 
=====avr-libc=====
Line 335: Line 355:
  
 
===Windows===
 
===Windows===
 +
We generally don't support Windows at CCRMA, but there are a number of excellent tools available for developing for AVR microcontrollers on Windows.
 +
 +
====AVRStudio====
 +
[http://www.atmel.com/dyn/products/tools_card.asp?family_id=607&family_name=AVR+8%2DBit+RISC+&tool_id=2725 AVR Studio] is a free IDE from Atmel for developing AVR applications on Windows. It is built on top of the avr-gcc compiler and features a full suite of tools to help write, edit, debug and download programs to AVR microcontrollers.
 +
 +
====WinAVR====
 +
[http://winavr.sourceforge.net/index.html WinAVR] is a collection of open source tools for developing AVR applications on Windows. It includes avr-gcc, avrdude, and a variety of other tools, and has a one-click installer. To set up your system to do development with WinAVR:
 +
 +
 +
1. Download the most recent installer from the [http://winavr.sourceforge.net/ WinAVR SourceForge Site].
 +
 +
2. Run the WinAVR installer.
 +
* To minimize problems, install WinAVR into a new home directory you create and choose without spaces in the path (e.g. c:\ccrma).
 +
* If you are running Win2000 or WinXP, it is recommended that you install WinAVR with administrator access.
 +
 +
3. Add a windows environment variable that points to your new HOME directory.
 +
For most versions of Windows:
 +
* Right-click My Computer
 +
* Select Properties
 +
* Select the Advanced tab
 +
* Click Environment Variables
 +
* Click New to add a system environment variable
 +
** Variable name: HOME
 +
** Variable value: c:\ccrma (or whatever you chose as your home directory)
 +
 +
4. Download [http://ccrma.stanford.edu/courses/250a/avrlib/avrlib_ccrma20070527.tar.gz avrlib] and place in your home directory.
 +
 +
 +
It's a good idea to put the WinAVR tools in a directory path that has no spaces because spaces can cause problems with unix command-line parsing. It's a convention at CCRMA that avrlib lives in each user's home directory, so if you put avrlib in your designated windows HOME directory, you have less to change when you copy over AVR projects from your CCRMA Linux account.
  
 
==Compiling and Downloading Programs==
 
==Compiling and Downloading Programs==
 +
With the development tools properly installed, compiling and downloading programs to the AVR is easy. We will outline the steps involved in compiling the "button" program in the [[#avrlib-demos]] in Linux or Mac OS and downloading it to an AVRmini v4.
 +
 +
*Connect the AVRmini to your computer with a USB cable and switch on the power of the AVRmini. You should see the red USB indicator LED flash a few times as the FT232R chip negotiates with the driver on your computer.
 +
 +
*On your computer, open a terminal, and change to the directory where project you want to compile resides. In the example below, the avrlib-demos are in a directory called 250a in the user's home directory.
 +
 +
*Type <tt>make</tt> in the terminal:
 +
<pre>
 +
~> cd ~/250a/avrlib-demos/button
 +
~/250a/avrlib-demos/button> make
 +
</pre>
 +
 +
*You should see a bunch of output in the terminals, and hopefully a line that says
 +
<pre>
 +
Errors: none
 +
</pre>
 +
This means that the program compiled successfully. If you type <tt>ls</tt> in the terminal, you should see a file called <tt>button.hex</tt> that was created as a result of the compilation. This is the file that gets copied into the AVR's Flash memory.
 +
 +
*To copy the compiled program into the AVR's Flash memory, you need to do the following steps in rapid succession:
 +
1. Type <tt>make load</tt> in the terminal, but DO NOT press Enter.<br>
 +
2. Reset the power to the AVRmini by momentarily pressing and releasing the Reset button.<br>
 +
3. Press Enter on your keyboard (within 3 seconds of pressing the Reset button).<br>
 +
 +
You should see a bunch of text written to the terminal, including three progress indicators made up of # characters.
 +
 +
===Modifying the avrlib-demos===
 +
To write your own programs for the AVR, it is normally easiest to use one of the avrlib-demos as a starting point. It is best to leave the avrlib-demos intact and <b>make a copy</b> of the entire project directory before you modify it. For example:
 +
<pre>
 +
~/250a> cp -r avrlib-demos/button ./mybutton
 +
</pre>
 +
 +
It is a good idea at this point to remove any files that were generated by previously compiling the program. You can do this by typing <tt>make clean</tt> in the terminal. This should leave only <tt>button.c</tt>, <tt>global.h</tt> and <tt>makefile</tt> in the directory.
 +
 +
Now, you probably want to rename <tt>button.c</tt> to <tt>mybutton.c</tt>. In our classes, it frequently happens that someone is editing one program but compiling and downloading another, because they both have the same name. It is not required that the directory and the <tt>.c</tt> file have the same name, but it makes it easier to keep track of your programs.
 +
 +
The last step is to modify the makefile to reflect the new name of the <tt>.c</tt> file it is going to issue instructions to compile. Open the makefile in an editor. On line 26, you will see the text
 +
<pre>
 +
        TRG = button
 +
</pre>
 +
 +
If you have changed the name of your program to be <tt>mybutton.c</tt>, then this line should be changed to
 +
 +
<pre>
 +
        TRG = mybutton
 +
</pre>
 +
 +
Note that the .c suffix is omitted. Now you are ready to modify and compile your new mybutton program.
 +
 +
===Common Errors===
 +
<pre>
 +
avrdude: ser_open(): can't open device "/dev/ttyUSB0": No such file or directory
 +
make: *** [load] Error 1
 +
</pre>
 +
 +
This will happen if you don't have a device named /dev/ttyUSB0 on your system. This can occur for a number of reasons:
 +
 +
1. You are using Windows or Mac OS, and the [http://www.ftdichip.com/Drivers/VCP.htm FTDI Virtual Com Port Driver] is not installed. Get the appropriate one for your operating system and try again.
 +
 +
2. The [http://www.ftdichip.com/Products/FT232R.htm FT232R] chip on your AVRmini hasn't established itself with the system. Try turning off and turning back on the power to the AVRmini (not with the Reset button, but with the actual power switch). If this doesn't help, try typing
 +
<pre>
 +
~> ls /dev/tty*
 +
</pre>
 +
to see a list of all the tty devices on your system. If you don't see one that resembles a USB device, then the [http://www.ftdichip.com/Drivers/VCP.htm FTDI Virtual Com Port Driver] is not installed or not working. For Linux kernels greater than 2.4.20, it is included in the kernel, so no additional installation should be necessary. See the [http://www.ftdichip.com/Products/FT232R.htm FT232R] support for more information.
 +
 +
3. You are using Windows or Mac OS, and the name of the USB device is different than the default in the project makefile. On line 30 of the default project makefile, you will see
 +
 +
<pre>
 +
        AVRDUDE_PORT = /dev/ttyUSB0
 +
</pre>
 +
 +
Comment out the above line (with a # character) and add a line with the name of the device on your system, i.e.
 +
<pre>
 +
#      AVRDUDE_PORT = /dev/ttyUSB0
 +
        AVRDUDE_PORT = /dev/tty.usbserial-A30007PY
 +
</pre>
 +
 +
* On most Macs, the device appears as <tt>/dev/tty.usbserial-A30007PY</tt>. Type <tt> ls /dev/tty* </tt> in a terminal to make sure.
 +
* In Windows, it appears as a COM device. Check in your Windows Device Manager for the COM port number. If, for example, it is COM3, your makefile should be changed to
 +
 +
<pre>
 +
#      AVRDUDE_PORT = /dev/ttyUSB0
 +
        AVRDUDE_PORT = COM3
 +
</pre>
 +
 +
----
  
 
==Communicating with Pd via OSC over USB==
 
==Communicating with Pd via OSC over USB==
 +
With the AVRmini v4, we most commonly send data formatted according to the OpenSound Control (OSC) protocol to a computer over USB. To program the AVR to send OSC messages, see the <tt>osctest</tt> program in the [[#avrlib-demos]]
 +
 +
On the computer, we normally use [http://www.puredata.org/ Pd] (sometimes referred to as Pure Data) to receive OSC messages from the AVR. Pd doesn't have built in objects for doing this, so we use our own external objects. These externs have been designed to mimic way the udpreceive and OpenSoundControl objects work together in Max/MSP. There are 2 objects:
 +
 +
* serialIO -- A general purpose object for sending and receiving serial data from a /dev/tty device. For receiving, it has an OSC mode in which it parses the data looking for OSC messages. When it finds one, it stores the data in a buffer and outputs a list consisting of the symbol "FullPacket", the length of the message in bytes and a pointer to the buffer where the data is stored.
 +
 +
* OpenSoundControl -- An object both for parsing incoming OSC packets and creating OSC packets to be transmitted. Incoming OSC packets can be received from the serialIO object, or a Max-style udpreceive object (yet to be written). Outgoing packets can similarly be transmitted over a serial port via serialIO, or through a network socket.
 +
 +
If you want to compile the objects from source, or help develop them, the source is available in an svn repository at CCRMA. To check out a copy, use:
 +
<pre>
 +
~>svn co file:///usr/ccrma/group/pid/svn/pd ./pd_OSC_serial
 +
</pre>
 +
Or, you can download the source from
 +
[http://ccrma.stanford.edu/courses/250a/pd/pd_OSCserial_src20070810.tar.gz pd_OSCserial_src20070810.tar.gz]. If you want to develop these objects at CCRMA with the subversion repository, you must belong to the pid group. E-mail gurevich (at) ccrma and carrlane (at) ccrma to request to be added to the group.
 +
 
===Linux Machines at CCRMA===
 
===Linux Machines at CCRMA===
===PlanetCCRMA Linux on your own PC===
+
The serialIO and OpenSoundControl objects are installed in the directory <tt>/usr/ccrma/courses/250a/pd/externs</tt>. In order to use them, make sure that this directory is in your Pd path. You can do this by adding the following to the .pdrc file in your home directory (in an editor)
===Mac OS X===
+
 
 +
<pre>
 +
-path /usr/ccrma/courses/250a/pd/externs
 +
</pre>
 +
 
 +
or, through the dialog box in Pd from the File->Path menu. See the help patches for these objects, or osctest.pd from the avrlib-demos for more info.
 +
 
 +
===Mac OS X or other Linux===
 +
Download [http://ccrma.stanford.edu/courses/250a/pd/pd_OSCserial_externs20070810.tar.gz pd_OSCserial_externs20070810.tar.gz]. Decompress the tarfile and copy the externs for your system into a directory in your Pd path. On Mac OS X, I put the .pd_darwin files in /Library/Pd/Externals and the help patches in /Library/Pd/Help.
 +
 
 
===Windows===
 
===Windows===
 +
Unfortunately, these objects have not yet been compiled for Windows. Until they are, you can use a small utility program that receives incoming serial data and sends it to a network port as UDP data.
 +
 +
* First, download [http://ccrma.stanford.edu/courses/250a/pd/serialosc2udp.zip serialosc2udp.zip].
 +
 +
* Copy the file serialosc2udp.exe to your C:\ccrma\bin
 +
 +
* Open the Windows command window and Run from the command line: "serialosc2udp.exe COM# localhost 999" where '#' is your serial com port number.
 +
   
 +
* Shut down your firewall
 +
   
 +
* In Pd, make sure you have the standard OSC objects installed. Create a "dumpOSC" object with port "999" as the argument.
  
 
==Communicating with Max/MSP via OSC over USB==
 
==Communicating with Max/MSP via OSC over USB==
 +
 
===Mac OS X===
 
===Mac OS X===
 +
The serialIO object has been compiled as a Mac OS X Universal Binary and tested in Max 4.6 and Max 5 on an Intel-based MacBook Pro and iMac. It should be used in conjunction with the [http://www.cnmat.berkeley.edu/OpenSoundControl/Max/ CNMAT OpenSound Control objects].
 +
 +
* Source: [http://ccrma.stanford.edu/courses/250a/maxmsp/serialIO_src_20071106.zip serialIO_src_20071106.zip]
 +
 +
* Binary object and help patch: [http://ccrma.stanford.edu/courses/250a/maxmsp/serialIO_bin_20071106.zip serialIO_bin_20071106.zip]
 +
 
===Windows===
 
===Windows===
  
 +
Untested yet. see [[#Windows_2]]
  
 
==Communicating via OSC over udp ==
 
==Communicating via OSC over udp ==
Line 354: Line 531:
  
 
Note that you don't need a bootloader to program your AVR. You can use [[#ftisp]] or any of the methods we are about to describe for installing the bootloader. Otherwise, to install the bootloader, first you need to do download it from  
 
Note that you don't need a bootloader to program your AVR. You can use [[#ftisp]] or any of the methods we are about to describe for installing the bootloader. Otherwise, to install the bootloader, first you need to do download it from  
[http://hubbard.engr.scu.edu/embedded/avr/bootloader/index.html http://hubbard.engr.scu.edu/embedded/avr/bootloader/index.html]. At CCRMA, we use an ATMega32 with a 14.746 MHz clock and the "New V1" bootloader: [http://hubbard.engr.scu.edu/embedded/avr/bootloader/v1/stkload_m32_2k32k_14745600.hex http://hubbard.engr.scu.edu/embedded/avr/bootloader/v1/stkload_m32_2k32k_14745600.hex]. If you have a different AVR chip or clock speed, download the one that is appropriate for you.
+
[http://hubbard.engr.scu.edu/embedded/avr/bootloader/index.html http://hubbard.engr.scu.edu/embedded/avr/bootloader/index.html]. At CCRMA, we use an ATMega644 with a 14.746 MHz clock and the "New V1" bootloader: [http://hubbard.engr.scu.edu/embedded/avr/bootloader/v1/stkload_m644_2k64k_14745600.hex http://hubbard.engr.scu.edu/embedded/avr/bootloader/v1/stkload_m644_2k64k_14745600.hex]. If you have a different AVR chip or clock speed, download the one that is appropriate for you.
  
 
===AVRISP===
 
===AVRISP===
The easiest way to install a bootloader is with an external programmer such as an AVRISP. The [http://www.atmel.com/dyn/products/tools_card.asp?family_id=607&family_name=AVR+8%2DBit+RISC+&tool_id=3808 AVRISP mkII] (Around $35 at [http://www.digikey.com Digikey], [http://www.digikey.com/scripts/DkSearch/dksus.dll?Detail?Ref=366605&Row=467656&Site=US P/N ATAVRISP2-ND]), connects to your computer's USB port, and has a 10-pin connector that plugs into the "AVR ISP" header on an AVRmini. The older AVRISP connects to the PC via an RS232 serial port. You should be able to use [[#uisp]] or [[#avrdude]] to program the AVR with an AVRISP. On Windows, you can also use [http://www.atmel.com/dyn/products/tools_card.asp?family_id=607&family_name=AVR+8%2DBit+RISC+&tool_id=2725 AVR Studio]. With [[#uisp]], the command would be as follows (note, these are untested, as we do not have an AVRISP mkII to test with at CCRMA). First, erase the chip:
+
The easiest way to install a bootloader is with an external programmer such as an [http://www.atmel.com/dyn/products/tools_card.asp?family_id=607&family_name=AVR+8%2DBit+RISC+&tool_id=3808 AVRISP mkII]. With [[#uisp]], the command would be as follows (note, these are untested, as we do not have an AVRISP mkII to test with at CCRMA). First, erase the chip:
  
 
<pre>
 
<pre>
~> uisp -v -dpart=atmega32 -dprog=avrisp -dserial=/dev/ttyUSB0 --erase
+
~> uisp -v -dpart=atmega644 -dprog=avrisp -dserial=/dev/ttyUSB0 --erase
 
</pre>
 
</pre>
  
 
Then, upload the bootloader:
 
Then, upload the bootloader:
 
<pre>
 
<pre>
~> uisp -v -dpart=atmega32 -dprog=avrisp -dserial=/dev/ttyUSB0 --upload if=stkload_m32_2k32k_14745600.hex
+
~> uisp -v -dpart=atmega644 -dprog=avrisp -dserial=/dev/ttyUSB0 --upload if=stkload_m644_2k64k_14745600.hex
 
</pre>
 
</pre>
  
 
With avrdude, it would be something like:
 
With avrdude, it would be something like:
 
<pre>
 
<pre>
~> avrdude -v -F -p m32 -c avrisp2 -P /dev/ttyUSB0 -Uflash:wstkload_m32_2k32k_14745600.hex
+
~> avrdude -v -F -p m644 -c avrisp2 -P /dev/ttyUSB0 -Uflash:wstkload_m644_2k64k_14745600.hex
 
</pre>
 
</pre>
  
Line 382: Line 559:
 
With uisp:
 
With uisp:
 
<pre>
 
<pre>
~> uisp -v -dprog=dasa2 -dpart=atmega32 -dlpt=/dev/ttyS0 --erase
+
~> uisp -v -dprog=dasa2 -dpart=atmega644 -dlpt=/dev/ttyS0 --erase
~> uisp -v -dprog=dasa2 -dpart=atmega32 -dlpt=/dev/ttyS0 --upload if=stkload_m32_2k32k_14745600.hex
+
~> uisp -v -dprog=dasa2 -dpart=atmega644 -dlpt=/dev/ttyS0 --upload if=stkload_m644_2k64k_14745600.hex
 
</pre>
 
</pre>
  
 
With avrdude:
 
With avrdude:
 
<pre>
 
<pre>
~> avrdude -v -F -p m32 -c siprog -P /dev/ttyS0 -Uflash:w:stkload_m32_2k32k_14745600.hex
+
~> avrdude -v -F -p m644 -c siprog -P /dev/ttyS0 -Uflash:w:stkload_m644_2k64k_14745600.hex
 
</pre>
 
</pre>
  
 
===Setting the Fuses and Lock Bits===
 
===Setting the Fuses and Lock Bits===
After installing the bootloader, your AVR chip must be configured to run the bootloader code when it powers on, to know how much memory it occupies, and to allow the bootloader to overwrite the rest of the AVR's Flash memory. The following commands show how to set the fuses and lock bits for the stkload_m32_2k32k_14745600.hex bootloader on an ATMega32 with uisp and avrdude. You can also use the [http://www.lancos.com/prog.html PonyProg] software itself or AVRStudio. If you have a different AVR device and bootloader, you'll have to refer to the specific device's datasheet to find out what byte values to use. These instructions also assume SI-Prog-style programmer hardware. For AVRISP, change the flags for uisp and avrdude accordingly.
+
After installing the bootloader, your AVR chip must be configured to run the bootloader code when it powers on, to know how much memory it occupies, and to allow the bootloader to overwrite the rest of the AVR's Flash memory. The following commands show how to set the fuses and lock bits for the stkload_m644_2k64k_14745600.hex bootloader on an ATMega644 with uisp and avrdude. You can also use the [http://www.lancos.com/prog.html PonyProg] software itself or AVRStudio. If you have a different AVR device and bootloader, you'll have to refer to the specific device's datasheet to find out what byte values to use. These instructions also assume SI-Prog-style programmer hardware. For AVRISP, change the flags for uisp and avrdude accordingly.
  
 
With uisp:
 
With uisp:
 
<pre>
 
<pre>
~> uisp -dprog=dasa2 -dpart=atmega32 -dlpt=/dev/ttyS0 --wr_fuse_l=0xbf
+
~> uisp -dprog=dasa2 -dpart=atmega644 -dlpt=/dev/ttyS0 --wr_fuse_l=0xbf
~> uisp -dprog=dasa2 -dpart=atmega32 -dlpt=/dev/ttyS0 --wr_fuse_h=0xc2
+
~> uisp -dprog=dasa2 -dpart=atmega644 -dlpt=/dev/ttyS0 --wr_fuse_h=0xc2
~> uisp -dprog=dasa2 -dpart=atmega32 -dlpt=/dev/ttyS0 --wr_lock=0xef
+
~> uisp -dprog=dasa2 -dpart=atmega644 -dlpt=/dev/ttyS0 --wr_lock=0xef
 
</pre>
 
</pre>
  
Line 404: Line 581:
  
 
<pre>
 
<pre>
~> uisp -dprog=dasa2 -dpart=atmega32 -dlpt=/dev/ttyS0 --rd_fuses
+
~> uisp -dprog=dasa2 -dpart=atmega644 -dlpt=/dev/ttyS0 --rd_fuses
 
</pre>
 
</pre>
  
Line 410: Line 587:
  
 
<pre>
 
<pre>
Atmel AVR ATmega32 is found.
+
Atmel AVR ATmega644 is found.
  
 
Fuse Low Byte      = 0xbf
 
Fuse Low Byte      = 0xbf
Line 428: Line 605:
 
With avrdude:
 
With avrdude:
 
<pre>
 
<pre>
~> avrdude -v -F -p m32 -c siprog -P /dev/ttyS0 -Ulfuse:w:0xbf:m -Uhfuse:w:0xc2:m  
+
~> avrdude -v -F -p m644 -c siprog -P /dev/ttyS0 -Ulfuse:w:0xbf:m -Uhfuse:w:0xc2:m  
~> avrdude -v -F -p m32 -c siprog -P /dev/ttyS0 -Ulock:w:0xef:m
+
~> avrdude -v -F -p m644 -c siprog -P /dev/ttyS0 -Ulock:w:0xef:m
 
</pre>
 
</pre>
 +
 +
 +
[[Category:PID_2007]] [[Category:PID_2008]] [[Category:PID]]

Latest revision as of 16:10, 7 July 2008

AVR Microcontrollers

AVR 8-bit RISC microcontrollers by Atmel are currently at the heart of the embedded technology platform we use in Physical Interaction Design research and courses at CCRMA. These chips have a modern Harvard Architecture, executing most instruction cycles in a single clock cycle. An extremely efficient open source C compiler is available, and these devices are used and supported by a large community of developers. The AVR architecture and instruction set is available in a large family of 8-bit devices that come in a variety of packages. AVR-series chips come with as little as 1 Kbyte of Flash program memory, up to 256 Kbytes; 32 bytes to 8 Kbytes of RAM; and up to 20 MHz clock speeds. Specialized AVR devices exist for automotive, LCD and lighting control, USB and radio applications. Code is easily portable between devices.

AVR Hardware at CCRMA

ATMega644

We currently use the ATMega 644 (Product Page). It features:

  • 64 Kbyte self-programming Flash Program Memory
  • 4 Kbyte SRAM
  • 2 Kbyte EEPROM
  • 8-Channel 10-bit A/D-converter
  • Up to 20 Mhz clock
  • I2C, SPI interfaces
  • 1 USART, 2-channels PWM, 2 ext. interrupts

ATMega 3644 Documentation:

AVRmini Development Board

The AVRmini development board, made by Pascal Stang, is a general purpose prototyping board that provides easy access to the AVR's I/O and programming interfaces, along with a number of useful peripheral devices. We are currently using the AVRmini v4.0. The AVRmini v4.0 provides:

  • Support for most 40-pin AVR processors
  • Ethernet, USB, SD/MMC, RS-232 I/O
  • I2C header
  • Character LCD header
  • 10-pin I/O headers
  • 4 buttons and 4 LEDs
  • 5-V regulator

AVRmini Documentation:

CCRMA's AVR Prototyping Kit

For our PID courses at CCRMA, we assemble a prototyping kit based on the AVRmini. We mount the AVRmini on a sheet of 1/8" acrylic, and add solderless breadboard strips, an LCD display and a small loudspeaker. Pins 9 and 10 of the AVRmini v4.0's "AUX" header (JP13) are connected to the ground and +5V power rails of the breadboard strips.

  • kit Photo

Spyglass User Interface Board

The LCD display on CCRMA's prototyping board is part of the Spyglass User interface Board, which communicates with the AVR via I2C. We purchased these on eBay, and from a few other places, but they are hard to come by these days. Pascal Stang has written a brief Spyglass User Guide. He has also developed a replacement I2C button module/LCD driver (no documentation available) to which we can connect an LCD display and use just like the Spyglass.

  • Spyglass photo
  • buttonmodule photo


AVR Software at CCRMA

We use a set of open source tools for compiling C programs and downloading them to the AVR. Here is a brief description of what these tools are. See below for detailed instructions on setting up these tools on your own computer.

Programming the AVR

avrlib

The avrlib is a library of easy-to-use C functions for a variety of tasks on the AVR microcontroller. It gives high-level functions for accomplishing tasks that might otherwise be tedious to program. These include serial communication, analog-to-digital conversion, displaying text on LCD displays and interfacing to a whole range of other devices such as hard drives, GPS units, Ethernet devices and sensors. The avrlib is distributed under a GNU Public License. At CCRMA, we make a few slight modifications to the original avrlib.

The avrlib directory contains mainly a collection of .h and .c files containing the library function. They are well-documented and compatible with the doxygen documentation generation tool. Here is a link to the avrlib on-line documentation.

avrlib-demos

The avrlib-demos are a set of example AVR development projects developed at CCRMA, some based on code from Pascal Stang's examples in the avrlib. Each project in the avrlib-demos contains at least 3 files:

  • project-title.c

This is the .c file containing the code for the project. Since microcontroller programs are typically very small, all the code we need to write is normally contained in one .c file. We normally use other functions from the .c files in the #avrlib, but these are linked in when we compile the code. By convention, the name of this file (minus the .c extension) is the same name as the directory in which it is contained, i.e. button.c is in the button directory - this is the "name" of the project. If you want to create your own project based on one of the avrlib-demos, you should copy the directory, change its name, and change the name of the corresponding .c file. You'll need to change the target name in the makefile as well (see below). See the tutorial on writing C programs for the AVR for more information.

  • global.h

The global.h file is required by the #avrlib. In most cases, it simply defines the clock speed of the AVR microcontroller that you are using. The general philosophy of the #avrlib is that the library should remain general-purpose, and able to support a range of projects for different microcontrollers and hardware without modification. So, since you may have different projects on your computer for different AVR devices at different clock speeds, there is a global.h in every project directory (rather than keeping a common one in the #avrlib directory).

  • makefile

This file contains project-specific settings for compiling and downloading your code to the microcontroller. The makefile is read by a program called make that is a sort of scripting language commonly used for generating compilation instructions. The makefile in each project contains settings that are passed to a global makefile called avrccrma_make that resides in the avrlib/make directory. The 2 most common things you may need to modify in the makefile are the target name of the .c file that you are compiling and the list of avrlib .c files that you are using. See the tutorial on writing C programs for the AVR for more information.


There is one other type of file that is present in some of the avrlib-demos directories that you may need in your projects. These are configuration files that contain settings for specific avrlib modules. For example, in the lcdtest directory, you will see a file called lcdconf.h. lcdconf.h contains settings relevant to the lcd display you are using, such as the number of lines and columns. As described above, you may have different projects using different lcd displays, so rather than change a global configuration file each time you compile your code, the avrlib requires that you put a different configuration file in each project directory.

avr-gcc

avr-gcc is actual compiler that generates AVR byte code from the c files that you compile. We don't invoke avr-gcc directly, rather it is called from the makefile. At the end of a successful compilation, the compiler will generate a .hex file that must be loaded onto the microcontroller. See below for instructions on installing avr-gcc on your own computer.


Downloading Compiled Programs to the AVR

After the compiler has generated a .hex file, it must be loaded onto the microcontroller. There are a variety of ways of doing this, using different programming hardware and/or protocols for transmitting the data. We use an option that requires no additional programming hardware (other than the FTDI FT232R chip that is on the AVRmini v4), and uses freely-available software.

Programming Hardware

The AVRmini v4 also supports programming by external programming hardware, such as the STK500 development board, the low-cost AVRISP mkII, and a variety of bit-banging hardware options. The AVRISP and bit-banging programmers interface to the AVR microcontroller and carry the programming instructions via the SPI serial interface.

AVRISP

The AVRISP mkII (Around $35 at Digikey, P/N ATAVRISP2-ND), is a simple external programmer that connects to your computer's USB port, and has a 10-pin connector that plugs into the "AVR ISP" header on an AVRmini. The older AVRISP connects to the PC via an RS232 serial port. The AVRISP interfaces to the AVR microcontroller and carries the programming instructions via the SPI serial interface. You can to use #uisp or #avrdude to program the AVR with an AVRISP. On Windows, you can also use #AVRStudio.

STK500

The STK500 is a development kit for AVR microcontrollers from Atmel. It is similar to, but much more expensive than the #AVRmini. Among its advantages, however, is that it has its own communication protocol that may be used to program a variety of microcontrollers. The STK500 can function similar to the AVRISP as an external SPI programmer (connected to an AVRmini's AVR ISP header, for example), or can be used to program AVR devices on the STK500 itself via the UART.

Bit-Banging Programmers

bit-banging methods emulate the behavior of real serial communication devices without an actual UART or serial device. Bit-banging programmers are significantly slower than real serial programmers like the AVR ISP, but can be built quite cheaply using only a few components. One of the most popular bit-banging methods for microcontroller programming is associated with the PonyProg software and its SI-Prog hardware. The SI-Prog hardware is very simple, and the circuit can be copied on a breadboard or assembled on a piece of perf board. The programmer can connect to the 10-pin AVR ISP header on an AVRmini v4. Like the AVRISP, bit-banging programmers interface to the AVR and carry the programming instructions via the SPI serial interface. If you have an AVRmini v2, v3, or v3.1, the SI-Prog hardware is built into the board. These boards have a second DB9 serial connector for programming via this interface. To use this method, your computer must have an RS232 serial port. USB-Serial adapters generally don't work for this application. There are many other bit-banging programmer schematics, specifications, and devices that can be found on the web.


Bootloaders

Bootloaders are another way to program microcontrollers that requires minimal external hardware. At CCRMA, we install a bootloader on the ATMega644 microcontroller that takes advantage of the AVR's self-programming feature. Residing in a special section of program memory, the bootloader is a small program that is executed as soon as the AVR is reset. For a certain amount of time, it looks for incoming programming instructions on the microcontroller's serial UART which it uses to load a new application program into memory, overwriting the rest of the Flash. If no programming instructions are received, the bootloader times out and branches to the beginning of the main program memory, running whatever application program was previously there. The serial data may come from the DB9 serial connector on the AVRmini connected to a real serial port on a PC using the RS232 protocol, or via USB through the FT232R chip that can appear as a serial port both to applications on a PC and to the AVR chip, emulating RS232 communication. The bootloader we use implements the STK500's serial programming protocol (Version 1). You can download the bootloader and get more information here: http://hubbard.engr.scu.edu/embedded/avr/bootloader/index.html.

If you have an AVR development kit that you got from CCRMA, you probably have a bootloader installed. If you didn't, you may want to install a bootloader (see below) or use an alternate programming method, such as #ftisp.


Programming Software

All of the above hardware programming methods require software on the PC to send the compiled program data to the microcontroller, via an external programmer or an RS232 serial connection.

avrdude

avrdude is the "standard" and probably most widely-used open-source AVR programmer software. By default, the makefiles in the #avrlib-demos and #avrlib use avrdude. There have been problems with some versions of avrdude on the Mac, so support for uisp is included as well.

uisp

uisp is another open-source AVR programmer software. It does not appear to have been updated in awhile, and it is unknown whether its development is still active. It may be necessary on some Macs where some versions of avrdude don't work with the hardware and software we are using.

PonyProg

PonyProg is a gui-based closed-source programming software package for a variety of devices including AVR microcontrollers. It is free to download, and available for Windows and Linux only. PonyProg has its own hardware /software specification for interfacing with AVR microcontrollers, or it can use other standard protocols.

ftisp

ftisp is utility program that allows direct ISP programming of AVR processors via a USB connection without a bootloader. Ftisp uses the fast synchronous [bit-bang features found in the FT2232 and FT232R USB interface chips from FTDI (www.ftidchip.com).

AVRStudio

AVR Studio is a free IDE for developing AVR applications on Windows. In addition to an editor, it has its own programming/downloading application for writing programs to the AVR.

Setting up your Computer to do AVRLib / CCRMA-Style AVR Development

ALL PLATFORMS

avrlib

No matter what platform you use, you need to get the avrlib. If you are using a Linux machine at CCRMA, see the next section for the best way to do this. Otherwise, you can download the avrlib here:

and decompress it into your home directory. On a Linux or Mac system you can do this with:

~> tar xzf avrlib_ccrma20070527.tar.gz

avrlib-demos

A set of demo programs to demonstrate the basic functionalities of the AVRlib and AVRmini are also available:

Again on Linux or Mac, you can decompress them with:

~/somewhere> tar xzf avrlib-demos20070124.tar.gz

The avrlib-demos can reside anywhere, but they assume that the avrlib is in your home directory.


Linux Machines at CCRMA

The Linux machines at CCRMA already have the AVR development tools installed, and in your path. All you need to do is get a copy of the AVRlib. The avrlib-demos are helpful in getting started.

To get the most up-to-date versions, use subversion.

avrlib

In a terminal, change into your home directory, and then type:

~> svn checkout file:///usr/ccrma/group/pid/svn/avr/avrlib ./avrlib

This will create an avrlib directory in your home directory. You can update it anytime from a terminal, by changing into the avrlib directory and typing:

~/avrlib> svn update

avrlib-demos

To get the avrlib-demos with subversion:

~/somewhere> svn checkout file:///usr/ccrma/group/pid/svn/avr/avrlib-demos ./avrlib-demos

You can update them with svn update as well. The avrlib-demos can reside anywhere, but they assume that the avrlib is in your home directory.



PlanetCCRMA Linux on your own PC

AVR Development Tools

If you have PlanetCCRMA installed on your PC, then you just need to make sure that you have the AVR development packages installed, using yum or apt.

For Fedora Core 4, the AVR compiler tools are under Applications/Development. The AVR downloading/programming tools are under Development/Tools.

AVRlib and avrlib-demos

Download the avrlib and avrlib-demos as described above. Note that you need to get the .tar.gz files, as the svn repository is not available outside of CCRMA.



Mac OS X / Linux

These instructions are excerpted from avr-libc: Installing the GNU Tool Chain.

Mac OS X: The Easy Way

1.You need the gnumake program, and you also need a symbolic link to it called make.

There are two options: i) Install Apple's developer tools, which include gnumake and much, much, much more. If you want to develop OSX applications you probably want or already have these anyway. They have a fancy easy-to-use installer.

ii) Alternately, you could just download my copy of gnumake: For PPC: osx-gnumake_ppc.tar.gz For Intel: osx-gnumake_intel.tar.gz

Then, unstuff it and install the resulting file with these commands in terminal:

~> tar xvf osx-gnumake_<platform>.tar.gz
~> sudo mv gnumake /usr/bin
~> sudo ln -s /usr/bin/gnumake /usr/bin/make
  • where "<platform>" is either "intel" or "ppc"

2. Download, un-stuff this archive and put the resulting avr directory in /usr/local, which you may need to create if it doesn't exist:

You will probably need to do this as administrator, i.e.

~> tar xvf usr-local-avr_ppc.tar.gz
~> sudo mv avr /usr/local

3. Add /usr/local/avr/bin to your Unix path. For example, if you use the tcsh shell, add this line to the file .cshrc in your home directory:

set path=($path /usr/local/avr/bin)

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

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

Linux / Mac OS X (the not-so easy way)

This requires compiling the tools from source. It is not too difficult, but may take some time, depending on your bandwidth and CPU speed. On a Mac, this assumes you have the Apple's developer tools installed. On Linux, it assumes you have gcc and a basic operational build setup.

First, you need to download the following sources (either .tar.gz or .tar.bz2):

Next, you'll need to decide where to install the tools. It is usually a good idea to keep the avr build tools separate from your system build tools, so we recommend installing everything to /usr/local/avr. In order to do this, it is helpful to set an environment variable called PREFIX that points to this location. In a Bash shell (if your prompt is a $, this is probably what you're using), do:

$ PREFIX=/usr/local/avr
$ export PREFIX

The equivalent in csh or tcsh is:

~> setenv PREFIX /usr/local/avr

3. You'll also want to set your path to include the location where you are going to install the tools. In Bash:

$ PATH=$PATH:$PREFIX/bin
$ export PATH

In csh or tcsh:

set PATH = ($PATH $PREFIX/bin)

In either case, you should also add this to your default path, as in Step 3 of the previous section.

GNU Binutils for the AVR target

The binutils package provides all the low-level utilities needed in building and manipulating object files. Once installed, your environment will have an AVR assembler (avr-as), linker (avr-ld), and librarian (avr-ar and avr-ranlib). In addition, you get tools which extract data from object files (avr-objcopy), dissassemble object file information (avr-objdump), and strip information from object files (avr-strip). Before we can build the C compiler, these tools need to be in place.

Download and unpack the source files:

~> bunzip2 -c binutils-<version>.tar.bz2 | tar xf -
~> cd binutils-<version>

Note: Replace <version> with the version of the package you downloaded. If you obtained a gzip compressed file (.gz), use gunzip instead of bunzip2.

There are 2 patches that need to be run before you can compile the binutils. From this URL:

Download the patch files called patch-newdevices.txt and patch-avr-coff.txt, and save them in the binutils-<version> directory. Apply the patches with:

~> patch -p0 < patch-newdevices.txt
~> patch -p0 < patch-avr-coff.txt

Now you are ready to compile binutils. It is usually a good idea to configure and build binutils in a subdirectory so as not to pollute the source with the compiled files.

~> mkdir obj-avr
~> cd obj-avr

The next step is to configure and build the tools. This is done by supplying arguments to the configure script that enable the AVR-specific options.

~> ../configure --prefix=$PREFIX --target=avr --disable-nls

When configure is run, it generates a lot of messages while it determines what is available on your operating system. When it finishes, it will have created several Makefiles that are custom tailored to your platform. At this point, you can build the project.

~> make

Note: BSD users should note that the project's Makefile uses GNU make syntax. This means FreeBSD users may need to build the tools by using gmake. If the tools compiled cleanly, you're ready to install them. If you specified a destination that isn't owned by your account, you'll need root access to install them. To install:

~> sudo make install

You should now have the programs from binutils installed into $PREFIX/bin.

GCC for the AVR target

Warning: You must install avr-binutils and make sure your path is set properly before installing avr-gcc.

The steps to build avr-gcc are essentially same as for binutils:

~> bunzip2 -c gcc-<version>.tar.bz2 | tar xf -
~> cd gcc-<version>

At this point there is another patch for avr-gcc. Download the file patch-newdevices.txt (different from the patch for binutils of the same name) from here:

Move the patch file into the gcc-<version> directory and apply it with:

~>patch -p0 < patch-newdevices.txt

Now, you can compile avr-gcc:

~> mkdir obj-avr
~> cd obj-avr
~> ../configure --prefix=$PREFIX --target=avr --enable-languages=c,c++ --disable-nls --disable-libssp --with-dwarf2
~> make
~> sudo make install
avr-libc

Warning: You must install avr-binutils, avr-gcc and make sure your path is set properly before installing avr-libc.

To compile and install the avr-libc

~> tar xzf avr-libc-<version>.tar.gz 
~> cd avr-libc-<version>
~> ./configure --prefix=$PREFIX --build=`./config.guess` --host=avr
~> make
~> sudo make install
avrdude

avrdude is the application that downloads the compiled code from you computer into the AVR's program memory. To compile and install it:

~> tar xzf avrdude-<version>.tar.gz 
~> cd avrdude-<version>
~> mkdir obj-avr
~> cd obj-avr
~> ../configure --prefix=$PREFIX
~> make
~> sudo make install

Windows

We generally don't support Windows at CCRMA, but there are a number of excellent tools available for developing for AVR microcontrollers on Windows.

AVRStudio

AVR Studio is a free IDE from Atmel for developing AVR applications on Windows. It is built on top of the avr-gcc compiler and features a full suite of tools to help write, edit, debug and download programs to AVR microcontrollers.

WinAVR

WinAVR is a collection of open source tools for developing AVR applications on Windows. It includes avr-gcc, avrdude, and a variety of other tools, and has a one-click installer. To set up your system to do development with WinAVR:


1. Download the most recent installer from the WinAVR SourceForge Site.

2. Run the WinAVR installer.

  • To minimize problems, install WinAVR into a new home directory you create and choose without spaces in the path (e.g. c:\ccrma).
  • If you are running Win2000 or WinXP, it is recommended that you install WinAVR with administrator access.

3. Add a windows environment variable that points to your new HOME directory. For most versions of Windows:

  • Right-click My Computer
  • Select Properties
  • Select the Advanced tab
  • Click Environment Variables
  • Click New to add a system environment variable
    • Variable name: HOME
    • Variable value: c:\ccrma (or whatever you chose as your home directory)

4. Download avrlib and place in your home directory.


It's a good idea to put the WinAVR tools in a directory path that has no spaces because spaces can cause problems with unix command-line parsing. It's a convention at CCRMA that avrlib lives in each user's home directory, so if you put avrlib in your designated windows HOME directory, you have less to change when you copy over AVR projects from your CCRMA Linux account.

Compiling and Downloading Programs

With the development tools properly installed, compiling and downloading programs to the AVR is easy. We will outline the steps involved in compiling the "button" program in the #avrlib-demos in Linux or Mac OS and downloading it to an AVRmini v4.

  • Connect the AVRmini to your computer with a USB cable and switch on the power of the AVRmini. You should see the red USB indicator LED flash a few times as the FT232R chip negotiates with the driver on your computer.
  • On your computer, open a terminal, and change to the directory where project you want to compile resides. In the example below, the avrlib-demos are in a directory called 250a in the user's home directory.
  • Type make in the terminal:
~> cd ~/250a/avrlib-demos/button
~/250a/avrlib-demos/button> make
  • You should see a bunch of output in the terminals, and hopefully a line that says
Errors: none

This means that the program compiled successfully. If you type ls in the terminal, you should see a file called button.hex that was created as a result of the compilation. This is the file that gets copied into the AVR's Flash memory.

  • To copy the compiled program into the AVR's Flash memory, you need to do the following steps in rapid succession:

1. Type make load in the terminal, but DO NOT press Enter.
2. Reset the power to the AVRmini by momentarily pressing and releasing the Reset button.
3. Press Enter on your keyboard (within 3 seconds of pressing the Reset button).

You should see a bunch of text written to the terminal, including three progress indicators made up of # characters.

Modifying the avrlib-demos

To write your own programs for the AVR, it is normally easiest to use one of the avrlib-demos as a starting point. It is best to leave the avrlib-demos intact and make a copy of the entire project directory before you modify it. For example:

~/250a> cp -r avrlib-demos/button ./mybutton

It is a good idea at this point to remove any files that were generated by previously compiling the program. You can do this by typing make clean in the terminal. This should leave only button.c, global.h and makefile in the directory.

Now, you probably want to rename button.c to mybutton.c. In our classes, it frequently happens that someone is editing one program but compiling and downloading another, because they both have the same name. It is not required that the directory and the .c file have the same name, but it makes it easier to keep track of your programs.

The last step is to modify the makefile to reflect the new name of the .c file it is going to issue instructions to compile. Open the makefile in an editor. On line 26, you will see the text

        TRG = button

If you have changed the name of your program to be mybutton.c, then this line should be changed to

        TRG = mybutton

Note that the .c suffix is omitted. Now you are ready to modify and compile your new mybutton program.

Common Errors

avrdude: ser_open(): can't open device "/dev/ttyUSB0": No such file or directory
make: *** [load] Error 1

This will happen if you don't have a device named /dev/ttyUSB0 on your system. This can occur for a number of reasons:

1. You are using Windows or Mac OS, and the FTDI Virtual Com Port Driver is not installed. Get the appropriate one for your operating system and try again.

2. The FT232R chip on your AVRmini hasn't established itself with the system. Try turning off and turning back on the power to the AVRmini (not with the Reset button, but with the actual power switch). If this doesn't help, try typing

~> ls /dev/tty*

to see a list of all the tty devices on your system. If you don't see one that resembles a USB device, then the FTDI Virtual Com Port Driver is not installed or not working. For Linux kernels greater than 2.4.20, it is included in the kernel, so no additional installation should be necessary. See the FT232R support for more information.

3. You are using Windows or Mac OS, and the name of the USB device is different than the default in the project makefile. On line 30 of the default project makefile, you will see

        AVRDUDE_PORT = /dev/ttyUSB0

Comment out the above line (with a # character) and add a line with the name of the device on your system, i.e.

 #       AVRDUDE_PORT = /dev/ttyUSB0
         AVRDUDE_PORT = /dev/tty.usbserial-A30007PY
  • On most Macs, the device appears as /dev/tty.usbserial-A30007PY. Type ls /dev/tty* in a terminal to make sure.
  • In Windows, it appears as a COM device. Check in your Windows Device Manager for the COM port number. If, for example, it is COM3, your makefile should be changed to
 #       AVRDUDE_PORT = /dev/ttyUSB0
         AVRDUDE_PORT = COM3

Communicating with Pd via OSC over USB

With the AVRmini v4, we most commonly send data formatted according to the OpenSound Control (OSC) protocol to a computer over USB. To program the AVR to send OSC messages, see the osctest program in the #avrlib-demos

On the computer, we normally use Pd (sometimes referred to as Pure Data) to receive OSC messages from the AVR. Pd doesn't have built in objects for doing this, so we use our own external objects. These externs have been designed to mimic way the udpreceive and OpenSoundControl objects work together in Max/MSP. There are 2 objects:

  • serialIO -- A general purpose object for sending and receiving serial data from a /dev/tty device. For receiving, it has an OSC mode in which it parses the data looking for OSC messages. When it finds one, it stores the data in a buffer and outputs a list consisting of the symbol "FullPacket", the length of the message in bytes and a pointer to the buffer where the data is stored.
  • OpenSoundControl -- An object both for parsing incoming OSC packets and creating OSC packets to be transmitted. Incoming OSC packets can be received from the serialIO object, or a Max-style udpreceive object (yet to be written). Outgoing packets can similarly be transmitted over a serial port via serialIO, or through a network socket.

If you want to compile the objects from source, or help develop them, the source is available in an svn repository at CCRMA. To check out a copy, use:

~>svn co file:///usr/ccrma/group/pid/svn/pd ./pd_OSC_serial 

Or, you can download the source from pd_OSCserial_src20070810.tar.gz. If you want to develop these objects at CCRMA with the subversion repository, you must belong to the pid group. E-mail gurevich (at) ccrma and carrlane (at) ccrma to request to be added to the group.

Linux Machines at CCRMA

The serialIO and OpenSoundControl objects are installed in the directory /usr/ccrma/courses/250a/pd/externs. In order to use them, make sure that this directory is in your Pd path. You can do this by adding the following to the .pdrc file in your home directory (in an editor)

-path /usr/ccrma/courses/250a/pd/externs

or, through the dialog box in Pd from the File->Path menu. See the help patches for these objects, or osctest.pd from the avrlib-demos for more info.

Mac OS X or other Linux

Download pd_OSCserial_externs20070810.tar.gz. Decompress the tarfile and copy the externs for your system into a directory in your Pd path. On Mac OS X, I put the .pd_darwin files in /Library/Pd/Externals and the help patches in /Library/Pd/Help.

Windows

Unfortunately, these objects have not yet been compiled for Windows. Until they are, you can use a small utility program that receives incoming serial data and sends it to a network port as UDP data.

  • Copy the file serialosc2udp.exe to your C:\ccrma\bin
  • Open the Windows command window and Run from the command line: "serialosc2udp.exe COM# localhost 999" where '#' is your serial com port number.
  • Shut down your firewall
  • In Pd, make sure you have the standard OSC objects installed. Create a "dumpOSC" object with port "999" as the argument.

Communicating with Max/MSP via OSC over USB

Mac OS X

The serialIO object has been compiled as a Mac OS X Universal Binary and tested in Max 4.6 and Max 5 on an Intel-based MacBook Pro and iMac. It should be used in conjunction with the CNMAT OpenSound Control objects.

Windows

Untested yet. see #Windows_2

Communicating via OSC over udp

Installing the STKload Bootloader

The only "catch" with our method of programming the AVR is that the bootloader must first be installed on the AVR. If you have an AVRmini v3.1 or v4 that you got from CCRMA, it probably already has the STK500-emulating bootloader installed, and you don't need to do anything.

Note that you don't need a bootloader to program your AVR. You can use #ftisp or any of the methods we are about to describe for installing the bootloader. Otherwise, to install the bootloader, first you need to do download it from http://hubbard.engr.scu.edu/embedded/avr/bootloader/index.html. At CCRMA, we use an ATMega644 with a 14.746 MHz clock and the "New V1" bootloader: http://hubbard.engr.scu.edu/embedded/avr/bootloader/v1/stkload_m644_2k64k_14745600.hex. If you have a different AVR chip or clock speed, download the one that is appropriate for you.

AVRISP

The easiest way to install a bootloader is with an external programmer such as an AVRISP mkII. With #uisp, the command would be as follows (note, these are untested, as we do not have an AVRISP mkII to test with at CCRMA). First, erase the chip:

~> uisp -v -dpart=atmega644 -dprog=avrisp -dserial=/dev/ttyUSB0 --erase

Then, upload the bootloader:

~> uisp -v -dpart=atmega644 -dprog=avrisp -dserial=/dev/ttyUSB0 --upload if=stkload_m644_2k64k_14745600.hex

With avrdude, it would be something like:

~> avrdude -v -F -p m644 -c avrisp2 -P /dev/ttyUSB0 -Uflash:wstkload_m644_2k64k_14745600.hex

After installing the bootloader, you need to set the lock bits and fuses appropriately. See below.

PonyProg-Style Programmers

Another convenient way to program the AVR is with so-called bit-banging methods that emulate the behavior of real serial communication devices. One of the most popular bit-banging methods is associated with the PonyProg software and associated SI-Prog hardware. The SI-Prog hardware is very simple, and the circuit can be copied on a breadboard or assembled on a piece of perf board. If you have an AVRmini v2, v3, or v3.1, the SI-Prog hardware is built into the board. These boards have a second DB9 serial connector for programming via this interface. To use this method, your computer must have an RS232 serial port. USB-Serial adapters generally don't work for this application. As mentioned above, you could use this method for everyday programming, not just for installing the bootloader.

If you want to install the bootloader on an AVRmini v4 and you happen to have an older AVRmini v2, v3 or v3.1 lying around, you can use a shortcut instead of buying an AVRISP or building the SI-Prog circuit. First, remove any socketed AVR chip from the AVRmini v2, v3 or v3.1. Then, with a ribbon cable, connect the 10-pin "ISP" header to the 10-pin "AVR ISP" header on the AVRmini v4. Now, you can install the bootloader on the AVRmini v4:

With uisp:

~> uisp -v -dprog=dasa2 -dpart=atmega644 -dlpt=/dev/ttyS0 --erase
~> uisp -v -dprog=dasa2 -dpart=atmega644 -dlpt=/dev/ttyS0 --upload if=stkload_m644_2k64k_14745600.hex

With avrdude:

~> avrdude -v -F -p m644 -c siprog -P /dev/ttyS0 -Uflash:w:stkload_m644_2k64k_14745600.hex

Setting the Fuses and Lock Bits

After installing the bootloader, your AVR chip must be configured to run the bootloader code when it powers on, to know how much memory it occupies, and to allow the bootloader to overwrite the rest of the AVR's Flash memory. The following commands show how to set the fuses and lock bits for the stkload_m644_2k64k_14745600.hex bootloader on an ATMega644 with uisp and avrdude. You can also use the PonyProg software itself or AVRStudio. If you have a different AVR device and bootloader, you'll have to refer to the specific device's datasheet to find out what byte values to use. These instructions also assume SI-Prog-style programmer hardware. For AVRISP, change the flags for uisp and avrdude accordingly.

With uisp:

~> uisp -dprog=dasa2 -dpart=atmega644 -dlpt=/dev/ttyS0 --wr_fuse_l=0xbf
~> uisp -dprog=dasa2 -dpart=atmega644 -dlpt=/dev/ttyS0 --wr_fuse_h=0xc2
~> uisp -dprog=dasa2 -dpart=atmega644 -dlpt=/dev/ttyS0 --wr_lock=0xef

To verify the fuses and lock bits, the output of

~> uisp -dprog=dasa2 -dpart=atmega644 -dlpt=/dev/ttyS0 --rd_fuses

should be

Atmel AVR ATmega644 is found.

Fuse Low Byte      = 0xbf
Fuse High Byte     = 0xc2
Fuse Extended Byte = 0xff
Calibration Byte   = 0xc4  --  Read Only
Lock Bits          = 0xef
    BLB12 -> 1
    BLB11 -> 0
    BLB02 -> 1
    BLB01 -> 1
      LB2 -> 1
      LB1 -> 1


With avrdude:

~> avrdude -v -F -p m644 -c siprog -P /dev/ttyS0 -Ulfuse:w:0xbf:m -Uhfuse:w:0xc2:m 
~> avrdude -v -F -p m644 -c siprog -P /dev/ttyS0 -Ulock:w:0xef:m