Introduction: How to Get Started With Eclipse and AVR

About: Andrew is a software engineer by trade and prefers projects that are simple yet effective. Andrew's areas of interest include software systems that do complex things from simple input, aesthetically pleasing k…

Programming AVRs is fun, but sometimes the manufacturers development environments make code maintenance a chore. If your looking for a free, cross platform, high quality piece of software for programming AVRs Eclipse is a good choice.

Moving to an Integrated Development Environment (IDE), such as Eclipse is a logical step up from learning to program basic functions. By using an IDE you will be able to work easier and work with a range of tools inside the same program. you will be able to easily package and reuse your code and you will have access to advanced functions like refactoring and code analysis. For details on these benefits please have a quick skim over Step 12: Quick Tour of Cool Features.

In this instructable I will show you how to install and configure Eclipse to program AVR micro controllers (aka. Micro Controller Units or MCUs). I will also provide a quick run through uploading to your MCU and I will briefly cover some of the cool feature Eclipse has to offer.

Step 1: Why?

Eclipse is cool. Like, really cool. Compared to something like the Arduino programming software, the Eclipse IDE is the proverbial Swiss army knife.

For example, the Arduino development environment only lets you work in one file at a time. Also if you want to rename a variable you have to do a find/replace. If you want to take some code and wrap it in a method, you have to do it by hand. Eclipse can help with these otherwise tedious tasks and more. More generally speaking, moving to a fully featured IDE like eclipse is a step up from less full featured environments.

Note: Yes, Eclipse can be used to program the Arduino - however the set up for this is slightly more complex and the specifics of using Arduino in Eclipse will not be covered here.

Step 2: Preparation

If you are operating on an office computer (i.e. in your place of work) you need to get permission to install software on your machine. It would also be prudent to check that the corporate firewall does not block http://Eclipse.org and http://sourceforge.net (just type these addresses into the address bar or click the links, if you get a warning from your firewall then you don't have access to these sites).

If you are working from a home computer with an internet connection and your computer has USB ports your good to go.

To program AVR devices you will either need a programmer and your AVR (two separate units) or an AVR with a programmer on board, like the Arduino. If you don't have either yet, I would advise looking into the Arduino or similar to get started. If you are at the beginner stage I would point you towards googling "getting started with Arduino" and taking it from there. Moving on to Eclipse is very much for when you are more sure footed about AVR development.

Brew up a cup (or glass) of your favourite beverage and hopefully we will be done installing before it gets cold, warm or whatever temperature it shouldn't be...well, we should be done at least before it sprouts mould.



Step 3: Download and Install Eclipse

Firstly we will need to download Eclipse itself. I recommend having a separate workspace and Eclipse version because the AVR plug in seems to corrupt both the Eclipse installation and the workspace over time (every now and again the installation inexplicably breaks, taking the workspace with it). So if you have eclipse already I would advise having a second copy on your computer and an 'AVR workspace' for AVR development so that any failures breakages are contained to AVR workspace. More on these issues later.

Go to the eclipse website and find the downloads page (at the time of writing this is here; http://www.eclipse.org/downloads/packages/release/helios/r). The list of versions contains an entry titled "Eclipse IDE for C/C++ Developers", next to it there should be a one or more links. Click the "32 bit" option for the platform that you are running (for example click the 32 bit link next to "Windows:" if you are running a Windows machine). This should take you to the download page.

Near the top of the download page should be some text reading "Download eclipse-cpp-helios-linux-gtk.tar.gz from:" followed by a link titled ...Mirror Service...(http) or similar. Click the link and the download should begin.I will refrain from posting a link because Eclipse is updated fairly regularly, so you need to check this page to get the latest version.

Once downloaded, you need to extract the Eclipse program from the compressed file you downloaded. This step differs depending on operating system, but broadly, if you double click on the download an extractor program will open.  Extract the program to an appropriate place, for Windows users the Programs folder is acceptable. Open the eclipse folder that you just extracted and double click the eclipse executable. Eclipse will now start.

Note: It is a good idea to make a desktop short cut that runs the executable, to save time and effort later.

The start up screen will ask you where to find a workspace. If you do not know what this is leave this as it is and press OK. For the more experienced programmers, a word to the wise; Back-up your workspace either with version control or even just a local copy and avoid using an existing work space.

Step 4: Install AVR-GCC and AVR Dude

The AVR GCC toolchain is the compiler that is used to compile data suitable for AVR's. AVR-dude is a tool for putting that information onto your AVR (basically it communicates with the AVR via the physical programmer).

Windows
On a Windows machine simply go to the WinAVR site and follow the installation instructions. WinAVR(Help page here and download page here) has both of the above and a few extra bits to make things like debugging easier. Now go to the next step (the stuff below is for Linux users)!

Linux
On Linux it is necessary to install the packages required manually, however the effort involved is no that much different. Go to your Package Manager and install the following;

- gcc-avr
- binutils-avr
- gdb-avr
- avr-libc
- avrdude

Step 5: Note About the CDT Plugin

Some instructions you find online indicate that at this point you should install the C\C++ Development Tools (CDT) plug in. This is not necessary in this case because we have downloaded the C\C++ version of Eclipse, which already has it installed. So... no instructions here, go to the next step...Stop hanging round here...we have installing to do!

Step 6: Install AVR Plugin


The AVR plug in allows us to easily deal with AVR's from within Eclipse. Once installed it will allow you to build and deploy a C project to an AVR device. There are also neat features such as being able to pull up data on chips without having to refer to the data sheet.

To install the AVR plugin go to top menu in Eclipse, select Help>Install New Software. A new window titled Install will open. Near the top is a drop down box with "work with:" to it's left. Click the box and type http://avr-eclipse.sourceforge.net/updatesite/ then click add. In the pop up box that appears type AVR Eclipse Plugin into the "name" box.

In the box below an entry (CDT Optional Features) should appear after a short while. Select the check box directly to the left of this entry and click Next . The next screen asks if the selected new packages are correct. Press Next. The next page asks you to agree to the terms and conditions. Check the radio button next to 'I agree' and click Finish .

A progress bar will slowly fill up, indicating that eclipse is installing the plug-ins specified. If there are any security warnings just click OK or Continue. The security warnings just relate to the fact that the plugin is not authenticated, it's no big deal.

A pop up informing you that you need to restart eclipse will appear when the installation is complete. Select Restart Now. Eclipse will shut itself down and restart. When eclipse restarts it will ask you to select a workspace (either select your workspace if you want a different one to that suggested or if you don't know what this is just press OK). The AVR Plug in is now installed.

Now Eclipse has what it needs to talk to AVR's. Perhaps it's time for a celebratory post installation biscuit (or snack) to go with that beverage?

Step 7: Make a New Project

Now we have Eclipse set up what we still need to do is; create a project to hold our settings and files, Set up the project, create a blinky light application, load to an AVR.

A note on projects for people from an Arduino IDE background (Skip to next paragraph if you know about projects already); Projects separate code out for each piece of work we want to do. For example If I wanted to create a flashy light to adorn my mantle I would make a FlashyLight Project to contain it. Equally if I wanted to make fading lights to spruce up my desk I would make a project called FadingLights. The key difference from single files (like a sketch - i.e. a source file) is that the project can contain a bunch of settings and also any number of source files.Roughly, a project is a special folder and source files are the files put into them. We tell the Project what platform we are targeting (for example the Attiny2313), how we want to program it, what data we want to put in it's EEPROM, what fuse bit's we want to burn, and so on.

To create a new project Click File>New>C Project type a name for your project, such as BlinkyLight. Make sure the Empty Project option under AVR Cross Target Application is selected and click next. Deselect the Debug option (we don't need it at this point) then click Finish. If instead of clicking Finish, you click Next there are a number of settings that you can set, but we will set them manually in a minute (we need to set some other settings too, so we shall do them all at once).

Step 8: Set Build Settings

Now you should have a project called whatever you named it in the Project Explorer tab. Now we want to set the settings for this project, so right click on the project and select Properties (right at the bottom).

Click on the plus [+] sign next to C\C++ Build and click Settings. In the window that appears select the following;
Generate Hex File for Flash Memory
Print Size
AVR Dude

Deselect the other two options (we don't really need them). Click Apply (its near the bottom right, you may have to scroll down).

Now we have told Eclipse that we want it to generate a HEX file (this will be flashed to the device, it is the "compiled" version of our code), we have told it to use AVR Dude to write to our AVR and we have told it to tell us how big the compiled program is (this is sometimes useful if space is an issue).

Step 9: Set AVR Target Settings

Finally in setting up our project we need to tell Eclipse about the AVR we want to program and what we are programming it with. Select the plus [+] sign next to the AVR option to expand it. Select AVRDude. We don't have any configurations at this point so click New. Now select the programmer that you are using, if you are using an Arduino, it is on the list too. At the top of the page give a brief name and description, something such as "Arduino Programmer" "For programming a standard Arduino" would be fine - this is just so you know what it is for if you want to program using different devices from the same computer.

Note: You may need to specify a serial port if the defaut one doesn't work. First try these steps ignoring this note and then if it doesn't work retry and follow this note. The serial port can change (normally it's a fixed name with an incremental number like COM1). If you have multiple arduinos plugged in, or you have unplugged, replugged-in your arduino the number may have incremented. It can get confusing. The easiest method of finding the correct serial port name is to unplug all the arduinos except the one you want to program and then use the serial ports dropdown in the arduino software to find the name of the serial port. Once you have the serial port enter it into the appropriate box.

Click OK. Click Apply.

Now we will see whether our settings have worked - we will attempt to get the MCU to tell us what it is. Click the TargetHardware list item on the left of the screen. Make sure that your programmer is;
A) plugged in to the power(if necessary) and USB (or Serial).
B) turned on.
C) connected to your AVR target device.

Now click LoadFromMCU. If all has worked the device listed in the box should change to the device that is currently in your programmer. If it worked click Apply then click OK. If it didn't work, select the MCU from the list (it may be that your programmer does not support the Load From MCU feature) then click Apply and then click OK.

Your project is now set up and good to go.

Step 10: New Source File

Creating source and header files is very easy. Simply right click on the project or project folder that you want your new file to be created within, and click New>Source File. In the window that appears look for the type of file that you want to create, type in a name for your new file and click Finish.

Please note that you Needa file called main.c somewhere in your project, this is because that is the file that the compiler starts with. The compiler will compile main.c and any source files included within it. For an simple example of what to put in main.c try using the source listing from this page (for attiny2313). I have used this example in the pictures on this step.

Now that you have finished the code we need to build it. What is build you ask? Building a project is the act of compiling all of the source code and creating a "compiled" result. For normal C programmers you would build an executable file (an EXE for windows users). Since we are putting data onto an AVR we are building a Flash image. Before you hit build you will not see any errors in your code. After hitting build you will see that some lines are underlined in red. These are called "Compile Errors" - these are bits of code that are incorrect, because the compiler cannot understand them or has a problem with them.

Note about source files (again for people from an Arduino IDE background): Now that we have moved on from a single source file it's time to get serious about organising our code. Doing so is not hard and it means that when you want to make your project do something else (like adding a button to your blinky light). In C, the language that we are now using, the way to make code is to organise it into groups of "utility" files. Say we want to know if a number is a prime, if a number is a Fibonacci number and if a number is a square. Now imagine that we want to use these new methods in both the Blinky Light project and the completely separate Fading Light project. If you wanted to do this in the Arduino IDE the only realistic way would to be copy and paste your methods (which is kind of hard work). Further more it kinda sucks because if I discover that my method isAFibonacciNumber actually has a bug, I have to copy and paste the fix to both projects. Wouldn't it be easier if you could write a function once and use it many times? Well you can, and it's easy... We use source files and header files. We might make a source file called NumberUtilities.c . Number Utilities would contain all of the number crunching methods we might want to use. Now if I want to use Number Utilities all I need to do is import it once. The great thing is that if I need to make a change, or a fix then I need only do so once. For more help with C and AVR you may want to hit google, an AVR forum or your library. Remember that there is a links section at the end of this instructable!.

Step 11: Build and Upload to AVR

I assume you now have your project set up with at least a main.c file and some content in the main.c file. This step should be performed whenever you wish to build and/or flash your AVR device.

Next we need to build the project. What is this build of which you speak? It is the process of compiling the code. Effectively, turning the "source" code that we can (sort of) understand into binary machine code that the AVR can understand. Once we hit build the compiler will try to perform this task, sometimes however it will encounter problems in the source file. (An illustrative example is in the images attached to this step). In these situations the compiler will report an error (see the next step, "Compilation Errors" for help).

Click Project>Build All to build your project. After fixing any compilation errors click AVR>Upload Project To Target Device. The console tab should now fill up with green text describing the process that is taking place. If the upload process fails check that the device is definitely switched on and plugged in. If you are uploading to an Arduino, press the reset button just before you upload.

Your project should now be uploaded and on you device, plug it into a circuit and off you go! The bulk of the Instructable is now over. The remaining steps are informational (i.e. not instructional) and can be ignored if you are happy with the results you have got thus far.

If you want to make a new project after this point follow steps 6, 8 9 and 10. We can ignore step 7 because eclipse will remember the settings we applied the first time that we set the settings in step 7 and apply them to future projects. Remember when repeating step 8 that since we have already created a Programmer Configuration you can just select it in the Programmer Configuration drop down box instead of creating a new configuration like we did the first time round.

Step 12: Compilation Errors

What are compilation errors?
Compilation errors are errors that the compiler has detected during a build. A build is the process of taking all the written code and transforming (i.e. compiling) it to a single binary file that the AVR can understand. Compilation errors are only refreshed when you click Build and so after fixing a problem it is advisable to save and rebuild the project (If you don't eclipse gets confused).

Why do I get them?
Normally build errors are basic programming errors, for example look at the following code fragment;

if(1))
{
}


Notice how the if has two closing brackets but only one opening bracket? This would result in a compilation error. This is because the syntax is wrong, fixing this example would just require deleting one of the two closing round brackets. Once fixed save and rebuild the project - the underlining should be gone. If this error existed in a program you were trying to build, the first line if(1)) would be underlined in red. This indicates that there is an error on the line indicated. To get more detailed messages look for the Errors tab close to the bottom of the page.

In the errors tab you will see that there are a number of columns telling you information about each error line by line. If you double click an error in this window Eclipse will automatically open the file in question and highlight the problem line.

How do I fix them?
Normally errors that the compiler finds are syntax related - this means that fixing the errors is a relatively easy matter; Simply work out which syntax rule you have transgressed and fix it. If you are unsure of the solution post your problem in a forum, either on instructables or a dedicated C programming forum. Please do not use the comments section of this page to find help for programming problems. 

For helpful sites please see the links section.

Are there other types of error?
Yes...If the program you have coded behaves unexpectedly while it is running then it is suffering from what is known as a "runtime error" - an error that occurs while the program is running. These types of error are often much harder to diagnose, there are advanced tools for resolving this type error, however the use of such tools is beyond the scope of this instructable.

Step 13: Quick Tour of Cool Features

There are a number of cool features that I would like to briefly draw your attention to. These features are In some way directly helpful of useful for every day programming.

Refactor Method, File
Top of the list is Refactor. The idea behind refactoring is simple, if I refactor a method, I change it's name. More specifically, I type in a new name and eclipse updates all the references to that method. So if I wanted to rename the method  oldMethodName() I would select it's declaration, right click, Refactor>Rename thentype a new name (say newMethodName()) and click OK. Then Eclipse goes away replaces every call to oldMethodName() to newMethodName(). This feature is a real time saver. Refactor can also be used to turn a section of code into a method, and a number of variations on that theme.


Custom Perspectives
As you are no doubt aware the eclipse window is full of tabs and panes, and many many buttons. If you are not happy with the way these are laid out then you can simply move tem around with drag and drop. You can close tabs that you don't think you will need, and add ones that you think you will. If you want to make Eclipse a little less complex one of the easiest ways is to reorganise the way the windows are presented, aka. "perspective". You can save the new reorganised window and indeed have as many of these perspecives as you want.

AVR views (supported devices and MCU inspector)
The AVR plugin also adds two new tabs, one which contains a compatibility list of AVR devices and one which allows you to explore the features of an AVR micro-controller. These two tabs are quite useful if you quickly need a bit of info on the chips but you don't need all the verbose content of the data sheet.

Minimise and maximise panels in eclipse with double click
Panels in eclipse can be made full screen by double clicking the pane tab (at the top), and the process reversed by double clicking it again. This means if you want to code full screen, or you want to see the full list of errors you need only double click.

C\C++ Perspectives (Specifically call hierarchy)
The built in C\C++ perspectives may be very useful in tracking down glitchy code and general bug. You are encouraged to explore the various perspective of eclipse, some of which are extremely useful.

More...
There are far too many cool features for me to cover here. I would suggest that you explore the eclipse help files (Help>Help Contents) and the right click (aka. context- ) menus for projects, source files and lines of code. Specifically look at the Refactor and Source sections.

Step 14: Some Notes on Backing Up

Word to the wise: Eclipse has crashed on me many times before, taking my work with it. The typical failure mode of Eclipse with the AVR Plugin seems to be to break both the program and the work space. For this reason it is Highly advisable to;

-Keep a backup
-Use version control
-Maintain separate workspace for AVR stuff
-Use separate Eclipse for AVR stuff.
-Did I mention backups?

Step 15: Links

AVR Development Community - http://www.avrfreaks.net/

AVR GCC tutorial - http://electrons.psychogenic.com/modules/arms/art/3/AVRGCCProgrammingGuide.php

AVR C programming without an IDE - http://www.tuxgraphics.org/electronics/200904/avr-c-programming.shtml


If you think any links should be added to this list please remember to either leave suggestions in the comments or PM me.