# EE109 – Spring 2018: Introduction to Embedded Systems

## Installing the Arduino Toolchain

### Introduction

The purpose of this lab assignment is to help students install the software that will be used throughout the semester to program the Arduino Uno microcontroller development board. Most of the following lab assignments can not be completed until the programming environment has been successfully set up on whatever computer a student plans to use.

The Arduino company that makes the microcontroller development boards we will be using also provides a software package for programming the boards known as the "Arduino IDE". However, for this class we won't be writing programs within that environment. The Arduino IDE does a number of things that makes programming the boards very simple, but our goal in EE 109 is to learn how these things are done, not just to do them.

The software package we will be using is "avr-gcc", a version of the gcc C compiler that creates code for the Atmel AVR processor used on the Arduino boards. The collection of programming tools included in avr-gcc (compiler, linker, downloader, etc.) is known as a "toolchain". The avr-gcc toolchain is command line based and is used via a program like Terminal on a Mac or the Windows Command Prompt. One of the goals of this class is to get everyone familiar with using a command line interface since that skill will be required in many of your subsequent engineering classes.

### Command Line Usage

For the rest of this lab, and throughout the semester, you will have to use a command line or "terminal" interface to work with the software that programs that Arduino.

Before proceeding with this lab go to the Command Line Reference web page and spend a few minutes reading the material that covers using the most common commands. You don't need to do anything but just study the material there so that you can work with the commands to move around the file system and use commands to view, copy, rename and delete files.

Highly Recommended: We do recommend you follow the instructions on the Command Line Reference web page on how to make the icons for the Command Prompt (Windows) or Terminal (Mac) appear permanently on your Desktop. You will be using the command line interface program extensively throughout the semester so make it as quick and easy as possible to get the program started whenever you need it.

### Installing the Development Software

#### Mac OS X Installation

The avr-gcc software for use on a Mac can be obtained from the instructor or downloaded from a couple of web sites. It should run on any Intel-based Mac OS X system. The Apple Xcode developer tools are not required in order to run the avr-gcc software, and if it has been installed it should not affect running the avr-gcc software.

To install the avr-gcc software:

1. The avr-gcc software can be downloaded from http://www.obdev.at/products/crosspack. Obtain the file "CrossPack-AVR-20131216.dmg" or a more recent one. Double click on it to open the disk image and double click on the "CrossPack-AVR.pkg" file and follow the instructions to install the cross compiler software. Depending on what version of the operating system is on your computer, you may get a box popping up with a message stating that CrossPack-AVR "Can’t be opened because it is from an unidentified developer." If this happens follow these steps.
1. From the Apple menu, open the System Preferences.
2. Click on "Security & Privacy" and then on the "General" tab.
3. Look for a line under the "Allow apps downloaded from" about CrossPack being blocked from opening and an option to "Open Anyway" and click on that. It may put up another box telling you that CrossPack is from an unidentified developer. If so, click on OK and that should start the installer.
4. Older versions of the OS may not show a line specifically about CrossPack. For these click on the little padlock icon in the lower left and enter your password. Make a note of the current setting of where it allows apps to be installed from, then click on the option to allow installing software from anywhere. Go back to the CrossPack-AVR.pkg file and start the installation as before and it should complete. Then come back and change your security setting back to what it was before.
2. Once the installation is complete, the Safari web browser may open to show notes about the software. You don't need to read these now so quit Safari.
3. Open a Terminal window (the Terminal app is in the Utilities folder inside the Applications folder) and type the command "printenv PATH" to show the search path used for finding executable programs. It should contain the directory "/usr/local/CrossPack-AVR/bin".
4. Check that the software that downloads the programs to the Arduino has been installed by typing the command "avrdude -?". If the program is working it should print out a bunch of stuff and at the end give the version number of the program. Probably something like "avrdude version 6.0.1".

You should now be ready to run the avr-gcc development software to program a microcontroller. Go to "Editing Files".

#### Windows Installation

The avr-gcc software for use on a Windows system can be obtained from the instructor or downloaded from a couple of web sites. It has been run on Windows 10 systems and probably runs on other versions.

To install the avr-gcc software:

1. The avr-gcc software can be downloaded from http://sourceforge.net/projects/winavr/. Download the file "WinAVR-20100110-install.exe" or a more recent one. Double click on it to start the installation. Follow the instructions and use the default settings and locations.
2. Download the Arduino IDE software from http://arduino.cc/en/main/software. We won't be using this to program the Arduinos, but it is handy to have installed for checking on which I/O port the Arduino is connected to. Install the package using the default options. At some point it may ask you to install the USB driver. Choose "Install". When done, you can click "Complete".
3. Open a Command Prompt window (Windows button ... search for "Command Prompt") and type the command "path" to show the search path used for finding executable programs. It should contain the directories "C:\WinAVR-20100110\bin" and "C:\WinAVR-20100110\utils".
4. Check that the software that downloads the programs to the Arduino has been installed by typing the command "avrdude -?". If the program is working it should print out a bunch of stuff and at the end give the version number of the program. Probably something like "avrdude version 5.10".

You should now be ready to run the avr-gcc development software to program a microcontroller. Go to "Editing Files".

#### Linux Installation

For installation on Debian and Ubuntu Linux systems see the "AVR Toolchain" web page in the Tools and Links section of the class web site.

### Editing Files

You will need a text editing program on your system in order to edit the C files in your projects. The main requirement is that it be able to edit a file of plain text characters and not turn it into something like an RTF (Rich Text Format) file or ".docx" file. While there are many free editors that can be used, unless you have had significant experience with another text editor, for this class we ask that all students download and install one the following text editors since this makes it easier for the instructors and TAs to provide help.

Mac OS X
Use BBEdit. This is a commercial product ($50) but most features are available when used for free. DO NOT use Apple’s TextEdit program. Despite its name this program is not a text editor and is incapable of properly editing program code. Windows Use Notepad++. One requirement of editing text files on Windows is that the editor be able to save files without adding a filename extension like ".txt". If the editor insists on adding the extension it is usually necessary to then use a Command Prompt window to rename the file and remove the extension (instructions here). On Unix-type systems (Mac OS X, Linux, etc.) files can also be edited using a command line interface editor. The most common of these are "emacs" or "vim". Some of these may already be installed on your system and all are available in various forms from several Internet sites. ### Creating a New Project In order to make it easier for the instructors and TAs to provide help, all student are required to follow some simple guidelines for where their EE109 lab assignment files are located on their system. The following is a short version of the instructions on the Project Setup web page. 1. Open a "Command Prompt" (Windows) or "Terminal" (Mac) window. 2. Enter the commands below to create a folder called "ee109" on the Desktop of your system. Important Note: The $ represents the prompt and you should NOT type it.

$cd Desktop$ mkdir ee109
$cd ee109  There should be no spaces between the "ee" and the "109", and this rule should also extend to any subfolders created later inside the ee109 folder. There should be no spaces in any filename or folder you create. You may use underscores if you wish (e.g. my_homework). Names with spaces are great when navigating folders in a GUI, but not so great (i.e. very painful) when using command line interfaces. 3. To confirm that you are now in the "ee109" folder, type the "pwd" command ("pwd" stands for "Print Working Directory"). $ pwd
/Users/my_name/Desktop/ee109    <-- on Mac
C:\Users\my_name\Desktop\ee109  <-- on Windows

4. Download the Zip file “template.zip” from the class web site and put it in the ee109 folder you created above.
Mac OS X - Extract the files from template.zip by typing the command “unzip template.zip” in the Terminal window. This will create the files "ee109.c" and "Makefile" in the ee109 folder.
Windows - Right click on template.zip and select "Extract All...". This creates a new "template" folder with the files "ee109.c" and "Makefile" inside it. Move these two files back up to the ee109 folder and trash the template folder.

5. Use the "ls" command to check which files are now in the "ee109" folder.
$ls Makefile ee109.c template.zip  6. As described on the Project Setup web page, make a folder for this lab and copy the files into it by typing the following commands. $ mkdir lab0
$cp ee109.c lab0/lab0.c$ cp Makefile lab0/Makefile
$cd lab0  Now that the necessary files are in the right place, the next step is to do some editing on both of these files. ### Modifying lab0.c Go to your ee109/lab0 folder and open up the lab0.c file in your text editor. Edit it to look like the program below. This program makes an LED on the Arduino blink on and off at a 1Hz rate. Also add your name and class section number in the comments at the top. Make sure to save your changes. Important: You’re not expected at this time to know what the various statements in the program below are doing. We’ll be discussing how the program works and what these commands do in detail in future class sessions. For now, just copy the lines of the program as shown and let’s make the LED blink. /******************************************** * * Name: * Section: * Assignment: Lab 0 - Blink the LED on Port B, bit 5 * ********************************************/ #include <avr/io.h> #include <util/delay.h> int main(void) { DDRB |= (1 << DDB5); /* Set PB5 for output */ while(1) { PORTB |= (1 << PB5); /* LED on */ _delay_ms(500); /* Wait 500 milliseconds */ PORTB &= ~(1 << PB5); /* LED off */ _delay_ms(500); /* Wait 500 milliseconds */ } return 0; /* never reached */ }  ### From a C Program to Bits The above C program does everything needed to make the Arduino's LED blink. Unfortunately the Arduino doesn't understand the C programming language directly, so in order to use it in the Arduino we have convert it into a form the Arduino can work with by compiling it. You can read more about this process in the Addendum below. When writing software, the compiling and linking steps have to be done each time the program is changed. For our programming projects we will use a script to automate much of the painful compilation steps through a program called make. This program is run from a command line interface and will do all the necessary compiling of the source code and linking of the object files to create the executable binary file. make will look for the compilation script in a text file with the name Makefile. This file is kept in the same folder with the source code file and contains all the information and commands needed to compile and link the program to produce binary data, and to download it to Arduino Uno board. The Makefile can be very complex for some projects, and even for simple projects like our LED blinker can have a lot of strange looking stuff in it. Thankfully most of the time you only need to edit a few lines to adapt it to work for any new project that you start. 1. Use your editor (Notepad++ or BBEdit) to open the Makefile that you copied into this folder at the start of this exercise and look at the first four lines at the top. These provide information on what type of processor is being used, how to program it, and which files need to be compiled to build the executable program. Regardless of where the Makefile came from, it’s very important to make sure the correct information is at the top. DEVICE = atmega328p CLOCK = 16000000 PROGRAMMER = -c arduino -b 115200 -P /dev/tty.usbmodem* OBJECTS = myfile.o  2. You SHOULD NOT need to change the DEVICE and CLOCK lines. They simply indicate what type of processor we’re compiling the program for and how fast it will be running. The Arduino Uno uses an ATmega328P running at 16MHz. 3. You MAY need to modify the PROGRAMMER line that contains parameters used by the program that downloads the data to the microcontroller. For our class the important parameter here is what comes after the "-P". This is the device your computer uses to connect to the Arduino and and this will be different depending on the type of system you are using. For Macs: Use "/dev/tty.usbmodem*" PROGRAMMER = -c arduino -b 115200 -P /dev/tty.usbmodem* For Windows: 1. Connect one of the Arduino Unos to the computer using a USB cable. 2. Start the Arduino IDE/GUI (a round, green icon with the infinity sign is likely on your desktop) 3. Find the port that the Arduino is connected to by running the Arduino IDE program. From the "Tools" menu, select "Serial Ports" and it should be listed there as "COM3" or something like that. 4. Now switch back to editing the Makefile and use the port name you found above from the Arduino IDE program (e.g. “COM3”). It should look something like: PROGRAMMER = -c arduino -b 115200 -P COM3 where COM3 is replaced with whatever you found above. (Note: Each time you connect the Arduino to your computer it may select a different COM port. You will need to look it up from the Arudino IDE and change your Makefile to reflect that COM port. 4. You WILL ALWAYS need to modify the OBJECTS line that lists all object files that need to be linked together. Since our C program file is lab0.c, the object file created by the compiler will be lab0.o. Edit the line to replace myfile.o with lab0.o. In general, when you perform a lab and use a filename like lab1.c for your code, you will need to modify the Makefile's OBJECT line to be lab1.o (i.e. same prefix but using the .o suffix rather than .c) 5. After making the above changes to the PROGRAMMER and OBJECTS lines SAVE the file. 6. Important: The name of the file must be "Makefile" (or "makefile"). On occasion your Mac or Windows machine may try to add an extension to the file and call it something like "Makefile.txt". This will prevent the make program from working. Some systems will add the extension, and then make the extension invisible from the GUI so the file looks like its name is Makefile but it’s really not. If you run the make program and it returns an error message about no Makefile found, use a Terminal or Command Prompt window to go to the project folder and use the ls (Mac) or dir (Windows) command to display a list the files showing the full names. If necessary use one of the following commands to fix the name. rename makefile.txt makefile <-- on Windows mv Makefile.txt Makefile <-- on Mac  ### Building and Downloading the Program Once the Makefile is correct try compiling and linking the lab0.c program by using the command line interface and typing the command "make". You type: $ make


On Macs, running "make" at this point may put up an error message about Xcode not being installed and also put up a dialog box asking if you want to install some software. Cancel whatever it is asking you to do and go follow the instructions on the Toolchain web page about fixing this issue with "make" on Macs.

If it compiles properly you should see something like this on the screen with no reports of any compiling or linking errors.

avr-gcc -Wall -Os -DF_CPU=16000000 -mmcu=atmega328p -c lab0.c -o lab0.o
avr-gcc -Wall -Os -DF_CPU=16000000 -mmcu=atmega328p -o main.elf lab0.o
rm -f main.hex
avr-objcopy -j .text -j .data -O ihex main.elf main.hex


The first line says the lab0.c file was successfully compiled to create the lab0.o object file. The second, third and fourth lines show that the linker used the lab0.o file to create the final output file main.hex which contains the binary data containing the program. This will be followed by some lines about how big the program is.

The next step is to download the binary program data from the file main.hex to the Arduino. We could do this by typing a command in by hand but fortunately our Makefile already contains the necessary information on that PROGRAMMER line you edited, so we can use the make program to also do the downloading.

If it isn’t connected already, hook one of the Arduino Unos to your system. The command below will run the "avrdude" program that downloads the data using the parameters you specified in the Makefile.

\$ make flash


If it works a bunch of stuff will fly by on the screen as it writes the data to the microcontroller and then verifies it. Eventually you should see something like:

avrdude: verifying ...
avrdude: 176 bytes of flash verified
avrdude: safemode: Fuses OK (H:00, E:00, L:00)
avrdude done. Thank you.


If it says avrdude done. Thank you. things have worked correctly. At this point the new program will start executing in the Uno and you should see a small LED near the minus sign in the Arduino logo start to flash once per second.

To ensure you really have done everything correctly and understand the flow of how to edit, compile, and download go back and

1. Edit the lab0.c to change all occurrences of 500 to 100.
2. Be sure to save the changes to lab0.c
3. Back at the Terminal, recompile the updated code by typing make
5. Verify that the light on the Arduino board is blinking much faster

### Lab Report

Complete the Lab 0 questionnaire on Blackboard. You may take it as many times as you like.