13.1 Characterizing with SysId#

Why it matters#

In Lesson 13 you guessed kG by slowly raising the voltage. That works for one term, but kS, kV, and kA are almost impossible to guess well. SysId (System Identification) measures them for you. It drives your mechanism through a few controlled tests, records voltage, position, and velocity, and fits the feedforward equation to that real data.

Good SysId numbers mean feedforward does most of the work, and PID only has to clean up small errors.

Read this#

• Introduction to System Identification
• Creating an Identification Routine
• Running the Identification Routine
• Loading Data and Viewing Diagnostics

Walkthrough#

The big picture#

The four tests#

SysId runs two kinds of tests, each in both directions:

Running both directions matters because friction and gravity act differently going up vs. down. That's how SysId separates kS from kG.

Step 1: Add a SysIdRoutine to your subsystem#

This example characterizes an arm. The same pattern works for an elevator, flywheel, or drivetrain.

import static edu.wpi.first.units.Units.*;

import edu.wpi.first.wpilibj.RobotController;
import edu.wpi.first.wpilibj2.command.Command;
import edu.wpi.first.wpilibj2.command.SubsystemBase;
import edu.wpi.first.wpilibj2.command.sysid.SysIdRoutine;

public class Arm extends SubsystemBase {
    private final PWMSparkMax motor = new PWMSparkMax(1);
    private final Encoder encoder = new Encoder(0, 1);

    private final SysIdRoutine sysId = new SysIdRoutine(
        // Test settings. Defaults are 1 V/s ramp, 7 V step, 10 s timeout.
        // An arm needs a gentler step so it doesn't slam into its stops.
        new SysIdRoutine.Config(
            Volts.of(1).per(Second),   // quasistatic ramp rate
            Volts.of(4),               // dynamic step voltage
            Seconds.of(5)              // safety timeout per test
        ),
        new SysIdRoutine.Mechanism(
            // How SysId drives the motor:
            voltage -> motor.setVoltage(voltage.in(Volts)),
            // What SysId records every loop:
            log -> log.motor("arm")
                .voltage(Volts.of(motor.get() * RobotController.getBatteryVoltage()))
                .angularPosition(Radians.of(getAngleRadians()))
                .angularVelocity(RadiansPerSecond.of(getVelocityRadPerSec())),
            this
        )
    );

    public Command sysIdQuasistatic(SysIdRoutine.Direction direction) {
        return sysId.quasistatic(direction);
    }

    public Command sysIdDynamic(SysIdRoutine.Direction direction) {
        return sysId.dynamic(direction);
    }

    // getAngleRadians() and getVelocityRadPerSec() come from your encoder,
    // with 0 radians = arm horizontal (see Lesson 13).
}

Step 2: Bind the tests and run them#

In RobotContainer.java, put the tests on a separate controller (port 1) so a driver can't trigger them by accident:

private final CommandXboxController sysIdController = new CommandXboxController(1);

private void configureSysIdBindings() {
    sysIdController.a().whileTrue(arm.sysIdQuasistatic(SysIdRoutine.Direction.kForward));
    sysIdController.b().whileTrue(arm.sysIdQuasistatic(SysIdRoutine.Direction.kReverse));
    sysIdController.x().whileTrue(arm.sysIdDynamic(SysIdRoutine.Direction.kForward));
    sysIdController.y().whileTrue(arm.sysIdDynamic(SysIdRoutine.Direction.kReverse));
}

whileTrue is a safety feature: let go of the button and the motor stops.

Also make sure WPILib's data log is running, so the test data gets saved to a file. In Robot.java's constructor or robotInit():

DataLogManager.start();

Running the tests on the robot:

1. Use a fully charged battery. A tired battery gives noisy data.
2. Clear space. For an arm, start somewhere in the middle of its travel. For a drivetrain, put it on the floor with lots of room (not on blocks, since the wheels need real load).
3. Enable in Teleop (or Test mode).
4. Hold A (quasistatic forward). Let go before the mechanism hits a hard stop.
5. Move the mechanism back to the start if needed, then hold B, X, and Y the same way.
6. Disable the robot.

Step 3: Get the log file#

WPILib logs are .wpilog files saved on the roboRIO (or a USB stick plugged into it).

1. Connect to the robot.
2. Open DataLogTool (installed with WPILib).
3. Download the newest .wpilog file to your laptop.

Step 4: Analyze in the SysId tool#

1. Open the SysId tool (in the WPILib tools folder, or Ctrl+Shift+P → WPILib: Start Tool → SysId).
2. Open your .wpilog file.
3. In the Data Selector:
   • Pick the test-state entry. It's named something like sysid-test-state-arm.
   • Drag your logged position, velocity, and voltage entries into the matching slots.
   • Set the units to match what you logged (radians for this arm).
   • Click Load.

4. In the Analyzer, set the mechanism type:

   Mechanism	Choose	Gains you get
   Flywheel, roller, turret	Simple	kS, kV, kA
   Drivetrain	Simple (characterize left and right sides)	kS, kV, kA
   Elevator	Elevator	kS, kV, kA, kG
   Arm	Arm	kS, kV, kA, kG

5. Read off the feedforward gains.

Step 5: Check the data before trusting it#

SysId always produces numbers, even from bad data. Before using them, look at the Diagnostics plots:

The SysId diagnostic plots (highlighted in red). From the WPILib docs, Viewing Diagnostics (CC BY 4.0).

• Fit quality: each plot should show the fitted line passing through the middle of the data points, not off to one side.
• Velocity vs. time: the quasistatic plots should rise smoothly. Jagged plots or big gaps mean a noisy sensor or a test that was too short.
• Sanity check the signs: kS, kV, and kA should all be positive. A negative gain almost always means a sensor is inverted relative to the motor, or the units are wrong.

Step 6: Use the gains#

Copy the numbers into Constants.java and plug them into the feedforward from Lesson 13:

public static final class ArmConstants {
    // From SysId, <date>, fresh battery
    public static final double kS = 0.21;   // volts
    public static final double kG = 0.48;   // volts
    public static final double kV = 1.87;   // volts per (rad/s)
    public static final double kA = 0.06;   // volts per (rad/s²)
}

private final ArmFeedforward ff = new ArmFeedforward(
    ArmConstants.kS, ArmConstants.kG, ArmConstants.kV, ArmConstants.kA);

These example numbers are made up. Yours will be different.

SysId's analyzer can also suggest PID gains for a velocity or position loop. Treat them as a starting point, then fine-tune with the recipe in Lesson 12.

Try it#

• Add a SysIdRoutine to your arm (or drivetrain) and confirm the four commands run in simulation without errors
• With a mentor, run all four tests on the real robot
• Load the log in SysId and get kS, kV, kA (and kG if it applies)
• Check the diagnostics: are all gains positive? Does the fit look good?
• Put the gains in your feedforward and compare tracking to your hand-tuned version from Lesson 13

Check yourself#