Command

class commands2.Command

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)

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

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

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

Decorates this command to run “by proxy” by wrapping it in a ProxyCommand. This is useful for “forking off” from command compositions when the user does not wish to extend the command’s requirements to the entire command composition.

Returns:

the decorated command

beforeStarting(before: Command | Callable[[], None]) → SequentialCommandGroup

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

Cancels this command. Will call end(true). Commands will be canceled regardless of InterruptionBehavior interruption behavior.

deadlineWith(*parallel: Command) → ParallelDeadlineGroup

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)

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

execute()

The main body of a command. Called repeatedly while the command is scheduled.

finallyDo(end: Callable[[bool], Any]) → WrapperCommand

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

How the command behaves when another command with a shared requirement is scheduled.

Returns:

a variant of InterruptionBehavior, defaulting to {@link InterruptionBehavior#kCancelSelf kCancelSelf}.

getName() → str

Gets the name of this Command.

Returns:

Name

getRequirements() → Set[Subsystem]

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

getSubsystem() → str

Gets the subsystem name of this Subsystem.

Returns:

Subsystem name

handleInterrupt(handler: Callable[[], Any]) → WrapperCommand

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

Whether the command requires a given subsystem.

Parameters:

requirement – the subsystem to inquire about

Returns:

whether the subsystem is required

ignoringDisable(doesRunWhenDisabled: bool) → WrapperCommand

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

Initializes this Sendable object.

Parameters:

builder – sendable builder

initialize()

The initial subroutine of a command. Called once when the command is initially scheduled.

isFinished() → bool

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

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

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

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

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

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

requirements: Set[Subsystem]

runsWhenDisabled() → bool

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

schedule() → None

Schedules this command.

setName(name: str)

Sets the name of this Command.

Parameters:

name – Name

setSubsystem(subsystem: str)

Sets the subsystem name of this Subsystem.

Parameters:

subsystem – subsystem name

unless(condition: Callable[[], bool]) → ConditionalCommand

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

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

Decorates this command to have a different InterruptionBehavior interruption behavior.

Parameters:

interruptBehavior – the desired interrupt behavior

Returns:

the decorated command

withName(name: str) → WrapperCommand

Decorates this command with a name.

Parameters:

name – the name of the command

Returns:

the decorated command

withTimeout(seconds: float) → ParallelRaceGroup

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