Compiling with WebbotLib without using AVR Studio.

Who should use this document?

This document will be of use to anyone who cannot (or will not) use Atmel's excellent and free AVR Studio.

This will be mostly relevant to people using Linux, BSD or Apple Mac operating systems.
It will also be useful background reading for anyone using AVR Studio who want's to know what is going on in the background or anyone setting up a different IDE.

What does this do?

The instructions in this document explain how to combine code written for AVRs using WebbotLib with the compiled processor specific static library without using AVR Studio.

If you are new to this and running a windows PC, do your self a favor and use AVR Studio as documented in the PDF included with WebbotLib.

What this document does NOT do.

This document does not contain information on uploading compiled code to an AVR.

This document will presume you can decide which parts of WebbotLib's official documentation are still relevant. For a new user to WebbotLib it is recommended you build the same sample "Hello World" program found in the WebbotLib .pdf and use these intructions as a replacment for the AVR Studio specific parts.

The choices.

There are a few ways of acheiving building code for AVRs but they all involve manipulating the avr-gcc compiler and associated tools (an AVR specific compiler based on Gnu Compiler Collection).
Also required are the AVR LibC C libraries.

1. Implement avr-gcc and associated tools from the command line.
2. Use a Makefile to automate the gcc build process.
3. Use Apache Ant to automate the gcc build process. (Not discussed in this doc. A document on Ant will follow. ***Insert Future Link Here***)
4. Run AVR Studio in Wine. (Not recommended for new users. See "Further reading" section at end.)
5. Configure an IDE other than AVR Studio. (See "Other methods of building your project" section at end.)

In this document we will discuss 1. and 2. from the list above.

System requirements.

Before you start make sure the following software tools are installed:

1. The Gnu Compiler (AKA GCC.)
2. BinUtils (AVR specific versions of GCC tools.)
3. AVR LibC (AVR C libraries.)

These tools are all available under some sort of Open Source license so are free to use.
4. WebbotLib (This is why we are here right?)

This page http://electrons.psychogenic.com/modules/arms/art/3/AVRGCCProgrammingGuide.php provides a more thorough description of these components.

Installing these components varies a little depending on your platform.

Linux.

Depending on your distribution use your package manager to search for the 3 tools listed above.

On Ubuntu for example the requirements can be met as follows:

$ sudo apt-get install binutils-avr gcc-avr avr-libc

Next unpack WebbotLib somewhere that makes sense on your system.
Follow the advice in WebbotLib-x-xx.pdf: install WebbotLib once and link to it rather than copying it into every project.
On my Linux system i keep it here: /usr/lib/avr/lib/ but it is equally correct to keep it in your home directory. The important thing is it stays in the same place and has the same folder name when you upgrade WebbotLib so it does not break your build scripts.

$ sudo unzip /tmp/webbotavrclib-1.14a.zip -d /usr/lib/avr/lib/WebbotLib/

Mac.

Follow the instructions here to install CrossPack: http://www.obdev.at/products/crosspack/index.html
To install WebbotLib,
*** Need Volunteer for this bit. Please contact me if you can fill in the deatails. mrdunk(at)gmail.com***

Windows.

Are you guys still here? I thought we told you to use AVR Studio...
Free Windows packages can be found for all these tools as well. Search and ye shall find.
Unpack WebbotLib somewhere that makes sense on your system.

Hello World.

For your first WebbotLib program read WebbotLib-x-xx.pdf included in your WebbotLib package. Read the stuff on AVR Studio as well so you get an idea of what we are trying to achieve.

From here on i will presume you have the sample Hello World program from WebbotLib-x-xx.pdf in a folder called "~/Geek_projects/avr_projects/WebbotLib_test" and saved it with the filename "main.c".
I will also presume you have installed WebbotLib in the directory /usr/lib/avr/lib/WebbotLib.
Edit these instructions to suit you install directories and filenames.

Method 1.

Implement avr-gcc and associated tools from the command line.

All other methods of building code for the AVR use this method in the background so it makes sense to start here.

Information you need to know at this point are:
1. The name and directory of your project file. (~/Geek_projects/avr_projects/WebbotLib_test/main.c for this example.)

2. The Install directory of WebbotLib. (/usr/lib/avr/lib/WebbotLib/ for this example.)

3. The speed your AVR is running at. You may need to refer to your MCU board documentation to find this out. (16000000Hz or 16MHz in this example.)

4. The AVR type in a format the avr-gcc tools will understand.
This command will give you a list with the correct format:

$ avr-as --help

5. The name of the pre-compiled WebbotLib static library to match your AVR.
These can be found in the top directory of your WebbotLib source file using:

$ ls -l /usr/lib/avr/lib/WebbotLib/*.a

Pick the one that matches your target. (You may need to refer to your MCU board documentation to see which AVR it uses.)

** Important Point.** When you use these static libraries (the .a files) on the command line avr-gcc will expect them *without* the leading "lib" and *without* the trailing ".a".
So "libWebbot-ATMega2560.a" becomes "Webbot-ATMega2560".

Ok, we are all set.
*Drumroll.*
Change to your project directory. ("~/Geek_projects/avr_projects/WebbotLib_test/" in this example.)

1. Compile your code:

$ cd ~/Geek_projects/avr_projects/WebbotLib_test
$ avr-gcc -I"/usr/lib/avr/lib/WebbotLib" -c main.c -mmcu=atmega2560 -Wall -gdwarf-2 -std=gnu99 \
-DF_CPU=16000000UL -O0 -funsigned-char -funsigned-bitfields -fpack-struct -fshort-enums \
-MD -MP -MT main.o -MF main.d

If all goes well avr-gcc should return with no message. If you see errors then something has gone wrong.

You are looking for the creation of the new file "main.o".

2. Link your code. This step links your new "main.o" with the pre-compiled "libWebbot-ATMegaXXXX.a".
**Remember, "libWebbot-ATMega2560.a" becomes "Webbot-ATMega2560" for the "-l" flag.**

$ avr-gcc -mmcu=atmega2560 -Wl,-Map=WebbotTest.map main.o -L"/usr/lib/avr/lib/WebbotLib" \
-lWebbot-ATMega2560 -lm -lc -o main.elf

Again avr-gcc will quit with no errors if things work. No news = Good news.
Check for the creation of "main.elf".

3. Convert your .elf file into an AVR readable Intel HEX file.

$ avr-objcopy -O ihex main.elf main.hex

avr-objcopy will quit with no errors if things work.
Check you have a file called main.hex.
If it exists you are done. That's the file to upload to your AVR.

A point to note: When linking the Webbot-ATMegaXXXX library with your "main.o" file, the order *is* important. The "main.o" comes first.
A point to note: avr-gcc *will not* overwrite files. To rebuild or relink files you will have to delete the old ones first.
A point to note: Everything you do on Linux or Mac is case sensitive.

Method 2.

Use a Makefile to automate the gcc build process.

Q. What does this do that Method 1. did not?
A. It simplifies the process making you less likely to make a mistake while compiling but at the expense of setting up a Makefile.

The following is a Makefile in it's simplest form. Copy and paste it into a file called "Makefile" in your project's directory.

# Name: Makefile
# Created: 12/FEB/2010 to work with WebbotLib-1-15
# Last Updated: 12/FEB/2010

# PROJECT is the program file name used without the .c
# Choose TARGET to match your MCU from this list: atmega8, atmega32, atmega168, atmega640, atmega329p, atmega2560, atmega2561
# Choose LIBRARY to match your MCU from this list: Webbot-ATMega8, Webbot-ATMega32, Webbot-ATMega168, Webbot-ATMega640, Webbot-ATMega328P,Webbot-ATMega2560, Webbot-ATMega2561
# CPU_SPEED is in Hz. 16MHz = 16000000. 8MHz = 8000000. 1MHz = 1000000
# WEBBOTLIB is where you unpacked WebbotLib.

PROJECT = main
TARGET = atmega2560
LIBRARY = Webbot-ATMega2560
CPU_SPEED = 16000000
WEBBOTLIB = /usr/lib/avr/lib/WebbotLib/

# If your system has problems finding avr-gcc, specify the full path here.
GCC = avr-gcc
LINKER = avr-objcopy

COMPILE = -Wall -I"$(WEBBOTLIB)" -mmcu=$(TARGET) -Wall -gdwarf-2 -std=gnu99 -DF_CPU=$(CPU_SPEED)UL -O0 -funsigned-char -funsigned-bitfields -fpack-struct -fshort-enums -MD -MP

LINK = -L"$(WEBBOTLIB)" -mmcu=$(TARGET) -Wl,-Map=WebbotTest.map -l$(LIBRARY) -lm -lc

# symbolic targets:
all:    link

compile:
        $(GCC) $(COMPILE) -c $(PROJECT).c -o $(PROJECT).o -MT $(PROJECT).o

link: main.elf compile
        $(GCC) $(PROJECT).o $(LINK) -o $(PROJECT).elf

copy: main.hex link
        $(LINKER) -O ihex $(PROJECT).elf $(PROJECT).hex

clean:
        rm -f main.elf main.hex main.lst main.obj main.cof main.list main.map main.eep.hex main.bin *.o main.s

main.elf:
        rm -f main.elf

main.hex:
        rm -f main.hex

Don't worry if it looks complicated.
The bits you have to worry about are the Lines labeled PROJECT, TARGET, LIBRARY, CPU_SPEED and WEBBOTLIB. Edit these to match your project.
If you have called your first program "main.c" and installed WebbotLib in "/usr/lib/avr/lib/" you are already set on 2 of them.

Next build your project by typing:

$ make

You will see avr-gcc commands like in Method 1. Hopefully no errors.

If you want to delete all the working files so you can build from scratch issue:

$ make clean

If you just want to compile the "main.o" file without linking it for whatever reason:

$ make compile

It is beyond the scope of this document to go into detail on how to write a Makefile but the one included here is enough to build simple projects with WebbotLib.

Other methods of building your project.

Use Apache Ant to automate the gcc build process.
Ant is used by Webbot to build the WebbotLib static libraries. As a tool it is far better suited to building projects with multiple dependencies.
For more information about using Ant to build WebbotLib look here:
http://www.societyofrobots.com/member_tutorials/node/382

Run AVR Studio in Wine.
This is possible.
According to WineHQ.org if you get the right version of Wine and the right version of AVR studio it will run without problems.
http://appdb.winehq.org/objectManager.php?sClass=application&iId=402
My experiment today for this article with Wine-1.1.38 and AVR Studio 4.18 was barely usable with particular issues using the mouse when selecting files. (Things usually worked when i entered file paths and names by the keyboard.)
So in summary, i advise against Wine unless you have exactly the versions of everything recommended by WineHQ.

Configure an IDE other than AVR Studio.

I have had good success with KontrollerLab on Linux. It integrates with most hardware programmers and has a serial console built in.

The down side of KontrollerLab is it is not possible to include external libaries (like WebbotLib) by default so you will be left hacking about with external Makefiles. It is posible to use external Makefiles from within KontrolerLab but it's a messy solution.

My current recomendation is Eclipse with the AVR plugin.
Eclipse runs on Windows, Mac, Linux, etc.

It is very very good once set up, integrates with Apache Ant, most hardware programmers and many other plug-ins.
The down side of Eclipse is that because it has an option for everything it takes a long time to set up.

At some point i intend to write a doc on how to set up Eclipse to work with WebbotLib but if anyone feels the need to do this first then please do.