Inheritance diagram for org.wpilib.command3.Command:

Public Member Functions
void	run (Coroutine coroutine)
default void	onCancel ()
default void	onExit ()
String	name ()
Set< Mechanism >	requirements ()
default int	priority ()
default boolean	isLowerPriorityThan (Command other)
default boolean	requires (Mechanism mechanism)
default boolean	conflictsWith (Command other)
default Command	withTimeout (Time timeout)
default ParallelGroupBuilder	until (BooleanSupplier endCondition)
default SequentialGroupBuilder	andThen (Command next)
default ParallelGroupBuilder	alongWith (Command... parallel)
default ParallelGroupBuilder	raceWith (Command... parallel)

Static Public Member Functions
static NeedsNameBuilderStage	noRequirements (Consumer< Coroutine > body)
static NeedsExecutionBuilderStage	requiring (Mechanism requirement, Mechanism... rest)
static NeedsExecutionBuilderStage	requiring (Collection< Mechanism > requirements)
static ParallelGroupBuilder	parallel (Command... commands)
static ParallelGroupBuilder	race (Command... commands)
static SequentialGroupBuilder	sequence (Command... commands)
static NeedsNameBuilderStage	waitUntil (BooleanSupplier condition)
static NeedsNameBuilderStage	waitFor (Time duration)

Public Attributes
int	DEFAULT_PRIORITY = 0
int	LOWEST_PRIORITY = Integer.MIN_VALUE
int	HIGHEST_PRIORITY = Integer.MAX_VALUE

Detailed Description

Performs some task using one or more mechanisms. Commands are fundamentally backed by a Coroutine that can be used to write imperative code that runs asynchronously.

Programmers familiar with the earlier versions of the command framework can think of a v3 command similar to a v1 or v2 command that executes the lifecycle methods in a single method, as demonstrated in the example below. (Note, however, that more sophisticated code than this is possible!



coroutine -> {

  initialize();

  while (!isFinished()) {

    execute();

    coroutine.yield(); // be sure to yield at the end of the loop

  }

  end();

}

Note: Because coroutines are opt-in collaborate constructs, every command implementation must call Coroutine#yield() within any periodic loop. Failure to do so may result in an unrecoverable infinite loop.

Requirements

Commands require zero or more mechanisms. To prevent conflicting control requests from running simultaneously (for example, commanding an elevator to both raise and lower at the same time), a running command has exclusive ownership of all of its required mechanisms. If another command with an equal or greater priority() is scheduled that requires one or more of those same mechanisms, it will interrupt and cancel the running command.

The recommended way to create a command is using Mechanism#run(Consumer) or a related factory method to create commands that require a single mechanism (for example, a command that drives an elevator up and down or rotates an arm). Commands may be composed into parallel groups and sequences to build more complex behavior out of fundamental building blocks. These built-in compositions will require every mechanism used by every command in them, even if those commands aren't always running, and thus can leave certain required mechanisms in an uncommanded state: owned, but not used, this can lead to mechanisms sagging under gravity or running the previous motor control request they were given.

Advanced Usage

For example, a hypothetical drive-and-score sequence could be coded in two ways: one with a sequence chain, or one that uses the lower-level coroutine API. Coroutines can be used in an async/await style that you may be familiar with from languages like JavaScript, Python, or C# (note that there is no async keyword; commands are inherently asynchronous). Nested commands may be forked and awaited, but will not outlive the command that forked them; there is no analog for something like a ScheduleCommand from the v2 commands framework.



class Robot extends TimedRobot {

  private final Drivetrain drivetrain = new Drivetrain();

  private final Elevator elevator = new Elevator();

  private final Gripper gripper = new Gripper();



 // Basic sequence builder - owns all 3 mechanisms for the full duration,

 // even when they're not being used

 private Command basicScoringSequence() {

    return drivetrain.driveToScoringLocation()

      .andThen(elevator.moveToScoringHeight())

      .andThen(gripper.release())

      .named("Scoring Sequence (Basic)");

  }



  // Advanced sequence with async/await - only owns mechanisms while they're

  // being used, allowing default commands or other user-triggered commands

  // to run when not in use. Interrupting one of the inner commands while it's

  // running will cancel the entire sequence.

  private Command advancedScoringSequence() {

    return Command.noRequirements(coroutine -> {

      coroutine.await(drivetrain.driveToScoringLocation());

      coroutine.await(elevator.moveToScoringHeight());

      coroutine.await(gripper.release());

    }).named("Scoring Sequence (Advanced)");

  }

}

Definition at line 98 of file Command.java.

Member Function Documentation

◆ alongWith()

default ParallelGroupBuilder org.wpilib.command3.Command.alongWith ( Command... parallel )

Creates a parallel command group, running this command alongside one or more other commands. The group will exit once every command has finished.

More configuration options are needed after calling this function before the command can be created. See ParallelGroupBuilder for details.



ParallelGroup abc =

  commandA()

    .alongWith(commandB(), commandC())

    .withAutomaticName();

Parameters

parallel The commands to run in parallel with this one

Returns: A parallel group builder

Definition at line 411 of file Command.java.

◆ andThen()

default SequentialGroupBuilder org.wpilib.command3.Command.andThen ( Command next )

Creates a command sequence, starting from this command and then running the next one. More commands can be added with the builder before naming and creating the sequence.



Sequence aThenBThenC =

  commandA()

    .andThen(commandB())

    .andThen(commandC())

    .withAutomaticName();

Parameters

next	The command to run after this one in the sequence

Returns: A sequence builder

Definition at line 389 of file Command.java.

◆ conflictsWith()

default boolean org.wpilib.command3.Command.conflictsWith ( Command other )

Checks if this command conflicts with another command.

Parameters

other the commands to check against

Returns: true if both commands require at least one of the same mechanism, false if both commands have completely different requirements

Definition at line 210 of file Command.java.

◆ isLowerPriorityThan()

default boolean org.wpilib.command3.Command.isLowerPriorityThan ( Command other )

Checks if this command has a lower priority than another command.

Parameters

other the command to compare with

Returns: true if this command has a lower priority than the other one, false otherwise

Definition at line 185 of file Command.java.

◆ name()

String org.wpilib.command3.Command.name ( )

The name of the command.

Returns: the name of the command

Implemented in org.wpilib.command3.ParallelGroup, org.wpilib.command3.SequentialGroup, and org.wpilib.command3.StateMachine.

◆ noRequirements()

NeedsNameBuilderStage org.wpilib.command3.Command.noRequirements ( Consumer< Coroutine > body )

static

Creates a command that does not require any hardware; that is, it does not affect the state of any physical objects. This is useful for commands that do some cleanup or state management, such as resetting odometry or sensors, that you don't want to interrupt a command that's controlling the mechanisms it affects, or for a command composition that you don't want to inherit the requirements of its child commands.

More configuration options are needed after calling this function before the command can be created. See StagedCommandBuilder for details.

Parameters

body	The command's body. Cannot be null.

Returns: a builder that can be used to configure the resulting command

Definition at line 248 of file Command.java.

◆ onCancel()

default void org.wpilib.command3.Command.onCancel ( )

An optional lifecycle hook that can be implemented to execute some code whenever this command is canceled before it naturally completes. Commands should be careful to do a single-shot cleanup (for example, setting a motor to zero volts) and not do any complex looping logic here.

Definition at line 132 of file Command.java.

◆ onExit()

default void org.wpilib.command3.Command.onExit ( )

An optional lifecycle hook that can be implemented to execute some code whenever this command exits, regardless of exit condition (natural completion, cancellation, or interruption). Commands should be careful to do a single-shot cleanup (for example, setting a motor to zero volts) and not do any complex looping logic here.

Definition at line 142 of file Command.java.

◆ parallel()

ParallelGroupBuilder org.wpilib.command3.Command.parallel ( Command... commands )

static

Starts creating a command that runs a group of multiple commands in parallel. The command will complete when every command in the group has completed naturally.

More configuration options are needed after calling this function before the command can be created. See ParallelGroupBuilder for details.

Parameters

commands The commands to run in parallel

Returns: A command builder

Definition at line 291 of file Command.java.

◆ priority()

default int org.wpilib.command3.Command.priority ( )

The priority of the command. If a command is scheduled that conflicts with another running or pending command, their priority values are compared to determine which should run. If the scheduled command is lower priority than the running command, then it will not be scheduled and the running command will continue to run. If it is the same or higher priority, then the running command will be canceled and the scheduled command will start to run.

Returns: the priority of the command

Implemented in org.wpilib.command3.ParallelGroup, org.wpilib.command3.SequentialGroup, and org.wpilib.command3.StateMachine.

Definition at line 174 of file Command.java.

◆ race()

ParallelGroupBuilder org.wpilib.command3.Command.race ( Command... commands )

static

Starts creating a command that runs a group of multiple commands in parallel. The command will complete when any command in the group has completed naturally; all other commands in the group will be canceled.

More configuration options are needed after calling this function before the command can be created. See ParallelGroupBuilder for details.

Parameters

commands The commands to run in parallel

Returns: A command builder

Definition at line 307 of file Command.java.

◆ raceWith()

default ParallelGroupBuilder org.wpilib.command3.Command.raceWith ( Command... parallel )

Creates a parallel command group, running this command alongside one or more other commands. The group will exit after any command finishes.

More configuration options are needed after calling this function before the command can be created. See ParallelGroupBuilder for details.

Parameters

parallel The commands to run in parallel with this one

Returns: A parallel group builder

Definition at line 425 of file Command.java.

◆ requirements()

Set< Mechanism > org.wpilib.command3.Command.requirements ( )

The mechanisms required by the command. This is used by the scheduler to determine if two commands conflict with each other. No mechanism may be required by more than one running command at a time.

Returns: the set of mechanisms required by the command

Implemented in org.wpilib.command3.ParallelGroup, org.wpilib.command3.SequentialGroup, and org.wpilib.command3.StateMachine.

◆ requires()

default boolean org.wpilib.command3.Command.requires ( Mechanism mechanism )

Checks if this command requires a particular mechanism.

Parameters

mechanism the mechanism to check

Returns: true if the mechanism is required, false if not

Definition at line 198 of file Command.java.

◆ requiring() [1/2]

NeedsExecutionBuilderStage org.wpilib.command3.Command.requiring ( Collection< Mechanism > requirements )

static

Creates command that requires some number of mechanisms.

More configuration options are needed after calling this function before the command can be created. See StagedCommandBuilder for details.

Parameters

requirements The required mechanisms. May be empty, but cannot contain null values.

Returns: A command builder

Definition at line 276 of file Command.java.

◆ requiring() [2/2]

NeedsExecutionBuilderStage org.wpilib.command3.Command.requiring	(	Mechanism	requirement,
		Mechanism...	rest )

static

Creates a command that requires one or more mechanisms.

More configuration options are needed after calling this function before the command can be created. See StagedCommandBuilder for details.

Parameters

requirement	The first required mechanism
rest	Any other required mechanisms

Returns: A command builder

Definition at line 262 of file Command.java.

◆ run()

void org.wpilib.command3.Command.run ( Coroutine coroutine )

Runs the command. Commands that need to periodically run until a goal state is reached should simply run a while loop like while (!atGoal()) { ... } and call Coroutine#yield() at the end of the loop.

Warning: any loops in a command must call coroutine.yield(). Failure to do so will prevent anything else in your robot code from running. Commands are opt-in collaborative constructs; don't be greedy!

Parameters

coroutine the coroutine backing the command's execution

Implemented in org.wpilib.command3.ParallelGroup, org.wpilib.command3.SequentialGroup, and org.wpilib.command3.StateMachine.

◆ sequence()

SequentialGroupBuilder org.wpilib.command3.Command.sequence ( Command... commands )

static

Starts creating a command that runs a group of multiple commands in sequence. The command will complete when the last command in the group has completed naturally. Commands in the group will run in the order they're passed to this method.

More configuration options are needed after calling this function before the command can be created. See SequentialGroupBuilder for details.

Parameters

commands The commands to run in sequence.

Returns: A command builder

Definition at line 323 of file Command.java.

◆ until()

default ParallelGroupBuilder org.wpilib.command3.Command.until ( BooleanSupplier endCondition )

Creates a command that runs this one and ends when the end condition is met (if this command has not already exited by then).

More configuration options are needed after calling this function before the command can be created. See ParallelGroupBuilder for details.

Parameters

endCondition The end condition to wait for.

Returns: The waiting command

Definition at line 367 of file Command.java.

◆ waitFor()

NeedsNameBuilderStage org.wpilib.command3.Command.waitFor ( Time duration )

static

Creates a command that simply waits for a given duration. The command will not require any mechanisms.

Parameters

duration How long to wait

Returns: A command builder

Definition at line 351 of file Command.java.

◆ waitUntil()

NeedsNameBuilderStage org.wpilib.command3.Command.waitUntil ( BooleanSupplier condition )

static

Starts creating a command that simply waits for some condition to be met. The command will not require any mechanisms.

More configuration options are needed after calling this function before the command can be created. See StagedCommandBuilder for details.

Parameters

condition The condition to wait for

Returns: A command builder

Definition at line 338 of file Command.java.

◆ withTimeout()

default Command org.wpilib.command3.Command.withTimeout ( Time timeout )

Creates a new command that runs this one for a maximum duration, after which it is forcibly canceled. This is particularly useful for autonomous routines where you want to prevent your entire autonomous period spent stuck on a single action because a mechanism doesn't quite reach its setpoint (for example, spinning up a flywheel or driving to a particular location on the field). The resulting command will have the same name as this one, with the timeout period appended.

Parameters

timeout the maximum duration that the command is permitted to run. Negative or zero values will result in the command running only once before being canceled.

Returns: the timed out command.

Definition at line 228 of file Command.java.

Member Data Documentation

◆ DEFAULT_PRIORITY

int org.wpilib.command3.Command.DEFAULT_PRIORITY = 0

The default command priority.

Definition at line 100 of file Command.java.

◆ HIGHEST_PRIORITY

int org.wpilib.command3.Command.HIGHEST_PRIORITY = Integer.MAX_VALUE

The highest possible command priority. Commands with the highest priority can only be interrupted by other maximum-priority commands.

Definition at line 112 of file Command.java.

◆ LOWEST_PRIORITY

int org.wpilib.command3.Command.LOWEST_PRIORITY = Integer.MIN_VALUE

The lowest possible command priority. Commands with the lowest priority can be interrupted by any other command, including other minimum-priority commands.

Definition at line 106 of file Command.java.

The documentation for this interface was generated from the following file:

org/wpilib/command3/Command.java

Public Member Functions

Static Public Member Functions

Public Attributes

Detailed Description

Requirements

Advanced Usage

Member Function Documentation

◆ alongWith()

◆ andThen()

◆ conflictsWith()

◆ isLowerPriorityThan()

◆ name()

◆ noRequirements()

◆ onCancel()

◆ onExit()

◆ parallel()

◆ priority()

◆ race()

◆ raceWith()

◆ requirements()

◆ requires()

◆ requiring() [1/2]

◆ requiring() [2/2]

◆ run()

◆ sequence()

◆ until()

◆ waitFor()

◆ waitUntil()

◆ withTimeout()

Member Data Documentation

◆ DEFAULT_PRIORITY

◆ HIGHEST_PRIORITY

◆ LOWEST_PRIORITY