7. Command-Based Programming#

Why it matters#

Imagine writing a whole robot inside teleopPeriodic(): the drivetrain, the intake, the arm, the shooter, every button, every timer, every "only do this if that." It works for a week. Then it's 600 lines of tangled if statements where changing the intake breaks the arm.

Command-based programming organizes the robot into small, reusable pieces:

• Subsystems are the robot's parts (nouns).
• Commands are the things those parts do (verbs).
• Triggers decide when commands run.

Almost every competitive FRC team uses it, and it's what the WPILib template is built for.

Read this#

• What Is Command-Based Programming?
• Subsystems
• Commands
• Binding Commands to Triggers
• Structuring a Command-Based Robot Project

Walkthrough#

The mental model#

Only one command can use a subsystem at a time. The scheduler enforces this, so two commands can't fight over the same motor.

Subsystems are the robot's parts; commands are things the robot does with them. From the WPILib docs, What Is "Command-Based" Programming? (CC BY 4.0).

new Trigger(condition::get).onTrue(Commands.runOnce(() -> piston.set(DoubleSolenoid.Value.kForward)));

if (condition.get()) {
  if (!pressed) {
    piston.set(DoubleSolenoid.Value.kForward);
    pressed = true;
  }
} else {
  pressed = false;
}

What goes in a subsystem#

A subsystem owns hardware and offers actions. A good subsystem:

• creates its own motors and sensors as private fields, so nothing outside can touch them directly
• offers methods that read state, like hasGamePiece() or getAngle()
• offers command factories: methods that return commands, like runIntake()
• puts telemetry in its periodic() method, which runs every loop

A subsystem should not know about buttons or controllers. "Run the intake" belongs in the subsystem; "when A is pressed" belongs in RobotContainer. Keeping them apart means you can reuse the same intake command in teleop, in autonomous, and in a test.

Build an Intake subsystem#

Create src/main/java/frc/robot/subsystems/Intake.java:

package frc.robot.subsystems;

import edu.wpi.first.wpilibj.DigitalInput;
import edu.wpi.first.wpilibj.motorcontrol.PWMSparkMax;
import edu.wpi.first.wpilibj2.command.Command;
import edu.wpi.first.wpilibj2.command.SubsystemBase;
import frc.robot.telemetry.Telemetry;
import frc.robot.telemetry.TelemetryTable;

public class Intake extends SubsystemBase {
    private final PWMSparkMax motor = new PWMSparkMax(0);
    private final DigitalInput beamBreak = new DigitalInput(0);
    private final TelemetryTable telemetry = Telemetry.getTable("Intake");   // Lesson 6.1

    /** True when a game piece is blocking the beam break sensor. */
    public boolean hasGamePiece() {
        return !beamBreak.get();   // many beam breaks read false when blocked
    }

    /** Runs the rollers in. Stops them when the command ends. */
    public Command runIntake() {
        return startEnd(
            () -> motor.set(0.75),   // when it starts
            () -> motor.set(0.0)     // when it ends
        ).withName("Intake");
    }

    /** Spits a game piece out. */
    public Command outtake() {
        return startEnd(() -> motor.set(-0.5), () -> motor.set(0.0)).withName("Outtake");
    }

    /** Intakes until a game piece is detected, then stops on its own. */
    public Command intakeUntilFull() {
        return runIntake().until(this::hasGamePiece).withName("Intake Until Full");
    }

    @Override
    public void periodic() {
        telemetry.log("Has Piece", hasGamePiece());
        telemetry.log("Output", motor.get());
    }
}

Command factories#

The methods startEnd, run, and others come from SubsystemBase. Each one builds a command that automatically requires this subsystem:

Commands that don't end by themselves keep going until a button is released, another command takes over the subsystem, or you add an end condition.

Changing how a command ends#

Chain these onto any command:

The Commands helpers#

The Commands class has factories for commands that don't belong to one subsystem:

import edu.wpi.first.wpilibj2.command.Commands;

Commands.none()                  // does nothing (useful as a placeholder)
Commands.waitSeconds(1.0)        // waits one second
Commands.print("Got here")       // prints a message
Commands.runOnce(() -> System.out.println("hi"))

Binding commands to buttons#

All bindings go in RobotContainer.java, in configureBindings():

public class RobotContainer {
    private final Intake intake = new Intake();
    private final CommandXboxController driver = new CommandXboxController(0);

    public RobotContainer() {
        configureBindings();
    }

    private void configureBindings() {
        driver.a().whileTrue(intake.runIntake());
        driver.b().whileTrue(intake.outtake());
        driver.x().onTrue(intake.intakeUntilFull());
    }
}

Read them out loud: "While driver A is held, run the intake." "When X is pressed, intake until full." Good command-based code reads like English.

Use whileTrue with commands that never end on their own, like runIntake(), so the driver controls how long they run. Use onTrue with commands that do end, like intakeUntilFull().

Controller buttons#

CommandXboxController gives you a trigger for every button:

Combining triggers#

Triggers can be combined, and any true/false check can be a trigger:

// Only while both are held
driver.a().and(driver.rightBumper()).whileTrue(intake.runIntake());

// Automatically, whenever a game piece arrives
new Trigger(intake::hasGamePiece).onTrue(Commands.print("Got one!"));

Longhand command classes#

Factories cover most commands. For a command with more logic, you can write a full class in the commands/ folder. It has four methods the scheduler calls for you:

public class RunIntake extends Command {
    private final Intake intake;

    public RunIntake(Intake intake) {
        this.intake = intake;
        addRequirements(intake);   // "this command uses the intake"
    }

    @Override public void initialize() { /* once, at the start */ }
    @Override public void execute()    { /* every loop */ }
    @Override public boolean isFinished() { return false; }   // checked every loop
    @Override public void end(boolean interrupted) { /* once, at the end */ }
}

Lesson 7.1 explains exactly when each of these runs.

Try it#

• Build the Intake subsystem above in your project
• Bind A to runIntake() and B to outtake() with whileTrue
• Run in Sim GUI. Drag your keyboard or a controller into Joystick 0 and watch PWM[0] change as you press buttons.
• Bind X to intakeUntilFull() with onTrue. In the Sim GUI, toggle DIO[0] to fake a game piece arriving and watch the command end.
• Change A's binding to onTrue(intake.runIntake()). What happens when you release A? Change it back.
• Add an outtake().withTimeout(0.5) binding on Y, so one tap spits a piece out for half a second

Check yourself#