Skip to content

Drivetrain

The drivetrain is the part of this template I want treated with the most discipline. Swerve bugs are expensive because they affect every driver, every autonomous path, every mechanism alignment, and every log interpretation. Configure it carefully; do not redesign it casually.

What is already provided

The template keeps the AdvantageKit CTRE swerve infrastructure:

  • TalonFX module IO
  • Pigeon2 gyro IO
  • Phoenix high-rate odometry
  • module state optimization
  • CTRE status signal handling
  • simulation IO
  • replay-safe no-op IO
  • SysId routines
  • AdvantageKit input and output logging
  • AdvantageScope calibration asset

Normal robot work should not replace this. Most teams should only edit constants and tuning values.

CTRE Tuner X constants

The main drivetrain configuration lives in frc.robot.generated.TunerConstants.

Configure:

  • CAN bus name
  • Pigeon2 device ID
  • drive motor IDs
  • steer motor IDs
  • CANcoder IDs
  • module absolute offsets
  • drive/steer inversion
  • wheel radius
  • drive and steer gear ratios
  • module X/Y locations
  • slip current
  • supply/current limits
  • maximum realistic speed
  • steer gains
  • drive gains
  • simulation inertias and friction values

Prefer generating this file from CTRE Tuner X, validating on the robot, and copying the known-good values into the template. Do not hand-type offsets from memory.

Module geometry

Module positions must be measured from the robot center, in meters, using WPILib's coordinate convention:

  • positive X is forward
  • positive Y is left
  • rotations are counterclockwise positive

A sign error here makes odometry and field-relative control feel haunted. If the robot drives fine robot-relative but rotates or translates incorrectly field-relative, check geometry and gyro orientation before blaming autonomous.

Offset calibration

Use the supplied AdvantageScope swerve calibration layout. The normal flow is:

  1. Put the robot on blocks.
  2. Boot robot code and AdvantageScope.
  3. Align each wheel to the calibration direction.
  4. Read each absolute encoder value.
  5. Update the corresponding CTRE offset.
  6. Reboot and verify the modules align correctly while disabled.
  7. Only then test closed-loop steering.

Offsets should be boring. If an offset changes unexpectedly, find the mechanical or wiring reason instead of compensating in code.

Wheel radius and distance accuracy

Wheel radius affects odometry and path following. Measure it, then validate it with a characterization or controlled drive distance. A nominal wheel diameter from a product page is not enough once tread wear and compression matter.

Symptoms of bad wheel radius:

  • autos consistently undershoot or overshoot
  • odometry distance disagrees with measured field movement
  • BLine tuning looks different at different speeds
  • teleop pathfinding terminal approach is consistently off

Fix radius before tuning path controllers.

Current limits and slip

Start conservative. A robot that brownouts during tuning gives you bad data.

Tune current limits and slip behavior after:

  • module directions are correct
  • steering is stable
  • wheel radius is plausible
  • battery and main breaker are healthy
  • logs show expected module velocities

If the drive feels weak, check logs before raising limits. A weak-feeling swerve can be caused by bad offsets, wrong inversion, current limiting, wheel scrub, or controller saturation.

The Drive API

Commands should use the public Drive methods for behavior:

  • get the current pose
  • reset pose
  • drive robot-relative speeds
  • drive field-relative speeds
  • stop or X-lock modules
  • orient modules before a path
  • add timestamped vision measurements

Do not call module IO, TalonFX objects, CANcoders, or Phoenix status signals from commands.

Characterization

Use the included characterization commands to identify drivetrain behavior. Characterize after the robot is mechanically sound and before raising autonomous constraints.

Recommended order:

  1. Verify module offsets.
  2. Verify wheel radius.
  3. Verify measured module states.
  4. Run low-speed SysId checks.
  5. Review logs.
  6. Increase speed only when data looks sane.

Characterization data taken with slipping wheels, low battery, or wrong geometry is worse than no characterization data.

Simulation

Simulation is useful for command wiring, autonomous sequencing, vision plumbing, and replay safety. It is not proof that the real robot is tuned.

Use sim to check:

  • commands schedule and finish
  • autos load
  • events trigger
  • navigation goals resolve
  • pose estimates flow through logs
  • no hardware IO is required in replay

Use the real robot on blocks and then carpet to check:

  • current draw
  • wheel slip
  • module azimuth behavior
  • gyro orientation
  • carpet interaction
  • brownout margin

Common drivetrain mistakes

  • Editing drivetrain internals instead of fixing TunerConstants.
  • Testing autonomous before verifying wheel radius.
  • Assuming camera localization can hide bad odometry.
  • Mixing PathPlanner autos with BLine autos.
  • Logging dashboard-only values through direct NT publishers.
  • Changing module inversion without recalibrating and retesting.
  • Tuning at full speed before low-speed behavior is correct.