What Choreo Is — and What Makes It Different

Choreo (formerly SwerveLib) is an open-source trajectory planning tool for FRC swerve drives, maintained primarily by Team 3011 (Firebears). Where PathPlanner generates paths by fitting smooth spline curves through waypoints and then constraining velocity based on curvature, Choreo takes a fundamentally different approach: it solves a mathematical optimization problem to find the trajectory that minimizes total travel time, subject to the actual physical constraints of your specific robot.

This distinction matters more than it might initially sound. A PathPlanner path is "as smooth and fast as the spline shape allows, constrained by your chosen maxVelocity." A Choreo trajectory is "as fast as your specific motors, mass, wheel friction, and gear ratios physically allow, given that you need to arrive at this pose with this heading." The optimizer accounts for motor torque curves, drivetrain inertia, and wheel slip limits. The resulting trajectory is not necessarily a smooth spline — it's whatever shape is fastest for your robot's actual hardware.

In practice, on a well-configured competition swerve drivetrain, Choreo trajectories are typically 5–15% faster than equivalent PathPlanner paths because they use the robot's full physical capability throughout, not just on straight segments. They also tend to be more repeatable because the trajectory is derived from physics rather than from constraint parameters that require manual tuning.

How Choreo Generates Trajectories

When you define a trajectory in the Choreo GUI, you specify waypoints with position and heading constraints — the same high-level information you'd give PathPlanner. But then Choreo does something very different: it runs a numerical trajectory optimization algorithm using your robot's physical model.

The optimizer needs to know:

• Robot mass and moment of inertia — from CAD or estimation
• Motor model — motor type (Kraken, Falcon, NEO), number per module, gear ratio
• Wheel parameters — radius and coefficient of friction
• Module positions — the (x, y) offsets of each swerve module from robot center

Given these parameters, the optimizer solves a constrained optimization problem: "Find the trajectory from start to end that minimizes total travel time, subject to the constraint that at no point does any wheel exceed its friction limit or any motor exceed its torque capability." The result is a trajectory that is genuinely time-optimal for your specific robot — not "as fast as you set maxVelocity."

Installation and Setup

Installing the Choreo GUI

Download Choreo from the GitHub releases page at github.com/SleipnirGroup/Choreo/releases. The application is available for Windows, macOS, and Linux. Select your robot project folder when launching — Choreo stores trajectories in deploy/choreo/ within your project directory.

Adding ChoreoLib to Your Project

// Option 1: VS Code vendor library install
// W key → "Manage Vendor Libraries" → "Install new libraries (online)"
// Paste: https://sleipnirgroup.github.io/Choreo/vendordep/ChoreoLib.json
// (Check github.com/SleipnirGroup/Choreo for the current season's URL)

// Option 2: Direct Gradle dependency
repositories {
    maven { url "https://frcmaven.wpi.edu/release" }
}
dependencies {
    implementation "com.choreo:ChoreoLib:2025.x.x"
    // Replace with the current season's version from the Choreo releases page
}

// Verify with: ./gradlew dependencies | grep -i choreo

Configuring Your Robot in the Choreo GUI

Open Choreo and navigate to Robot Configuration. Enter the same physical parameters you'd use for SysId characterization: robot mass (kg), moment of inertia (kg·m²), module positions as (x, y) offsets from center, motor type, gear ratio, wheel radius, and coefficient of friction. These values directly determine the optimizer's physical model — inaccurate values produce trajectories that look correct in the GUI but are wrong for your actual robot.

The Choreo Workflow

ChoreoLib Java Integration

ChoreoLib provides an AutoFactory pattern for assembling autonomous routines from trajectory commands and event triggers. The interface is different from PathPlanner's AutoBuilder but serves the same purpose: wire your drivetrain's methods into the trajectory execution layer once, then build auto routines from trajectory files.

import choreo.auto.AutoFactory;
import choreo.auto.AutoRoutine;
import choreo.auto.AutoTrajectory;
import choreo.trajectory.SwerveSample;

public class DriveSubsystem extends SubsystemBase {

    private final AutoFactory m_autoFactory;

    public DriveSubsystem() {
        // AutoFactory requires the same four drivetrain methods as PathPlanner's AutoBuilder
        m_autoFactory = new AutoFactory(
            this::getPose,          // Supplier<Pose2d> — current odometry pose
            this::resetPose,       // Consumer<Pose2d> — reset to trajectory start
            this::followSample,    // Consumer<SwerveSample> — apply trajectory state
            true,                  // flipForAlliance: mirrors trajectory for red alliance
            this                   // subsystem requirement for all auto commands
        );
    }

    public AutoFactory getAutoFactory() { return m_autoFactory; }

    // ChoreoLib calls this every loop with the desired trajectory state.
    // Compute feedforward from the sample's velocity + acceleration,
    // then apply PID correction from odometry error.
    private void followSample(SwerveSample sample) {
        ChassisSpeeds feedforward = sample.getChassisSpeeds();
        Pose2d desired = sample.getPose();
        Pose2d actual  = getPose();

        ChassisSpeeds correction = m_choreoController.calculate(actual, desired,
            feedforward.vxMetersPerSecond(),
            feedforward.vyMetersPerSecond(),
            feedforward.omegaRadiansPerSecond());

        driveFieldRelative(correction);
    }
}

public Command getTwoPieceChoreoAuto() {
    AutoFactory factory = m_drive.getAutoFactory();

    // Create a routine — a named container for this auto's trajectories and events
    AutoRoutine routine = factory.newRoutine("TwoPieceChoreo");

    // Load trajectory files from deploy/choreo/
    AutoTrajectory scorePreload = routine.trajectory("ScorePreload");
    AutoTrajectory pickupOne    = routine.trajectory("PickupPieceOne");
    AutoTrajectory scoreOne     = routine.trajectory("ScoreOne");

    // Wire up event triggers — fire commands at specific trajectory events
    // scorePreload.atTime(0.5) fires when 0.5 s into ScorePreload trajectory
    scorePreload.atTime(0.5).onTrue(
        new SpinUpShooterCommand(m_shooter, 4000));
    scorePreload.done().onTrue(
        Commands.sequence(
            Commands.parallelRace(new EjectCommand(m_shooter),
                                    Commands.waitSeconds(0.5)),
            pickupOne.cmd()));  // transition to next trajectory after scoring

    pickupOne.atTime(0.3).onTrue(new IntakeUntilSensorCommand(m_intake).withTimeout(2.0));
    pickupOne.done().onTrue(
        Commands.parallel(
            scoreOne.cmd(),
            new SpinUpShooterCommand(m_shooter, 4000)));

    scoreOne.done().onTrue(
        Commands.parallelRace(new EjectCommand(m_shooter),
                               Commands.waitSeconds(0.5)));

    // Return the routine command — starts with ScorePreload, transitions via triggers
    return routine.cmd().beforeStarting(scorePreload.cmd());
}

PathPlanner vs. Choreo: Choosing the Right Tool

Which Should Your Team Use?

🔌 System Check

Knowledge Check