Command
- class commands2.Command[source]
Bases:
Sendable
A state machine representing a complete action to be performed by the robot. Commands are run by the
commands2.CommandScheduler
, and can be composed into CommandGroups to allow users to build complicated multistep actions without the need to roll the state machine logic themselves.Commands are run synchronously from the main robot loop; no multithreading is used, unless specified explicitly from the command implementation.
- class InterruptionBehavior(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)
Bases:
Enum
An enum describing the command’s behavior when another command with a shared requirement is scheduled.
- kCancelIncoming = 0
This command ends,
commands2.Command.end()
is called, and the incoming command is scheduled normally.This is the default behavior.
- kCancelSelf = 1
This command continues, and the incoming command is not scheduled.
- addRequirements(*requirements: Subsystem)[source]
Adds the specified subsystems to the requirements of the command. The scheduler will prevent two commands that require the same subsystem from being scheduled simultaneously.
Note
The scheduler determines the requirements of a command when it is scheduled, so this method should normally be called from the command’s constructor.
- Parameters:
requirements – the requirements to add
- alongWith(*parallel: Command) ParallelCommandGroup [source]
Decorates this command with a set of commands to run parallel to it, ending when the last command ends. Often more convenient/less-verbose than constructing a new {@link ParallelCommandGroup} explicitly.
Note
This decorator works by adding this command to a composition. The command the decorator was called on cannot be scheduled independently or be added to a different composition (namely, decorators), unless it is manually cleared from the list of composed commands with
commands2.CommandScheduler.removeComposedCommand()
. The command composition returned from this method can be further decorated without issue.- Parameters:
parallel – the commands to run in parallel
- Returns:
the decorated command
- andThen(*next: Command) SequentialCommandGroup [source]
Decorates this command with a set of commands to run after it in sequence. Often more convenient/less-verbose than constructing a new SequentialCommandGroup explicitly.
Note
This decorator works by adding this command to a composition. The command the decorator was called on cannot be scheduled independently or be added to a different composition (namely, decorators), unless it is manually cleared from the list of composed commands with
commands2.CommandScheduler.removeComposedCommand()
. The command composition returned from this method can be further decorated without issue.- Parameters:
next – the commands to run next
- Returns:
the decorated command
- asProxy() ProxyCommand [source]
Decorates this command to run “by proxy” by wrapping it in a ProxyCommand. Use this for “forking off” from command compositions when the user does not wish to extend the command’s requirements to the entire command composition. ProxyCommand has unique implications and semantics, see the WPILib docs for a full explanation.
- Returns:
the decorated command
- beforeStarting(before: Command | Callable[[], None]) SequentialCommandGroup [source]
Decorates this command with a callable or command to run before this command starts.
Note
This decorator works by adding this command to a composition. The command the decorator was called on cannot be scheduled independently or be added to a different composition (namely, decorators), unless it is manually cleared from the list of composed commands with
commands2.CommandScheduler.removeComposedCommand()
. The command composition returned from this method can be further decorated without issue.- Parameters:
before – the command to run before this one
- Returns:
the decorated command
- cancel() None [source]
Cancels this command. Will call
end(true)
. Commands will be canceled regardless of InterruptionBehavior interruption behavior.
- deadlineFor(*parallel: Command) ParallelDeadlineGroup [source]
Decorates this command with a set of commands to run parallel to it, ending when the calling command ends and interrupting all the others. Often more convenient/less-verbose than constructing a new ParallelDeadlineGroup explicitly.
Note
This decorator works by adding this command to a composition. The command the decorator was called on cannot be scheduled independently or be added to a different composition (namely, decorators), unless it is manually cleared from the list of composed commands with
commands2.CommandScheduler.removeComposedCommand()
. The command composition returned from this method can be further decorated without issue.- Parameters:
parallel – the commands to run in parallel
- Returns:
the decorated command
- deadlineWith(*parallel: Command) ParallelDeadlineGroup [source]
Decorates this command with a set of commands to run parallel to it, ending when the calling command ends and interrupting all the others. Often more convenient/less-verbose than constructing a new ParallelDeadlineGroup explicitly.
Note
This decorator works by adding this command to a composition. The command the decorator was called on cannot be scheduled independently or be added to a different composition (namely, decorators), unless it is manually cleared from the list of composed commands with
commands2.CommandScheduler.removeComposedCommand()
. The command composition returned from this method can be further decorated without issue.- Parameters:
parallel – the commands to run in parallel
- Returns:
the decorated command
- end(interrupted: bool)[source]
The action to take when the command ends. Called when either the command finishes normally, or when it interrupted/canceled.
Do not schedule commands here that share requirements with this command. Use
andThen()
instead.- Parameters:
interrupted – whether the command was interrupted/canceled
- finallyDo(end: Callable[[bool], Any]) WrapperCommand [source]
Decorates this command with a lambda to call on interrupt or end, following the command’s inherent
commands2.Command.end()
method.- Parameters:
end – a lambda accepting a boolean parameter specifying whether the command was interrupted.
- Returns:
the decorated command
- getInterruptionBehavior() InterruptionBehavior [source]
How the command behaves when another command with a shared requirement is scheduled.
- Returns:
a variant of InterruptionBehavior, defaulting to {@link InterruptionBehavior#kCancelSelf kCancelSelf}.
- getRequirements() Set[Subsystem] [source]
Specifies the set of subsystems used by this command. Two commands cannot use the same subsystem at the same time. If another command is scheduled that shares a requirement,
getInterruptionBehavior()
will be checked and followed. If no subsystems are required, return an empty set.Note
it is recommended that user implementations contain the requirements as a field, and return that field here, rather than allocating a new set every time this is called.
- Returns:
the set of subsystems that are required
- handleInterrupt(handler: Callable[[], Any]) WrapperCommand [source]
Decorates this command with a lambda to call on interrupt, following the command’s inherent
commands2.Command.end()
method.- Parameters:
handler – a lambda to run when the command is interrupted
- Returns:
the decorated command
- hasRequirement(requirement: Subsystem) bool [source]
Whether the command requires a given subsystem.
- Parameters:
requirement – the subsystem to inquire about
- Returns:
whether the subsystem is required
- ignoringDisable(doesRunWhenDisabled: bool) WrapperCommand [source]
Decorates this command to run or stop when disabled.
- Parameters:
doesRunWhenDisabled – true to run when disabled.
- Returns:
the decorated command
- initSendable(builder: wpiutil._wpiutil.SendableBuilder) None [source]
Initializes this Sendable object.
- Parameters:
builder – sendable builder
- initialize()[source]
The initial subroutine of a command. Called once when the command is initially scheduled.
- isFinished() bool [source]
Whether the command has finished. Once a command finishes, the scheduler will call its
commands2.Command.end()
method and un-schedule it.- Returns:
whether the command has finished.
- isScheduled() bool [source]
Whether the command is currently scheduled. Note that this does not detect whether the command is in a composition, only whether it is directly being run by the scheduler.
- Returns:
Whether the command is scheduled.
- onlyIf(condition: Callable[[], bool]) ConditionalCommand [source]
Decorates this command to only run if this condition is met. If the command is already running and the condition changes to false, the command will not stop running. The requirements of this command will be kept for the new conditional command.
Note
This decorator works by adding this command to a composition. The command the decorator was called on cannot be scheduled independently or be added to a different composition (namely, decorators), unless it is manually cleared from the list of composed commands with
commands2.CommandScheduler.removeComposedCommand()
. The command composition returned from this method can be further decorated without issue.- Parameters:
condition – the condition that will allow the command to run
- Returns:
the decorated command
- onlyWhile(condition: Callable[[], bool]) ParallelRaceGroup [source]
Decorates this command with a run condition. If the specified condition becomes false before the command finishes normally, the command will be interrupted and un-scheduled.
Note
This decorator works by adding this command to a composition. The command the decorator was called on cannot be scheduled independently or be added to a different composition (namely, decorators), unless it is manually cleared from the list of composed commands with
commands2.CommandScheduler.removeComposedCommand()
. The command composition returned from this method can be further decorated without issue.- Parameters:
condition – the interrupt condition
- Returns:
the command with the interrupt condition added
- raceWith(*parallel: Command) ParallelRaceGroup [source]
Decorates this command with a set of commands to run parallel to it, ending when the first command ends. Often more convenient/less-verbose than constructing a new {@link ParallelRaceGroup} explicitly.
Note
This decorator works by adding this command to a composition. The command the decorator was called on cannot be scheduled independently or be added to a different composition (namely, decorators), unless it is manually cleared from the list of composed commands with
commands2.CommandScheduler.removeComposedCommand()
. The command composition returned from this method can be further decorated without issue.- Parameters:
parallel – the commands to run in parallel
- Returns:
the decorated command
- repeatedly() RepeatCommand [source]
Decorates this command to run repeatedly, restarting it when it ends, until this command is interrupted. The decorated command can still be canceled.
Note
This decorator works by adding this command to a composition. The command the decorator was called on cannot be scheduled independently or be added to a different composition (namely, decorators), unless it is manually cleared from the list of composed commands with
commands2.CommandScheduler.removeComposedCommand()
. The command composition returned from this method can be further decorated without issue.- Returns:
the decorated command
- runsWhenDisabled() bool [source]
Whether the given command should run when the robot is disabled. Override to return true if the command should run when disabled.
- Returns:
whether the command should run when the robot is disabled
- setSubsystem(subsystem: str)[source]
Sets the subsystem name of this Subsystem.
- Parameters:
subsystem – subsystem name
- unless(condition: Callable[[], bool]) ConditionalCommand [source]
Decorates this command to only run if this condition is not met. If the command is already running and the condition changes to true, the command will not stop running. The requirements of this command will be kept for the new conditional command.
Note
This decorator works by adding this command to a composition. The command the decorator was called on cannot be scheduled independently or be added to a different composition (namely, decorators), unless it is manually cleared from the list of composed commands with
commands2.CommandScheduler.removeComposedCommand()
. The command composition returned from this method can be further decorated without issue.- Parameters:
condition – the condition that will prevent the command from running
- Returns:
the decorated command
- until(condition: Callable[[], bool]) ParallelRaceGroup [source]
Decorates this command with an interrupt condition. If the specified condition becomes true before the command finishes normally, the command will be interrupted and un-scheduled.
Note
This decorator works by adding this command to a composition. The command the decorator was called on cannot be scheduled independently or be added to a different composition (namely, decorators), unless it is manually cleared from the list of composed commands with
commands2.CommandScheduler.removeComposedCommand()
. The command composition returned from this method can be further decorated without issue.- Parameters:
condition – the interrupt condition
- Returns:
the command with the interrupt condition added
- withInterruptBehavior(behavior: InterruptionBehavior) WrapperCommand [source]
Decorates this command to have a different InterruptionBehavior interruption behavior.
- Parameters:
interruptBehavior – the desired interrupt behavior
- Returns:
the decorated command
- withName(name: str) WrapperCommand [source]
Decorates this command with a name.
- Parameters:
name – the name of the command
- Returns:
the decorated command
- withTimeout(seconds: float) ParallelRaceGroup [source]
Decorates this command with a timeout. If the specified timeout is exceeded before the command finishes normally, the command will be interrupted and un-scheduled. Note that the timeout only applies to the command returned by this method; the calling command is not itself changed.
Note
This decorator works by adding this command to a composition. The command the decorator was called on cannot be scheduled independently or be added to a different composition (namely, decorators), unless it is manually cleared from the list of composed commands with
commands2.CommandScheduler.removeComposedCommand()
. The command composition returned from this method can be further decorated without issue.- Parameters:
seconds – the timeout duration
- Returns:
the command with the timeout added