Edubot Wiki
Edubot Wiki

Troubleshooting Guide

Overview

Something is wrong with your robot. Maybe it drives to the left when it should go straight. Maybe the lift arm drops instead of holding position. Maybe the program just does nothing at all.

Figuring out what is wrong — and fixing it — is one of the most important skills in robotics engineering. The good news is that debugging is a learnable skill, not magic.

Why does this matter?

Every professional engineer — mechanical, software, electrical — spends a large part of their job debugging. The faster you can isolate and fix problems, the more time you have to improve your robot.

The Five-Step Debugging Process

Use this process for any problem — mechanical or software.

Step 1 — Reproduce the Problem

Before you can fix a problem, you need to be able to make it happen reliably. Run the robot several times and observe exactly what goes wrong.

Ask yourself:

  • Does it happen every time, or only sometimes?
  • Does it happen in the same place in the routine every time?
  • Does it happen under specific conditions (certain battery charge, certain starting position)?

A problem you can reproduce consistently is much easier to fix than one that only happens randomly.

Step 2 — Isolate the Problem

Narrow down where the problem is coming from. Is it mechanical, electrical, or software?

Quick isolation checklist:

  • Mechanical: Lift the robot off the ground and run it. Do the wheels spin smoothly? Do they all spin at the same speed? Does anything grind, stick, or bind?
  • Electrical: Check every cable. Is any cable half-unplugged? Is the Brain showing an error for a specific port? Are there any loose connections?
  • Software: Does the Brain screen show what you expect? Try printing sensor values and motor states to the screen to see what the code is actually doing.

Step 3 — Hypothesize

Come up with a specific, testable explanation for what is causing the problem.

Good hypothesis: “The robot drifts left because the right motor has slightly more friction than the left motor.”
Bad hypothesis: “Something is wrong with the motors.”

A good hypothesis is specific enough that you can design a test to check it.

Step 4 — Test

Change one thing and observe the result. Only change one thing at a time. If you change three things at once, you will not know which change fixed the problem.

Write down what you changed and what happened in your engineering notebook. This is not optional — if you do not record your tests, you will repeat the same failed attempts over and over.

Step 5 — Verify

Once the problem seems fixed, run the robot several times to confirm the fix is reliable — not just lucky. If the problem returns, go back to Step 2.

Common Mechanical Problems

Robot Drifts to One Side During Straight Drives

Possible causes:

  • One wheel has more friction (bearing is worn or axle is bent)
  • Motors have different friction levels
  • One wheel is a slightly different diameter than the others
  • Chassis is twisted — not perfectly flat and square

How to check:

  1. Lift the robot and spin each wheel by hand. Do they all feel equally smooth?
  2. Power on and run all motors at 50% with no PID. Do they spin at the same speed? (Check the Brain motor monitor.)
  3. Check the chassis: place it on a flat surface. Does it wobble?

Motor Not Spinning

Possible causes:

  • Cable is unplugged or damaged
  • Port assignment in code does not match physical port
  • Cartridge is worn out or wrong gear ratio
  • Motor is overheated (stalled for too long)

How to check:

  1. On the Brain, go to the motor monitor and check if the port shows a motor.
  2. Swap the cable with a known-good cable.
  3. Swap the motor with a known-good motor.

Mechanism Slips or Drops

Possible causes:

  • Lock nut is missing on a pivot screw — arm wobbles
  • Gear mesh is too loose — gears skip under load
  • Motor cartridge is stripped (too much torque applied for too long)
  • Set screw on the axle collar is loose

How to check:

  1. Wiggle every joint by hand — there should be no slop.
  2. Try to turn gears by hand while holding the motor. You should not be able to skip teeth.
  3. Check every set screw with a hex key. If it spins freely, it is loose.

Common Software Problems

Program Does Nothing When Run

Possible causes:

  • Wrong program selected on the Brain
  • Compilation error (program did not actually upload)
  • The first function in main() is waiting for a condition that is never met

How to check:

  1. Check the Brain screen — is the correct program name showing?
  2. Look at VEXcode — did the compile succeed? Are there error messages in red?
  3. Add Brain.Screen.print("Program started"); as the very first line. If this does not appear, the program is not running at all.

Robot Moves in the Wrong Direction

Possible causes:

  • Motor is wired to the wrong port
  • Motor direction is reversed in the device configuration
  • Drive math has a sign error (plus/minus flipped)

How to check:

  1. Open device configuration in VEXcode. Check which port each motor is assigned to.
  2. Check the “reversed” toggle for each motor in the configuration panel.
  3. Trace your drive math on paper: if forward = 75 and turn = 0, what do leftSpeed and rightSpeed equal?

PID Controller Oscillates (Bounces Back and Forth)

Possible causes:

  • Kp is too high
  • Kd is too low (not enough damping)
  • Mechanical play (loose wheels or gears) introduces lag that confuses the controller

How to fix:

  1. Reduce Kp by 20% and test again.
  2. Increase Kd slightly to add damping.
  3. Fix any mechanical looseness first — PID cannot compensate for slipping gears.

Sensor Giving Wrong or Noisy Values

Possible causes:

  • Cable is partially unplugged
  • Sensor is pointed in the wrong direction
  • The sensor is too close to a motor (electrical interference)
  • Sensor needs calibration (especially the inertial sensor)

How to check:

  1. Open the sensor monitor on the Brain and look at live values. Are they reasonable?
  2. Wiggle the cable. Does the reading change?
  3. Try a known-good sensor in the same port.

Logging for Debugging

When a problem is hard to reproduce visually, add temporary debug output to your code. Print sensor values, motor speeds, or state machine states to the Brain screen.

# VEX IQ Python — debug output
brain.screen.clear_screen()
brain.screen.set_cursor(1, 1)
brain.screen.print("Left enc: ", left_motor.position(DEGREES))
brain.screen.set_cursor(2, 1)
brain.screen.print("Heading: ", inertial.heading())
brain.screen.set_cursor(3, 1)
brain.screen.print("State: ", current_state)

Reading live data while the robot runs often reveals the cause of a problem in seconds — much faster than guessing.

The Golden Rule

Fix mechanical problems before tuning software.

PID controllers, sensor fusion, and autonomous routines cannot compensate for a loose wheel, a stripped gear, or a bent axle. Always check the hardware first.

Prev
Brain User Interface
Next
Competitions