FrcCatalyst
A Java library of pre-built mechanism building blocks for FRC robots on Phoenix 6 and WPILib 2026.
Latest release
v1.11.0 adds the other half of the spec sheet: which parts of Catalyst the robot actually runs. Autopilot, Strategist, Sequence, Goal Director and Physics Core each record themselves under /Catalyst/Robot/Catalyst/ as they are built, with the name they were built under, so the list is what came up rather than what a team meant to use. There is nothing to declare and nothing to keep in step.
v1.10.0 made the robot say who it is. RobotIdentity.declare("Ratchet") publishes that spec sheet under /Catalyst/Robot/ — team number, season, roboRIO and image, library versions, drivetrain geometry, CAN inventory — all of it derived rather than typed in, and anything the library does not know is absent from the wire rather than published as a zero. Catalyst also names its own build: CatalystVersion.describe().
v1.8.0 makes the simulated field solid: robots and game pieces now collide with terrain and each other, and what happens depends on what they are made of. v1.7.0 validated Physics Core against a ground-truth simulator and added a guide to measuring your robot. v1.6.0 completed it — the optional layer that watches how your robot actually behaves. It fuses wheel odometry and the IMU into one velocity with an honest confidence attached, scores which wheel is lying when a tyre breaks loose, notices when something hit the robot, and predicts where the robot will be at the instant a shot leaves it. On top of v1.5.0’s shadow mode it adds a live centre of mass and tipping margin that tracks your elevator as it moves, closed-form ballistics, online identification of feedforward gains and battery resistance (reported, never applied), residual-based fault isolation, and pre-flight capability evaluation.
It is entirely optional and strictly advisory: it writes no pose, schedules no command, and blocks no transition, so every existing API works exactly as before. Even the new limit layer only computes speed and acceleration caps — applying one is a line of your code. 214 HAL-free tests, telemetry under Catalyst/Physics/…. The validator marks the estimator against the RFC’s acceptance criteria — and building it found three real defects that 300 unit tests had missed, taking the fused-velocity result from 0.08% to 48% better than raw encoders.
It follows v1.4.0’s optional Catalyst desktop app (every tool in one native window, one-click vendordep install, offline auto-update, an AI-agent connector) and the v1.3.x line, which made the state machine understandable and debuggable: a plain-language explain() dump of what you built and why it’s stuck, a ServoMechanism, live sim status panels, the State Machine Internals guide, and the State Machine Visualizer browser tool. See the release notes and the CHANGELOG.
Browser tools
Eleven single-file tools served from this site. Click and use — no clone, no install.
HealthCheck on the robot, live. 📈Motion ProfileTrapezoid + S-curve sketcher with copyable constants. 🎯PID Step ResponseDial gains, watch the simulated response. ⚡MotorType BrowserEvery motor preset + gear-ratio calculator. 🔌CAN ID PlannerCatch CAN ID collisions before crimping. 🧭Auto BuilderGenerate a behavior-framework auto. 🔀State Machine VisualizerDraw the graph your Superstructure logs — states, guards, dead-ends. Why
Every season teams rebuild the same elevator, arm, intake, and swerve scaffolding. Catalyst replaces it with one builder call:
LinearMechanism elevator = new LinearMechanism(
LinearMechanism.Config.builder()
.name("Elevator").motor(13).follower(14, true)
.motorType(MotorType.KRAKEN_X60)
.gearRatio(10.0).drumRadius(0.0254).mass(5.0)
.pid(50, 0, 0.5).gravityGain(0.35)
.motionMagic(2.0, 4.0, 20.0)
.position("STOW", 0.0).position("HIGH", 1.1)
.build()
);
Motion Magic, gravity FF, sim, telemetry, command factories, health monitoring, live tuning — all wired in.
| Raw WPILib + Phoenix | Catalyst | |
|---|---|---|
| Elevator with gravity FF | ~150 lines | 8 lines |
| Swerve + PathPlanner + Vision | ~400 lines | 15 lines |
| Sim + telemetry per mechanism | you write it | included |
| Temperature cutoff | manual | automatic |
| Limit-switch auto-zero | manual | one call |
What’s in the box
Mechanisms
| Mechanism | Use Case | Key Features |
|---|---|---|
| LinearMechanism | Elevators, slides | Position control, gravity FF, limit switches, multi-follower |
| RotationalMechanism | Arms, wrists, turrets | Cosine gravity, hard stops, Motion Magic, multi-follower |
| FlywheelMechanism | Shooters | Dual motor + per-shaft followers, velocity PID, at-speed trigger |
| RollerMechanism | Intakes, conveyors | Stall detection, beam break, auto-stop |
| WinchMechanism | Climbers | Extend/retract limits, position tracking, dual-arm support |
| ClawMechanism | Motor-driven grippers | Stall detection, beam break, multi-follower, passive-hold |
| DifferentialWristMechanism | Diffy wrists (pitch + roll) | Phoenix-6 native differential control, separate Slot 0 / Slot 1 tuning |
| PneumaticMechanism | Solenoids / pistons | Double or single solenoid, optional pressure-gating, pulse / toggle commands |
| Superstructure (v1.2.0+) | Whole-robot coordination | Real state machine over all nine mechanism types plus your own subsystems — legal-transition graph, guards, interlocks, staged actuation, proven arrival, full logging. Replaces the now-deprecated SuperstructureCoordinator (linear + rotational only), which still works and is not being removed |
Subsystems
- SwerveSubsystem — wraps the TunerX-generated drivetrain. Heading lock, point-at-target, skew correction, PathPlanner.
- VisionSubsystem — multi-camera with Kalman innovation tracking, high-speed rejection, heading-divergence filtering.
- LEDSubsystem — 14 patterns (fire, gradients, Larson scanner, alignment indicator).
Advanced
StateSpaceController | LQR + Kalman for optimal mechanism control |
MotionConstraintCalculator | Physics-derived velocity / accel from motor specs |
SignalProcessor | EMA, median, low-pass, composite filters |
PoseHistory | Timestamped pose ring buffer with interpolation |
DynamicAutoBuilder | Runtime path generation via PathPlanner |
TunableNumber | Dashboard-editable constants for live PID tuning |
AutoSelector | PathPlanner auto chooser with safe fallbacks |
GamePieceTracker | Multi-stage piece state machine with Triggers |
Superstructure / StateMachineCore (v1.2.0+) | Enum-typed whole-robot state machine: undeclared edges are refused, arrival is measured rather than assumed, and every decision is logged |
RobotIdentity (v1.10.0+) | One line publishes the robot’s spec sheet on NetworkTables — derived, never typed in, and silent about anything the library cannot read |
CatalystFeatures (v1.11.0+) | Which parts of Catalyst the robot runs, recorded by each part as it is built |
| Skew correction | Pose-exponential discretization for swerve |
| Collision zones | Prevent physical mechanism collisions |
SimDashboard (v1.1.0+) | Generic browser sim cockpit that adapts to any mechanism via describe() / MechanismView; sim-only, dependency-free |
Health and safety (v0.3.3+)
HealthCheck / HealthMonitor | Debounced INFO / WARN / ERROR layer; every motor gets OverCurrent / HighTemp / OverTemp by default |
HealthHistory | Ring buffer of recent transitions; published for the dashboard timeline |
RobotSafety | Optional watchdog with trippedTrigger() for one-line bindings |
MotorType | NEO / Vortex / 550 / Minion / Kraken (including X44 and corrected FOC torques), plus a public constructor for custom motors |
Driver & robot state (v0.4.0+)
DriverProfile | Per-driver deadband + curve + speed cap + slow mode |
RumbleEvents | Bind any Trigger to a controller rumble pattern |
RobotState | One singleton wrapping alliance / match time / mode / battery + ready-to-bind triggers |
LimelightTriggers | Trigger.tagInView(7), .detectorClass("note"), .horizontalErrorBelow(2.0) |
| SysId on every motor | mechanism.sysIdQuasistatic(Direction) / .sysIdDynamic(Direction) work out of the box |
SwerveSetpointGenerator | Chassis-aware accel + skid clamp for the common driver-skid case |
Every mechanism gets
Builder config, Motion Magic or ProfiledPID, named position presets (goTo("STOW")), WPILib sim, NetworkTables telemetry, temperature cutoff, limit-switch auto-zero, HealthCheck-based fault monitoring, multi-follower support, pre-built commands, SysId quasistatic / dynamic routines (v0.4.0+), a self-describing describe() / MechanismView snapshot driveable in the built-in SimDashboard (v1.1.0+).
Documentation
| Installation | Add Catalyst to your build.gradle |
| Quick Start | First mechanism in five minutes |
| Mechanisms | All nine mechanism types |
| Subsystems | Swerve, Vision, LEDs, LimelightTriggers, SwerveSetpointGenerator |
| Driver | DriverProfile, RumbleEvents, controller feel |
| Utilities | Health Kit, RobotSafety, RobotState, MotorType, CANRegistry, feedforward, profiles |
| Advanced | Behavior framework, turret + SOTF, state-space, live tuning, health, SysId |
| Tools | The eleven browser tools — incl. Auto Builder + State Machine Visualizer |
| Examples | Whole-robot examples |
| Testing | Unit-testing Catalyst-based code |
Compatibility
| Component | Version |
|---|---|
| WPILib | 2026.2.1 |
| CTRE Phoenix 6 | 26.1.1 |
| PhotonVision | v2026.3.1 |
| PathPlanner | 2026.1.2 |
| Java | 17+ |