003 AVR Eclipse, ATMEL Toolchain and ATmegaCLib

Struggle to learn C language, you will not regret it! Yes, you can program also in Pascal or Basic but then, you will have to stick with mikroElektronika products and it will costs you more money. With avr-gcc you can code better as you have total control. Hopefully, ATmegaCLib(2) library will bear some of the burden for you.

1. Installing Eclipse under Linux

Personally, I prefer downloading Eclipse from the eclipse.org site (if you installed Eclipse from your repository, uninstall it), as some Linux distros does not have it in their repository and anyway, I can't impose you a specific Linux distribution (even if openSUSE was used at the time I wrote this tutorial on my Romanian site - I use Fedora19 now, when I struggle to translate the tutorial into this page).

From the download page of eclipse.org site, take the "Eclipse IDE for C/C++ Developers", 32 or 64 bit variant, as you need. Expand the archive in your personal $HOME folder (/home/suse, in my case). You will obtain the $HOME/eclipse path (/home/suse/eclipse, in my case). Nowadays, you can use a GUI archive manager from your Linux desktop so, I will not give you a console command.

Launch Eclipse (open your File Manager and navigate to $HOME/eclipse folder, and double-click on eclipse executable file) then chose a name for your "workspace" folder (or let it as it is, but you will want to rename it if you use many versions of eclipse in your Linux - Android someone?).

2. Installing avr-eclipse 2.4.0 plug-in

Exactly this version! Launch Eclipse if you didn't by now, go to "Help/Install New Software…" menu, and in the first field of the newly displayed window insert the following link “http://avr-eclipse.sourceforge.net/updatesite” – without quotes. At the right of this field you have the [Add...] button - press it and another window will appear!

In the "Name" field insert anything you like, but if you don't have any ideas, write as it is on the above image, then press [OK] button. Wait, and after a while, a new window is shown (see the next image).

Click to zoom

Check the element from the list (as is shown above) then press the [Next >] button. After another few clicks (just follow the screen indications), it will ask you to approve the license and then the installation will begin. After that, you can restart Eclipse, and/or just close it, as we have to install another "vital" component.

Download the .jar file from here. Now, put the .jar file in $HOME/eclipse/plugins folder, replacing (overwriting) the original one. This is all, and now we will configure the plug-in (in the next chapter).

3. avr-eclipse plugin configuration

First of all, we will download the ATMEL toolchain for linux. The ATMEL site will ask for your name and email and only after the validation you will be able to download the toolchain. In the end, you will have the avr8-gnu-toolchain-3.4.2.939-linux.any.x86.tar.gz file (which contains the "newly" avr-gcc-4.7.2 and, anyway, is the version I tested and use at the date of this article). Expand the archive in $HOME folder and rename the resulted folder, as the original is too big, by example, avr8-gnu-toolchain - this will be our toolchain folder. Done with this.

One more small step to do before plug-in configuration: avrdude installation. The ATMEL Toolchain does not include the avrdude tool, and the reason we are installing the ATMEL Toolchain is that it supports far more AVR microcontrollers (almost all, including xmegas) than the gnu one. I have it archived on my site, so you have to download it (as my avrdude.conf file contains a few more microcontroller definitions than the original one). Unpack it to $HOME/avr8-gnu-toolchain/bin folder (you can install avrdude from your repository and take only my .conf file but for tutorial consistency, lets do it my way - at least, put the .conf file in the folder I said). Done with avrdude.

Now, lets configure the avr-eclipse plug-in. Launch the Eclipse, and go to "Window/Preferences" menu. In the appeared window, expand the AVR tree from the left panel, select "AVRDude" element, then in the right check the "Use custom configuration file for AVRDude" option and press [Browse] button to search for the .conf file (as is shown in image bellow).

Go directly to the folder you unpacked the avrdude archive ($HOME/avr8-gnu-toolchain/bin) and select the avrdude.conf file as in image bellow and press [OK] button.

Click to zoom

The window will close and then we have to select the "Paths" sub-tree element form the left panel of the Preferences window. You will have to wait a lot of time until Eclipse will give you control again (it will search to see where you have the toolchain installed and it will take a lot of time - you can drink your coffee...). When it finishes, in the right will appear a list with the paths already configured - we will change them (everything is relative to the folder where I installed the toolchain):

Click to zoom

Select them and press [Edit] button to change them one by one.

In the image above, pay attention to the combobox from up-left, you will not be able to change anything if is not set to "Custom". Now you can change the paths and in the end, on my system everything looks like in the following image (well, now I have Fedora19, with a different user name, but you get the idea):

Click to zoom

Click [OK] button, and from now on, we have a fully functional toolchain

4. Installing Subclipse for SVN access

With Eclipse opened, go to "Help/Install New Software…" menu and in the first field of the appearing window paste the following link: http://subclipse.tigris.org/update_1.8.x/ and then press [Add] button and another window will show-up where you must give a name to the freshly added repository (just name it Subclipse) and press [OK] button - do not change "Location".

Click to zoom

Bellow the "type filter text" field is a list with two main elements(trees), expand them and select everything except the two remained unchecked (see the image bellow) and proceed with the installation (accept the license, etc.):

Click to zoom

Now, you must reply with [OK] at "Security Warnings" then restart Eclipse when the installation is done.Don't forget that this plug-in require subversion installed on your system so, if you don't have it yet, proceed with the installation. For Ubuntu, the command is:

sudo apt-get install subversion

For Fedora18/19,

sudo yum install subversion

For other Linux distributions, check the included package manager and install it from there.

5. Importing ATmegaCLib directly from SVN (googlecode)

The ATmegaCLib is a library created as an Eclipse project, and commited to atmega-clib.googlecode.com as is (using Subclipse) so, we will be able to import it back as Eclipse project - no later project configurations needed. OK, lets proceed:

Launch Firefox web browser (or your favorite one) and go to this address: https://code.google.com/p/atmega-clib/source/checkout . Select the text (as in image bellow) and copy it:

Click to zoom

Switch to Eclipse and go to “File/Import“ menu, and from the appearing window, expand SVN tree and select the “Checkout Projects from SVN“ sub-element (see the image bellow) then press [Next] button.

Press [Next] button once more to create a new repository location and paste the text copied from Firefox, inside URL field as in the image bellow ):

Press once more [Next] button and from the appearing list, select ATmegaCLib element and press [Finnish] button (see image).

After a while, in the left panel of Eclipse IDE (Project Explorer), a new project will show up (see bellow):

Click to zoom

Do right-click on that element and from the contextual menu chose “Clean Project“ option. Right-click again, and chose "Properties" option. From the appearing window expand AVR tree and select “Target Hardware“ element. In the right zone of the window you can change the microcontroller target but I advise you to let the 16MHz frequency unchanged (for now, as the library is not tested with other type of crystals - we're talking mainly about boards with 16MHz crystal and Optiboot bootloader...):

Click to zoom

5.1 Importing from the branches

You may want to do that since the branch version (ATmegaCLib2) is better developed and contains many other features and the development will continue on this version.

So, instead of "trunk", you'll have to specify "branches" in the link you put on location. Anyway, copy the link bellow, is faster this way:

https://atmega-clib.googlecode.com/svn/branches/

6. Importing a project example from SVN

Similarly, we'll import an example project. Go tot “File/Import…” and do the same as importing the library, but this time, select the existing repository (“Use existing repository location“ option). By example, select the “ATmega_PWM_LED” project, clean it with “Clean Project“ from the contextual menu (right-click on the project from the Project Explorer - left panel), expand it, and open the pwmofledexample.c file to study the requirements (what settings you need to make in the library header).

6.a Configuring the library's header for our project

Assure yourself that your project has selected the same microcontroller target as ATmegaCLib library (otherwise it may compile but it may not work). If they differ, make the changes and then clean both projects. The library project ATmegaCLib (or ATmegaCLib2, if you imported the project from the branches) is designed as a single source file and a header file. Inside the source file are contained many libraries for different devices and peripherals. The user make changes on the header to activate the functions he needs for his own project configuration. These configuration differs from a project to another so, every time you start (or just reopen) a project, you must check two things:

- if the selected microcontroller of the library is the same as the one used for your project;

- if the configuration from the library's header matches the requirements specified in the source of your project (at the beginning of the main source, there is a comment where the required setup is specified - you have to make the same for every project of yours, if you have a short memory as mine).

The structure of the library's header is as follows:

- The "switch" zone - where the user only enable/disable library's features as in image bellow (with one exception - the baud rate needs to be set as per your needs):

click to zoom (ATmegaCLib2 from branches)

- Right after this, the user zone continues with the default settings for pinout for various modules as 7 segment digits, software I2C, LCD, GLCD, one-wire bus, slave select, and other defines (the disabled features/code is grayed). At the end of user zone is a barrier - over that, the editing is not allowed, unless you know what you are doing (optimizing the code, adding new functionality, etc.)

The grayed bloc is code/feature disabled from the "switches" zone.

6.b Compiling the project

After you finished with the library settings, clean the project, go to your ATmega_PWM_LED project, and make a build (right-click on the project on the left sidebar (Project Explorer) and chose "Build project").

6.c Uploading the hex file on the microcontroller (having an Optiboot bootloader)

Do click-right on the project name in the left panel and select "Properties" (at the bottom of the pop-up menu). In the appearing window, expand "AVR" item in the left tree/list, and select "AVRDude" sub-item. On the right side, press [New..] button to define a new programmer.

click to zoom

Input the data as in the bellow image. Chose a name for your programmer (it will appear in the combobox list), chose the protocol type from the list (Arduino in our case), set the port as /dev/ttyACM0 or /dev/ttyUSB0 (depends on the USB adapter included in your board) and set the baud on 115200, again, depending on the microcontroller and crystal you have.

click to zoom

At the end, the newly defined programmer will show in the combobox list and the next time when you create/edit a new/existing project, all you have to do is to chose the programmer from the list.

click to zoom

Press [OK] button to close the window, compile the project, select the project from the "Project Explorer" list (left sidebar), and press [AVR] button from the upper toolbar to have the hex file uploaded in your microcontroller.