EE109 – Spring 2023: Introduction to Embedded Systems

Navigation menu

Lab 0

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.

USB Adapter Needed?

The Arduino board and cable provided in your tool kit uses a traditional "USB Type-A" connector, but many newer laptops (mainly Apple MacBooks) only have the newer USB-C connectors. If your computer only has the USB-C ports you will have to purchase a USB-C to USB-A adapter for use throughout the semester. If you are attending the lab session in the VHE 205 classroom we have some adapters that you can borrow, but you will need to purchase your own for the following lab sessions. USB-C to USB-A adapters can be purchased at the USC Bookstore or online. The ones we have in the classroom were purchased from here.

Note: Students have had problems with USB-C hubs that have several USB-A ports on them. For some reason these don't seem to always work for programming the Arduino. We recommend that you use an adapter that just goes from USB-C to a single USB-A port.

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 recommend that students download and install Visual Code which is available for Macs, Windows and Linux. With all students using the same editor it makes it easier for the instructors and TAs to provide help.

If you wish to try a different editor, the ones below have been used by EE109 students in the past.

macOS: 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: 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 (macOS, 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.

Installing the Development Software

The Arduino development software can be run on Macs, Windows, or Linux systems. Please click on one of the links below for instructions on installing the software.

For macOS, click here
For Windows, click here
For Linux, click here

The development software must be installed on your computer before moving on to the rest of steps described below. Once you have installed the development software you are now ready to run the avr-gcc development software to program a microcontroller.

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.

Open a "Command Prompt" (Windows) or "Terminal" (Mac) window.
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.

To go to the Desktop, for a Mac type
```
$ cd Desktop
```
or for Windows type
```
$ cd OneDrive/Desktop
```
Once you have moved to the Desktop, the commands below will create the "ee109" folder and move into it.
```
$ 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.
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\OneDrive\Desktop\ee109  <-- on Windows
```
Download the Zip file “lab0.zip” from the class web site and put it in the ee109 folder you created above.
macOS - Extract the files from lab0.zip by typing the command “unzip lab0.zip” in the Terminal window. This will create the files "ee109.c" and "Makefile" in the ee109 folder.
Windows - Right click on lab0.zip and select "Extract All...". This creates a new "lab0" folder with the files "ee109.c" and "Makefile" inside it. Move these two files back up to the ee109 folder and trash the lab0 folder.
Use the "ls" command to check which files are now in the "ee109" folder.
```
$ ls
Makefile    ee109.c      lab0.zip
```
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.

The make program 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 files 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.

Use your text editor 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/cu.usbmodem*
OBJECTS    = myfile.o
```
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.
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/cu.usbmodem*"
```
PROGRAMMER = -c arduino -b 115200 -P /dev/cu.usbmodem*
```
For Windows: If you do not have an Arduino available at this time, you can skip these four steps for now but will have to come back and do them later before actually trying to download a program.
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 "Ports" and it should be listed there as "COM3 (Arduino Uno)" 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.
For Linux: For most Linux systems use "/dev/ttyACM0"
```
PROGRAMMER = -c arduino -b 115200 -P /dev/ttyACM0
```
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)
After making the above changes to the PROGRAMMER and OBJECTS lines SAVE the file.

Very 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".

Really, Really Important: Make sure you are in the correct folder when running the make command. The most common problem people have with using make is that they use their editor to modify code files, or the Makefile, in one folder, but from the command line they run the make command while in a different folder. Your editor screen should show you what folder the files you are editing are stored in, and from the command line on macOS, Windows or Linux the command pwd will tell you what folder you are currently in.

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 you DON'T have an Arduino Uno...

Without an Arduino you can't actually download your program, but you can test whether the Makefile works to run the downloading command. The command below will run the "avrdude" program that normally downloads the data using the parameters you specified in the Makefile.

$ make flash

Without an Arduino connected you should get some error messages like this.

avrdude: ser_open(): can't open device "/dev/cu.usbmodem*": No such file or directory

avrdude done.  Thank you.

make: *** [Makefile-lab0:29: flash] Error 1

If you see the above at least you know the downloading program can be executed. At this point you can stop work on this lab assignment but come back to this section when you have an Arduino to connect to.

If you DO have an Arduino Uno...

If it isn’t connected already, use the USB cable to hook your Arduino Uno 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 make a change in the program.

Edit the lab0.c to change all occurrences of 500 to 100.
Be sure to save the changes to lab0.c
Back at the Terminal or Command Prompt, recompile the updated code by typing make
Download the code by typing make flash
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.

Addendum

Compilation & Linking

Like most computers the Arduino can only deal with numerical or "digital" data, usually expressed as a bunch of binary numbers or "bits". The process of converting the C language program into Arduino compatible bits is normally done in two steps. The first step is is called "compiling" the program and it converts the C program into a binary form known as an "object file". The compiling is done by a program (the "compiler") that reads the lines of text in the C program and outputs binary numbers that will tell the computer how to do the tasks specified in the program.

The numbers in the object file are not everything that is needed to have an executable program that can be downloaded to the Arduino. Even for a very simple program like this, there is other binary data that must be combined with it to make the final executable program. The second step is to "link" the program's object file together with other data to create the final executable program. For a simple program like this the linking is very simple but for larger projects it can be a complex process involving hundreds of object files. In any event, at the end of the linking step we will have a single file of executable binary data that can be downloaded to the Arduino for blinking the LED.

If Your Windows Machine Doesn't Recognize Your Arduino

Windows will probably try to install a driver and this sometimes fails or it installs the wrong driver. Open the Device Manager (Windows button ... search for “Device Manager”), find the Arduino device and double click on it. On the Properties windows that come up, click on the Driver tab and then on the Update Driver button. On the next windows, click on the Browse button and, assuming you installed the WinAVR software in the default location, search for the directory "C:\WinAVR-20100110\utils\libusb\bin" and tell it to install the driver from that directory. With any luck the installation should succeed.