Choreo (Constraint-Honoring Omnidirectional Route Editor and Optimizer)

Choreo (Constraint-Honoring Omnidirectional Route Editor and Optimizer) is a time-optimal drivetrain trajectory planner designed for the FIRST Robotics Competition (FRC). It is used to generate trajectories that maximize the performance of swerve or differential drivetrains while strictly obeying their physical dynamics constraints.

Key features include:

• Accuracy: Leverages full drivetrain performance within dynamics constraints.
• Easy UI: A graphical interface with real-time playback.
• Cross-Platform: Supports Windows (x86_64/aarch64), macOS (x86_64/arm64), and Linux (x86_64).
• Customization: Supports various waypoints, constraints, and obstacles.
• ChoreoLib: A dedicated robot-side vendor library for integration.
• Open Source: Licensed under BSD-3-Clause.

TrajoptLib is a library designed for generating time-optimal drivetrain trajectories. It ensures trajectories are subject to waypoint, kinematic, and dynamic constraints.

Key Features:

• Support for swerve drives with arbitrary module configurations.
• Position and velocity constraints at each waypoint.
• Obstacle avoidance using keep-out circles and polygons.
• Support for custom robot physical constraints and custom bumper shapes.

Choreo is a time-optimal drivetrain trajectory planner designed for the FIRST Robotics Competition (FRC).

To use the tool, you can access the official documentation at choreo.autos, which provides detailed guides on:

• Installation
• General usage
• Building the project
• Integrating Choreo paths into your robot code using ChoreoLib.

The repository is organized into several functional components:

• src: The Choreo frontend application.
• src-tauri: The Choreo backend (Tauri).
• src-cli: The Choreo command-line generation tool.
• src-core: Shared Rust code used by both the application and the CLI.
• choreolib: ChoreoLib — the robot-side library used for loading and following Choreo-generated paths.
• trajoptlib: TrajoptLib — the library used by Choreo to generate time-optimal trajectories for FRC robots.
• docs: Source files for the official documentation.

When deciding how to architect your autonomous routines with AutoFactory, choose based on complexity:

• Command Compositions: Best for short, simple autonomous routines. You use standard WPILib command grouping (sequences, parallels) combined with AutoFactory methods like trajectoryCmd().
• AutoRoutine: Best for complex autonomous routines that include many segments, complex logic, or branching behavior.

Trajectory Strategy Tip: While you can use "monolithic" trajectories (one long trajectory), AutoFactory is designed to work effectively with "segmented" trajectories (multiple small, reusable trajectories). If using monolithic trajectories, you can use the "Split" checkbox on waypoints in the Choreo application to treat them as segments.

The Theoretical panel provides calculated metrics based on your input. Use these values to validate that your configuration is physically realistic before running optimizations.

Calculated metrics include:

• Traction Accel Limit $[m/s^2]$: Maximum acceleration before wheels slip.
• Motor Accel Limit $[m/s^2]$: Maximum acceleration based on motor torque.
• Floor Speed $[m/s]$: Maximum straight-line speed.
• Floor Accel $[m/s^2]$: Maximum straight-line acceleration (the minimum of traction and motor limits).
• Ang Speed $[rad/s]$: Maximum angular speed when spinning in place.
• Ang Accel $[rad/s^2]$: Maximum angular acceleration when spinning in place.

ChoreoLib does not provide a built-in trajectory follower. Instead, it provides trajectory "samples" that represent the state of a trajectory at a specific point in time.

It is the responsibility of the user to implement the trajectory following logic within their robot's drive subsystem. This allows for custom implementations, such as:

• Adding telemetry hooks.
• Implementing vendor-specific features (e.g., wheel force feedforwards with CTRE Swerve).
• Integrating external feedback (e.g., vision-based detection).

Commonly, a follower will:

1. Receive a sample (SwerveSample or DifferentialSample).
2. Get the current robot pose.
3. Calculate error/feedback (using PID or LTV controllers).
4. Combine the sample's feedforward velocities with the feedback to generate target velocities.
5. Apply those velocities to the drivetrain.

Choreo uses two distinct file types to manage robot trajectories:

1. .chor files: These store the general configuration settings for your project.
2. .traj files: These store individual path information. Each .traj file corresponds to a single path created in Choreo.

Crucial Relationship: Choreo generates and updates .traj files in the same directory where your .chor file is stored. Because path-following libraries like ChoreoLib and PathPlannerLib expect these files in specific locations, you must save your .chor file in the correct directory for your programming language/environment.

To use trajectories created in Choreo, load a Trajectory object from its corresponding file located in deploy/choreo/.

Important: Always load trajectories during robot startup (e.g., in the constructor or robotInit), not when the autonomous period begins. Loading is a blocking operation and can take several seconds on a RoboRIO.

Depending on your robot's drivetrain, you must specify the correct sample type:

• Swerve Drive: Use SwerveSample (Java/C++) or load_swerve_trajectory (Python).
• Differential (Tank) Drive: Use DifferentialSample (Java/C++) or load_differential_trajectory (Python).

// Java: Loads from deploy/choreo/myTrajectory.traj
// Returns Optional.empty() if the file is missing or invalid
var trajectory = Choreo.loadTrajectory("myTrajectory");

Use these shortcuts to create, select, and modify waypoints:

• Select waypoint type in navbar: 1 through 4
• Change type of selected waypoint: Shift + 1 through Shift + 4
• Add waypoint: Left Mouse Click (adds the type currently selected in the navbar at the click position)
• Navigate waypoints: Left Arrow (previous) or Right Arrow (next)
• Delete selected waypoint: Delete or Backspace