FSM Library

A lightweight and extensible Finite State Machine (FSM) framework written in C++. Designed for embedded systems, robotics and any application that benefits from structured state-based logic.

This library provides:

• A flexible state and transition model
• Event-driven execution
• Command-based state control
• Support for meta-states
• Pluggable callbacks for states, transitions, commands, and events

Features

State Abstractions

The FSM provides a BaseState interface defining optional callbacks:

• OnEnter()
• OnExit()
• OnUpdate()

States are registered with a string key and can be executed dynamically.

Transitions

Transitions are represented using BaseTransition, allowing you to define:

• custom transition conditions
• transition callbacks
• mapping between origin → destination states

The FSM keeps an internal transitions map and supports enabling/disabling transitions at runtime.

Events

Events are inserted into a priority queue and processed in order of priority. Each event is associated with:

• a handler function
• optional metadata
• priority for scheduling

Commands

Commands allow controlling the state machine externally. Commands can be registered with:

• a name
• a callback
• optional conditions

Commands can be tied to specific states or made globally available.

Core Components

basestate.h

Defines the BaseState interface, including:

• state identity (string ID)
• optional callbacks (OnEnter, OnExit, OnUpdate)
• optional custom payload structures

Useful for implementing reusable logic in derived states.

basetransition.h

Defines the BaseTransition interface:

• condition evaluation (Check())
• optional callbacks for entering/leaving transitions
• identification of start and end states

fsm.h

Implements the main FSM class:

• Registers states, transitions, commands, and events

• Processes events from an internal priority queue

• Manages the current active state

• Resolves state changes when transitions are triggered

• Maintains maps such as:

  std::map<BaseCommandStateKey, bool>          stateCommandsMap_;
  std::map<std::string, BaseStateInfo>         stateFunctionsMap_;
  std::map<std::string, BaseCommandInfo>       commandFunctionsMap_;
  std::map<std::string, BaseTransitionInfo>    transitionFunctionsMap_;
  std::map<std::string, BaseEventInfo>         eventFunctionsMap_;
  std::map<BaseTransitionsMapKey, bool>        transitionsMap_;
  std::map<BaseTransitionsMapKey, std::string> transitionTransitionFunctionsMap_;
  std::map<std::string, std::string>           metastateStateMap_;
  std::priority_queue<BaseEventPriorityKey>    eventQueue_;

Example Usage

TBD.

Building

The build tool used for this project is CMake. To build and install the project navigate to the root of the cloned repo and execute the following commands:

$ mkdir build
$ cd build
$ cmake ..
$ sudo make install

Then include the header fsm.h anywhere in your project.

License

The software is released under the MIT License, as reported in the LICENSE.md file.

Mantainer

This project is mantained by the GRAAL Laboratory, University of Genoa (Italy).