Introduction to RobotC

Everything you need to get started with your programming adventures.

by the RCGFoPL

1
This
nyanical
guidewaswrittenbytheRCGFoPL.
Contactusat
https://sites.google.com/site/rcgfopl/
or
[email protected]
.

Time for Introductions.

Whats RobotC?
RobotC is a programming language used to program robots
participating in FTC competitions.
RobotC is a text-based programming language. It does not use drag and drop
blocks like NXT-G or LabView -- instead, it uses text to command (and conquer)
the robot.

Where Do I Get It?

To program, compile, and download programs to the robot, you must use the
RobotC IDE, which comes with your FTC robotics kit on a CD. It can also be purchased
at
http://www.robotc.net
.

2
This
nyanical
guidewaswrittenbytheRCGFoPL.
Contactusat
https://sites.google.com/site/rcgfopl/
or
[email protected]
.

So How Does One Write Code?

There are a few simple rules to follow when writing your code. These are called the
syntax
of the programming language. First off, code is organized into three basic types:
pragmas, lines, and blocks.
Pragmas
, also called pre-processor directives, always start with a hash (
#
). For
RobotC, youll generally only use them for hardware setup and including libraries,
which well cover later.
Example:
#include JoystickDriver.c
Lines
are the basic instructions in your code. They tell the program to set values or
execute functions. These lines always end in a semicolon (
;
).
Example:
motor[motorA] = 50;
Blocks
are groups of lines that are bunched together within curly brackets (
{ }
).
Unlike lines, blocks do not end in semicolons. Blocks include the main task,
functions, and control structures, among other things.
Example:
task main {
...lines of code go in here...
}

3
This
nyanical
guidewaswrittenbytheRCGFoPL.
Contactusat
https://sites.google.com/site/rcgfopl/
or
[email protected]
.

Now for the fun stuff.

With the introductions out of the way, lets get down to actually writing some code.
There are a few key components to every program in RobotC: setting up and initializing the
hardware, defining supplementary variables and functions, and the main task.

Hardware Setup
Before we can tell our robot to do anything,
we need to initialize the hardware. But dont worry;
as scary as this sounds, RobotC makes it rather
trivial. Just open up the
Motors and Sensors
Setup
dialog, accessible from the
Robot
menu.
From here, you can define the motors and
sensors that will be connected to your robot. You
can also give names to these motors and sensors so
you can refer to them in the code. Once finished,
click OK and RobotC will
magically
insert a few lines
of code at the top of your file. You may always change the setup using the same dialog
later on, and RobotC will update these lines of code to reflect those changes.

Main Task
The main task is what your robot will do when you run the program.
Think of it as the main list of instructions in a how-to guide; after everythings set up
and you have all the required materials, its the step-by-step guide that tells the
robot exactly what to do.
Heres how to define it in your code:
task main {
...put the code in here...
}

Motors
To activate a motor, use the following format:
motor[
motorA
]=
100
;
Substitute
motorA
with whatever name you gave to the motor you wish to
run.
The value
100
can be substituted with any value from -100 to 100. It is the
percentage of power to run the motor at, with negative values causing the
motor to go in reverse direction.
4
This
nyanical
guidewaswrittenbytheRCGFoPL.
Contactusat
https://sites.google.com/site/rcgfopl/
or
[email protected]
.

 Keep in mind, when you set the value of a motor, you are turning it on. The motor
will continue to run until you specifically tell it to turn off.
To stop applying power to a motor, use the following line, once again replacing
motorA
with the name you gave the motor:
motor[
motorA
] = 0;

The Wait Function

Often, you will need your program to wait a specified measure of time before doing
something. A common example is running a motor for a pre-measured length of
time before stopping, such as when you want to go a certain distance.
There are two forms of the wait function:
wait1Msec(
1000
);
This waits for one millisecond times the value in the parentheses.
wait10Msec(
1000
);
This waits for ten milliseconds times the value in the parentheses.
Therefore,
wait1Msec(1000);
and
wait10Msec(100);
do the same thing: wait for 1
second.
Here is an example of the wait function being used in conjunction with motors:
motor[motorA] = 100;
wait1Msec(5000);
motor[motorA] = 0;
This code will run the motor in port A at full power for 5 seconds before turning it
off again.

5
This
nyanical
guidewaswrittenbytheRCGFoPL.
Contactusat
https://sites.google.com/site/rcgfopl/
or
[email protected]
.

Time to Get Fancy.

Now that we have introduced you to the basics of RobotC and controlling the robot,
its time to learn how to do more complex things.

Comments
Comments are used to annotate your code. They can be incredibly useful in
providing information (explanations, todos, bugs, goals, etc.) about your code to yourself or
other programmers. This is especially applicable when multiple people are working on the
same project -- notes can be left for the other programmer to read. Comments can also be
useful in reminding
yourself
about information -- it can be tricky to remember all of the
idiosyncrasies of the program when there are hundreds of lines of code.
Comments are denoted in two different fashions:
motor[motorA] = 100;
//this is a comment
wait1Msec(1024);
/
* this is a
magical
multiline comment*/

Here is an example of comments being put to practical use:

motor[motorA] = 100;
//robot arm moves
wait1Msec(102400000000);
/*Phil, I think there is a bug here,
the rest of the program will not run*/

motor[motorA] = 0;

Variables
Variables store data.
There are different types of variables used for storing different types of data. The
most common ones are:
int
-- integer.

Examples:
5; -3; 0; 40028;
float
-- supports decimal values. E

xamples:
5.023; -99.2; 4; 3.141592;
string
-- text.

Examples:
Hello, world!; whats your name?; qwerty is

inferior; I am 9982883048723 years young!

bool
-- true/false values.

Examples:
true; false;

There are three primary actions you perform concerning variables:

Defining
is when you first pop the variable into existence. In this step, you
give it a name and a type, as such:
int x;
Here, we define an integer whose name shall be
x
.
Setting
is when you assign a value to a variable, like this:
x = 5;
From now on in the program, x

s value will be five (unless we change it again

later on).
6
This
nyanical
guidewaswrittenbytheRCGFoPL.
Contactusat
https://sites.google.com/site/rcgfopl/
or
[email protected]
.

 Getting
a variable returns its current value. This action is not its own line, but
is an expression which you can put into another line. To get the value of a
variable, simply type its name in place of a normal value:
motor[motorA] = x;
You can even set one variable to the current value of another:
y = x;
In this case, the program will read the current value of x

and set that as the

value of
y
.

Control Structures
Control structures are blocks you can use when you need to introduce logic or
repetition into your code. Theyre pretty straightforward:
The
if else
statement is the most basic way if introducing logic-based execution in
your code. Use them like this:
if (
y < 5
){
motors[motorA] = 100;
} else {
motors[motorB] = 100;
}
The code inside the parentheses after i
f
must evaluate to a

bool
value. If it is
true
,
the first block of code will execute; if it is
false
, the block after
else
will execute.
The
else
block may be omitted if you dont need to do anything when the value is
false
.
The
while
statement is used for repeating a block of code until the given b
ool
expression evaluates to
false
. Observe:
while (
5 == 4 + 1
){
motors[motorA] = 100;
wait1Msec(1000);
motors[motorA] = 0;
wait1Msec(1000);
}
The program, upon encountering the
while
block, while proceed as follows:
1. Check if the given expression evaluates to t
rue
or f
alse
.
2. If
true
, run the code inside the block, then go back to Step 1.
3. If
false
, exit this
while
block and continue with the rest of the program.
The while block can also be used to wait until a given expression is no longer true by
omitting the block part of it. For example:
while (
numberOfMagicalCookies == 0
);
Here, the program will constantly re-evaluate the expression until it returns false
before continuing. You will see later why this can be rather useful.
The
do while
statement is very similar to the w
hile
statement. The only difference is
7
This
nyanical
guidewaswrittenbytheRCGFoPL.
Contactusat
https://sites.google.com/site/rcgfopl/
or
[email protected]
.

the order in which it performs its logic and the syntax:

do {
motors[motorA] = 100;
wait1Msec(1000);
motors[motorA] = 0;
wait1Msec(1000);
} while (
y < 5
);
As opposed to the normal
while
block, the
do while
block executes in this order:
1. Run the code inside the block.
2. Check if the given expression evaluates to t
rue
or f
alse
.
3. If
true
, go back to Step 1.
4. If
false
, exit this
while
block and continue with the rest of the program.
The
do while
block runs the code before it bothers checking if the expression
evaluates to
true
. The use of this is that even if the expression evaluates f
alse
from
the very start, you can still be sure the contained code will execute at least once
before the program moves on.
The
for
statement is a very useful control structure which makes use of variables.
The first part of it looks like this:
for (int x = 0; x < 5; x++) {
Pay special attention the the stuff in the parentheses. There are three parts, divided
from each other by semicolons.
The first part (
int x = 0
) is run once at the very beginning of the
for
statement.
In this case, we define a variable
x
and set it to 0.
The middle part (
x < 5
) is an expression run after every time the code block is
executed to determine whether or not to continue -- just like a w
hile
statement.
The last part (
x++
) is also run after every time the code block is executed. It is
generally meant to update the variable, in this case, by incrementing it.
In this case, the for loop will run a total of five times. Also, inside the code block, by
getting
x

, our code can figure out which of those five times it is running.
Example:
//this will increment the power of motorA in 10% increments over 10 seconds.
for (int x = 1; x <= 10; x++) {
motors[motorA] = x * 10;
wait1Msec(1000);
}

Functions
Functions are handy,
magical, crumbly, unbelievably tasty bits
of code that you
can create once and reuse as many times as you want. Often, you will hear these
being referred to as
functions
and
methods
interchangeably. This is because some
programming languages call them functions, and others, methods. In reality, i
ts all
8
This
nyanical
guidewaswrittenbytheRCGFoPL.
Contactusat
https://sites.google.com/site/rcgfopl/
or
[email protected]
.

the same thing

(well, not
really
, but we dont need to worry about that.)
Remember
wait1Msec(1000)
? Thats a function. Lets dissect what is taking place in
this line of code:
wait1Msec()
is the function itself.
1000
is the value being p
assed
to the function. When a value (or variable) is
being passed to a function it is called an
argument
.
In this case,
wait1Msec()
is
using that argument to determine the amount of time to wait.
Functions can also
return
values, for example:
motor[motorA] =
myFuncWhichReturnsAnInt()
;
In this case, that function with the rather unwieldy name returns an
int
. We then set
the power of motorA to that i
nt
which it returns.
Functions that dont return anything are referred to as
void
functions. These
functions just
do
stuff -- they dont return any values that can be used for other
things.
wait1Msec();
is a void function.
Writing functions/methods
is where all the fun is. Heres how to do it:
int tricyclesRule(int x, int y) {
int z = x*y;
return z;
}
Okay, dont panic! Instead, lets all take a five minute
pie
break. While enjoying our
pie, lets walk through the above code. In the first line,
int
says that our function will
return an
int
. If it was a void function, we would write v
oid
there. Next, we have the
method name. Inside the parentheses, we define our parameters.
But you said
they were arguments!
The actual variable or value that is passed to the function
when it is called
is called the argument. The variable(s) f
ound in the method
declaration
are called parameters. This first line of code is called the m
ethod
declaration
.
Next we have the code which will execute when our function is called. Notice at the
very end
return z;
. This is called the
return statement
. When the program is
running and it encounters this, it will exit the method and return the given value (in
this case,
z
). It is important to understand the fact that the program leaves when
encountering this statement -- even if there was more code after it, in which case it
will skip that code. If the method is a void, you can just type r
eturn;
-- you dont need
to type any value after return, as the method wont be returning any value. Once
your function is written, you can call it in much the same way as
wait1Msec();
-tricyclesRule(5, 9);
(passing these arguments will get a return value,
z
, of 45). Do you
see now, how the pie is very
crumbly
and
tasty
,
just like the code?

Pragmas
A pragma, or pre-processor directive, gives the compiler instructions on how and
what extra stuff to compile. Pragmas have two main uses in RobotC:
Include statements
are used for importing libraries (and even other files you wrote
9
This
nyanical
guidewaswrittenbytheRCGFoPL.
Contactusat
https://sites.google.com/site/rcgfopl/
or
[email protected]
.

yourself) into your program. A common example is importing the drivers for using
the joysticks or for using third-party sensors.
#include
JoystickDriver.c

Inside the quotes, put the name of the file you wish to import. Just remember that
the file must be in the same folder as your source file for the compiler to properly
find it.
Hardware setup
pragmas tell the program to initialize hardware connected to the
robot. The code that
magically
appeared at the top of the file after the hardware set
up contained pragmas. Specifically, it told the compiler what names to accept for
motors and sensors, as well as other things. While these lines of code are v
ery
important
, you will not need to edit them. Any changes you wish to make pertaining
to hardware can be done through the procedures outlined earlier in this guide.

Sensors
Sensors, such as the touch sensor, provide information to the robot. While there are
many different types of sensors, here is an example of a practical way to use the touch
sensor:
Say, for instance, that you need your robot to travel forward until it hits a wall, stop,
and turn. The touch sensor is a very useful tool for the job. Using the sensor and a
while
statement, you can command the robot to move forward until it hits a wall (depressing the
touch sensor), stop, and turn.
To access a sensor, use the following syntax:
SensorValue[
sTouch
]
where
sTouch
is the name of the sensor.
The code would look something like this:
motor[motorA] = 100;
//turn on both motors to go forward
motor[motorB] = 100;
//wait until the touch sensor is pressed
while (SensorValue[touchSensor] != 1);
motor[motorA] = 0; /
/stop motorA but allow motorB to continue, so that
//we turn

Seeking Rescue
from Evil Unicorns
In case youve hungrily consumed
this entire guide and want to learn more
about RobotC, youre in luck. The people
10
This
nyanical
guidewaswrittenbytheRCGFoPL.
Contactusat
https://sites.google.com/site/rcgfopl/
or
[email protected]
.

who created RobotC have

magically
prepared a d
ecadent
feast of knowledge, otherwise
known as documentation. They even had the foresight to include this
masterpiece
of

knowledge inside the RobotC program.

To access this joyous wonderland, go to
Help -> RobotC Help
and read to your

hearts content. Or, if youre feeling stylish, you can just press the
F1
key (thats how all the
cool kids do it.)
Documentation is also available on the RobotC website:
http://www.robotc.net/support/nxt/MindstormsWebHelp/index.htm

11
This
nyanical
guidewaswrittenbytheRCGFoPL.
Contactusat
https://sites.google.com/site/rcgfopl/
or
[email protected]
.