Unit 7 · Lesson 12

Debugging Swerve Drive

You have built a complete swerve drivetrain. Now it needs to work under match conditions — and when it doesn't, you need to find the problem in ten minutes. This lesson is the field guide: systematic symptom-to-cause mapping, the competition Shuffleboard layout, the AdvantageScope workflows, and the checklist that covers every bringup and pre-match scenario.

By the end of this lesson, you will:

Apply the three-tier diagnostic process: hardware → CAN → code, in under ten minutes
Map every common swerve symptom to its most likely root cause and fix
Build a competition-ready Shuffleboard layout showing all critical drivetrain channels
Use AdvantageScope to replay a match log and identify the moment of failure
Run the complete pre-match verification checklist before every competition match
Know what to do if swerve partially fails mid-match and the team has 10 minutes to fix it

The Debugging Mindset: Eliminate Systematically

Swerve has more failure points than any other mechanism on the robot. The only reliable way to diagnose it quickly is systematic elimination. The three-tier process from Unit 6 Lesson 11 applies here with one addition specific to swerve:

Is the hardware physically functional? Power, wiring, LEDs. Test Mode. Does the motor spin when commanded directly in Tuner X?
Is the CAN communication correct? All 13 devices visible in Tuner X with unique IDs and no fault codes?
Is the configuration correct? Offsets, gear ratios, inversions — the swerve-specific layer.
Is the code correct? Last. Only here after the first three are confirmed.

The most common swerve bugs in competition are in layer 3 (configuration), not layer 4 (code). Wrong offsets, wrong inversion, wrong gear ratio. These are not code bugs. They are calibration problems. Recognizing this saves hours.

Symptom → Cause → Fix

Click a symptom below to see the diagnostic chain and fix.

Swerve symptom diagnostic tool

What is the robot doing?

← click a symptom to see the diagnostic chain and fix

The Competition Shuffleboard Layout

Build this layout once and keep it across all events. At competition, it tells you in five seconds whether the drivetrain is healthy. Click any cell to see why that channel belongs in a competition dashboard.

Competition Swerve Dashboard — Shuffleboard layout

FL/SteerAngleDeg0.0

FR/SteerAngleDeg0.0

BL/SteerAngleDeg0.0

BR/SteerAngleDeg0.0

FL/DriveVelocityMPS0.00m/s

FR/DriveVelocityMPS0.00m/s

BL/DriveVelocityMPS0.00m/s

BR/DriveVelocityMPS0.00m/s

Drive/HeadingDeg0.0°

Drive/BatteryV12.5V

Drive/PosePose2d(0.00m, 0.00m @ 0.0°)

FL/DriveCurrentA0.0A

FR/DriveCurrentA0.0A

Drive/FieldOrientedtrue

SchedulerFieldOrientedDrive

← click any channel to see why it belongs in a competition dashboard

Pre-Match Verification Checklist

Run this before every match. Click to check off items.

Pre-match swerve verification — ~3 minutes

Hardware

All 13 CAN devices visible in Tuner X with no fault codes

Battery voltage above 12.5V at rest (swap if under 12.2V)

All four drive wheels spin freely by hand — no binding

Software — before enabling

Deploy latest code — confirm build succeeded with no warnings

Open Shuffleboard — confirm all 13 channels appear with valid values

Confirm Drive/FieldOriented shows true

Correct autonomous routine selected in SendableChooser dropdown

Software — after enabling in pit

All four module SteerAngleDeg values read near 0° with wheels forward

Slow forward drive — all four DriveVelocityMPS positive and roughly equal

Slow strafe right — all four modules show ~270° steer angle

Gyro zero button (Start) works — HeadingDeg returns to 0 after pressing

On-field

Robot placed at correct starting position — press Start to zero gyro

Field2d widget shows robot at expected starting pose

Driver acknowledges alliance color — flip toggle tested if red alliance

AdvantageScope for Post-Match Debugging

When something goes wrong in a match, AdvantageScope's log replay is the fastest path from "the robot did something weird" to "here is exactly what happened and why." The workflow:

Download the WPILOG from the roboRIO immediately after the match (SSH or USB). /home/lvuser/logs/FRC_TBD_12345.wpilog
Open in AdvantageScope and find the timestamp of the failure. Use the Driver Station enabled/disabled events as anchors.
Open the Field2d channel to see the robot's estimated trajectory. Look for: sudden pose jumps (vision measurement issues), trajectory drift (wheel slip), or incorrect starting position (resetPose not called).
Overlay steer angle vs. desired state angle — the gap between commanded and actual angle is the steering error. A module that can't track its desired state has a PID or hardware problem.
Check battery voltage at the moment of failure. If it dipped below 8V, that's a brownout — all issues downstream of it are symptoms, not causes.
Check the Active Commands channel — see which command was running at the moment of failure. Confirm the autonomous sequence was in the expected phase.

🔍 LRI Perspective: "The 10-minute pit window is a debugging race"

At competition, you have ten minutes between matches. That includes walking from the field to the pit, gathering the sub-team, and pushing the robot back to queue. Realistically, you have four to six minutes of actual debugging time. That is not enough time to guess. It is exactly enough time for a systematic engineer: match log in AdvantageScope → find the failure timestamp → check battery voltage → check Field2d trajectory → check the steer angle channel for the suspicious module → open Tuner X → verify or fix. Six steps, six minutes. Teams that do this systematically fix it in time. Teams that guess waste the window and queue for the next match with the same problem.

🔌 System Check — After Any Code Change

Any time you change code between matches:

Re-run the five-step single-module isolation test (forward, strafe, rotate from Lesson 8's System Check) even if you only changed one line. Code changes can have unexpected side effects on constants, inversion flags, or PID gains.
Re-verify the auto routine is selected in the SendableChooser. A code redeploy always resets the chooser to its default option — the drive team's selection from before the match is gone.
Check that DataLogManager logging is still running after the redeploy. Confirm a new WPILOG file was written by navigating to /home/lvuser/logs/ before the next match.

Knowledge Check

1. During a match, the robot drives correctly for the first 30 seconds, then suddenly one module starts pointing 90° to the right of all other modules and the robot begins spinning. After the match, the WPILOG shows the FL/SteerAngleDeg channel jumping discontinuously from ~0° to ~92° at T+31s. What most likely happened and what should you check first?

A The field-oriented toggle was accidentally pressed, switching to robot-oriented mode.
B The Front Left CANcoder lost CAN bus communication mid-match — without the absolute encoder feedback, the steering PID is flying blind. Check the FL CANcoder CAN connection, check for a fault code in Tuner X, and inspect the CAN wire at the module for vibration damage.
C The FL steering motor stalled and the back-EMF forced the wheel to 90°.
D The CANcoder offset for FL was wrong and finally exceeded the correction range.

2. The robot's autonomous routine fails consistently at the 5-second mark. The Field2d trajectory shows the robot driving correctly for 5 seconds and then veering left by about 20°. Battery voltage was normal throughout. What does this log pattern indicate?

A The battery voltage dropped below brownout threshold at T+5s.
B A turning command at T+5s is not completing — the robot turns and then can't straighten out, or a heading-based command has a gyro calibration issue. Check: does the steer angle change correctly at T+5s? Does the gyro heading match the Field2d rotation? A wrong gyro convention (missing negation) often manifests as consistent drift in the turn direction.
C Field-oriented heading was not zeroed before autonomous, causing the path to run at an offset.
D The PathPlanner path file is corrupt and generates a wrong trajectory after 5 seconds.

3. A student redeploys code between matches changing only a PID gain. When they enable on the field, the robot immediately drives sideways at full speed without any joystick input. What is the most likely cause?

A The PID gain change caused the steering motors to command full output.
B The code redeploy reset the SendableChooser to its default option — "Drive Forward" at 100% speed is now the default autonomous command, and autonomousInit() is scheduling it in TeleOp mode because the team accidentally put it in the wrong mode selector. OR: the joystick deadband somehow changed and drift input is now commanding full speed. But the most likely scenario: check which command the Scheduler widget shows is running — something is being commanded that shouldn't be.
C The Pigeon 2 gyro was bumped during transport, causing heading drift that field-oriented is attempting to correct at full speed.
D A PID gain too high on drive motors causes runaway velocity.

💪 Practice Prompt — Unit 7 Capstone

Competition-Ready Swerve Drive

Build and populate the complete Shuffleboard layout from the dashboard section above. All 13+ channels should be published in your code. Open Shuffleboard, arrange the widgets, and screenshot the layout. Save it as your team's standard competition layout.
Deliberately introduce three bugs into your swerve code (one at a time, restore after each test): (a) wrong CANcoder offset for Front Left — observe and document the symptom; (b) wrong drive inversion for Front Right — observe; (c) remove the Pigeon 2 yaw negation — observe. Match each symptom to its entry in the diagnostic tool above. This "fault injection" exercise builds the pattern recognition you need for real competition debugging.
Download a WPILOG from a test run. Open it in AdvantageScope. Add the Field2d channel, all four SteerAngleDeg channels, all four DriveVelocityMPS channels, and the battery voltage. Navigate to a moment when you deliberately drove in a circle. Confirm all four steer angles show the expected X-tangent pattern, all four velocities show a speed differential (outer wheels faster), and the Field2d trajectory shows a clean arc.
Run the complete pre-match checklist from this lesson against your robot. Time it. The target is under 3 minutes. If any item takes too long (e.g., opening Tuner X, checking offsets), build a faster workflow — write a startup command that publishes all CANcoder values as a named block that you can check in one glance.
Stretch goal: Write a startup diagnostic that runs in robotInit() and logs a DriverStation.reportWarning() for any of these conditions: any CANcoder absolute position not within ±5° of 0 (offset needs recalibration), battery voltage below 12.0V, or any drive motor reporting a fault code via getFaults().hasAnyFault(). This automated pre-match health check replaces the manual Tuner X inspection for known common failure modes.

🎓 Unit 7 Complete — Drivetrains & Swerve Drive

You've built a complete, competition-ready swerve drive from first principles. Every line of code in your drivetrain — from the CANcoder offset stored in Constants.java to the vision measurement timestamp passed to the Kalman filter — you understand because you built it yourself. That understanding is what makes you effective when something goes wrong at 7 AM before qualifications.

The drivetrain is done. Unit 8 turns to the mechanisms mounted on top of it — control theory, PID tuning, feedforward, and motion profiling. Everything you've learned about the physics relationship between code and hardware will apply again, now for arms, elevators, and flywheels.

Unit 8, Lesson 1: Why Open-Loop Control Isn't Enough