Creating driving functions

From ROBOTC API Guide
< Tutorials‎ | Arduino Projects/Mobile Robotics/Lego
Revision as of 14:12, 10 August 2012 by Greycompanion (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Repetition

By now you have probably noticed that blocks of code are often repeated multiple times throughout your programs. Take for example the code to drive forward at speed 100.

motor[leftServo] = 100;
motor[rightServo] = 100;

or the code to stop

motor[leftServo] = 0;
motor[rightServo] = 0;

Constantly typing in these blocks gets to be tedious and time consuming, something no one wants. Fortunately, there is a way to make it simpler and easier, through the use of Functions.

What is a Function?

A Function is a special block of code that runs as a single unit when called from another location in the code. It is common for each function to represent a specific behavior in the program. Each function has a unique name within the code, and it is by referencing this name that you call and thus run the function.

The first step to using a function is to define it. Lets say that we have the following code:

task main()
{
  while(true)
  {
    //drive forward at speed 100 for 1 second
    motor[leftServo] = 100;
    motor[rightServo] = 100;
    wait1Msec(1000);
 
    //stop driving for 1 second
    motor[leftServo] = 0;
    motor[rightServo] = 0;
    wait1Msec(1000);
 
    //right point turn at speed 100 for 1 second
    motor[leftServo] = 100;
    motor[rightServo] = -100;
    wait1Msec(1000);
 
    //stop driving for 1 second
    motor[leftServo] = 0;
    motor[rightServo] = 0;
    wait1Msec(1000);
 
    //drive backward at speed 80 for 2 seconds
    motor[leftServo] = -80;
    motor[rightServo] = -80;
    wait1Msec(2000);
 
    //stop driving for 1 second
    motor[leftServo] = 0;
    motor[rightServo] = 0;
    wait1Msec(1000);
  }
}

You might notice that the code to stop driving for 1 second occurs 3 times in the program.

//stop driving for 1 second
motor[leftServo] = 0;
motor[rightServo] = 0;
wait1Msec(1000);

Defining a Function

So if we wanted to make the code shorter, and in most cases easier to read, we could put the stopping code into a function and call that function when we want to stop. To do this we would first place the following function definition in the file before task main().

//function to stop the robot for 1 second
void StopFor1Second()
{
  motor[leftServo] = 0;
  motor[rightServo] = 0;
  wait1Msec(1000);
}

Lets talk for a moment about the structure of a function definition. You'll notice that there is a comment on the first line of the code block. This comment is not required, but it is a good practice to have a comment that explains what the function does. This makes it easier for other programers to follow your code and also makes it easier to come back to a program later and modify it.

Next you will see void StopFor1Second(). This line tells the compiler that the code in the brackets is a function. The first word on the line is void. The word void can be replaced by a few others, but that is not particularly important in this tutorial. For now all you need to know is that void basically tells the compiler that when the function is called, just run the function code, then return right back to where it was called from (Other words will cause the function to return a value of some sort in addition to performing the code within). The next word is the name of the function. In this case we are calling the function "StopFor1Second" since it will make the robot stop for 1 second. You will also notice the parentheses immediately after the function name. The purpose of these will be discussed later in this tutorial.

Notepad.gif NOTE: When naming your functions you need to remember that the name can not contain any white spacing. That means no spaces, new lines, or tabs. To make function names easier to understand, it is standard practice within any C based language to capitalize the fist letter of each "word" in the name. For example, if you are thinking "do this simple task" you would name it "DoThisSimpleTask". It is also acceptable to leave the first word non-capitalized, for example "doThisSimpleTask"

Now you define the code that will be run when the function is called. Just like with task main(), while() loops, and for() loops, this code is placed inside of curly brackets { }.

Using a Function

Now that the function is defined, we can go ahead and replace the code in task main() to stop the robot with a call to the new function. To call a function, you simply enter the name of the function where you want to run it and end with a semi-colon. In this case the name of the function is StopFor1Second(), so we would use StopFor1Second();. So if we replace all the code, we get

//function to stop the robot for 1 second
void StopFor1Second()
{
  motor[leftServo] = 0;
  motor[rightServo] = 0;
  wait1Msec(1000);
}
 
task main()
{
  while(true)
  {
    //drive forward at speed 100 for 1 second
    motor[leftServo] = 100;
    motor[rightServo] = 100;
    wait1Msec(1000);
 
    StopFor1Second();
 
    //right point turn at speed 100 for 1 second
    motor[leftServo] = 100;
    motor[rightServo] = -100;
    wait1Msec(1000);
 
    StopFor1Second();
 
    //drive backward at speed 80 for 2 seconds
    motor[leftServo] = -80;
    motor[rightServo] = -80;
    wait1Msec(2000);
 
    StopFor1Second();
  }
}

Advanced Functions

Of course, it is possible to use functions to do more than just reduce repetition.

Passing Parameters

Parameters are a way of passing information into a function, allowing the function to run its commands differently depending on the values it is given. It may help to think of the parameters as placeholders – all parameters must be filled in with real values when the function is called, so in the places where a parameter appears, it will simply be replaced by its given value.

Now lets say that you have some blocks of code that are very similar, and the only difference is that they have different motor speeds.

task main()
{
  //drive forward at speed 100 for 1 second
  motor[leftServo] = 100;
  motor[rightServo] = 100;
  wait1Msec(1000);
 
  //stop for 1 second
  motor[leftServo] = 0;
  motor[rightServo] = 0;
  wait1Msec(1000);
 
  //drive backward at speed 80 for 1 second
  motor[leftServo] = -80;
  motor[rightServo] = -80;
  wait1Msec(1000);
 
  //stop for 1 second
  motor[leftServo] = 0;
  motor[rightServo] = 0;
  wait1Msec(1000);
}

It is still possible to use functions to make the code less repetitive, cleaner, and more manageable by using functions with parameters. In the case of the code above, we would pass the desired motor speed to the function in a parameter.

To define a function that accepts parameters you take the basic function definition and inside the parentheses, you place the variable name and type of the parameter you wish to use. In this case we want to pass an int (a data type that stores integers) that represents the motor speed, so we will call it "speed".

//set both drive motors to the specified speed and wait 1 second
void SetBothMotors(int speed)
{
  motor[leftServo] = speed;
  motor[rightServo] = speed;
  wait1Msec(1000);
}

Using a function with parameters is very similar to using one without any. The difference is that when calling the function, instead of having empty parentheses, you place the value you wish to pass inside the parentheses.

//set both drive motors to the specified speed and wait 1 second
void SetBothMotors(int speed)
{
  motor[leftServo] = speed;
  motor[rightServo] = speed;
  wait1Msec(1000);
}
 
task main()
{
  //drive forward at speed 100 for 1 second
  SetBothMotors(100);
 
  //stop for 1 second
  SetBothMotors(0);
 
  //drive backward at speed 80 for 1 second
  SetBothMotors(-80);
 
  //stop for 1 second
  SetBothMotors(0);
}

You are also able pass more than one parameter to a function. This is done by separating the list of parameters with commas. So say that we needed to modify the above code to allow variable times, you would end up with:

//set both drive motors to the specified speed and wait 1 second
void SetBothMotors(int speed, int time)
{
  motor[leftServo] = speed;
  motor[rightServo] = speed;
  wait1Msec(time);
}
 
task main()
{
  //drive forward at speed 100 for 1 second
  SetBothMotors(100, 1000);
 
  //stop for 1 second
  SetBothMotors(0, 1000);
 
  //drive backward at speed 80 for 2 seconds
  SetBothMotors(-80, 2000);
 
  //stop for 1 second
  SetBothMotors(0, 1000);
}