Class Command
- java.lang.Object
-
- edu.wpi.first.wpilibj.command.Command
-
- All Implemented Interfaces:
Sendable
,AutoCloseable
- Direct Known Subclasses:
CommandGroup
,ConditionalCommand
,InstantCommand
,PIDCommand
,TimedCommand
,WaitForChildren
,WaitUntilCommand
public abstract class Command extends Object implements Sendable, AutoCloseable
The Command class is at the very core of the entire command framework. Every command can be started with a call tostart()
. Once a command is started it will callinitialize()
, and then will repeatedly callexecute()
until theisFinished()
returns true. Once it does,end()
will be called.However, if at any point while it is running
cancel()
is called, then the command will be stopped andinterrupted()
will be called.If a command uses a
Subsystem
, then it should specify that it does so by calling therequires(...)
method in its constructor. Note that a Command may have multiple requirements, andrequires(...)
should be called for each one.If a command is running and a new command with shared requirements is started, then one of two things will happen. If the active command is interruptible, then
cancel()
will be called and the command will be removed to make way for the new one. If the active command is not interruptible, the other one will not even be started, and the active one will continue functioning.- See Also:
Subsystem
,CommandGroup
,IllegalUseOfCommandException
-
-
Constructor Summary
Constructors Constructor Description Command()
Creates a new command.Command(double timeout)
Creates a new command with the given timeout and a default name.Command(double timeout, Subsystem subsystem)
Creates a new command with the given timeout and a default name.Command(Subsystem subsystem)
Creates a new command with the given timeout and a default name.Command(String name)
Creates a new command with the given name.Command(String name, double timeout)
Creates a new command with the given name and timeout.Command(String name, double timeout, Subsystem subsystem)
Creates a new command with the given name and timeout.Command(String name, Subsystem subsystem)
Creates a new command with the given name.
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description void
cancel()
This will cancel the current command.protected void
clearRequirements()
Clears list of subsystem requirements.void
close()
boolean
doesRequire(Subsystem system)
Checks if the command requires the givenSubsystem
.protected void
end()
Called when the command ended peacefully.protected void
execute()
The execute method is called repeatedly until this Command either finishes or is canceled.CommandGroup
getGroup()
Returns theCommandGroup
that this command is a part of.String
getName()
Gets the name of this Command.String
getSubsystem()
Gets the subsystem name of this Command.protected void
initialize()
The initialize method is called the first time this Command is run after being started.void
initSendable(SendableBuilder builder)
Initializes thisSendable
object.protected void
interrupted()
Called when the command ends because somebody calledcancel()
or another command shared the same requirements as this one, and booted it out.boolean
isCanceled()
Returns whether or not this has been canceled.boolean
isCompleted()
Whether or not this command has completed running.protected abstract boolean
isFinished()
Returns whether this command is finished.boolean
isInterruptible()
Returns whether or not this command can be interrupted.boolean
isRunning()
Returns whether or not the command is running.protected boolean
isTimedOut()
Returns whether or not thetimeSinceInitialized()
method returns a number which is greater than or equal to the timeout for the command.protected void
requires(Subsystem subsystem)
This method specifies that the givenSubsystem
is used by this command.protected void
setInterruptible(boolean interruptible)
Sets whether or not this command can be interrupted.void
setName(String name)
Sets the name of this Command.void
setRunWhenDisabled(boolean run)
Sets whether or not thisCommand
should run when the robot is disabled.void
setSubsystem(String subsystem)
Sets the subsystem name of this Command.protected void
setTimeout(double seconds)
Sets the timeout of this command.void
start()
Starts up the command.double
timeSinceInitialized()
Returns the time since this command was initialized (in seconds).String
toString()
The string representation for aCommand
is by default its name.boolean
willRunWhenDisabled()
Returns whether or not thisCommand
will run when the robot is disabled, or if it will cancel itself.
-
-
-
Constructor Detail
-
Command
public Command()
Creates a new command. The name of this command will be set to its class name.
-
Command
public Command(String name)
Creates a new command with the given name.- Parameters:
name
- the name for this command- Throws:
IllegalArgumentException
- if name is null
-
Command
public Command(double timeout)
Creates a new command with the given timeout and a default name. The default name is the name of the class.- Parameters:
timeout
- the time (in seconds) before this command "times out"- Throws:
IllegalArgumentException
- if given a negative timeout- See Also:
isTimedOut()
-
Command
public Command(Subsystem subsystem)
Creates a new command with the given timeout and a default name. The default name is the name of the class.- Parameters:
subsystem
- the subsystem that this command requires- Throws:
IllegalArgumentException
- if given a negative timeout- See Also:
isTimedOut()
-
Command
public Command(String name, Subsystem subsystem)
Creates a new command with the given name.- Parameters:
name
- the name for this commandsubsystem
- the subsystem that this command requires- Throws:
IllegalArgumentException
- if name is null
-
Command
public Command(double timeout, Subsystem subsystem)
Creates a new command with the given timeout and a default name. The default name is the name of the class.- Parameters:
timeout
- the time (in seconds) before this command "times out"subsystem
- the subsystem that this command requires- Throws:
IllegalArgumentException
- if given a negative timeout- See Also:
isTimedOut()
-
Command
public Command(String name, double timeout)
Creates a new command with the given name and timeout.- Parameters:
name
- the name of the commandtimeout
- the time (in seconds) before this command "times out"- Throws:
IllegalArgumentException
- if given a negative timeout or name was null.- See Also:
isTimedOut()
-
Command
public Command(String name, double timeout, Subsystem subsystem)
Creates a new command with the given name and timeout.- Parameters:
name
- the name of the commandtimeout
- the time (in seconds) before this command "times out"subsystem
- the subsystem that this command requires- Throws:
IllegalArgumentException
- if given a negative timeoutIllegalArgumentException
- if given a negative timeout or name was null.- See Also:
isTimedOut()
-
-
Method Detail
-
close
public void close()
- Specified by:
close
in interfaceAutoCloseable
-
setTimeout
protected final void setTimeout(double seconds)
Sets the timeout of this command.- Parameters:
seconds
- the timeout (in seconds)- Throws:
IllegalArgumentException
- if seconds is negative- See Also:
isTimedOut()
-
timeSinceInitialized
public final double timeSinceInitialized()
Returns the time since this command was initialized (in seconds). This function will work even if there is no specified timeout.- Returns:
- the time since this command was initialized (in seconds).
-
requires
protected void requires(Subsystem subsystem)
This method specifies that the givenSubsystem
is used by this command. This method is crucial to the functioning of the Command System in general.Note that the recommended way to call this method is in the constructor.
- Parameters:
subsystem
- theSubsystem
required- Throws:
IllegalArgumentException
- if subsystem is nullIllegalUseOfCommandException
- if this command has started before or if it has been given to aCommandGroup
- See Also:
Subsystem
-
initialize
protected void initialize()
The initialize method is called the first time this Command is run after being started.
-
execute
protected void execute()
The execute method is called repeatedly until this Command either finishes or is canceled.
-
isFinished
protected abstract boolean isFinished()
Returns whether this command is finished. If it is, then the command will be removed andend()
will be called.It may be useful for a team to reference the
isTimedOut()
method for time-sensitive commands.Returning false will result in the command never ending automatically. It may still be canceled manually or interrupted by another command. Returning true will result in the command executing once and finishing immediately. We recommend using
InstantCommand
for this.- Returns:
- whether this command is finished.
- See Also:
isTimedOut()
-
end
protected void end()
Called when the command ended peacefully. This is where you may want to wrap up loose ends, like shutting off a motor that was being used in the command.
-
interrupted
protected void interrupted()
Called when the command ends because somebody calledcancel()
or another command shared the same requirements as this one, and booted it out.This is where you may want to wrap up loose ends, like shutting off a motor that was being used in the command.
Generally, it is useful to simply call the
end()
method within this method, as done here.
-
isTimedOut
protected boolean isTimedOut()
Returns whether or not thetimeSinceInitialized()
method returns a number which is greater than or equal to the timeout for the command. If there is no timeout, this will always return false.- Returns:
- whether the time has expired
-
clearRequirements
protected void clearRequirements()
Clears list of subsystem requirements. This is only used byConditionalCommand
so canceling the chosen command works properly inCommandGroup
.
-
start
public void start()
Starts up the command. Gets the command ready to start.Note that the command will eventually start, however it will not necessarily do so immediately, and may in fact be canceled before initialize is even called.
- Throws:
IllegalUseOfCommandException
- if the command is a part of a CommandGroup
-
isRunning
public boolean isRunning()
Returns whether or not the command is running. This may return true even if the command has just been canceled, as it may not have yet calledinterrupted()
.- Returns:
- whether or not the command is running
-
cancel
public void cancel()
This will cancel the current command.This will cancel the current command eventually. It can be called multiple times. And it can be called when the command is not running. If the command is running though, then the command will be marked as canceled and eventually removed.
A command can not be canceled if it is a part of a command group, you must cancel the command group instead.
- Throws:
IllegalUseOfCommandException
- if this command is a part of a command group
-
isCanceled
public boolean isCanceled()
Returns whether or not this has been canceled.- Returns:
- whether or not this has been canceled
-
isCompleted
public boolean isCompleted()
Whether or not this command has completed running.- Returns:
- whether or not this command has completed running.
-
isInterruptible
public boolean isInterruptible()
Returns whether or not this command can be interrupted.- Returns:
- whether or not this command can be interrupted
-
setInterruptible
protected void setInterruptible(boolean interruptible)
Sets whether or not this command can be interrupted.- Parameters:
interruptible
- whether or not this command can be interrupted
-
doesRequire
public boolean doesRequire(Subsystem system)
Checks if the command requires the givenSubsystem
.- Parameters:
system
- the system- Returns:
- whether or not the subsystem is required, or false if given null
-
getGroup
public CommandGroup getGroup()
Returns theCommandGroup
that this command is a part of. Will return null if thisCommand
is not in a group.- Returns:
- the
CommandGroup
that this command is a part of (or null if not in group)
-
setRunWhenDisabled
public void setRunWhenDisabled(boolean run)
Sets whether or not thisCommand
should run when the robot is disabled.By default a command will not run when the robot is disabled, and will in fact be canceled.
- Parameters:
run
- whether or not this command should run when the robot is disabled
-
willRunWhenDisabled
public boolean willRunWhenDisabled()
Returns whether or not thisCommand
will run when the robot is disabled, or if it will cancel itself.- Returns:
- True if this command will run when the robot is disabled.
-
getSubsystem
public String getSubsystem()
Gets the subsystem name of this Command.- Returns:
- Subsystem name
-
setSubsystem
public void setSubsystem(String subsystem)
Sets the subsystem name of this Command.- Parameters:
subsystem
- subsystem name
-
initSendable
public void initSendable(SendableBuilder builder)
Description copied from interface:Sendable
Initializes thisSendable
object.- Specified by:
initSendable
in interfaceSendable
- Parameters:
builder
- sendable builder
-
-