Repository files navigation

HSMCPP is a C++ library providing implementation of state machine design pattern (also known as statecharts). It allows you to easily add hierarchical (HSM) or finite state machine (FSM) to your project. The main motivation behind creating it was the lack of suitable non-commercial alternatives which do not require the usage of large frameworks. And even existing commercial solutions couldn't satisfy all 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 design concept and which problems it helps you solve, I recommend reading:

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

And if you just want to know if state machines are for you or not, here is a quick list (taken fromstatecharts.dev)

Statecharts offer a surprising array of benefits

• It'seasier to understand a statechart than many other forms of code.
• Thebehaviour is decoupled from the component in question.
  • This makes iteasier to make changes to the behaviour.
  • It also makes iteasier to reason about the code.
  • And the behaviour can betested independently of the component.
• The process of building a statechart causesall the states to be explored.
• Studies have shown that statechart based code haslower bug counts than traditional code.
• Statecharts lends itself to dealing withexceptional situations that might otherwise be overlooked.
• As complexity grows, statechartsscale well.
• A statechart is a great communicator: Non-developers canunderstand the statecharts, while QA canuse a statecharts as an exploratory tool.

It's worth noting that you'realready coding state machines, except that they're hidden in the code.

There are a few downsides to using statecharts that you should be aware of.

• Programmers typicallyneed to learn something new, although the underpinnings (state machines) would be something that most programmers are familiar with.
• It's usually a very foreign way of coding, so teams might experience pushback based on how very different it is.
• There is an overhead to extracting the behaviour in that thenumber of lines of code might increase with smaller statecharts.

• People don't know about them, and YAGNI.

There are a few common arguments against statecharts in addition to the ones listed above:

• It'ssimply not needed.
• Itgoes against the grain of[insert name of technology].
• Itincreases the number of libraries, for web applications this means increased load time.

The benefits outlined above should make it clear that the introduction of statecharts is generally anet positive.

• visual state machine editors (throughthirdparty editors)
• code generation based onW3C SCXML format
• 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 toimplement your own dispatcher
• visual debugger to help analyze state machine behavior

• states
• substates (possible to define hierarchy)
• transitions
• history
• timers
• state and transitioncallbacks (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 availableonline.

Check outdocumentation to learn more about available editors.

Read documentation for details on how to use debugger.

git clone https://github.com/igor-krechetov/hsmcpp.gitcd ./hsmcpp./build.shcd ./buildmake 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.

Seedetailed 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>enumclassStates{    OFF,    ON};enumclassEvents{    SWITCH};intmain(constint argc,constchar**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();return0;}

See/examples/07_build for CMake configuration examples.

For other examples seeGetting 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