"

2013 FRC Java API

"

edu.wpi.first.wpilibj.command
Class Command

java.lang.Object
  extended by edu.wpi.first.wpilibj.command.Command
All Implemented Interfaces:
NamedSendable, Sendable
Direct Known Subclasses:
CommandGroup, PIDCommand, PrintCommand, StartCommand, WaitCommand, WaitForChildren, WaitUntilCommand

public abstract class Command
extends Object
implements NamedSendable

The Command class is at the very core of the entire command framework. Every command can be started with a call to start(). Once a command is started it will call initialize(), and then will repeatedly call execute() until the isFinished() 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 and interrupted() will be called.

If a command uses a Subsystem, then it should specify that it does so by calling the requires(...) method in its constructor. Note that a Command may have multiple requirements, and requires(...) 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.

Author:
Brad Miller, Joe Grinstead
See Also:
Subsystem, CommandGroup, IllegalUseOfCommandException

Constructor Summary
Command()
          Creates a new command.
Command(double timeout)
          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.
 
Method Summary
 void cancel()
          This will cancel the current command.
 boolean doesRequire(Subsystem system)
          Checks if the command requires the given Subsystem.
protected abstract  void end()
          Called when the command ended peacefully.
protected abstract  void execute()
          The execute method is called repeatedly until this Command either finishes or is canceled.
 CommandGroup getGroup()
          Returns the CommandGroup that this command is a part of.
 String getName()
          Returns the name of this command.
 String getSmartDashboardType()
           
 ITable getTable()
          
protected abstract  void initialize()
          The initialize method is called the first time this Command is run after being started.
 void initTable(ITable table)
          Initializes a table for this sendable object.
protected abstract  void interrupted()
          Called when the command ends because somebody called cancel() or another command shared the same requirements as this one, and booted it out.
 boolean isCanceled()
          Returns whether or not this has been canceled.
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 the timeSinceInitialized() 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 given Subsystem is used by this command.
protected  void setInterruptible(boolean interruptible)
          Sets whether or not this command can be interrupted.
 void setRunWhenDisabled(boolean run)
          Sets whether or not this Command should run when the robot is disabled.
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 a Command is by default its name.
 boolean willRunWhenDisabled()
          Returns whether or not this Command will run when the robot is disabled, or if it will cancel itself.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

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(String name,
               double timeout)
Creates a new command with the given name and timeout.

Parameters:
name - the name of the command
timeout - the time (in seconds) before this command "times out"
Throws:
IllegalArgumentException - if given a negative timeout or name was null.
See Also:
isTimedOut()
Method Detail

getName

public String getName()
Returns the name of this command. If no name was specified in the constructor, then the default is the name of the class.

Specified by:
getName in interface NamedSendable
Returns:
the name of this command

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 given Subsystem 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 - the Subsystem required
Throws:
IllegalArgumentException - if subsystem is null
IllegalUseOfCommandException - if this command has started before or if it has been given to a CommandGroup
See Also:
Subsystem

initialize

protected abstract void initialize()
The initialize method is called the first time this Command is run after being started.


execute

protected abstract 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 and end() will be called.

It may be useful for a team to reference the isTimedOut() method for time-sensitive commands.

Returns:
whether this command is finished.
See Also:
isTimedOut()

end

protected abstract 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 abstract void interrupted()
Called when the command ends because somebody called cancel() 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


isTimedOut

protected boolean isTimedOut()
Returns whether or not the timeSinceInitialized() 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

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 called interrupted().

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

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 given Subsystem.

Parameters:
system - the system
Returns:
whether or not the subsystem is required, or false if given null

getGroup

public CommandGroup getGroup()
Returns the CommandGroup that this command is a part of. Will return null if this Command 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 this Command 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 this Command will run when the robot is disabled, or if it will cancel itself.

Returns:
whether or not this Command will run when the robot is disabled, or if it will cancel itself

toString

public String toString()
The string representation for a Command is by default its name.

Overrides:
toString in class Object
Returns:
the string representation of this object

getSmartDashboardType

public String getSmartDashboardType()
Specified by:
getSmartDashboardType in interface Sendable
Returns:
the string representation of the named data type that will be used by the smart dashboard for this sendable

initTable

public void initTable(ITable table)
Description copied from interface: Sendable
Initializes a table for this sendable object.

Specified by:
initTable in interface Sendable
Parameters:
table - The table to put the values in.

getTable

public ITable getTable()

Specified by:
getTable in interface Sendable
Returns:
the table that is currently associated with the sendable

"

2013 FRC Java API

"

"
For updated information see the Java FRC site
"