Troubleshooting

Common issues and solutions for VingVing Robot tuning and path following

Quick Diagnostic Checklist

Before diving into detailed troubleshooting, verify these basics:

Battery is fully charged (12.5V+)

All motors are connected and responding

Motor directions are correct in RobotConfig

Encoders are reading values (not stuck at 0)

IMU is calibrated and not drifting

FTC Dashboard shows robot position updating

Localization Issues

Robot Position Not Updating

FTC Dashboard shows robot stuck at (0, 0) or position doesn't change when you move the robot.

Possible Causes:

Encoder cables disconnected or loose
Wrong encoder port names in RobotConfig
Localizer not initialized in OpMode
update() method not being called in loop

Solution:

// Verify in your OpMode
@Override
public void runOpMode() {
    robot = new Robot(hardwareMap, RobotConfig.class);
    robot.initializeLocalizer(hardwareMap); // Make sure this is called!

    waitForStart();

    while (opModeIsActive()) {
        robot.update(); // MUST call every loop!
        robot.getLocalizer().telemetryDebug(telemetry);
    }
}

Position Drifts Over Time

Robot starts at correct position but gradually drifts away from actual location.

Possible Causes:

Incorrect encoder directions (X/Y swapped or reversed)
Wrong track width or center wheel offset values
Wheels slipping on surface
IMU not fused with odometry (for 2-wheel setups)

Solution:

Run the Localization Test OpMode and verify encoder readings match physical movement:

// Push robot FORWARD 12 inches:
// - forwardEncoder should INCREASE by ~12
// - strafeEncoder should stay ~0
// - turnEncoder should stay ~0

// Push robot LEFT 12 inches:
// - strafeEncoder should INCREASE by ~12
// - forwardEncoder should stay ~0

// If wrong, adjust encoder directions in RobotConfig

Heading (Rotation) Incorrect

Robot's reported heading doesn't match actual rotation, or spins unexpectedly.

Solution:

// For Drive Encoder localizer - verify turn encoder direction
.turnEncoderDirection(TurnEncoder.REVERSE) // Try flipping this

// For IMU-based heading - verify IMU orientation
.imu("imu")
.imuOrientation(IMUOrientation.LOGO_UP_USB_LEFT) // Match your hub mounting

// Re-calibrate IMU
// Leave robot PERFECTLY STILL during init!

Path Following Issues

Robot Doesn't Move at All

Follower starts but robot stays still, motors don't spin.

Possible Causes:

Motor names incorrect in RobotConfig
setDrivePowers() not being called
Follower not initialized properly
Path completion callback stopping immediately

Solution:

// Verify motor names match hardware config EXACTLY
.leftFront("leftFront")   // Must match device name in phone
.rightFront("rightFront")
.leftBack("leftBack")
.rightBack("rightBack")

// Verify you're setting motor powers
while (!follower.isPathComplete() && opModeIsActive()) {
    robot.update();
    follower.update();
    robot.setDrivePowers(follower.getMotorPowers()); // CRITICAL!
}

Robot Oscillates / Wobbles

Robot shakes side-to-side or back-and-forth while following paths.

Solution:

P coefficient too high, not enough damping. Increase D:

// For translational wobble:
.translationalPID(new PIDFCoefficients(
    0.15,  // Reduce P from 0.3 → 0.15
    0.0,
    0.008, // Increase D from 0.0 → 0.008
    0.0
))

// For heading wobble:
.headingPID(new PIDFCoefficients(
    1.5,   // Reduce P from 3.0 → 1.5
    0.0,
    0.15,  // Increase D from 0.0 → 0.15
    0.0
))

Robot Overshoots Endpoints

Robot passes the target position and has to back up to reach it.

Solution:

// Reduce P, increase D for better braking
.translationalPID(new PIDFCoefficients(
    0.2,   // Lower P
    0.0,
    0.01,  // Higher D
    0.0
))

// Verify zero-power acceleration values are correct
.forwardZeroPowerAcceleration(-38.2)  // Should be NEGATIVE
.lateralZeroPowerAcceleration(-42.1)   // Should be NEGATIVE

// These tell follower how fast robot naturally decelerates

Robot Stops Short of Target

Robot thinks it's done but is still several inches from endpoint.

Solution:

// Increase P to give more power near target
.translationalPID(new PIDFCoefficients(
    0.4,   // Increase P
    0.0,
    0.005,
    0.0
))

// Or add I term to eliminate steady-state error
.translationalPID(new PIDFCoefficients(
    0.3,
    0.05,  // Add I
    0.005,
    0.0
))

// Verify completion tolerances aren't too loose
.completionTolerances(2.0, 2.0, Math.toRadians(5))
// (xTolerance, yTolerance, headingTolerance)

Curved Paths Cut Corners

Robot takes shortcuts on curves, doesn't follow the path smoothly.

Solution:

// Increase centripetal force correction
.centripetalPID(new PIDFCoefficients(
    0.005, // Increase from 0.001 → 0.005
    0.0,
    0.0,
    0.0
))

// Verify velocity measurements are accurate
.xVelocity(52.3)  // Re-run velocity tuners
.yVelocity(48.5)

// Centripetal correction depends on accurate velocities

Performance Issues

Robot is Too Slow

Path following works but robot moves much slower than expected.

Solution:

// Increase maximum velocities (if safe)
.xVelocity(60.0)  // Increase from 52.3
.yVelocity(55.0)

// Reduce drive P (might be holding back speed)
.drivePID(new PIDFCoefficients(
    0.02,  // Reduce from 0.05
    0.0,
    0.0,
    0.0
))

// Verify maxPower is at 1.0
.maxPower(1.0)  // Not 0.5 or 0.7!

Inconsistent Performance

Sometimes works great, other times fails completely.

Possible Causes:

Battery voltage fluctuating (low/dying battery)
Loose wire connections
IMU not fully calibrated (moved during init)
Surface changes (field tiles vs. concrete)
Different starting positions each run

FTC Dashboard Not Showing Paths

Follower works but Dashboard doesn't show the path visualization.

Solution:

// Verify FtcDashboard is initialized
import com.acmerobotics.dashboard.FtcDashboard;
import com.acmerobotics.dashboard.telemetry.MultipleTelemetry;

@Override
public void runOpMode() {
    // Add this line:
    telemetry = new MultipleTelemetry(telemetry, FtcDashboard.getInstance().getTelemetry());

    robot = new Robot(hardwareMap, RobotConfig.class);
    // ... rest of code
}

Advanced Debugging

Enable Detailed Telemetry

Get more information about what's happening internally:

while (!follower.isPathComplete() && opModeIsActive()) {
    robot.update();
    follower.update();
    robot.setDrivePowers(follower.getMotorPowers());

    // Detailed debugging info
    telemetry.addData("X Error", follower.getXError());
    telemetry.addData("Y Error", follower.getYError());
    telemetry.addData("Heading Error", Math.toDegrees(follower.getHeadingError()));
    telemetry.addData("X Velocity", robot.getLocalizer().getVelocityX());
    telemetry.addData("Y Velocity", robot.getLocalizer().getVelocityY());
    telemetry.addData("Closest Point", follower.getClosestPointOnPath());
    telemetry.addData("Motor Powers", Arrays.toString(follower.getMotorPowers()));
    telemetry.update();
}

Test Individual Components

Isolate the problem by testing each system separately:

Localization: Run LocalizationTest - verify position tracking works
Motors: Manually set motor powers - verify all motors spin correctly
Heading: Run HeadingTuner - tune heading PID in isolation
Translation: Run TranslationalTuner - tune movement PID separately

Common Beginner Mistakes

Forgetting to Call robot.update()

Localization won't work without this! Must be called every loop iteration before follower.update().

Wrong Motor Directions

Robot spins instead of going forward? One or more motors are reversed. Fix in RobotConfig, not hardware config.

Tuning on Low Battery

PID values that work at 12.5V will fail at 11V. Always tune with full battery and keep batteries charged during competition.

Moving Robot During IMU Calibration

IMU must be perfectly still during init. Moving it causes incorrect heading readings and mysterious turning issues.

Skipping Automatic Tuning

Don't guess velocity and acceleration values! Run the automatic tuners - they're essential for accurate path following.

Still Stuck?

If you've tried everything and it's still not working, consider:

▸Check the GitHub repository for known issues and updates
▸Review the sample code to see a complete working implementation
▸Start from scratch with a fresh RobotConfig using default values
▸Verify your hardware is functioning correctly (test motors/encoders manually)

View Sample Code →GitHub Repository →