Install the AVR tool chain

You want to compile from Linux a software for the AVR processors. Therefore you need to install a complete development environment for the AVR processors. The AVR has a very good support from the open source community. There's a complete GNU Tool Chain and a very good C library called AVR Libc. There are multiple ways to get it working, so follow what suits you.

The manual way

To install the GNU tool chain, follow the instructions given at http://www.nongnu.org/avr-libc/user-manual/install_tools.html

Notes:

1. read the firsts paragraphs about the prefix, don't blindly use 'PREFIX=$HOME/local/avr' unless you haven't root access to your computer;
2. use the latest GCC-4.1.1 as that's the version we're using for the firmware;
3. both binutils and GCC have now support for the ATmega88 that we use, there's no need to apply the patches for recent AVR devices;
   
4. the dwarf2 implementation of GCC is currently broken, there's a patch at http://gcc.gnu.org/bugzilla/show_bug.cgi?id=26504 but dwarf2 is only used by AVRStudio on Windows, under Linux you don't really have any use of dwarf2 so simply drop the '--with-dwarf2' option there;
5. you don't need uisp, avrdude, GDB and AVaRice, those tools are to be used with AVR programmers and debuggers; Tux Droid has it's own uploader called tuxup to bootload new firmware;
6. I don't think there's any use of Simulavr neither as it doesn't support the ATMega88
7. if you used 'PREFIX=/usr/local/avr', you will need to update the path and manpages path in your profile. Just add the following to your /etc/profile or ~/.bashrc
   Check with 'echo $PATH' that you have '/usr/local/avr/bin' in your path
   

   export PATH="/usr/local/avr/bin:$PATH"
   export MANPATH="/usr/local/avr/man:$MANPATH"

8. depending on your distro, there are maybe other things to do to get everything compiling:
   
   • Ubuntu users will have to install build-essential: 'sudo apt-get install build-essential'
     

At this point, you should now have a complete AVR tool chain. You can test it with the examples given by avr-libc. Just try to compile them to know if everything works fine. Check with 'echo $PATH' that you have '/usr/local/avr/bin' in your path, otherwise start a new terminal window or re-login (or source /etc/profile or your .bashrc file). Then copy the demo example and try to compile it.

# cd
# cp -r /usr/local/avr/share/doc/avr-libc-*/examples/demo .
# cd demo
# make

You shouldn't get any error if you did it right.

The script way

There's a script to download, patch and compile all necessary tools of the AVR GNU tool chain. It's in a sticky post at http://www.avrfreaks.net in the AVR GCC Forum: Script for building AVR-GCC 4.1.1 on Linux. I didn't try it but it should work. You need an account on avrfreaks to download it though, but anybody who wants to do AVR dev should have one anyway.

The distro way

Some distros should have binaries of the AVR tool chain packaged. If you got it working that way, please add a comment or a post on the forum to tell us how you did and we'll add this information here.

• Gentoo users should be able to emerge avr-libc though I couldn't get crossdev to compile a toolchain based on GCC-4.1.1, I always got 3.4.6. If someone can get it that way, please send me the details.
• Debian, Ubuntu, Knoppix, SELinux users can use apt as root (or sudo) to get the following packages: (not tested!)
  

  # apt-get install gcc-avr
  # apt-get install avr-libc
  # apt-get install gdb-avr

• Red Hat based systems like Fedora Core, SuSe, Mandrake can use YUM as root: (not tested!)
  

  # yum install avr-gcc
  # yum install avr-binutils
  # yum install avr-libc
  # yum install avr-gdb

Getting the sources from SVN

If you don't have subversion (SVN), it's time to install it. (check your distro if you don't know how)

Then simply checkout the firmware from the repository, replace tuxfirmware with the name you want:

# svn co http://svn.tuxisalive.com/firmware tuxfirmware

SVNWCRev

Each firmware includes the revision number at build time in the svnrev.h file. In order to extract it from SVN, we use a small utility called SVNWCRev available at http://svnwcrev.tigris.org/.

SVNWCRev is a port of the SubWCRev.exe tool of TortoiseSVN to Linux. It can be used to read the status of a Subversion working copy and optionally perform keyword substitution in a template file. This is often used as part of the build process as a means of incorporating working copy information into the object you are building. Typically it might be used to include the revision number in an “About” box. Here we use it to include the revision number and status in the hex file so that they can be retrieved through the tux API.

To compile the firmware, you'll have to install SVNWCRev. Download the tar file from the link above, extract it and follow the instructions in the 'INSTALL' file. You'll need the subversion and apr libs to be installed. Then copy the 'svnwcrev' executable in the '/usr/local/bin' directory or anywhere in your path. Basically, this should work:

# wget http://svnwcrev.tigris.org/files/documents/3444/29110/svnwcrev-0.1.tar.gz
# tar -xzvf svnwcrev-0.1.tar.gz
# cd svnwcrev-0.1
# cp config_mk.template config.mk
# make
# cp svnwcrev /usr/local/bin/

Note:

• Ubuntu users should install subversion and the libsvn0-dev packages to be able to compile.
• Debian Etch users should take the more recent libsvn-dev package and edit config.mk to point to the right headers:
  

APR_INCLUDE=/usr/include/apr-1.0

Compile the firmware

Well, now that everything is ready, here's the easy part. You should simply be able to build the 'core' or 'audio' firmware by typing 'make' inside the respective folders.

Go to the trunk folder of one of the firmware files and type 'make'. You should end up with a bootloader.hex and the hex and eep files of the firmware. (i.e. core.hex and core.eep) Those files are ready to be programmed with Tux Droid's bootloader.

The eep file is the eeprom data and is in ihex (intel hex) format as is the hex file. The eeprom can also be programmed with the bootloader.

Program the new firmware

I'm planning to add a program target in the makefile itself to be able to do a 'make program' and get it uploaded directly in Tux. But for now, follow the instructions of the 'Updating the firmware' how-to.

Compiling under Windows

Yes, it's possible to compile the firmware under Windows. The excellent WinAVR package is a compilation of all the UNIX tools above and much more. You can even use AVRStudio from Atmel as an IDE. Many people use Windows to develop for the AVR.

Unfortunately the use is rather limited as after compiling you'll need to switch to Linux to be able to program the firmware with the bootloader but mainly to be able to use your Tux Droid.

Debugging your code

Currently there's nothing to help you debug your code. In the future, we would like to add some debug functions to be able to send some messages to the computer and display them in real time. That should be done soon.

If you're a newbie regarding AVR programming and want to learn that with Tux Droid, then my first suggestion would be to start from something that works and gradually add/change things and regularly check if Tux does what is supposed to. Then use what you can to add some debug code, use the blue led's or movements. Look at the resources given at the bottom of the page to get started.

Programming or debugging with specific hardware

If you're an experienced AVR developer and have your own programmer for the AVR, you can of course program all AVR's directly through the ISP connectors available on the mainboard but you'll have to open your Tux Droid. Needless to say you should be very careful with the ESD, the wires lying around, etc. and that you can do much damage we can't be responsible for. Tux can get crazy, your wife may be afraid and leave, your fridge can explode and your house can burn. But if you still want to get further, here are some tips that may be helpful to you.

ISP programming

The mainboard has 3 ISP connectors. The left hand bottom connector is for the 'core' CPU and doesn't need any special care. The top left connector is for the 'audio' CPU and the top right connector for the 'RF'.

The 'audio' and 'RF' CPU's share the spi port which is also used for ISP. You should then remove the RF board when you reprogram the 'audio' CPU. Some times it works without, most of the time not, and I could once kill the 'audio' CPU completely that way, probably getting a completely wrong programming of the fuses. So just remove the RF board when you program the 'audio' CPU should get you safe.

Normally you shouldn't reprogram the 'RF' CPU but if you want to, then it's even more difficult. You should first remove the RF board, then erase the audio CPU so that the spi lines won't be used, replace the RF board and program it. Then remove again the RF board to restore the program of the audio CPU. That's a bit tedious so if you want to do that often, just build yourself an adaptor where you can plug the RF board directly.

ICD

To do In Circuit Debugging, you'll have to get specific hardware. The ATMega88 used on Tux Droid use the DebugWire protocol, not JTAG. You then need to have the expensive 'JTAG ICE mkII' or the new and cheaper 'AVRDragon' from Atmel.

Support of DebugWire under UNIX is still at an early stage and there are limitations. I personally didn't try it yet as it was not implemented when I started debugging. I will give it a try soon as that's certainly the way to go.

The best way I found so far to debug Tux Droid is to use a virtual machine running windows (like vmware) and debugging from AVRStudio. It can then be connected to the dongle under Linux and using the debugger from AVRStudio.

Resources

• AVR Libc Documentation

  You'll find the library reference there, but also the important FAQ and additional information. You'll also find the avr-libc mailing lists on the main page.

• AVRFreaks

  This is the place to discuss AVR and ask your questions. The forums have thousands of user posts; I can usually find all my answers there simply by doing searches.

• AVR Libc examples

  To get started, I would advise to check the examples given with AVR Libc. They are simple, though should also introduce you some advanced stuff. There's a very helpful documentation you should follow while you read the examples. And the FAQ will answer most of your questions and is a must read for everybody.

  The examples documentation is at http://www.nongnu.org/avr-libc/user-manual/group__demos.html and the examples should already be installed at '/usr/local/avr/share/doc/avr-libc-*/examples'.