7.1 How the Command Scheduler Works#

Why it matters#

In Lesson 7 you bound a button to a command and it "just worked." That's the command scheduler doing its job. Most confusing command-based bugs come from not knowing what the scheduler does:

• a command that never stops
• a command that stops the moment it starts
• a button that does nothing
• two mechanisms fighting each other

Once you can picture what the scheduler does every 20 ms, you can predict exactly what your robot will do, and debugging gets much easier.

Read this#

• The Command Scheduler
• Commands, especially the command lifecycle
• Binding Commands to Triggers
• Command Compositions

Walkthrough#

The scheduler is one object, run once per loop#

There is exactly one scheduler in your robot program: CommandScheduler.getInstance(). It doesn't run on its own. The Command Robot template calls it from Robot.java:

@Override
public void robotPeriodic() {
    CommandScheduler.getInstance().run();
}

Remember the 20 ms loop from Lesson 6. Every time robotPeriodic() runs, the scheduler gets one turn. Everything it does happens inside that turn, on one thread, one step at a time. Nothing happens "in the background."

What happens in one run()#

Every 20 ms, the scheduler does these steps, in this order:

Here's the same sequence as drawn in the WPILib docs:

One run of the scheduler. From the WPILib docs source, scheduler-run-sequence.drawio.svg (CC BY 4.0).

1. Subsystem periodic() methods run. Every registered subsystem gets its periodic() called, whether or not a command is using it. This is the place for telemetry and reading sensors.
2. Triggers are checked. Every button binding and other trigger you set up in configureBindings() is checked: is the A button pressed right now? Was it pressed last loop?
3. Commands are scheduled or canceled. If a trigger changed (button just pressed, just released), the scheduler starts or cancels the bound command.
4. Running commands run. For each scheduled command, it calls execute(), then asks isFinished().
5. Finished commands end. Any command that returned true from isFinished() gets end(false) called and is removed.
6. Default commands start. Any subsystem that now has no command using it gets its default command scheduled.

Then run() returns, the loop finishes, and 20 ms later it all happens again.

The life of a command#

Every command has four methods. The scheduler, not you, decides when each one is called.

Here's a command written out longhand so you can see all four:

public class SpinUpShooter extends Command {
    private final Shooter shooter;
    private final double targetRpm;

    public SpinUpShooter(Shooter shooter, double targetRpm) {
        this.shooter = shooter;
        this.targetRpm = targetRpm;
        addRequirements(shooter);   // "I need the shooter" (see below)
    }

    @Override
    public void initialize() {
        shooter.setTarget(targetRpm);          // runs once
    }

    @Override
    public void execute() {
        shooter.runControlLoop();              // runs every 20 ms
    }

    @Override
    public boolean isFinished() {
        return shooter.isAtSpeed();            // checked every 20 ms
    }

    @Override
    public void end(boolean interrupted) {
        if (interrupted) {
            shooter.stop();                    // only stop if we were canceled
        }
    }
}

The shortcut factories from Lesson 7 build these same four methods for you:

Most of these never finish on their own. They run until a button release, a timeout, or another command interrupts them. Add .until(condition) or .withTimeout(seconds) when you want one to stop by itself.

Requirements: one command per subsystem#

A requirement is a command saying "I'm using this subsystem." The scheduler enforces a simple rule:

Only one running command may require a given subsystem at a time.

This is what stops two commands from setting the same motor to different speeds in the same loop. Factories made from a subsystem (intake.run(...)) require that subsystem automatically. A longhand command calls addRequirements(...) in its constructor.

When you schedule a command whose requirements are already in use, the scheduler has to pick one:

• By default, the new command wins. The old command is interrupted: its end(true) runs, then the new one starts.
• A command can refuse to be interrupted. If the running command was built with .withInterruptBehavior(InterruptionBehavior.kCancelIncoming), the new command is ignored instead.

Here's how the scheduler decides, as a flowchart:

What happens when a command is scheduled. From the WPILib docs source, scheduler.drawio.svg (CC BY 4.0).

Default commands#

A default command runs whenever nothing else requires its subsystem. The drivetrain's joystick command from Lesson 10 is the classic example.

• When another command takes the subsystem, the default command is interrupted.
• When that command ends, the scheduler restarts the default command in step 6 of the same loop.
• A default command must require its own subsystem, and it shouldn't finish on its own. If it finishes, the scheduler just starts it again the next loop.

How triggers turn button presses into commands#

Triggers are checked every loop (step 2). The scheduler remembers whether each one was true last loop, so it can tell a press from a hold:

Triggers aren't only buttons. Any BooleanSupplier can be a trigger:

new Trigger(intake::hasGamePiece)
    .onTrue(leds.flashGreen().withTimeout(1.0));

Walk through it loop by loop#

Here's exactly what happens when a driver holds A, which is bound with driver.a().whileTrue(intake.runIntake()), while the intake has a default command that holds the rollers still.

The driver held the button for about 40 loops × 20 ms = 0.8 seconds.

Compositions and the scheduler#

When you combine commands, such as a.andThen(b), the scheduler sees one command: the composition. It requires every subsystem that a or b needs, for its whole run. That has two consequences that surprise people:

1. A sequence holds every subsystem, the whole time. In drive.andThen(shoot), the shooter is reserved even while the robot is still driving, so the shooter's default command won't run.
2. A command inside a composition belongs to it. You can't schedule it separately or put the same command object in two compositions. Build a fresh one each time, which is one reason factory methods that return a new command are the standard pattern.

Disabled mode#

When the robot is disabled, the scheduler still runs every loop, but it cancels running commands, and it won't start new ones unless they're marked .ignoringDisable(true). Use that for things that are safe when disabled, like LEDs or resetting a sensor.

Seeing the scheduler work#

On the dashboard. Add this to RobotContainer, then open Elastic and find Scheduler in the SmartDashboard table:

SmartDashboard.putData(CommandScheduler.getInstance());

In the console. The scheduler can call your code whenever a command starts, gets interrupted, or finishes:

CommandScheduler.getInstance().onCommandInitialize(
    cmd -> System.out.println("START  " + cmd.getName()));
CommandScheduler.getInstance().onCommandInterrupt(
    cmd -> System.out.println("CANCEL " + cmd.getName()));
CommandScheduler.getInstance().onCommandFinish(
    cmd -> System.out.println("DONE   " + cmd.getName()));

Give commands readable names with .withName("Intake").

Loop overruns. If the scheduler's turn takes longer than 20 ms, you'll see a loop overrun warning that lists how long each step took: each subsystem's periodic(), and each command's execute(). The slow one is your culprit, usually blocking code (Lesson 6) or slow logging.

Common scheduler bugs#

Try it#

• Add the three onCommand... print hooks and SmartDashboard.putData(CommandScheduler.getInstance())
• In simulation, press and hold your intake button. Match what prints to the loop-by-loop table above.
• Give the intake a default command that sets the motor to 0. Watch it get interrupted and come back.
• Change the intake binding from whileTrue to onTrue. What happens now when you release the button, and why?
• Write the SpinUpShooter command longhand, then rewrite it with runOnce, run, and .until(). Both should behave the same.
• Break it on purpose: make a command that sets the intake motor without requiring the intake, bind it to B, and press A and B together. Explain what you see.

Check yourself#