Skip to content

Latest commit

 

History

History
70 lines (45 loc) · 5.69 KB

README.md

File metadata and controls

70 lines (45 loc) · 5.69 KB
Raw

State Controller Library

Author: Philipp Allgeuer

Version: 1.2.2

Date: 21/11/14

General Overview

The State Controller Library is a generic platform-independent C++ framework that allows finite state machines and multi-action planning generalisations thereof to be realised. The structure and implementation of this library focuses on the application of finite state machines to real-time control loops, but can be reasonably adapted for virtually any other application, even completely unrelated to control systems. 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, while still maintaining ease of use. Code size has also been kept to a minimum.

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. Please refer to the extensive documentation for more information.

Feature List

  • Small and highly efficient performance-oriented cross-platform C++ library
  • Independent code with few external dependencies
  • Can be used to implement finite state machines, generalised state machines, hierarchical state machines, and most notably, multi-action planning state controllers
  • Can be used to implement a basic finite state machine with minimal coding effort and execution overhead, while simultaneously allowing for extensibility to more complex generalised finite state machines
  • Tried and tested by the author on various robotic platforms
  • Documented using the Doxygen documentation generation tool, including code samples and a discussion of all usage caveats
  • Well-commented library source code to allow easy modification/extension by users (who are encouraged to submit improvements/bug fixes to the author, so that the library can be improved!)
  • Academic paper on the framework: Hierarchical and State-based Architectures for Robot Behavior Planning and Control, published in Proceedings of 8th Workshop on Humanoid Soccer Robots @ Humanoids 2013

Installation

This library is implemented as a collection of platform-independent C++ source files. To get started just clone the state_controller_library repository.

There are three ways of using the library:

  1. Directly include the (non-test) source files in your project, and build them with the rest of your project.

  2. Build a static library (e.g. *.a or *.lib) of the source code and link your project to it.

  3. Build a dynamic library (e.g. *.so or *.dll) of the source code and link your project to it.

Due to the small and efficient nature of the library, one of the first two options is recommended. Very minimal benefit is expected over the other two options when choosing to build it as a dynamic library.

Note that as at release v1.2.2, the required (non-test) source files are simply state_controller.h and state_controller.cpp.

A sample makefile for building the static and dynamic libraries using gcc is included in the release. The makefile also demonstrates how the test_state_controller unit test can be built. As mentioned in the makefile however, the State Controller Library could equivalently be built using any other compiler, such as for example MSVC.

Dependencies

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

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

A unit test for the library (test_state_controller) is included in the release. It is not required to build this executable in order to use the library - it is for demonstration and testing purposes only. The unit test has one additional dependency, namely the Google Test Framework.

Documentation

Doxygen Documentation

The first place to look for help and guidance when trying to use the State Controller Library is the Doxygen documentation. This can be generated by running State Controller Library vX.X.X/doc/generate_doc.sh, and is then located at:

State Controller Library vX.X.X/doc/State Controller Library.html

Or equivalently:

State Controller Library vX.X.X/doc/out/html/index.html

The Doxygen documentation provides a complete explanation of the entire framework, including all caveats and details, and includes code samples to make the task of learning the framework a lot easier. Complete documentation of all functions, classes and namespaces of the library is also included. As such, the Doxygen documentation is intended to be the primary help resource when working with the library.

Source Code

If anything is not adequately explained in the Doxygen documentation, or more details as to the inner workings of the library are required, the next place to look would be in the library source code. The code is well-commented and should be fairly self-explanatory. A good starting point is state_controller.h. A look inside the source code for test_state_controller should also shed some light on how the library is intended to be used.

Where To Get More Help?

If neither the Doxygen documentation nor a look into the source code can resolve your issues for whatever reason, you can open a GitHub issue.

Bugs and Improvements

I welcome all feedback, suggestions and bug reports (by opening a GitHub issue). If you improve or fix anything about the library then I encourage you to let the author know so that the library can be improved for everyone!