HSMCPP is a C++ library providing implementation of state machine design pattern. It allows you to easily add hierarchical (HSM) or finite state machine (FSM) to your project. Main motivation behind creating it was lack of suitable alternatives which do not require usage of large frameworks (often commercial). And even they couldn't satisfy project needs that I usually have to deal with. This is in no way a "silver bullet" library, but it might be useful for you when dealing with RTOS systems, multi-threading or event driven applications.

It's also applicable for single threaded and synchronous applications, but it might not be the most efficient option.

If you are not familiar with HSM/FSM and which problems they can solve in your code, I recommend reading:

• Welcome to the world of Statecharts
• Introduction to Hierarchical State Machines
• Hierarchical Finite State Machine for AI Acting Engine

• visual state machine editors (through thirdparty editors)
• code generation (using state machine described in SCXML format as an input)
• PlantUML diagrams generation (from SCXML files)
• asynchronous / synchronous execution
• thread safety
• supported platforms:
  • POSIX compliant systems
  • Windows
  • Arduino
  • FreeRTOS
• configurable event dispatchers:
  • std::thread based
  • glib based
  • glibmm based
  • Qt based
  • FreeRTOS based
  • Arduino based
  • possibility to implement your own dispatcher
• visual debugger to help analyze state machine behavior

• states
• substates (possible to define hierarchy)
• transitions
• history
• timers
• state and transition callbacks (enter, exit, state changed, on transition)
• passing data to state and transition callbacks
• parallel states
• final states
• conditional transitions
• conditional entry points
• state actions
• self transitions
• transition cancelation
• support for std::function and lambdas as callbacks

Documentation is available online.

Check out documentation to learn more about available editors.

Read documentation for details on how to use debugger.

git clone https://github.com/igor-krechetov/hsmcpp.git
cd ./hsmcpp
./build.sh
cd ./build
make install

By default it will build all included components, tests and examples. You can disable any of them using cmake build flags. For example you probably will not have glib or glibmm libraries available on Windows so you might want to exclude them.

See detailed instructions in documentation.

• For library:
  • C++11 or newer
  • glib (optional, for dispatcher)
  • glibmm (optional, for dispatcher)
  • Qt (optional, for dispatcher)
• For build:
  • cmake 3.16+
  • Visual Studio 2015+ (for Windows build)
• For code generator:
  • Python 3
• For hsmdebugger:
  • Python 3
  • PyYaml (pip3 install PyYaml)
  • PySide6 (pip3 install PySide6)
  • plantuml (minimal version: V1.2020.11)

HSM structure:

Implementation using HsmEventDispatcherSTD:

#include <chrono>
#include <thread>
#include <hsmcpp/hsm.hpp>
#include <hsmcpp/HsmEventDispatcherSTD.hpp>

enum class States
{
    OFF,
    ON
};

enum class Events
{
    SWITCH
};

int main(const int argc, const char**argv)
{
    std::shared_ptr<hsmcpp::HsmEventDispatcherSTD> dispatcher = hsmcpp::HsmEventDispatcherSTD::create();
    hsmcpp::HierarchicalStateMachine<States, Events> hsm(States::OFF);

    hsm.initialize(dispatcher);

    hsm.registerState(States::OFF, [&hsm](const VariantList_t& args)
    {
        printf("Off\n");
        std::this_thread::sleep_for(std::chrono::milliseconds(1000));
        hsm.transition(Events::SWITCH);
    });
    hsm.registerState(States::ON, [&hsm](const VariantList_t& args)
    {
        printf("On\n");
        std::this_thread::sleep_for(std::chrono::milliseconds(1000));
        hsm.transition(Events::SWITCH);
    });

    hsm.registerTransition(States::OFF, States::ON, Events::SWITCH);
    hsm.registerTransition(States::ON, States::OFF, Events::SWITCH);

    hsm.transition(Events::SWITCH);

    dispatcher->join();

    return 0;
}

See /examples/07_build for CMake configuration examples.

For other examples see Getting Started guide or /examples.

There is no one-for-all library, so if hsmcpp doesn't fully suit your needs you can check out one of these alternatives:

• Qt (using QStateMachine or QScxmlStateMachine)
• QP/C++
• TinyFSM
• Another Finite State Machine
• HFSM2
• arduino-fsm