dlife.robot.controllers.fsm
Class FiniteStateController

java.lang.Object
  dlife.robot.Controller
      dlife.robot.controllers.fsm.FiniteStateController

public abstract class FiniteStateController
extends Controller

A Controller based on a finite state machine. A finite state controller consists of a number of States, one of which is the active state. During each step, the controller invokes the step() method of the active state. The active state then returns the name of the next state to be active (possibly itself).

In addition the FiniteStateController also provides a call/return stack to support the use of subroutines. State names can be pushed onto the call/return stack before transitioning to a state that is a subroutine. The subroutine can then pop a state name off of the stack to use as the state to which to return. This way it is not necessary for the subroutine to know in advance to which state it will return. Thus it may be invoked from any state.

Typical usage will be to create a sub-class of this class and define the states as private inner classes. Then create and add instances of those States in the constructor of the sub-class. The reason for using inner classes is so that all of the State's have access to the robot and devices of the Controller. A outline for a controller follows:

 public class FSCex extends FiniteStateController {
     public FSCex() {
         addState(new State1());
         addState(new State2());
         setInitialState("one");
     }
 
     public void startUp(Robot robot) {
         ... create and add devices here ...
     }
 
     private class State1 extends State {
         public State1() {
             super("one");
         }
 
         public void step(long elapsedTime) {...}
     }
 
     private class State2 extends State {
         public State2() {
             super("two");
         }
 
         public void step(long elapsedTime) {...}
     }
 }
 

For a concrete example of a FiniteStateController see the PioTriangle example.

Version:

Aug 8, 2008

Author:

Grant Braught, Dickinson College

Constructor Summary

FiniteStateController()
Create a new FiniteStateController.

Method Summary

void	addState(State newState) Add the specified State to this FiniteStateController.
State	getCurrentState() Get the State object for the current state of this FiniteStateController.
State	getInitialState() Get the initial State for this FiniteStateController.
String	peekReturnState() Peek at the name on the top of the call/return stack.
String	popReturnState() Pop a state name off the top of the call/return stack.
void	pushReturnState(String stateName) Push the specified state name onto the call/return stack.
void	setInitialState(String stateName) Set the State in which execution of this FiniteStateController should begin.
void	step() Handle the processing of this FiniteStateController.

Methods inherited from class dlife.robot.Controller

shutDown, startUp

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FiniteStateController

public FiniteStateController()

Create a new FiniteStateController. The new controller does not contain any states.

Method Detail

addState

public void addState(State newState)

Add the specified State to this FiniteStateController.

Parameters:

newState - the State to add to the controller.

Throws:

DuplicateStateNameException - if the State being added has the same name as a state already added to the Controller.

setInitialState

public void setInitialState(String stateName)

Set the State in which execution of this FiniteStateController should begin. Changing the initial state of a controller that is already running will have no effect.

Parameters:

stateName - the name of the initial State

Throws:

UnknownStateException - if there is no State with the specified name.

getInitialState

public State getInitialState()

Get the initial State for this FiniteStateController. This method is likely to have little practical use and is included primarily for testing purposes.

Returns:

the initial state if one has been set or null otherwise.

getCurrentState

public State getCurrentState()

Get the State object for the current state of this FiniteStateController. If step has not yet been called, this method returns null.

Returns:

the current State or null if step has not been invoked.

pushReturnState

public void pushReturnState(String stateName)

Push the specified state name onto the call/return stack. Typically a State will push its own name onto the stack and then return the name of the State for the subroutine it wishes to call. The subroutine State will then later return the name on the top of the stack to return to the calling State.

Parameters:

stateName - the state name to push onto the stack.

Throws:

UnknownStateException - if there is no State with the specified name.

popReturnState

public String popReturnState()

Pop a state name off the top of the call/return stack. Typically a State that is a subroutine will pop the name off of the top of the stack and return it. Thus, control will return to the State that invoked the subroutine.

Returns:

the state name from the top of the stack.

Throws:

UnknownStateException - if the call/return stack is empty.

peekReturnState

public String peekReturnState()

Peek at the name on the top of the call/return stack. The call/return stack is not altered by this method.

Returns:

the state name from the top of the stack.

Throws:

UnknownStateException - if the call/return stack is empty.

step

public final void step()

Handle the processing of this FiniteStateController. At each step the processing is as follows:

• The step method of the current State is invoked.
• If the controller is leaving the current state then the current State's leaveState method is invoked followed by the new State's enter state method.

Specified by:

step in class Controller

Throws:

UnknownStateException - if this is the first call to step and no initial state has been set or if the name returned by current state's step() method is not the name of a State in this FiniteStateController.