# 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: ```c 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: ```c // 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: ```c 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.