CS 153: Lab 1

Lab Exercise 1: Equipping yourself for the projects

The purpose of this lab time is to give you an introduction to the basic tools we will be using this semester. These tools include the Arduino Development Environment, Colby's file system and your Personal and Courses directories, and the Colby Wiki. We'll also cover a little bit of C/C++ and write some programs for your board.

Labs and projects are tightly coupled. Each project is initiated with a set of lab exercises. In the projects, you will write code that expands on the code written in lab. For each project, you will be writing C/C++ code and running it on your Arduino boards. Always bring your Arduino kit to lab. Your programs will make the board do something or sense something about the environment. You will turn in your code by putting it in a special directory on the Courses server. We'll also normally ask you to submit a video of your board working. Today's lab will allow you to practice each of these tasks.

Tasks

Introduction to the Terminal

Open up the Terminal application, which is a text-based method of using your computer. On the Mac lab computers, this should be in the dock (or in your Applications/Utilities folder). On the Linux machines, it is in the list of applications. You can click and drag it into your dock for future use.

A terminal is simply a text-based interface to the computer. In a terminal, you can type commands, manipulate files, execute programs, and open documents. Anything you can do in the Mac Finder or a windowed file system, you can do in a terminal (the reverse is not true).

When working in a terminal, the current directory is called your working directory. A terminal will usually start in the home directory of your account.

In a terminal we often need to specify a file or directory on the hard drive. The complete description of where a directory or file on a computer is located is called its path.

Directories in a path are separated by a forward slash /. The topmost directory on the filesystem is indicated by a single slash. The directory tree for your computer is all relative to the top level directory. In other words, starting with a /, you can type the complete path to any file on your computer. For example, the following is the path to my home directory.

/Users/bmaxwell

Most of the time, however, you will be specifying paths relative to your current directory. Any path that starts without a slash is relative to your current working directory. Note that paths are case-sensitive, so be sure to use proper capitalization.

You will use paths, and filenames to change directories, list the contents of directories, and run commands.

Some important terminal commands are the following. We'll walk through how to use them together in lab.

ls - with no argument, ls lists the files in the current directory. If you put a path after the ls command, it will list the contents of the specified path.

cd <directory> - change directory. If you use the command with no arguments, it changes the directory back to your top-level home directory. The current directory is specified as . and the parent directory of the current working directory is specified using ..

`cd`	Set the current directory to your home directory
`cd ~`	Set the current directory to your home directory. (The ~ character is shorthand for your home directory.)
`cd ..`	Move up to the parent directory of the current directory
`cd blah`	Move into the sub-directory blah
`cd -`	Move to your last working directory

mv <from> <to> - move a file, including just renaming it in the current directory. The mv command will remove the file in the old location after copying it to the new location.
cp <from> <to> - copy a file to a new location or name
mkdir ≶path> - make the new directory specified by the path
rm <filename> - remove the file (will not remove a directory). Not that this is not the same as dragging a file to the trash. Once the filed as been removed, it is gone for good.
rm -r <directory> - remove the directory and all the files and subdirectories in it

Some useful terminal properties are the following.

Wildcard characters: the star character * is a wildcard character. If you want to see all the files in a directory that start with A, you can type:
ls A*

A possibly bad thing to do is to type rm *
Tab completion: when you have typed part of the name of a file or program, pressing the tab key will complete the filename as far as possible while the choice is unique. For example, if you have only one file that starts with the letter b, then typing b and then the tab key will complete the filename.
If you have two or more files that start with b, tab completion will beep at you. If you press tab again, then the terminal will show you the options (all the files that start with b).
Hitting return - you don't have to be at the end of the line to press return. If you go back and edit something in a terminal command, you can press return and execute the whole line no matter where the cursor is located. Try it.

Introduction to the file servers
A fileserver is a central file system you can access from any computer. It's like having a virtual USB key you can plug into a computer to store your files. Colby maintains two different fileservers we use in this course. One (the Personal server) is for you to store the code you are working on. The other (Courses) is for you to turn in code. We will talk about the Courses directory later in the lab. For now, let's focus on where you should keep code that is work in progress.

On the Dwarves (the linux machines in Davis 122), your home directory is your home directory on the Personal file server. The actual hard drive is located in the Miller machine room, and there is a fast network connection from there to the computer on which you are working. What this means is that you are automaticaly working on your Personal folder.

On the Macs in Davis 101 or 102, you can mount the Colby fileservers by going to the Finder and typing cmd-K, or selecting 'Connect To Server...' from the Go menu. It will bring up a dialog box, into which you want to enter the following.
smb://filer.colby.edu
You can mount the Colby fileservers on Windows 10 by first clicking on the Windows Flag and then typing

\\filer.colby.edu

For other systems, please see the ITS Fileserver instructions page

After connecting to the server, if you are on your own machine it will bring up a dialog asking for your Colby credentials. If you are on a lab computer, it may skip that step.

Once you have given your credentials, you should have the option of selecting one of several volumes, including ones labeled as Personal and Courses. Personal contain a directory to which only you have access. It is useful for storing your own documents and work. Courses will contain a directory where you can submit your project code for grading. You should not store intermediate files or work on the Courses volume.

These volumes are backed up regularly, and you can access them from any computer on the Colby network. We strongly suggest you store all of your work for this course in your Personal directory. You can, in fact, work directly from your personal directory.

Project Prep:
1. Go to your terminal window and type cd to make sure you are in your home directory.
2. Make a directory for cs153 using the command mkdir cs153
3. Change directories into cs153 using the command cd cs153
4. Make a directory named project01 using the command mkdir project01
5. Change directories into project01 using the command cd project01
6. List the current directory (should be nothing) using the command ls

Introduction to Coding and the Arduino IDE
Text editors are the workhorse programs for writing code. You don't want fancy fonts or WYSIWYG layouts, you just want to see lines of text, preferably with syntax highlighting, which means that special words in a language are highlighted to make it easer to read the code. There are many editors to choose from.

An Integrated Development Environment, or IDE is a text editor with some additional capabilities. In particular, an IDE usually lets you run your code and debug it all within the same program. We're going to be using the Arduino IDE because it handles the job of compiling your code and sending it to the Arduino microprocessor your board.

To work on your own computer, you can download the Arduino App or IDE from www.arduino.cc.
1. Start the Arduino IDE. It should bring up a window with some (mostly blank) code in it. Delete the setup and loop functions.
2. Plug in your board. Under the Tools::Board menu, select "Arduino/Genuino Uno". Then under the Tools::Port menu, select the option that corresponds with the board.
3. All code in C/C++ is organized into functions. A function is a block of code with a name. We can use functions in order to break code into re-usable pieces and build more complex programs.
  Execution of your program always starts in a function called main. The main function has a return type of int. The contents of a function are enclosed within curly brackets, and the final statement in a function is a return. A main function that executes properly should return a value of 0. Delete any existing code in your file and type the following code into your file.
```
int main(void) {

  return(0);
}
```
4. Before code will run properly on the Arduino chip, it has to be initialized. The Arduino library contains a function init() that will handle standard initialization so everything works properly. Put a call to init() as the first thing in your main() function.
```
int main(void) {
  init();

  return(0);
}
```
5. In order to control a pin on the board, we need to set up the pin. The Arduino library contains a set of functions that let us control the board inputs and outputs. One of those functions is pinMode()code>, which takes in a pin number and a mode. The pin that controls the built-in yellow LED on the board is pin 13, and we want it to be an output. There is a constant OUTPUT defined in the Arduino library we can use.
  You can find the complete Arduino reference here.
6. To actually set the pin to a value, we use the Arduino function digitalWrite(), which takes in a pin number and a value. The possible values for a digital pin are HIGH and LOW, which are also defined as constants in the Arduino library.
7. We want to modify the value of the pin after a period of time. We can make the execution halt for a while by using the delay function. The delay() function interprets the numerical argument as the number of milliseconds to wait before proceeding to the next instruction in the code. 1000ms = 1s. Put a call to the delay function after your first digitalWrite, and then call digitalWrite again to set the value back to LOW.
  At this point, your main function should look like the following. Note the helpful comments.
```
int main() {
  init();

  pinMode( 13, OUTPUT );    // set up the pin

  digitalWrite( 13, HIGH ); // write a high value to the pin
  delay(1000);              // wait for 1s
  digitalWrite( 13, LOW );  // write a low value to the pin

  return(0);
}
```
8. Save your code/sketch as myBlink before continuing by using the File::Save As... option and selecting your project01 directory.
9. Upload your code to the board by either clicking on the Upload icon in the IDE window or using the Sketch::Upload menu option. Verify that the small yellow LED on the board blinks and then turns off.
10. Modify your code to add another blink (set it to HIGH then back to LOW). Upload and test your code. Does it blink twice now?
11. The timing of the blinking light is controlled by the parameter in the call to the delay() function. Change the delay time to a half second, or 500ms.
12. Upload your program to the board and verify that it behaves differently.

Congratulations, you've just written your first code for an embedded system.

Controlling the Arduino
The next task will be to use your breadboard, a resistor, and an LED to generate a couple of Morse code patterns.

Arduino Reference
- Create a new file. Start with the basic main function template.
```
// main Arduino function
int main(void) {
  init();

  // code here

  return(0);
}
```
- Using the pinMode() function, set up pin 13 as an OUTPUT. The duplicate the prior program and have the LED turn on (HIGH) and off (LOW) with a 1000ms delay. Upload and run the code to make sure it works.
- Take out your breadboard, an LED, and a resistor (any of them will work, but for the brightest light use the smallest ohm resistor). Connect the long pin of the LED into one of your digital outputs (e.g. pin 6). Connect the short pin of the LED into one of the 5-hole rows on your breadboard. Connect one end of the resistor into the same 5-hole row and connect the other end of the resistor to the ground [GND] output on your board. (You may want to use some of your wires in between the Metro board and the breadboard, rather than plugging the circuit elements into the board directly). This connects the resistor in series with the LED, which limits the amount of current flowing to the LED and avoids burning it out.
- Edit your code so that it uses pin 6 instead of 13. Then upload and run your code.
- Changing the pin required you to edit three places in the code. In order to make that easier in the future, create an int variable pin and assign it the pin number to use. Then replace the 6 with the variable pin everywhere in the code.
  To define a variable in C, specify the type, then the name. Put all variable definitions at the beginning of your functions, inside the curly brackets. For example, to define an integer variable pin:
```
int pin;
```
  Upload and run your code. Try changing the value of the pin variable to 13 and repeat, double-checking that with one modification, the board uses a different pin.
- Create the following functions:
  void dot(int unit, int pin) - the function takes in a unit of time (ms) and a pin number. It should make the pin go high for one unit of time then go low for one unit of time.
  
  void dash(int unit, int pin) - the function takes in a unit of time (ms) and a pin number. It should make the pin go high for three units of time then go low for one unit of time.
  
  The following is an example of a generic function with two arguments that returns nothing (void). You can use this as a template for dot and dash.
```
void myfunction( int myparameter1, int myparameter2 ) {
  // your code goes here

  return; // don't return anything
}
```
- In your main function, remove the code after pinMode. Then make one call to dot, one call to dash, and two calls to dot. Pass in 1000ms for the unit and the pin variable for the pin number. Upload and test your code.
- If you want to modify the timing to 500ms, how could you make it faster and easier than going through and changing all the 1000 values to 500? Do that and change the unit time to 500ms.
- Make your main function write an H and a W in Morse code. An H is four dots; a W is one dot and two dashes. There should be a total delay of three units between letters. Upload and test your program.

Introduction to the Wiki
Colby Wiki - a Wiki is a convenient way to put content up on the web quickly and easily. If you haven't yet used the Colby Wiki, you need to create your own personal wiki space.

Open a new browser window/tab and Log in to the wiki at wiki.colby.edu. Then follow the lab instructions directions to create your personal space. Note that the wiki can't handle lots of people doing this simultaneously, so you will need to take turns.

For each project, you will create a new page in your wiki space. You can edit any page in your space by going to the Edit tab. There you will find one or two options for editing your page. The Rich-text option lets you do the normal select and point and click type formatting. The wiki markup lets you use the wiki markup language to make your page.

Project Prep:
1. Make a page for Project 1. Go to the Add menu in the upper right corner, and select the Page option. Replace the "New Page" title with something meaningful, like "Stephanie's CS151 Project 1" so that the page content is clear from the title.
2. Now save your page. Even though it has no content, let's save it -- it is a good idea to save often. After saving your page, it will show up in the list of child pages on the bottom of your home page. You can link to it one your home page by editing the home page, pressing the link button (it looks like a chain) and searching your space for it. But it is also perfectly acceptable to simply leave it as a child page.
3. Now let's edit the content of the project 1 wiki page. Click on the link to it, then press Edit. Write a stub for your write-up saying "This is an example of some text".
4. Label the page. The label field is a text field at the bottom of the page, and is different from the title of your page. Each assignment will specify a label, which we will use to find your pages so we can show off your work and so we can grade it. For this project, add the label cs151f18project1.
5. Save it, sit back and think about how much you have already accomplished.
For your information
If you ever need to remove a page, go to that page and select "Remove" from the "Tools" menu in the upper right.

Remember to save your wiki page before navigating away from it. The wiki won't detect it and remind you.

How to turn in code
You will turn in your code by putting it in a directory in the Courses server. On the Courses server, you should have access to a directory called CS153, and within that, a directory with your user name. Within your user directory there is a directory called Private. Files that you put into the Private directory you can edit, read, and write, and the professor can edit, read, and write, but no one else. To hand in your code and other materials, create a new directory within your Private directory, such as project01, and then copy your code into the project directory for that week.

Mount the Courses directory the same way you mounted the Personal directory earlier. Then click on the CS151 directory, and then your hand-in directory. Inside the Private subdirectory, create a new project01 directory. You will use this directory to handin your project code.

When you are done with the lab exercises, you may start on the rest of the project.