Swerve Drive Config Generator

Set Up Your Robot Project

Clone the YAGSL repository.

Clone Yet-Another-Software-Suite/YAGSL to your computer.

Copy the example project out.

Copy the contents of the example project folder out of the cloned repository and into your own robot project directory — that's what you'll actually build and deploy.

Change the team number.

In your new project, set it to your own team number — with the WPILib VS Code extension, that's Ctrl+Shift+P → WPILib: Set Team Number (or edit it directly in .wpilib/wpilib_preferences.json).

Delete src/main/deploy/swerve.

Delete the example project's default src/main/deploy/swerve folder — you'll replace it with your own generated configuration next.

Unzip your downloaded config into src/main/deploy/swerve.

Extract the zip you downloaded from this site and place its contents directly into src/main/deploy/swerve, so you end up with src/main/deploy/swerve/swervedrive.json and a src/main/deploy/swerve/modules/ folder alongside it.

Connect AdvantageScope to the Simulator

Build and start the robot simulator.

New to the simulator? WPILib's guide to robot simulation walks through starting it.

Open AdvantageScope.

Connect to the simulator.

File → Connect to Simulator (Ctrl+Shift+K).

Add the swerve fields to the Swerve widget.

Drag in each of these NetworkTables fields:

NT:/Mechanisms/swerve/states/current
NT:/Mechanisms/swerve/states/desired
NT:/Mechanisms/swerve/chassis/current
NT:/Mechanisms/swerve/chassis/desired

All of the tuning steps below follow the YAGSL example project. (Note: this link isn't live yet, but will be by the time you're using this site.)

Tune the Swerve Drive PID in Simulation

Edit the sim PID gains.

Open modules/pidfproperties_sim.json from your downloaded configuration and edit the drive and angle PID gains. Not sure how to tune a PID loop? WPILib's flywheel tuning guide walks through the same method used here for the drive PID, and the turret tuning guide covers the azimuth/angle PID.

Angle (azimuth) motor

Turns the wheel to point a new direction — this is what the angle PID controls.

Drive motor

Spins the wheel to roll forward/backward, without changing its heading — this is what the drive PID controls.

Feedforward is optional. s, v, and a (kS, kV, kA) can be tuned too, for an even better fit.
The drive motor already has a default v. It's computed from the free speed RPM of the motor you selected for that module, but only applies when you haven't set your own v.

modules/pidfproperties_sim.json

Before

{
  "$schema": "https://example.com/schemas/pidfproperties.json",
  "drive": {
    "p": 0.1,
    "i": 0,
    "d": 0,
    "s": 0,
    "v": 0.7,
    "a": 0.1
  },
  "angle": {
    "p": 0.01,
    "i": 0,
    "d": 0,
    "s": 0,
    "v": 0,
    "a": 0
  }
}

After

{
  "$schema": "https://example.com/schemas/pidfproperties.json",
  "drive": {
    "p": 0.35,
    "i": 0,
    "d": 0,
    "s": 0,
    "v": 0.7,
    "a": 0.1
  },
  "angle": {
    "p": 0.06,
    "i": 0,
    "d": 0.0015,
    "s": 0,
    "v": 0,
    "a": 0
  }
}

Restart the simulator to apply the changes.

Drive the simulated robot around.

Compare current vs. desired, and keep tuning.

Compare the "current" and "desired" traces in the Swerve widget, and keep adjusting the gains in pidfproperties_sim.json until the current state closely tracks the desired state.

All of the tuning steps below follow the YAGSL example project. (Note: this link isn't live yet, but will be by the time you're using this site.)

Nice work tuning the simulator! Now let's move to the real robot.

Run the program on the real robot.

Open AdvantageScope (if it isn't already open).

Point AdvantageScope at the robot's address.

App → Show Preferences (Ctrl+,), and set the robot address to the IP address of the system core.

Connect to the robot.

File → Connect to Robot (Ctrl+K).

Add the swerve fields to the Swerve widget.

Drag in each of these NetworkTables fields:

NT:/Mechanisms/swerve/states/current
NT:/Mechanisms/swerve/states/desired
NT:/Mechanisms/swerve/chassis/current
NT:/Mechanisms/swerve/chassis/desired

All of the tuning steps below follow the YAGSL example project. (Note: this link isn't live yet, but will be by the time you're using this site.)

Module Locations

Know how module location is measured

This is very important: module locations are measured from the center of the robot to the center of each module (wheel), in inches. Keep this in mind as you go through the next step.

Both distances are measured from the center of the robot to the center of the module (wheel), in inches

The "center of robot" in the diagram above is actually the center of rotation — and ideally, that should also be your robot's center of mass. If the center of rotation isn't the center of mass, the robot will drift while rotating instead of spinning cleanly in place.

Enter each module's location in its json file.

Goes in that module's own json file (modules/frontleft.json, frontright.json, backleft.json, backright.json), under location.front and location.left.

modules/frontleft.json

Before

{
  "$schema": "https://example.com/schemas/module.json",
  "drive": {
    "type": "sparkmax_neo",
    "id": 1,
    "canbus": ""
  },
  "angle": {
    "type": "sparkmax_neo",
    "id": 2,
    "canbus": ""
  },
  "inverted": {
    "drive": false,
    "angle": false
  },
  "absoluteEncoder": {
    "type": "cancoder_can",
    "id": 3,
    "channel": 0,
    "canbus": ""
  },
  "absoluteEncoderOffset": 0,
  "absoluteEncoderInverted": false,
  "location": {
    "front": 0,
    "left": 0
  }
}

After

{
  "$schema": "https://example.com/schemas/module.json",
  "drive": {
    "type": "sparkmax_neo",
    "id": 1,
    "canbus": ""
  },
  "angle": {
    "type": "sparkmax_neo",
    "id": 2,
    "canbus": ""
  },
  "inverted": {
    "drive": false,
    "angle": false
  },
  "absoluteEncoder": {
    "type": "cancoder_can",
    "id": 3,
    "channel": 0,
    "canbus": ""
  },
  "absoluteEncoderOffset": 0,
  "absoluteEncoderInverted": false,
  "location": {
    "front": 12.5,
    "left": 10.5
  }
}

Align the Swerve Modules

Rotate every wheel forward, bevel gear left.

Viewed from directly above, with the robot's front pointing away from you.

Each wheel settles pointing forward with the bevel gear (yellow rectangle) facing left

Record each module's absolute encoder offset.

With AdvantageScope connected to the robot, for each module read the value at NT:/Mechanisms/swerve/[module_name]/azimuth/encoder while it's held in this aligned position, and copy that value into that module's absoluteEncoderOffset.

modules/frontleft.json

Before

{
  "$schema": "https://example.com/schemas/module.json",
  "drive": {
    "type": "sparkmax_neo",
    "id": 1,
    "canbus": ""
  },
  "angle": {
    "type": "sparkmax_neo",
    "id": 2,
    "canbus": ""
  },
  "inverted": {
    "drive": false,
    "angle": false
  },
  "absoluteEncoder": {
    "type": "cancoder_can",
    "id": 3,
    "channel": 0,
    "canbus": ""
  },
  "absoluteEncoderOffset": 0,
  "absoluteEncoderInverted": false,
  "location": {
    "front": 12.5,
    "left": 10.5
  }
}

After

{
  "$schema": "https://example.com/schemas/module.json",
  "drive": {
    "type": "sparkmax_neo",
    "id": 1,
    "canbus": ""
  },
  "angle": {
    "type": "sparkmax_neo",
    "id": 2,
    "canbus": ""
  },
  "inverted": {
    "drive": false,
    "angle": false
  },
  "absoluteEncoder": {
    "type": "cancoder_can",
    "id": 3,
    "channel": 0,
    "canbus": ""
  },
  "absoluteEncoderOffset": 173.4,
  "absoluteEncoderInverted": false,
  "location": {
    "front": 12.5,
    "left": 10.5
  }
}

Confirm the reading is counterclockwise positive (CCW+).

The absolute encoder reading should be counterclockwise positive (CCW+) (increasing as the module rotates counterclockwise from a top-down view). If it isn't, you need to set that module's absoluteEncoderInverted to true. This is rare — most absolute encoders already read counterclockwise positive (CCW+) by default, so only change this if you've confirmed the reading is backwards.

modules/frontleft.json

Before

{
  "$schema": "https://example.com/schemas/module.json",
  "drive": {
    "type": "sparkmax_neo",
    "id": 1,
    "canbus": ""
  },
  "angle": {
    "type": "sparkmax_neo",
    "id": 2,
    "canbus": ""
  },
  "inverted": {
    "drive": false,
    "angle": false
  },
  "absoluteEncoder": {
    "type": "cancoder_can",
    "id": 3,
    "channel": 0,
    "canbus": ""
  },
  "absoluteEncoderOffset": 173.4,
  "absoluteEncoderInverted": false,
  "location": {
    "front": 12.5,
    "left": 10.5
  }
}

After

{
  "$schema": "https://example.com/schemas/module.json",
  "drive": {
    "type": "sparkmax_neo",
    "id": 1,
    "canbus": ""
  },
  "angle": {
    "type": "sparkmax_neo",
    "id": 2,
    "canbus": ""
  },
  "inverted": {
    "drive": false,
    "angle": false
  },
  "absoluteEncoder": {
    "type": "cancoder_can",
    "id": 3,
    "channel": 0,
    "canbus": ""
  },
  "absoluteEncoderOffset": 173.4,
  "absoluteEncoderInverted": true,
  "location": {
    "front": 12.5,
    "left": 10.5
  }
}

All of the tuning steps below follow the YAGSL example project. (Note: this link isn't live yet, but will be by the time you're using this site.)

Tune the Real Robot

Lift the robot off the ground first

It is very important to initially tune the real robot with the modules elevated off the ground, so they can rotate freely without hitting anything.

If something is only happening to one module, there's likely something physically wrong with that module. When in doubt, check wiring first, then gears — and if all else fails, rebuild the module, paying special attention to the instructions.

Rotate the robot counterclockwise (CCW) and check the gyro.

With the robot off the ground, rotate it counterclockwise (CCW) (from a top-down view) and confirm the gyro reads counterclockwise positive (CCW+).

Expected

Rotating the robot counterclockwise (CCW) (top-down) increases the gyro reading.

Incorrect

The gyro decreases instead — set gyroInvert to true in swervedrive.json, redeploy, and recheck.

Only change gyroInvert if the CCW test above failed (the gyro decreased instead of increased). If it read correctly, leave it alone — there's nothing to change here.

swervedrive.json

Before

{
  "$schema": "https://example.com/schemas/swervedrive.json",
  "gyro": {
    "type": "pigeon2_can",
    "id": 1,
    "canbus": ""
  },
  "gyroAxis": "yaw",
  "gyroInvert": false,
  "modules": [
    "frontleft.json",
    "frontright.json",
    "backleft.json",
    "backright.json"
  ]
}

After

{
  "$schema": "https://example.com/schemas/swervedrive.json",
  "gyro": {
    "type": "pigeon2_can",
    "id": 1,
    "canbus": ""
  },
  "gyroAxis": "yaw",
  "gyroInvert": true,
  "modules": [
    "frontleft.json",
    "frontright.json",
    "backleft.json",
    "backright.json"
  ]
}

Tune the real robot's PID gains.

Just like in simulation, edit modules/pidfproperties.json to tune the drive and angle PID gains — this time for the real robot. Not sure how to tune a PID loop? WPILib's flywheel tuning guide walks through the same method used here for the drive PID, and the turret tuning guide covers the azimuth/angle PID.

Angle (azimuth) motor

Turns the wheel to point a new direction — this is what the angle PID controls.

Drive motor

Spins the wheel to roll forward/backward, without changing its heading — this is what the drive PID controls.

Feedforward is optional. s, v, and a (kS, kV, kA) can be tuned too, for an even better fit.
The drive motor already has a default v. It's computed from the free speed RPM of the motor you selected for that module, but only applies when you haven't set your own v.
You must redeploy to test. Editing the json file alone doesn't change anything on the robot — redeploy the code every time you want to test a change.

modules/pidfproperties.json

Before

{
  "$schema": "https://example.com/schemas/pidfproperties.json",
  "drive": {
    "p": 0.1,
    "i": 0,
    "d": 0,
    "s": 0,
    "v": 0.7,
    "a": 0.1
  },
  "angle": {
    "p": 0.01,
    "i": 0,
    "d": 0,
    "s": 0,
    "v": 0,
    "a": 0
  }
}

After

{
  "$schema": "https://example.com/schemas/pidfproperties.json",
  "drive": {
    "p": 0.28,
    "i": 0,
    "d": 0,
    "s": 0,
    "v": 0.7,
    "a": 0.1
  },
  "angle": {
    "p": 0.05,
    "i": 0,
    "d": 0.001,
    "s": 0,
    "v": 0,
    "a": 0
  }
}

Mistakes happen when building modules, and motors can and do die. If a module won't tune correctly, work through this before assuming the motor is bad:

Check it spins freely by hand. With the robot off the ground and powered off, both the drive wheel and the azimuth of the module should spin with no friction. If either doesn't, rebuild that module, paying special attention to the assembly instructions.
Check that motor's stator (output) current. A stalling motor draws exceedingly high stator current and heats up quickly — that usually means a dead or dying motor.

Spin each module 5 full turns and check it lands back where it started.

With the robot disabled (motors not fighting you, but telemetry still live) and off the ground, by hand rotate one module's azimuth exactly 5 full turns (360° × 5), then check that module's current state in AdvantageScope — it should read the relatively close same angle it started at. If it doesn't, that module's gear ratio is wrong:

Wrong gear installed: azimuth and drive gears often look very similar and are easy to mix up during assembly. Check the vendor's website for the expected gear ratio, and reassemble the module to check it was built correctly.
Wrong value entered: double check the gear ratio in physicalproperties.json (or that module's gearing override) against the vendor's spec.

You can run the same 5-turn test on each drive motor too — rotate the wheel by hand exactly 5 full turns and confirm the reported distance traveled matches what you'd expect. This only matters on the real robot — simulation doesn't model gearing mistakes.

modules/physicalproperties.json

Before

{
  "$schema": "https://example.com/schemas/physicalproperties.json",
  "gearing": {
    "drive": {
      "gearRatio": 6.75,
      "diameter": 4
    },
    "angle": {
      "gearRatio": 12.8
    },
    "statorCurrentLimit": {
      "drive": 40,
      "angle": 40
    }
  }
}

After

{
  "$schema": "https://example.com/schemas/physicalproperties.json",
  "gearing": {
    "drive": {
      "gearRatio": 6.75,
      "diameter": 4
    },
    "angle": {
      "gearRatio": 21.43
    },
    "statorCurrentLimit": {
      "drive": 40,
      "angle": 40
    }
  }
}

Hold the right stick left and check the spin direction.

Still with the robot off the ground, hold the right stick to the left. The right stick's left/right axis controls angular velocity — left commands the robot to rotate left (CCW), right commands it to rotate right (CW). Verify the robot matches the AdvantageScope swerve widget below (top-down view). Common problems:

Drifts or translates instead of spinning in place: the wrong CAN IDs for a module, or the wrong absolute encoder offset.
Spins cleanly but the wrong way (clockwise (CW) instead of CCW):
- Inverted drive motors.
- A diagonal module swap — front-left ↔ back-right, front-right ↔ back-left.
- Absolute encoder offsets that were captured with the bevel gear facing right instead of left.

Hold the right stick left to rotate left (CCW)

Expected

Wheels angle tangentially (pinwheel pattern) so the robot spins cleanly in place, matching the AdvantageScope swerve widget.

Incorrect

The robot spins cleanly, but the wrong way (clockwise (CW) instead of CCW) — check for inverted drive motors, a diagonal module swap (front-left ↔ back-right, front-right ↔ back-left), or absolute encoder offsets that were captured with the bevel gear facing right instead of left.

Incorrect

Wheels stay pointed the same direction, so the robot drifts or translates instead of spinning in place — check module CAN IDs and absolute encoder offsets.

All of the tuning steps below follow the YAGSL example project. (Note: this link isn't live yet, but will be by the time you're using this site.)

Verify Field Orientation

Add the field widget.

In AdvantageScope, open the 2D Field feature and drag in NT:/Mechanisms/swerve/pose.

Test forward/back/left/right at the starting heading.

Drive it forward, back, left, and right, and verify the robot moves in the matching direction on the field relative to the driver station's position. Common problems:

Wrong at every heading, including this one: check gyroInvert in swervedrive.json.
Only wrong once you rotate to 45°/125° later on: it doesn't show up until the robot isn't sitting at its starting heading, which points away from the gyro and toward one of these instead:
- An absolute encoder offset that's off.
- A drive motor inversion mistake.
- A wrong module location (front/left).
- Wiring: an absolute encoder wired to the wrong motor controller.
- A wrong CAN ID: a module assigned an incorrect ID.
Verify the wiring and CAN IDs are correct first — they're the quickest to rule out. If the problem persists, redo the guide's tuning steps starting from Align Modules to recapture everything.

Use the left stick to drive forward/back/left/right

Expected

Pushing forward moves the robot away from the driver station on the field widget, and left/right match too.

Incorrect

The field widget moves opposite what you'd expect — check the gyro offset/inversion.

Spin in place and watch the field widget.

Spin the robot in place again (right stick held left, CCW) — but this time watch the field widget's heading instead of the swerve module states widget. Common problems:

Drifts or translates instead of spinning in place: the wrong CAN IDs for a module, or the wrong absolute encoder offset.
Spins cleanly but the wrong way (clockwise (CW) instead of CCW):
- Inverted drive motors.
- A diagonal module swap — front-left ↔ back-right, front-right ↔ back-left.
- Absolute encoder offsets that were captured with the bevel gear facing right instead of left.
Looked correct on the previous tab, but wrong here: an inverted gyro can flip the field widget's spin direction even when the swerve module states widget looked right.

Hold the right stick left to rotate left (CCW)

Expected

Wheels angle tangentially (pinwheel pattern) so the robot spins cleanly in place, matching the AdvantageScope swerve widget.

Incorrect

Wheels stay pointed the same direction, so the robot drifts or translates instead of spinning in place — check module CAN IDs and absolute encoder offsets.

Retest cardinal directions at a 45° heading.

Rotate the robot so its heading reads about 45°, then test all four cardinal directions again — the robot should still move the same way relative to the driver station, no matter which way its chassis is pointing.

Expected

Pushing forward moves the robot away from the driver station on the field widget, and left/right match too. Even at a 45° heading, the direction shouldn't change.

Incorrect

The field widget moves opposite what you'd expect — check the gyro offset/inversion.

Repeat once more at a 125° heading.

Expected

Pushing forward moves the robot away from the driver station on the field widget, and left/right match too. Even at a 125° heading, the direction shouldn't change.

Incorrect

The field widget moves opposite what you'd expect — check the gyro offset/inversion.

Watch for absolute encoder drift

Your absolute encoder offsets should not change over time. If they do, it's likely because there's no loctite/glue on the magnet — if you're using magnetic encoders — on that module. Check that module's build instructions for how to properly loctite/glue the magnet in place, and reapply it.

Swerve Maintenance

Your swerve drive doesn't stop needing attention once it's tuned — keep these in mind for the rest of the season.

Grease the swerve modules regularly.

Regular greasing keeps modules performing optimally. Grease them at the beginning of tuning, and again in between events. Don't overgrease them, though — excess grease attracts debris and adds resistance instead of reducing it.

Re-measure your wheels if autonomous starts over/undershooting.

Swerve wheels wear down and degrade over time, so the diameter you configured may no longer match the wheel's actual size. If you notice consistent over- or under-shooting in autonomous, re-measure the wheel and double check the drive gear ratio and diameter in physicalproperties.json (or that module's gearing override).

modules/physicalproperties.json

Before

{
  "$schema": "https://example.com/schemas/physicalproperties.json",
  "gearing": {
    "drive": {
      "gearRatio": 6.75,
      "diameter": 4
    },
    "angle": {
      "gearRatio": 21.43
    },
    "statorCurrentLimit": {
      "drive": 40,
      "angle": 40
    }
  }
}

After

{
  "$schema": "https://example.com/schemas/physicalproperties.json",
  "gearing": {
    "drive": {
      "gearRatio": 6.75,
      "diameter": 3.87
    },
    "angle": {
      "gearRatio": 21.43
    },
    "statorCurrentLimit": {
      "drive": 40,
      "angle": 40
    }
  }
}

Watch for consistent azimuth angle drift.

If a module's azimuth angle is consistently off in real life — not just a one-time calibration slip — the gear may be skipping under load, or it may have been replaced with the wrong gear at some point. Recheck that module's gear against the vendor's spec, and rebuild the module if needed.

If it's only happening to one module, suspect that module.

When an issue is isolated to a single module instead of the whole drivetrain, there's likely something physically wrong with that module specifically. When in doubt, check wiring first, then gears — and if all else fails, rebuild the module, paying special attention to the instructions.

Check off all 5 remaining steps above to continue.