State Controller Library

Namespaces
	statecontroller
	This namespace defines everything that is required for the State Controller Library.

Detailed Description

Author

Philipp Allgeuer (pallg.nosp@m.euer.nosp@m.@ais..nosp@m.uni-.nosp@m.bonn..nosp@m.de)

Date

November 21, 2014

Version

1.2.2

Overview

The State Controller Library is a generic platform-independent C++ namespace that allows finite state machines and multi-action planning generalisations thereof to be realised. The structure and implementation of this library focuses on applications of finite state machines in control loops, but can reasonably be adapted for virtually any other application. An emphasis has been placed on having very low overhead so as not to hurt overall system performance no matter where this library is used.

Aside from implementing standard finite state machines and multi-action planning state machines, this library can also be used to implement hierarchical state controllers or any hybrid of the three. The hierarchical case can be achieved by creating a state controller within the state of another state controller, and stepping the child state controller within the execute() callback of the parent state controller. Minor variations of this approach are also possible to adjust the visibility of certain state variables and shared variables. An overview of the State Controller Library architecture is shown in the following diagram.

Figure 1: A block diagram of the State Controller Library architecture showing the states, state instances, state queue and state controller objects.

The State Controller Library was developed as a simple and state-based alternative to the more complex but powerful Behaviour Control Framework.

Academic Sources

The State Controller Library and the Behaviour Control Framework are detailed in the following paper.

P. Allgeuer and S. Behnke, "Hierarchical and State-based Architectures for Robot Behavior Planning and Control," in Proceedings of the 8th Workshop on Humanoid Soccer Robots, IEEE-RAS Int. Conference on Humanoid Robots, Atlanta, USA, 2013.

You are kindly asked to cite this paper if you use this framework for academic work.

@INPROCEEDINGS{Allgeuer2013,
  author = {Philipp Allgeuer and Sven Behnke},
  title = {Hierarchical and State-based Architectures for Robot Behavior Planning and Control},
  booktitle = {Proceedings of the 8th Workshop on Humanoid Soccer Robots, IEEE-RAS Int. Conference on Humanoid Robots},
  year = {2013},
  address = {Atlanta, USA}
}

Dependencies

This library depends on the following external libraries (to avoid requiring C++11):

• Boost Smart Ptr
• Boost Static Assert
• Boost Type Traits

For more information, or to download the Boost Libraries, please refer to http://www.boost.org/.

Library Implementation Notes

The following notes describe how to use the library, and outline some of the finer points.

• A new instance of a state class is created for every time the state controller is in that particular state. This instantiation occurs (incidentally, by the user of this library) when the state is placed into the state queue, which is stored internally in the state controller. This means that each state (i.e. derived State class) will have many state instances throughout the lifetime of the state controller, not all of which will necessarily be executed however (e.g. if a state is enqueued but then the queue is cleared and re-populated with other states before it had a chance to execute). Boost shared pointers are used (and should be used by the user) to ensure that the state instances get properly destroyed when no longer required (refer to the NewStateInstance macro). As such, state instances are one-use only. Do not try to feed an executed state instance back into the queue/state controller.

  Example of creating a state:

  StatePtr s = NewStateInstance<MyState>(arg1, arg2, ...); // arg1, arg2, ... are the parameters to pass to the MyState constructor
  ...
  ret_t ret;
  MyStateController sc;
  ret = sc.init(NewStateInstance<MyState>(&sc, arg2, ...)); // Pass the newly created state directly to init() function (recommended)

• There are three main kinds of variables that can be used within a state controller and its states:
  • State parameters: Stored in the state class, used as input parameters for a state instance, generally remain constant throughout the execution of that state instance, an example is a target theta value for an AdjustActuatorPosition state, state parameters differentiate themselves from state variables as they appear (and are set) in the state constructor by definition.
  • State variables: Stored in the state class, used for storing data locally between calls to execute() for a single state instance.
  • Shared variables: Stored in the state controller class, used as a form of 'global' storage as the values are retained between different instances of the same state, also used to share data between states, example is a pointer to a class with robot information. Shared variables are further sub-classified as output shared variables or internal shared variables. The former are the public shared variables that are used to pass information out of the state controller, while the latter are the private/protected shared variables that are used internally for data sharing between states.
• Never declare a member of a state class as static in order to share it between separate instances of a state, use shared variables for this purpose instead. The former may result in unexpected behaviour when more than one instance of the owning state controller is instantiated at a time (even if this situation is not intended to occur in your application).
• User-defined states can either inherit from the State class directly, or indirectly through GenState (with template parameter SCClass). The intended advantage of using GenState is that is keeps an internal pointer to the owning state controller (of class SCClass), so the user does not need to do this themselves in order to access the state instance independent ('global') variables stored in the state controller. GenState also provides a default implementation for the scname and scref() members. For obvious reasons, the SCClass template parameter of the GenState class must derive from the StateController class. A compile time error is issued if this is not the case.

• States with only a few state parameters can pass them directly as parameters to the constructor, making use of the initialisation list to copy these to internal members. States with many state parameters should define a StateParams struct inside the class and pass this to the constructor instead. This struct should then contain all the required state parameters.

  Example constructor that accepts a StateParams struct:

  class MyState : public GenState<MySC>
  {
  public:
      // State parameter data structure type
      struct StateParams
      {
          float myParam;
          ... // Remaining parameters
      };
  
      // Constructor
      WalkToBallState(MySC *sc, const StateParams& sp) : GenState(sc, WALK_TO_BALL, "WALK_TO_BALL"), sp(sp) {}
  
      ... // Rest of class
  
  protected:
      // State parameters
      StateParams sp;
  };

• State instances are added to a state controller object by enqueueing them in the state controller's internal StateQueue . No static/compile time association needs to be made between the states and the state controller, other than to define a pointer to the correct state controller class type inside each of the state classes, and populating this member via the state constructor. This is automatically handled if using GenState .
• A single step of the state controller is executed using the step() function. This function is useful for embedding state controllers inside timed loops or other higher level main loops. To execute a state controller until completion (i.e. termination or error) the loop() function can be used. This repeatedly calls the step() function as fast as execution allows.
• A constant reference to the current state of a state controller can be retrieved using the getCurState() function.
• Each state has three so-called state callbacks, namely activate() , execute() and deactivate() . The state callbacks should be overridden as required by classes derived (either directly or indirectly) from State, but never called by them. The activate() and deactivate() callbacks have default null implementations as they may frequently not be required by the user, so they can be omitted from the derived class implementation. Each of the callbacks must accept a cycle count parameter cyc, which is used to explicitly pass the current cycle count of the owning state controller. This could equivalently (but slightly less robustly in certain situations) be retrieved directly from the getCycle() function. The deactivate() function must also accept a boolean parameter that specifies whether the execute() callback of the state was ever called after the state was activated. This could change what needs to be done (e.g. what memory needs to be freed) in the deactivate() callback. There are only rare situations where the boolean parameter will ever be false, such as when the terminate() function was used from the activate() callback.
• Six user-overridable step callbacks exist in the StateController class. Namely, preStepCallback , preActivateCallback , preExecuteCallback , postExecuteCallback , onTerminateCallback and postStepCallback . All of these virtual functions get called during the step() function. Note that loop() internally calls step(), so the callbacks also get called if the loop() function is used to execute the state controller unto termination (or error). Exact descriptions of when each of these callbacks are executed are provided in the individual function descriptions.
• A state is activated by the state controller immediately before it is executed for the first time, but then never again - a new state instance has to be created in order to enter a particular state again later in time, after other states have been executed in the meantime. The execute() callback is then called in every state controller step that this state remains the current state. Transitions occur by enqueueing element(s) into the state queue (retrieve a pointer to the queue using the Queue() function) from within the execute() callback and then returning PROCEED_NEXT_STATE instead of HOLD_THIS_STATE, or by using the StateController::goToState() function. The StateController::terminate() function can be used to leave the current state and terminate the state controller. Every state that gets activated at some point also gets deactivated (this is a certainty that can be relied upon). This almost always occurs immediately when the state controller no longer needs the state, but if for whatever special reason this is not the case (shouldn't happen in normal use of the library), deactivation occurs at latest in the State destructor. Such a call is made with a default cycle count of 0. Any cycle count-specific code in the deactivate function should be able to deal with this possible count discontinuity.
• The cycle count that is passed to the state callbacks can be used to add a notion of timing to the state controller. That is, a state can be made to terminate after a set number of steps based on this count, which in a real-time control loop would approximately correspond to terminating after a fixed amount of time. The important functions are firstExecCycle() and execCycleNum() . The former returns the cycle number of the first call to execute() for that particular state instance, while the latter returns the number of times execute() has been called, including any current call. firstExecCycle() returns zero if execute() has never been called, and is guaranteed to be non-zero if execute() has been called at least once. The execCycleNum() function for example can be used as follows:

  // MyState execute callback
  action_t MyState::execute(cycle_t cyc)
  {
      ... // Perform the required state tasks
  
      // Change state after 5 steps (for a total of exactly 5 calls to this callback)
      if(execCycleNum(cyc) >= 5)
          return sc->goToState(NewStateInstance<MyNewState>(sc)); // The short and efficient way of using goToState() for simple next-state logic
  
      // Keep state controller in MyState until the termination condition above is satisfied
      return HOLD_THIS_STATE;
  }

• The id, name, scname and scref() state properties need to be defined for each state (noting however that scname and scref() are taken care of already if deriving from GenState). All but scref() are defined using constructor arguments.
  • id : A unique numeric ID for each state. e.g. MY_STATE_NAME, defined via an enumeration:

    enum MySCStateID
    {
        ... // Other state IDs
        MY_STATE_NAME,
        ... // Other state IDs
    };

  • name : A std::string with a useful name for the state. e.g. "MY_STATE_NAME", "performing_this_action", "waiting_for_input", etc...
  • scname : A std::string with a useful name for the owning state controller. This is generally retrieved directly from StateController::name .
  • scref() : A pointer to the owning state controller, used to verify which StateController derived class instance the state belongs to. This property is protected, unlike the other state properties, and is generally implemented as a static_cast of the internal state controller pointer (normally called sc).
• Be careful never to dereference the return value of scref() or call Queue() when the owning state controller object has already been destroyed, or a segmentation fault will result. Use of these functions in the state callbacks is completely safe (as long as the user doesn't find a devious way of calling the callbacks from outside the state controller, which with enough abuse of the library is actually possible to do incidentally [but I won't say how!], and then specifically dereferences one of these two functions just to break the program). In short, it will never happen in normal usage or by accident.
• It is not recommended to keep a local reference to any states that you pass to StateController::init() and StateController::forceState() . A local reference should never be needed anyway, so the temptation should be limited. Refer to the documentation for these functions for more information, as well as the code example of creating a state further above on this page.
• Although many of the state controller member functions are public by requirement, it is not recommended to call them from within a state callback. Callback protection has been implemented to ensure that such function calls are ignored, and as a result have no effect.
• If you want to initialise a state controller with a particular queue of states, the correct way of approaching this is to create an initialisation state that sets up the queue as desired and then immediately returns PROCEED_NEXT_STATE. Avoid trying to set up the initial queue by calling queue functions externally (this has intentionally been made near-impossible to do).

Code Example

A (relatively) minimal example of how to use this library is shown below.

//
// File: MyCode.h
//

// Includes
#include <state_controller.h>

// Using directives
using namespace statecontroller;

// State IDs
enum MySCStateID
{
  MY_STATE,
  ...
};

// State controller
class MySC : public StateController
{
public:
  // Constructors
  MySC() : StateController("MySC") {}

  // Shared variables
  ...
};

// Sample state
class MyState : public GenState<MySC>
{
public:
  // Constructors
  MyState(MySC *sc, int param) : GenState(sc, MY_STATE, "MY_STATE"), param(param) {}

protected:
  // State callbacks
  action_t execute(cycle_t cyc)
  {
      // Execute ten times then terminate state controller
      if(execCycleNum(cyc) >= 10)
          return sc->terminate();

      // Stay in this state until the above condition is satisfied
      return HOLD_THIS_STATE;
  }

  // State parameters
  int param;

  // State variables
  ...
};

//
// File: MyCode.cpp
//

// Includes
#include "MyCode.h"

// Main function
int main(int argc, char **argv)
{
  // Run the state controller
  MySC sc;
  sc.init(NewStateInstance<MyState>(&sc, 4));
  sc.loop();

  // Return value
  return 0;
}

See test/test_state_controller.h and test/test_state_controller.cpp for more examples of how to define states and state controllers and how to run them.

See state_controller.h and state_controller.cpp for the library source code.

See Also

statecontroller Namespace

StateController Class

StateQueue Class

State Class