If you note any errors, typos, etc. with this manual or our software libraries, let us know at

Oregon State University Robotics Club ORK 2011 Programming Guide Version 1.0 Updated: 10/28/2011 Note: Check back for more revisions and updates soon! If you note any errors, typos, etc. with this manual or our software libraries, let us know at osurcofficers@engr.orst.edu Necessary Software The following software and code will need to be downloaded to program your ORK. The programs or links to get them are available on the ORK Website. WinAVR - or - avr-gcc, avr-binutils, avr-libc ORKWare Loader Application Java Runtime Environment A text editor of your choice for writing the code, Notepad++ or Programmer s Notepad are good text Editors for Windows. Also, download the starter code (ORKWare.zip) 1. Getting started with C Syntax and Basics Before writing a program in C for the ORK, you should read over the first part of this manual and some of the code in the ORKWare libraries in ORK_lib.zip. C has a specific syntax (the way the code has to be typed) and has many basic rules, commands, structures, and operators that are the building blocks of any program you will write. If you have programmed before in C, then this first section should mostly be review and can be skipped. Case sensitivity C is case sensitive, so everything written in code needs to be correctly typed otherwise the code cannot be compiled into a program. Be very aware of this when you are writing your code, it will save you time in the long run. Brackets, braces, and parentheses Any time an opening (left) parentheses, brace, or bracket is created, a right handed parentheses, brace, or bracket must be properly nested so the last open brace is the next one that is closed. Having a ( followed by a ] will prevent your code from working as a program. In general, if a bracket, brace, or parentheses is missing or out of place, your program will not compile. It is often a good practice to create open and closing punctuation in your code at the same time before writing what goes inside of them. Page 1 of 14

Example of proper bracket, brace, and parentheses use int function(char parameter1) if(a==b) array[b]=z++; //Notice the balanced braces? Line endings The end of each statement must have a semicolon typed at the end of the line. Some lines, such as ones with if, else, or most loop statements do not need a semicolon after the statement. If you do not add these semicolons, the program will not compile and cite missing semicolons as the cause. For example: int a = b+2; //Note the semicolon Numbers When you write in C, you can express numbers in three different bases: binary (0 or 1), decimal (0-9), and hexadecimal (0-F, really 0-15). In some cases, in most higher level programs, decimal values are typically used, however in some cases with low-level programming, it may be easier to write numbers in binary or hexadecimal. Decimal values can simply be written into your code as is. To write a binary number, type 0bNUMBER before the value or to write a hexadecimal (hex for short) value, type 0xNUMBER. Examples of 47 in binary, decimal, and hexadecimal: Binary: 0b101111 Decimal: 47 Hexadecimal: 0x2F Logical Values You may be familiar with simple Boolean logic, possibly from other languages, where there are explicit True and False values in the language to handle logical statements, such as (4 greater than 3), which would be true. In C, logical values, which should make more sense in the examples, take on the values of any number that is 0 for False and any non-0 number for True. It is possible to define the words true and false as 1 and 0. Operators In C there are a number of simple arithmetic operations that you should be familiar with as well as Boolean logic and bitwise logic operators. Operators simply manipulate data, for example xadding two numbers or checking whether Page 2 of 14

multiple conditions are true at the same time. Become acquainted with what these operators mean as most C statements typically include multiple operators. Arithmetic Operators Most of the ones that you will need are listed here. The assign = stores a value into a variable, the four basic math operators, +,-,*, and / operators perform addition, subtraction, multiplication, and division, and the increments and decrements add or subtract one from a value. Table of Arithmetic Operators Operation How to code it What it does Assign a = b Stores b in a Add a+b Adds a and b Subtract a - b Subtracts b from a Multiply a * b Multiplies a times b Divide a / b Divides a over b Increment a++ or ++a Adds one to a Decrement a-- or --a Subtracts one from a Logical Operators Logical operators perform simple Boolean operations to the logical values of numbers in C. They are useful for evaluating multiple logical statements at once to make compound logic. For example using an if statement, IF NOT A AND NOT B are both true then do some other activity. Table of Logical Operators Operation How to code it What it does Equate a == b Checks if a is equal to b, do not use a=b for this NOT!a Inverts the logical value of a AND a && b Returns true if both a and b are true, otherwise false OR a b Returns true if a or b, or both, are true, otherwise false Bitwise Operators Bitwise operators perform numerous logical functions on the individual bits of a number. Every number is stored as a binary value on the microcontroller, and each one of these operations goes through and performs the following operation on each one of the digits of that binary number. Table of Bitwise Operators Operation How to code it What it does NOT ~a Inverts each bit of a: 1010 0101 AND a & b ANDs each bit of a and b: 1001 & 1011 1001 OR a b ORs each bit of a and b: 1001 1011 1011 XOR a ^ b Exclusive ORs each bit of a and b: 1001^1011 0010 Left Shift a << b Shifts the bits of a left by b: 00101<<2 10100 Right Shift a >> b Shifts the bits of a right by b 10100>>1 01010 Page 3 of 14

Data Types and Variables Variables Data in C is entered in what are called variables. Variables have a data type, a name, and a value. To create a variable, you must declare what type it is and give it a name. To assign a variable a value such as a constant number, or another number, use the = operator. Example variable declaration and initialization. int a; a=3; char z = 33; Integer Types: char, int, long Each of these types stores an integer with a different number of bytes with char being the shortest, up to long being the longest in general use. These values have different ranges of values as some take up more space in memory, and more processing power to handle than others. The data type must be large enough to hold the largest number you expect to hold in that variable. The range of acceptable values for each type. Basic integer types, sizes, and their range of values. char (1 byte): -128 to 127 int (2 bytes): -32,768 to 32,767 long (4 bytes): -2,147,483,648 to 2,147,483,647 Signed and Unsigned numbers Numbers may also have a sign, meaning it can be positive or negative, or be unsigned and strictly positive. Any integer declared just using the above types will automatically be signed. The advantage of using unsigned numbers is that it increases the positive range of values by a factor of 2. So an unsigned char goes from 0 to 255 instead of -128 to 127. For many things, like counters, distance sensor values, or anything else that would only have a positive value, an unsigned number would be the best way to store it. Numbers that can be positive or negative, say the motor velocity, should be stored to signed numbers. Floating Point Numbers (i.e. numbers with a decimal point) Most microcontrollers, the ATMega32 included, do not have hardware capable of easily doing basic arithmetic with non-integer numbers like 42.3 or 0.0072. You may use the types float or double in your code, which will compile and work, however it takes the processor significantly longer to calculate with these numbers and may slow your program down noticeably. Page 4 of 14

Functions What is a function? A function is a reusable piece of a program that takes some input and subsequently produces some output depending on the inputs it has received. How to write a function Each function needs five things, a return type, a function name, parameters, the actual code to execute in the function, and a return statement. The code to execute is written to do what you want the function to do, however the following function components are necessary to know in order to implement functions. Return Type: Each function requires a return type to be declared at the very start of the function. If it returns an int, then you would write int functionname. Functions may return nothing, in which case the type void is used. Often times if you just want to change something but do not need a value back, void functions should be used. Function Name: Each function requires a one word function name, which is usually written starting with a lower case number. You can only have one function per function name, and it cannot conflict with any statement in C, so you can t have a while() function for example. Parameters: Parameters, the inputs of a function that go in parentheses and each one must have a type assigned to it, such as int, char, etc. These can be referred to in your function by the name given to them in the function header. Return Statements: All non-void functions require you to return a value at some point in the function. This is done with a return statement. To return from a function, type return and then the value (a number or a variable) to return after it. This exits the function and allows you to have the value in the part of your program where the function was called. returntype functionname(type param1, type param2) //Write code in here for function return value; The main() function Every program in C must have at least one function, the main() function. It is included in the starter code with a type of int. The main() function encapsulates the entire program, so when it starts, it starts in the main function and ends when the main function is finished (something you usually don t want to experience with your ORK). Page 5 of 14

How to call a function in your program To call any function in your program, simply type the function name followed by values for each parameter in parentheses separated by commas. To store the return value of a function, simply assign it to a variable. An example is shown below: Example of calling myfunction with parameters 1, 2 and storing the result to a int myfunction(int p1, char p2) int main() int a = myfunction(1,2); return 0; Flow Control When writing programs in almost any language, you will often find it necessary to control how the code you write is executed. Rarely is a program written that simply executes all of its instructions in order without regard to inputs or conditions within the program. Thus you will need to become acquainted with what are called flow control statements to allow your program to choose to execute certain pieces of code, for example moving forward only if one of the line sensors detects the line. If statements If statements in C allow you to control whether or not the block of code following it is executed depending on some condition being true. The basic syntax is shown below, where condition is some logical condition such as two numbers being equal, a value not being zero, or something else that can be answered with true or false. If that condition is true, then the next block of code in curly braces, or the next line, is executed. If the condition is false, then the program simply skips that portion of the code. if(condition) // execute this code if condition is true Else statements Another useful statement is the else statement. After the end of any block of code in an if statement, an else statement can be evaluated. If the condition of the if statement is false, then the code in the else block is executed, so the program has to choose one or the other based on condition. Page 6 of 14

Example if-else block if(condition) // code to execute if condition is true else // code to execute if condition is false Loops In most programs from robots up to desktop applications, there are frequently tasks that need to be repeated numerous times, sometimes indefinitely. Instead of simply writing the same code over and over to do this until you run out of program space, the C language has built in loops that will execute a block of code repeatedly. The three types of loops in C will be discussed briefly below. While Loops While loops are one of the easiest types of loop to understand, and you will frequently use them in your programs. A while loop simply continues executing a block of code as long as a condition is logically true. This condition is only checked once per loop cycle at the start of the loop, so the code in the braces will execute up through the last cycle where condition is true. The basic syntax of a while loop and a quick example follow: while(condition) Code to execute goes here Example while loop that adds one to z until z=4 int z=2; while(z!=4) z=z+1; Do-While Loops Do-While loops are similar to while loops, however they check the loop condition at the end of the loop cycle instead of the start. The syntax of a do-while loop is as follows: do Code to execute goes here while(condition); Page 7 of 14

For loops For loops are used to execute a block of code for some number of iterations. If you need to do something 10 times or count through some number of values, such as the elements in an array, a FOR loop is most commonly used. A for loop requires a counter variable, some logical condition to check to stay in the loop and something to do to the counter variable in each loop cycle. The basic syntax and an example follow: declare counter variable for(initialize counter; condition to exit loop; action to take each loop) Code to execute goes here Example FOR loop that runs 10 times (i=0-9, incrementing once per loop) multiplying the value z by 2 each iteration. The result of z should be z*2 10 : int z=1; unsigned char i; for(i=0, i<10 ; i++) z=2*z; Comments Comments are parts of a program source code file that are written so programmers can document their code and understand other people s code as it is not always 100% readable. When code is compiled into a program, the computer skips over all commented areas so portions of code can even be turned into a comment. There are two ways to make comments in C, which will be briefly described. Single line comments start with // and continue to the end of the current line. Multi line comments allow you to comment out multiple lines of a file starting with /* and ending with the opposite */. Both types of comment can be used to comment out parts of your code if you wish to temporarily disable it. Commenting Examples: // This is a single line comment comment /* This is * a * multi line comment */ // a = b+c; Headers, Source Files, and Libraries Often times when writing in C, you will not want to write every program entirely from scratch in one.c file. Thankfully, C allows for code reuse and use of multiple code sources with #include statements. The #include statement allows you to use what are known as header or.h files, which Page 8 of 14

include programming definitions, function declarations, and other important information about another.c file or a pre-compiled library containing the implementation of that information. Effectively it allows you to have a functions and data in another file that can be called from the file you are currently working in. Including header files is done in one of two ways. First, if the header is from a standard library for AVR-GCC, such as the I/O library, the delay library, or the default AVR serial libraries, then the file name to include goes in angle brackets < and >. These standard libraries come with Win- AVR and AVR-GCC should automatically know where to find them. If you want to include another one of your source files, or one from the ORKWare library source, the file name relative to the main project folder must be entered using quotations and. For example if you are working in the ORKWare folder, the relative file name for the motor library would be OrkLib/OrkMotorBasic.h Example of including header files: //Include a standard library with <header.h> #include <avr/io.h> //Include your own source file with header.h #include OrkLib/OrkCore.h 2. Writing a Simple ORK Program Now with a basic understanding of how to program in C, let s write a simple program for the ORK to get used to the libraries created for making the ORK move and sense things in its environment. Using a text editor (Programmer s Notepad for example) open the file OrkMain.c that was included in ORKWare.zip. You should scroll down to the main() function to begin writing your program. This code makes the ORK perform a slow dance of moving forwards, backwards, and then turning left before repeating the process. The program only requires two functions from the ORKWare libraries, setmotor(motoraddress, speed) and delay(time). The delay function simply makes the robot continue doing what it is currently doing for the number of milliseconds entered into the parameter. The set motor address sets the speed of each motor with two parameters, the motoraddress to which you should enter LeftMotor or RightMotor and a speed from -128 to 127. The speed is full forward at 127, stopped at 0, and full reverse at -128. Now, write the following code inside the curly braces in the while(1) loop located in the main function. Page 9 of 14

int main() while(1) // Start your program here // Go Forwards setmotor(leftmotor,127); setmotor(rightmotor,127); delay(1000); // Delay for 1000 milliseconds // Go Backwards setmotor(leftmotor,-128); setmotor(rightmotor,-128); delay(1000); // Turn Left setmotor(leftmotor,-128); setmotor(rightmotor,127); delay(1000); // End your program here Now compile your code using the included makefile. To do this in programmer s notepad go to Tools->[Win-AVR] Make All and AVR-GCC should begin running. Text should start appearing in the output console at the bottom of the screen and eventually it will say in blue letters that the exit code is 0. If the exit code is not 0, there were errors with the program that will be described further up in the output console. You should now have a file called orkprogram.hex in the source folder, this contains the program that is ready to be loaded onto the ORK. 3. Loading a Program onto the ORK over USB Connecting the ORK to a PC 1. Set the RUN/PRG jumper to the PRG position 2. Power on the ORK 3. Press the red reset button, the LED labeled LED should turn on 4. Plug the ORK into the PC with a USB A to mini-b cable 5. The ORK should now be connected Using the ORKWare USB Loader: 1. Open ORKWare Loader.jar 2. Check that the selected microcontroller is an ATmega32U4 3. Click the Browse button and find 4. Click the Program button to load your program onto the ORK 5. Wait until the output console says that programming has completed successfully 6. Set the ORK RUN/PRG jumper to the RUN position 7. Reset the ORK with the power jumper or reset button Page 10 of 14

4. Making Your ORK Follow a Line Basics of Line Following Basics of the Challenge The goal of the line following challenge will to have your ORK, or any autonomous robot, navigate across a black electrical tape curve on white paper from a starting point to an ending point. The line will have multiple changes of direction, right angle turns, and may have gaps from 1-2 in the line. The robot that makes it to the end the fastest, over multiple trials, wins the competition. Any close times will result in a sudden death match. The end will be marked by a solid black square the size of the robot. In general, the closer you stay to the line, the less distance you must travel and the quicker you make it to the end. Try to optimize your robot so that it does not wobble much on the line. Hardware modifications may give you a serious edge, including higher power motors and motor drivers that will increase the speed of your robot. Controlling Motors To control the motors, use the setmotor(motor, speed) function from the OrkMotorBasic.h file. This function sets the specified motor to some speed between -128 to 127. The motors are already defined in OrkMotorBasic so you may simply type LeftMotor or RightMotor into this function to address the motor correctly. Enter a char value in as the speed parameter, keeping in mind that positive values make the motors go forwards, zero is stopped, and negative values go backwards. Once the motors are set to a speed, they will continue to operate at that speed until it is updated by another setmotor() call. For very low speeds, the motors may not turn as they require some minimum power to overcome friction. Example for making the robot spin to the right slowly: setmotor(leftmotor, 80); setmotor(rightmotor, -80); Reading Sensors The line sensors work by reflecting infrared (IR) light off of a nearby surface into an IR detector. If the surface is highly reflective, as white paper is, then the sensor will return a 0 or False value. If the sensor is above a non-reflective surface, such as a black line, then they will return a 1 or True value. To read in these sensors, you will have to read the digital input of the microcontroller that is connected to each sensor. To do this, use the readdigitalpin(address) function. This function returns the logical value (0 or 1) of the sensor input at the address. For the address input, use CON1, CON2, CON3, etc. for the sensor hooked up to that connector. Page 11 of 14

Example for reading a line sensor. The returned value of the function can also be used as a truth value and be evaluated with other sensor values as shown in the if statement. unsigned char sensor1; sensor1=readdigitalpin(con1); if(readdigitalpin(con2) && readdigitalpin(con3)) //Do something here Handling Input Much of your line following program will likely be if and else statements that check the values of the sensors and then act on each sensor combination. Prior to coding, the best thing to do will to write down all of the possible sensor combinations you wish to handle, write down what each set of sensor inputs means, and write down what you think the robot should do in each case. This can then be turned into a large series of if-else statements to check each one of your states. You don t need every single sensor combination in the if statements, just the ones that cause the robot to change what it is doing. You can also simplify the states if you do not care about some of the sensors for a particular set of states (for example only needing the input from the center two sensors) Example using if-else statements to check robot states and act on them bool sens1, sens2, sens3, sens4; while(1) sens1=readdigitalpin(con1); sens2=readdigitalpin(con2); sens3=readdigitalpin(con3); sens4=readdigitalpin(con4); // All sensors detect a line At the end if(sens1 && sens2 && sens3 && sens4) // Stop setmotor(leftmotor, 0); setmotor(rightmotor, 0); else // All but sensor 4 detect the line if(sens1 && sens2 && sens3 &&!sens4) Page 12 of 14

else // Swing to the left setmotor(leftmotor, 0); setmotor(rightmotor, 127); Using Delay One useful tool in making a simple line follower is the use of time delays. As most of your program will likely execute thousands up to hundreds of thousands of times per second, this can sometimes lead to updates that are too fast to even have a noticeable effect on the physical robot system (such as changing the motor speed). Slowing your program down so it only changes its motor speed around 20-100 times per second will mostly fix this problem. To do this, add a delay by using the delay() function. The parameter of the delay is simply the time to wait in milliseconds before going to the next line of code. Example of using a delay at the end of a loop while(1) delay(20); // Delay for 20ms 5. Debugging Your Code Coming Soon Appendix A: ORK Library Reference OrkCore Definitions TRUE and true, 1 FALSE and false, 0 CON1, 1 CON2, 2 CON3, 3 CON4, 4 CON5, 5 CON6, 6 CON7, 7 Types char Boolean unsigned char unsigned 8-bit integer: uint8 Functions bool readdigitalpin(unsigned char address) Reads the digital value (0 or 1) of the addressed pin Page 13 of 14

Valid inputs: CON1-CON7 Output: The value (0 or 1) returned by the sensor plugged into the CONx sensor bool readlinesensor(unsigned char address) Currently the same as readdigitalpin() Valid inputs: CON1-CON7 Output: The value (0 or 1) returned by the sensor plugged into the CONx sensor bool readproxsensor(unsigned char address) Currently the same as readdigitalpin() Valid inputs: CON1-CON7 Output: The value (0 or 1) returned by the sensor plugged into the CONx sensor void ledon() Turns the LED on void ledoff() Turns the LED off void ledtoggle() Toggles the LED on and off OrkMotorBasic Coming Soon OrkMotorL298 Coming Soon OrkADC Coming Soon Appendix B: Advanced AVR Programming Topics The basics of AVR I/O ADC Usage Timer/Counters and PWM Serial Communications Glossary -Under Construction- Page 14 of 14