WPILib Commands.md

Back to README

WPILib Commands

Command Structure

Commands have 4 methods:

• initialize is called once when the command starts
• execute is called every robot clock cycle until the command is finished.
• isFinished is called every cycle and should return true when the command is finished. The default for commands is to return false, that is, to run forever.
• done(boolean interrupted) is called when the command is finished. The interrupted parameter will be true if the command was canceled before it finished.

Command Behavior

Instances

Command instances cannot be shared between Command Groups and/or Scheduling Commands.

Running

Once a command is running, it will only stop if:

• The isFinished method returns true
  • This will cause done(false) to be called
• The cancel function is called on the command
  • This will cause done(true) to be called, regardless of the command's set InterruptionBehavior
  • Note: cancel is called when a Trigger's whileTrue method ends
• Another command is scheduled that uses one of the same requirements, and the currently running command's set InterruptionBehavior is kCancelSelf (default behavior)
  • This will cause done(true) to be called

Command Classes

Class	Description
Simple Commands
InstantCommand	Accepts a function that becomes the initialize method. (The "isFinished" method returns true.)
RunCommand	Accepts a function that becomes the execute method. (The "isFinished" method returns false.)
StartEndCommand	Accepts two functions that become the initialize and done methods. (The "isFinished" method returns false.)
FunctionalCommand	Accepts four functions that become the four Command methods.
Command Groups	(Note: If a command group is interrupted, not all of the commands in the group are guaranteed to complete.)
SequentialCommandGroup	Accepts multiple Commands and executes them in sequence.
ParallelCommandGroup	Accepts multiple Commands and executes them in parallel. The command group ends, when all commands in the group complete.
ParallelRaceGroup	Accepts multiple Commands and executes them in parallel, until any one of them finishes. At that time the others are interrupted.
ParallelDeadlineGroup	Accepts multiple Commands and executes them in parallel, until the first one in the list (the deadline) finishes. At that time the others are interrupted.
Scheduling Commands	These command schedule given commands. [Note: The scheduled command(s) do not inherit this scheduling command's requirement(s).]
DeferredCommand	Accepts a Command Supplier that it will call on initialize.
ConditionalCommand	Accepts two Commands and a boolean supplier to choose between them at runtime.
SelectCommand	Accepts a map of Commands and an supplier that provides the map key to the command to choose at runtime.
RepeatCommand	Accepts a Command that it will run and continuously restart, after it has ended, until the Repeat Command is interrupted.
ProxyCommand	Accepts a Command or a Command Supplier and schedules it.
ScheduleCommand	Accepts multiple Commands and schedules them separately from the current command, then ends immediately.
NamedCommands	NamedCommands is a PathPlanner class that will register Names with a unique name for use by Path Planner. See: https://pathplanner.dev/pplib-named-commands.html
Special Commands
PrintCommand	Is a special InstantCommand that accepts a message and prints it once when the command is scheduled.
WaitCommand	Waits until the specified number of seconds has elapsed.
WaitUntilCommand	Has two use cases: Wait until the Match Timer is >= given seconds Wait for a given BooleanSupplier to return true

Command Key Methods

These are some key methods that you can call on a command

Command Method	Description
#addRequirements	Adds the specified subsystems to the requirements of the command.
#cancel	Cancels this command, before it runs.
#isScheduled	Returns whether the command is currently scheduled.
#runsWhenDisabled	Returns whether the given command should run when the robot is disabled.
#setName	Sets the name of this Command.

Command Transformation Methods

These are actions that you can do on an existing command to turn into into a new command.

Command Method	Description	Equivalence
#alongWith	Creates a ParallelCommandGroup containing Command and the supplied commands.	ParallelCommandGroup
#andThen	Creates a SequentialCommandGroup that will run Command and then the provided Commands or function.	SequentialCommandGroup
#asProxy	Returns Command wrapped in a ProxyCommand.	ProxyCommand
#beforeStarting	Creates a SequentialCommandGroup that will run the provided Commands or function and then Command.	SequentialCommandGroup
#deadlineWith	Creates a ParallelDeadlineCommandGroup containing Command and the supplied commands, where Command is the deadline.	ParallelDeadlineGroup
#finallyDo	Returns a version of Command that runs the provided function when the command ends. The function will receive a boolean interrupted parameter, like the end method.	WrapperCommand
#handleInterrupt	Returns a version of this command that will call the provided function when the command is interrupted.	WrapperCommand
#ignoringDisable	Returns a version of this command that will run or stop even when when disabled.	WrapperCommand
#onlyIf	Returns a version of Command that will only run if provided boolean supplier returns true.	ConditionalCommand
#onlyWhile	Creates a ParallelRaceCommandGroup containing Command and the supplied commands.	ParallelRaceGroup
#raceWith	Decorates this command with a set of commands to run parallel to it, ending when the first command ends.	ParallelRaceGroup
#repeatedly	Returns a version of Command that will be run repeatedly, forever.	RepeatCommand
#unless	Returns a version of Command that will not run if provided boolean supplier returns true.	ConditionalCommand
#until	Returns a version of Command that is interrupted when the boolean supplier returns true.	ParallelRaceGroup
#withInterruptBehavior	Returns a version of Command with the specified interruption behavior. (Call with kCancelIncoming to make command non-interruptible.)	WrapperCommand
#withName	Returns a version of this command with the new name.	WrapperCommand
#withTimeout	Decorates this command with a timeout.	ParallelRaceGroup

Commands Shortcut Methods

We generally don't use these; instead, instantiate one of the command classes directly, as this makes reading the code more clear and learning the command types easier.

Commands Method	Preferred Equivalence
deadline	ParallelDeadlineGroup
defer	DeferredCommand
deferredProxy	ProxyCommand
either	ConditionalCommand
idle	RunCommand
none	RunCommand
parallel	ParallelCommandGroup
print	PrintCommand
race	ParallelRaceGroup
repeatingSequence	SequentialCommandGroup.repeatedly()
run	RunCommand
runEnd	FunctionalCommand
runOnce	RunCommand
select	SelectCommand
sequence	SequentialCommandGroup
startEnd	StartEndCommand
waitSeconds	WaitCommand
waitUntil​	WaitUntilCommand