Actions

Actions are tasks executed by FlashLib's Scheduler. These tasks are more than a simple run, they are executed by specific steps, and can be considered as a complex task.

Properties

An Action has several properties, which enhance its capability.

Requirements

An Action has requirements. These are robot Subsystems which the Action aims to use. The Scheduler ensures only one running Action uses a certain Subsystem at any given time.

Timeout

An Action can define a run timeout, which defines the maximum amount of time the Action should run. Once the timeout was reached, the Action will be stopped.

Execution Flow

An Action has several execution steps, which define the flow of the task. These steps allow defining a more complex behavior for tasks, to handle different situations, and points in the execution cycle of the task.

The following is the flow of an Action:

Once started, the task enters the initialization step, which allows users to initialize data or reset data holders. Next, the task enters the execution step. During this step, users should perform the main task logic. This step continues until the task is marked to be stop.

Finishing steps

One the task is marked for finishing, the task can either enter end, or interruption steps.

The end step is entered if the task reports to have finished.

Interruption step is entered in one of several condition:

• The task was canceled by the user
• The task was canceled by the scheduler due to requirement conflict
• The task has timed out

Code

Actions are represented by the Action class, which is abstract class. Users are required to implement the contents of each execution step:

• initialize: code for the initialization step. Default implementation: does nothing
• execute: code for the execution step
• end: code for ordered stop of the action
• interrupted: code for interruption stop. Default implementation: calls end.
• isFinished: indicates whether or not the action should stop running. Default implementation: returns false, which indicates that action should not stop.

Steps

During the initialization phase, the method initialize is called once. This is done each time the action is started. During the execution phase, the method execute is called periodically (the interval depends on the Scheduler, but should largely be around few milliseconds). During the end step, end is called once. During the interruption step, interrupted is called once.

Finishing Condition

An Action can report itself has finished, by returning true from the isFinished method.

Extending an Action

To create an Action you will need to extend it, and implement the step methods:

public class SomeAction extends Action {
    @Override
    protected void execute() {
    }

    @Override
    protected void end() {
    }
}

execute and end are the only step methods which don't have a default implementation, and must be implemented. The rest can be ignored, but when needed, can be implemented.

Properties

The Action class contains methods for defining its properties. Setting the properties should be done once the Action is created, and cannot be done while it is running.

• To set the requirements of an Action, use the requires method. Each call to this method will add a new requirement and not override requirements already defined. Call to resetRequirements to clear defined requirements.

  Action action = new SomeAction();
  action.requires(subsystem);

  public class SomeAction extends Action {
      ...
      public SomeAction(Subsystem subsystem) {
          requires(subsystem);
      }
      ...
  }

• To set run timeout, use setTimeout method, which receives Time from FlashLib's Time API. You may also call cancelTimeout to remove the defined timeout.

  Action action = new SomeAction();
  action.setTimeout(Time.milliseconds(timeoutInMilliseconds));

  public class SomeAction extends Action {
      ...
      public SomeAction() {
          setTimeout(Time.milliseconds(timeoutInMilliseconds));
      }
      ...
  }

Running an Action

To start and action use the start method. To interrupt a running action, call cancel method. The isRunning method indicates whether or not the Action is running.

public class Robot extends IterativeRobot {
    ...
    @Override
    protected void modeInit(RobotMode mode) {
        new SomeAction().start();
    }
}

Action Groups

Action Groups are a specific implementation of Action which executes a group of 1 or more actions in a specific order. There are 2:

• ParallelActionGroup for executing multiple actions concurrently. One should not that whether the execution is truly parallel or simply concurrent depends on the implementation on the Scheduler. In addition, it is important to be aware that multiple actions do not use the same subsystems.
• SequentialActionGroup for executing actions in a sequential order, only starting the next, once the previous has finished.

Usage is quite simple. One must construct the wanted class, and define the wanted actions:

Action group = new ParallelActionGroup()
    .add(action1, action2);
group.start();

Action group = Actions.parallel(action1, action2);

Actions and Robot Modes

When the robot mode changes, all running actions will be interrupted.