These articles are all about programming robots for Botball competition. If you've never programmed before, fear not! Pay attention at the workshop if you get the opportunity to attend, otherwise, flip through the workshop slides and have someone who did go explain them to you.

After that, start off on the Hello World article for a review of the basics. Hold on to your hats though, because we'll quickly cover the most useful coding advice and information, from Servos to the infamous Create. With key understanding of the different kinds of devices you'll be programming and the functions to use, we'll then switch our focus to programming itself, and cover more abstract concepts that will let you create more intelligent robots.

As always, if you've got a question or suggestion, just post a comment at the bottom of an article!

Hello World

This will be your first chapter into the world of Botball programming with the KISS-C programming environment. You will learn the basics of how to start your program, the proper formatting of programs, commenting your code, and we will also get into examples of using the printf() command to print out text to the screen and also the fd(), bk(), off(), and ao() commands that will teach you how to run very simple motor functions.

Setting Up Your First Program

Here is a very simple program for KISS-C, which displays the words "Hello World!" on the screen.

  1. int main()
  2. {
  3. printf("Hello World!\n");
  4. return(0);
  5. }

If this looks really scary to you, that's fine -- it looks scary to all new programmers. Let's go through bit by bit, and we'll explain what this code is doing.

  1. int main()
  2. {
  3. printf("Hello World!\n");
  4. return(0);
  5. }

Lines 1, 2, 4, and 5 of the code above will be the same in just about all programs you write. All you need to know at this point is that when the computer runs your program, it will look for the "int main()" and run all the commands that are inside the following curly braces, stopping at the "return(0);" line. If you put your program's commands outside of those curly braces or after the "return(0);", it won't work properly.

  1. int main()
  2. {
  3. printf("Hello World!\n");
  4. return(0);
  5. }

On line 3, the "printf" function (a function is a command that does a particular thing) displays text on the screen. When we're giving information to a function about what it should do (e.g. giving printf the text to display), we put parentheses around the information, and put it after the function name. In this case, the data we're passing to printf is "Hello World!\n", so we stick that in parentheses and put it after printf. You may be wondering why the text is in quote marks -- whenever you're passing text of some kind to a function (as opposed to a number), you enclose it in double-quote marks. The \n at the end of the text is called a newline, and is the equivalent of pressing the Enter key to go to the next line. You should always put \n at the end of your printf text; otherwise, later printf commands will print on the same line, which looks weird. Finally, after the closing parenthesis for printf, we put a semicolon. In English, sentences stop with a period; in the C language, commands stop with a semicolon. Forgetting the semicolon is probably the most common mistake among new C programmers.

If you want to see your Hello World program in action, click Simulate in KISS-C, and you'll see it run on your computer. Or, you can click Download, and run it on your CBC.

Commenting Your Code

Something that good programmers do is comment their code. The sole purpose of commenting your code is to make it readable by people. Comments are also completely skipped over by the compiler, so you can write whatever you want in your comments, and they won't affect what your program does at all. Comments should describe what the code does, in a way that people unfamiliar with your code will understand. There are two types of comments in C. There are 1 line comments, and multi-line comments. Here is an example of using comments:

  1. /* This is a multi-line comment. Everything from after the forward slash and asterisk
  2. all the way until I end it with an asterisk and forward slash is a comment. So this can
  3.  be as many lines long as you want! You might stick one of these at the top of your
  4. program, with information on the author and maybe a change log.
  5.   */
  7. int main()
  8. {
  9. //These are one-line comments. Everything after the two forward slashes
  10. // to the end of the line is a comment.
  11. // You might use this to describe what specific lines of your code do, like this:
  13. printf("Hello World!\n"); // displays a greeting on the screen
  15. return(0);
  16. }

Above you see the first comment is a single line comment. To start a single line comment you start with two forward slashes (//). Everything after those two forward slashes on until the end of the line will now be a comment. It will not be compiled by the compiler and will have no affect on your program, but can be there to let the reader of the program know what the line before or after does or something along those lines. Next we see the multi-line comment. The multi-line comment starts with a forward slash and an asterisk (/*). Everything after the forward slash and asterisk is now a comment until you end it with an asterisk and then a forward slash (*/). These can be useful at the beginning of your program when you want to write in an in-depth explanation of the program and it is too long to be on just one line.

There are two main reasons why you should liberally comment your code. The first reason is that you may be sharing your code with someone else, and you need them to be able to figure out what your code is doing. But, you ask, what if you're not ever going to give your code to someone else? Well, be careful when making that claim, because if you ever have a problem with your code, you'll probably want to send a snippet to a friend or post it on a forum to get help. But even if you won't be sharing your code, what happens when, next year, you haven't touched your code in 6 months, and you want to add a small feature? Chances are, you'll have forgotten the inner details of how your code works. Comments will save you here. To make a long story short, you will usually regret it if you don't comment your code. So don't make that mistake.

The fd(), bk(), off(), And ao() Commands

Now that we have a basic understanding on how our program is setup and will look, and we've now seen how calling a function works, lets talk about simple motor movements. Here you will learn how to use the fd() [forward] bk() [backward] off() [off] and ao() [all off] commands. These have to do with moving the motors and each accept only one parameter, which is the motor port number (written next to the motor port on the CBC). The exception is ao(), which applies to all the motors, and so doesn't need you to specify a motor port number. Here is a simple example on how to use these commands:

  1. int main()
  2. {
  3. fd(1); //Turns motor number 1 on at full speed going forward
  4. bk(1); //Turns motor number 1 on at full speed going backward
  5. ao(); //Turns all motors off
  6. //Alternativly you could turn off individual motors by using off(motor number);
  8. return(0);
  9. }

So here we show easily how you can turn motor number 1 going forward, backward, then off. Do not however try to use this code, because it will not work without a function you will learn in the next section called sleep(). However this does give a good example on how these functions work.

The sleep() and msleep() Commands

As you probably know, computers do things very fast. The above program will not work properly, because first the computer sees the fd(1); which turns on the motor going forward. So far so good, right? But the moment after it finishes turning on that motor (possibly a few microseconds later), it goes on to the bk(1); which turns on the motor going backward. After another few microseconds, it gets to the ao(); command, turning the motor off. The computer does this as fast as it can, and the result is that the motor is only turned on for so short a time that you can't see it -- it will look like the motor stays off. Sometimes you want the computer to run stuff as fast as possible. But other times, like here, you will want the computer to simply sit and do nothing for some period of time -- this is called sleeping. Here's an example of the sleep() command in action, fixing the problem in the above program.

  1. int main()
  2. {
  3. fd(1);//Turn motor 1 on at full speed going forward
  4. sleep(2);//Wait 2 seconds before going on to the next command -- the motor will be turning forward for these 2 seconds
  5. bk(1);//Turn motor 1 on at full speed going backward
  6. sleep(4);// Wait 4 seconds before going on to the next command -- the motor will be turning backward for these 4 seconds
  7. ao();//Turns all motors off
  8. return(0);
  9. }

So can you guess what this program will do? Well I'll tell you. The first thing it does is turns on motor 1 forward at full speed. Then it hits the sleep command which forces it to wait for the amount of time given, in this case 2 (seconds). Then it hits the backward function where it will turn motor 1 backward at full speed. Then it hits sleep yet again, which will make it wait for the amount of time given, in this case 4 (seconds). Then it hits the last line to turn all motors off, and it does so. So this will essentially make motor 1 go forward for two seconds, then backward for four seconds, then stop. So what makes this program different from the one we gave earlier? We made it sleep which forced it to wait for the motors to physically move.

There is a similar function called msleep(), which is the same as sleep, but uses milliseconds instead of seconds. (1000 milliseconds = 1 second.) You will learn more about directly using this function for specific purposes later on, especially in the create chapter.

Congratulations, you've finished the first lesson! You should now be able to display text on the screen (using printf) and turn on or off motors (using fd, bk, off, and alloff) for a specified period of time (using sleep).

Exercise: write a KISS-C program which does the following (in order):

  1. Display your name, followed by "likes to move motors!". For example, you might make it display "David Miller likes to move motors!"
  2. Wait 2 seconds.
  3. Turn on motor 1, going forward.
  4. Wait 3 seconds.
  5. Display "Now the other way!"
  6. Make motor 1 go backward.
  7. Wait 2 seconds.
  8. Turn off motor 1.
  9. Display your name, followed by "is done with the motors!"

Also, add a comment at the top of your program, with your name, your Botball team's name, and the current date.

If you have any trouble doing this exercise, reread the above lesson. If you're still having trouble and can't make any progress by rereading the lesson, ask for help on the Botballer's Chat or the Botball Forum. (Please note that if you clearly didn't try to reread the lesson, people may become terse with you after a few minutes. We want to help, but we can't help you if you can't help us help you.) Once you are able to do the entire exercise without looking at notes (i.e. you've memorized how it works), you're ready to move on to the next article!


Though a lot of a Botball match is spent driving around the board, the key to any successful robot is the manipulators it uses to score points. Though creative use of a sled can score many kinds of points in Botball matches, the highest scoring objectives almost always require the use of claws or other more sophisticated manipulators. In this article, I'll be covering the software side of these kind of appendages by controlling servos.


(TODO: Pics of servos?)

As you probably already know, servos are often used to power manipulators like claws and sweepers because of their strength and precision. Though a servo can only rotate approximately 270 degrees (TODO: hardware confirmation?), they can simply and easily be commanded to move to extremely precise and repeatable positions, and are very good at holding those positions. Once set, a servo will "fight" any attempts to move it from its set position, which is what gives claws their grasp and lift arms the ability to hold a mechanism in the air. Better yet, servos are extremely simple to use in your program! Lets start with a simple example:

  1. int main() {
  2. printf("Powering servo to its center position\n");
  3. set_servo_position(3, 1000);
  4. enable_servos();
  6. sleep(4);
  8. printf("Sending servo to position 200\n");
  9. set_servo_position(3, 200);
  11. sleep(4);
  13. printf("Sending servo to position 1800\n");
  14. set_servo_position(3, 1800);
  16. sleep(4);
  18. printf("Turning servos off\n");
  19. disable_servos();
  20. }

To try this program out, you'll need to attach a servo to port 3. To attach the servos, look for the pins labeled "S3". The servo will only connect in one direction, so be sure the yellow wire goes into the pin marked 'S', and the black wire in the pin marked '-'. When you run the program, you should see the servo spring to life and move to the center, then counterclockwise and clockwise. (TODO: I don't actually remember if lower numbers = clockwise or counterclockwise :/)

Servo Positions

Looking closely at the program, we can see that servos are really quite simple! There's really only one function to move them around, and thats set_servo_position. Let's take a closer look:

  1. set_servo_position(1, 400); // move servo 1 to 400
  2. set_servo_position(3, 0); // move servo 3 to position 0, the lowest you can go (TODO: make sure this doesn't go beyond servo's internal stops)
  3. set_servo_position(4, 2047); // move servo 4 to position 2047, the highest you can go

Are you seeing the pattern yet? set_servo_position takes two arguments, or numbers in parenthesis. The first number is always the number on the servo port that we want to move. 1 means "S1", 2 means "S2", etc. Since their are only 4 servo ports, this number should always be between 1 and 4.

The second argument is the servo's position. Before we type the second number however, we must always put a comma to separate them. Otherwise, our code won't compile. After the comma, we can put any number from 0 to 2047. This number represents where the servo should travel to. Picture the servo as the needle on a speedometer, with the number 0 on the left and 2047 on the right (TODO, double check), and all the numbers in between representing intermediate positions. The number we specify is where the "needle" will travel to.

(TODO: somebody who whip up the picture described above?)

As you're running the program, try out the other interesting property of servos: They have some "fight" to them! Try to hold the servo back as it is moving, or push it to a different place while it is stationary. It can put out a surprising amount of force, though the amount of kick it has is highly dependent on battery level. This has some extremely useful applications to Botball that will be addressed in the "Tips and Tricks" section.

Enabling and Disabling Servos

If you look closely at the program, there's actually two more functions that we haven't covered yet: enable_servos and disable_servos. Though they may seem small and inconsequential, they are actually very important to a good servo-using program.

When you first plugged in the servos, you probably noticed that nothing happened. They were completely slack, and easy to move around. This is because when you first boot the CBC up, the servos are disabled. To enable them, your program must use enable_servos. This turns on the power to all four servo ports, causing the servos to travel to and hold their set positions. At the end of program, disable_servos is used to put servos back to their disabled state, where they are loose and easy to move about.

Lets talk a bit more about the proper way to enable servos. If you look at the example program, I set the servo's position before I enabled it. This initially doesn't make much sense, so lets think about it. When servos are disabled, they have no power, so the set position has no effect. But when we enable power, the servos all begin to travel to their set positions. In this case, the servo goes directly to the position set previously. So what? Well, consider if we enabled the servos without setting a position. At least initially, they would all begin to travel to random positions. When the servo travels too far and starts ripping your robot apart trying to lower the claw into the ground, you won't be very popular among your team's builders, so always be sure to set your servos before enabling!

Disabling servos at the end of your program is equally important. It isn't safe to remove servos while they're enabled, for instance, so disabling is important so your builders can perform quick fixes without fully powering off the CBC. It also saves battery life. Enabling servos represents a small performance drain that quickly becomes a large power drain if one of the servos is under load, or being forced to exert itself holding something up. Disabling servos lets your robot relax and hold on to battery life in between runs of your program.

Finding Servo Positions

Finding useful servo positions that cause your robots claw to move correctly can be tricky. Here's a simple program you can use to calibrate a single servo. Don't worry if you don't understand it yet, it uses some more advanced programming elements which will be covered later in the guide.

  1. #define TEST_SERVO 2
  3. int main() {
  4. int pos=1000;
  5. set_servo_position(TEST_SERVO, pos);
  6. enable_servos();
  8. printf("Simple servo calibration program.\n");
  9. printf("Use the left and right buttons to move\n");
  10. printf("the servo. Press B when finished.\n");
  12. while (1) {
  13. while (1) {
  14. if (left_button() && pos > 0) {
  15. while (left_button()) { }
  16. pos -= 100;
  17. break;
  18. }
  19. if (right_button() && pos < 2000) {
  20. while (right_button()) { }
  21. pos += 100;
  22. break;
  23. }
  24. if (b_button()) {
  25. disable_servos();
  26. return 0;
  27. }
  28. }
  29. set_servo_position(TEST_SERVO, pos);
  30. printf("Current position: %d\n", pos);
  31. }
  32. }

To use it, just use the arrows to move the servo to the correct spot, then use the current position that the program prints in your program. It only moves servos in increments of 100, so if you want a finer adjustment than that you can either modify the program, or resort to a bit of trial and error.

At the top of the program, you can see that I used #define to name one of the servo's TEST_SERVO. To change the program to test the correct servo, just change the number 2 to another servo port. This is also a very good technique to try to use in your own program.

Tips and Tricks

Here's some useful tips. Even if you've programmed botball robots for a while, some of these may still be helpful! These are probably a bit beyond someone who is just learning to program, so don't worry if you don't follow these parts. Focus on experimenting with the above programs instead.

Torque your servos

You can push your servos past where they can physically go to create a strong grip, which at least my team calls "torquing" the servo. If your claw is dropping things, particularly the more squishy scoring items, try telling the servo to move beyond the position that shuts the claw. It will never get there, but it will apply more force on the object your holding, giving your claw a greater ability to hold on. Don't do this for too long though, as it will drain your batteries rapidly!

Control your servo's speed

Though set_servo_position doesn't have an argument for servo speed, you can emulate speed by moving the servo in small increments with delays. If you're familiar with loops and variables, you can easily move the servo to a position using 100 small adjustments or more with a few milliseconds of delay between each. The servo will follow your commands, so the more time your code spends "guiding" it to intermediate positions the slower the servo will move.

Never forget to disable servos again

The following command will automatically disable servos when your program ends. Unfortunately, if you press the Stop button on the CBC, the program is terminated in such a way that the servos won't get turned off. Still, its a nice trick.

  1. int main() {
  2. atexit(disable_servos); // just put this at the top of your program!
  4. // ...
  5. }

Wrapping it up

And with that, you have everything you need to know to program servos, in three easy steps. Set an initial position and enable them, then move them around using set_servo_position. Be sure to disable your servos some time before the program ends, and you're ready to lift and grab your way to victory!

BEMF Motor Control

Even the most sophisticated servo-powered scoring devices are only effective when the robot can accurately manuever itself into scoring range. Though you can move your robot using fd()s and bk()s, to accurately travel at precise distances and speeds, its better to use something called closed loop motor control. Though that sounds big and fancy, the basic idea is simply that the CBC can control the motors more accurately with feedback, just like you can ride a bike easier with your eyes open. The CBC has the ability to get a form of feedback called Back-EMF directly from the motor's power cable, so every motor in your kit can be used (to varying degrees of success) with closed loop motor control. KIPR provides a small set of handy functions that make closed loop motor control with BEMF very easy to use, as we'll see in this article.

Speed control with mav

The simplest BEMF function is called mav. Here's a quick example to try out before we dive in to what it does:

  1. int main() {
  2. mav(0, 700); // begin moving motor 0 at 700 ticks per second
  3. mav(2, 700); // begin moving motor 2 at 700 ticks per second
  5. sleep(5);
  7. mav(0, -700); // change motor 0 to travel in reverse at 700 ticks per second
  8. // motor 2 is still moving at 700 ticks per second!
  10. sleep(5);
  12. off(0); // just like before, we shut our motors off with the off function
  13. off(2);
  14. }

Plug some motors on ports 0 and 2, and watch them spin. Didn't we learn this already? Well, sort of. You'll notice the wheels are spinning a bit slower than if you had done an fd(). Thats what the number 700 means. 1000 is roughly full speed, so 700 means 70%. So now your robot is moving a bit slower.

But why exactly is this useful? Well for starters, it is sometimes necessary for robots to move slowly. When you start using sensors on your bot, you'll find that sometimes going slower improves reaction times and enhances accuracy. But you'll mostly use this form of speed control to ensure that your robots go straight. By slightly adjusting the motor speeds, you can account for the slight differences in motor strength, robot construction, weight distribution, and other small factors that can lead to a robot that veers. Which ever direction your robot appears to drift to, simply reduce the opposite motor's speed by about 5-10 ticks at a time until the problem goes away. So for instance, if my robot veered left, I might say:

  1. int main() {
  2. mav(0, 900); // run the left wheel at normal speed
  3. mav(2, 890); // run the right wheel a tad bit slower
  4. }

Simple enough, right? But done correctly it can dramatically enhance your robots accuracy. Don't get too wrapped up in trying to get a perfectly straight robot however, because it often times isn't possible, and you'll just be wasting time that could be better spent trying to score points!

(Obviously this isn't finished yet but I'm taking a small break until the meeting, then resume working probably - Matt)