Botball Coach Guide

Your Job Isn't to Write the Code

The goal is for the students to understand what their robot is doing and why. When they're stuck, your instinct will be to fix it for them — resist that. Ask questions instead. "What do you think is happening?" is more valuable than pointing at the bug.

That said, don't let them spin indefinitely. A good rule: if students have tried three different ideas and nothing has changed, step in and suggest a new direction. Three attempts is enough to learn from; more than that without progress is just frustrating.

How to Coach a Troubleshooting Session

When something goes wrong, walk them through the same process every time. They'll internalize it.

1. Observe before touching anything. Watch the robot fail. Ask: "What did you expect to happen? What actually happened?" If they can't articulate the difference, they're not ready to fix it.

2. Isolate the problem. Is it mechanical (motor, servo, wiring), sensor-related, or code logic? Have them run the self-test program first if they're unsure. "Let's rule things out one at a time."

3. Form a hypothesis. "What do you think is causing it?" Make them guess. Wrong guesses are fine — they're learning. Then test the guess.

4. Change one thing at a time. Students will often change three things at once and then not know what worked. Slow them down. One change, one test, record what happened.

5. Use printf. If they can't see what the robot is thinking, have them print sensor values and motor states. "What does the sensor actually read when the robot is in that position?"

When They're Stuck on Code

They don't know where to start: Help them break it down. "What's the very first thing the robot needs to do in this section?" Get them writing one function at a time.

The code doesn't compile: Read the error with them, out loud. Compiler errors are intimidating but usually specific. Most common issues: missing semicolons, mismatched braces, calling a function before it's defined.

The robot does something unexpected: Ask them to walk you through the code line by line, out loud, and describe what each line should do. They'll often find the bug themselves mid-explanation. (This is called rubber duck debugging — it works.)

Timing is off (robot stops too early or too late): Remind them that msleep timings depend on battery level and surface conditions. If they're relying heavily on time-based movement, encourage them to add encoder or sensor checks.

The sensor threshold seems wrong: Have them print the sensor value in a loop while moving the robot to the exact position where the behavior should change. Then set the threshold to that value, with a small buffer.

Coaching Mecanum Bots Specifically

Mecanum robots are powerful but have a higher coordination cost. A few things to watch for:

• Motor directions matter more. Each wheel needs to spin the right way for strafing and diagonal moves to work. If the bot is spinning instead of strafing, at least one motor direction is flipped. Run the self-test to check each motor in isolation.
• "Squaring up" is tricky. Mecanum bots can strafe into walls to align, but students often just use time-based strafing. Encourage them to think about whether a sensor could give them a more reliable stop condition.
• Inconsistent strafing. Friction and floor surface variation affect mecanum movement more than regular drive. If a strafe distance is inconsistent, use encoder ticks (cmpc/gmpc) instead of msleep.

Pre-Practice Habits Worth Building

• Always run the self-test first. Before writing new code or debugging a route, verify the hardware is working. A loose motor wire will look like a code bug.
• Charge batteries before practice, not during. Nothing kills debugging momentum like stopping to swap batteries mid-session.
• Back up code before making changes. Encourage them to copy working code to a commented-out block or a separate file before experimenting. They'll thank you when they break something.
• Write port assignments as #define constants at the top of the file. If a wire gets moved to a different port, changing one line is far better than hunting through code.

Pre-Competition Checklist

Run through this with the team the day before and the morning of competition.

• Self-test passes on competition robot (all motors and servos respond correctly)
• Sensor thresholds verified on the actual competition surface and lighting
• wait_for_light() is the first call in main(), not buried in a section function
• shut_down_in(119) is called early in main() as a safety net
• All #define port constants match the physical wiring
• Robot starts from the correct position and orientation
• Team knows what to do if the robot fails mid-run (stay calm, note what happened for next run)
• Battery is fully charged

Managing the Team Dynamic

Middle schoolers will disagree about the code. That's good — let them argue it out to a point, then have them test the disagreement rather than just debate it. "Both ideas sound reasonable. Let's try yours first and see what happens."

If one student is dominating the keyboard, rotate. Even if they're the strongest coder, the others need hands-on time.

Celebrate working things. A section that runs correctly in practice is worth noting, even if the full route isn't done yet.

Coding Guide for Botball

Start Every File the Same Way

Define your ports at the top using #define. This way if a wire gets moved, you only change one line instead of hunting through the whole program.

#include <kipr/wombat.h>

// --- PORT ASSIGNMENTS ---
#define LEFT_MOTOR    0
#define RIGHT_MOTOR   3
#define ARM_SERVO     3
#define CLAW_SERVO    2
#define LINE_SENSOR   0
#define BUMP_SENSOR   1

// --- THRESHOLDS ---
#define BLACK_VALUE   3000
#define LINE_THRESHOLD 2000

Then your code reads like plain English: motor(LEFT_MOTOR, 100) is much clearer than motor(0, 100).

Break Your Route into Functions

Don't write one giant main(). Write one function per task. Each function should do one thing and have a name that describes what it does.

void drive_to_wall() { ... }
void grab_object()   { ... }
void return_to_start() { ... }

int main() {
    wait_for_light(0);
    shut_down_in(119);

    drive_to_wall();
    grab_object();
    return_to_start();

    ao();
    return 0;
}

Benefits: easier to test one section at a time, easier to fix bugs, easier to read.

Always Stop Your Motors

Every time you start motors, there needs to be a clear place where they stop. Forgetting ao() is one of the most common bugs.

// Good: clear start and stop
motor(LEFT_MOTOR, 80);
motor(RIGHT_MOTOR, 80);
msleep(1000);
ao();            // <-- don't forget this
msleep(200);     // brief pause after stopping

Two Ways to Control Distance

Time-based: Simple, but affected by battery level and surface friction. Good for rough positioning.

motor(LEFT_MOTOR, 80);
motor(RIGHT_MOTOR, 80);
msleep(1500);   // go for 1.5 seconds
ao();

Encoder-based: More reliable for consistent distances. Encoders count wheel "ticks" as the wheel turns — but how many ticks per full rotation depends on your motor and gearing. Common values are around 1440 ticks/rotation for Tetrix motors, but ask your coach before relying on exact numbers. The tick counts in your route code are found by testing, not calculated.

cmpc(LEFT_MOTOR);   // reset counter to 0
while (gmpc(LEFT_MOTOR) < 5000) {
    motor(LEFT_MOTOR, 80);
    motor(RIGHT_MOTOR, 80);
    msleep(10);     // always include a short sleep in loops like this —
                    // without it the loop runs so fast it can crash the Wombat
}
ao();

When precision matters (like lining up to grab something), use encoders. When you just need to get somewhere approximately, time-based is fine.

Sensor-Based Stopping

Using a sensor to stop is more reliable than guessing how long something takes.

// Stop when you hit a wall
while (digital(BUMP_SENSOR) == 0) {
    motor(LEFT_MOTOR, 60);
    motor(RIGHT_MOTOR, 60);
    msleep(10);
}
ao();

// Stop when you reach a black line
while (analog(LINE_SENSOR) < BLACK_VALUE) {
    motor(LEFT_MOTOR, 60);
    motor(RIGHT_MOTOR, 60);
    msleep(10);
}
ao();

If a sensor isn't working, a time-based fallback is okay for competition, but plan to fix it.

Debug with printf

printf is your best debugging tool. Print sensor values while the robot is running to see what it's actually experiencing.

// Print once each loop iteration - see what the sensor reads
while (1) {
    printf("line sensor: %d\n", analog(LINE_SENSOR));
    msleep(100);
}

Watch the output in the Wombat's terminal as the robot moves. This will tell you the right threshold values to use. When you find a value that works, set it as a #define constant.

Remove or comment out excessive printf calls before competition — they slow the program down.

Servos: Enable, Move, and Be Patient

Always call enable_servos() before using servos, and disable_servos() when done. After setting a position, give the servo time to physically reach it.

enable_servos();

set_servo_position(ARM_SERVO, 1000);   // move arm
msleep(1000);                           // wait for it to get there

set_servo_position(CLAW_SERVO, 2047);  // close claw
msleep(500);

disable_servos();

Servo positions range from 0 to 2047. You'll need to experiment to find the right positions for your specific arm — there's no universal answer.

Mecanum Wheels: Motor Direction Reference

If something isn't moving the right direction, check whether one or more motors is spinning backwards. The self-test program will help you verify each motor individually.

Common Mistakes

Changing too many things at once. If the robot isn't working, change one thing and test it before changing anything else. Otherwise you won't know what fixed it.

Hardcoding port numbers. Use #define constants. motor(0, 100) is hard to read and hard to fix when something changes.

No pause between movements. Add a short ao(); msleep(200); between sections. It gives the robot time to stop fully before the next movement starts.

Trusting timing over sensors. If the robot does the same task multiple times and the timing varies, use a sensor instead.

Not testing sections separately. If you're debugging section 3, comment out sections 1 and 2 so you don't have to wait through them every test run.

One giant main(). If your main() is longer than about 30 lines, you probably need more functions. Long main() functions are hard to debug and hard to test piece by piece.

Troubleshooting Guide

When something isn't working, don't just start changing code. Observe first, then figure out what's actually wrong.

Step 1: Run the Self-Test

Before assuming it's a code problem, run self_test.c. It will test each motor and servo one at a time. This rules out hardware problems quickly.

If a motor or servo fails the self-test:

• Check the cable connection at both ends
• Try swapping the cable
• Check the port number in the test file matches where it's plugged in

Fix Hardware Before Code

If something moves the wrong direction, fix the wiring first before changing code. Hardware fixes work everywhere. Code fixes only work in one program, and future code becomes confusing to write.

My Robot Won't Move At All

Work through this in order:

1. Are the motors getting power? Check that the Wombat is on and the battery has charge.
2. Does the self-test work? If a motor works in the self-test but not in your code, the bug is in your code.
3. Are you calling ao() before you move? If there's an ao() right before your motor call, that's fine. But if you have ao() inside a loop where you want movement, that's stopping the motor every iteration.
4. Are you using the right port number? Compare your #define constants to the physical port labels on the Wombat.

Robot Curves Instead of Driving Straight

If your robot drives forward but slowly curves left or right, this is very common and almost never a wiring problem.

Possible causes: one motor is slightly stronger than the other (very common), uneven wheel friction, low battery, or uneven weight distribution.

Fix it by adjusting motor speeds slightly until the robot tracks straight:

motor(LEFT_MOTOR, 80);
motor(RIGHT_MOTOR, 75);  // reduce the faster side in small steps (3-10 points)

Test, watch, adjust, repeat. Once it drives straight, write down the values.

Robot Spins in Place Instead of Moving Forward

If the robot spins rather than driving forward, one motor is running backwards. This is a direction problem, not a speed problem.

Fix this by swapping the two wires on that motor — don't fix it in code if you can avoid it. Code fixes for direction make future programs confusing.

If wiring can't be changed, you can negate the speed in code:

// If LEFT_MOTOR spins wrong, negate its value:
motor(LEFT_MOTOR, -80);   // was 80
motor(RIGHT_MOTOR, 80);

Mecanum Bot Spins Instead of Strafing

One or more wheels is going the wrong direction. Run the self-test to check each motor individually, then compare against the motor direction table in the coding guide. Fix in wiring if possible.

Robot Drifts to One Side

This is almost always a hardware issue, not a code issue. Check:

• Are both drive wheels touching the ground equally? An uneven chassis will cause drift.
• Are the wheels on tight? A loose wheel slips.
• Is one motor slightly slower than the other? You can compensate in code by lowering the faster motor's speed slightly (e.g., motor(LEFT_MOTOR, 95) instead of 100) until it drives straight. Use printf to print encoder values of both motors while driving — they should be roughly equal.

Debug with printf — Where Does the Output Go?

Open the Console window in the Wombat software. That's where printf messages appear. If you don't see the console, look for a "Console" or "Output" tab in the interface.

Sensor Isn't Reading What I Expect

First: print the actual value. Don't guess. Put this in a loop and watch the output:

while(1) {
    printf("sensor value: %d\n", analog(0));
    msleep(100);
}

Move the robot/sensor to different positions and see what values you get. Set your threshold based on actual readings, not guesses.

Digital sensor always reads 0 or always reads 1:

• Check the cable connection
• Make sure you're reading the right port number
• Check that the sensor isn't physically stuck

Analog sensor reads 0:

• Usually a disconnected or broken cable
• Try a different port and update the #define

Line sensor doesn't detect black:

• The sensor may be too far from the surface. It should be close but not dragging.
• Check what value it reads on white vs. black. Your #define BLACK_VALUE threshold should be somewhere between the two.
• Lighting in the competition venue may be different from where you practiced. Re-check thresholds on the day of competition if possible.

Robot Stops Too Early or Too Late

Time-based movement: msleep timing depends on battery charge and floor friction. A lower battery makes the robot slower, so it travels less distance in the same time. If you're using time-based movement for anything precise, consider switching to encoder-based.

Encoder-based movement: Print the encoder value at the moment it stops to make sure it's reaching the target. If it stops too soon, the target tick count is too low. Add printf("ticks: %d\n", gmpc(0)) inside your loop.

Sensor-based stopping: If the robot doesn't stop at a line, the threshold is probably wrong. Print sensor values and adjust. If the robot stops immediately, the sensor is already reading above the threshold before it starts moving — check your starting position.

Arm / Claw Isn't Moving

1. Did you call enable_servos() before set_servo_position()?
2. Is the port number correct?
3. Are you giving it enough time to move? set_servo_position tells the servo where to go, but msleep(1000) gives it time to actually get there.
4. Run the self-test — does the servo work at all? If not, check the cable.
5. Is the servo stalled against something mechanical? A servo fighting against a physical obstruction will hum, get hot, and eventually stop working.

Code Compiles But Crashes or Freezes

Infinite loop: You probably have a while loop with a condition that never becomes false. Add a printf inside the loop to confirm it's actually running. Ask: what would need to change for the loop to end? Is that thing actually changing?

Robot freezes partway through the route: Add printf("section X starting\n") at the beginning of each function. This tells you exactly where execution stopped.

Timing out: If your route takes more than 119 seconds, shut_down_in(119) will cut power to the motors. If the robot stops unexpectedly near the end of a long run, this might be why.

Competition Day Problems

The route worked in practice but fails at competition:

• Different lighting → re-check sensor thresholds
• Different floor surface → re-check line sensor sensitivity and timing
• Battery not fully charged → movements will be slower than expected

Robot starts before the light:

• wait_for_light() can be triggered by ambient light changes. If the venue is bright, it may fire early. Test wait_for_light() in the actual competition lighting before your run.