Releases

Quality Status

Static Code Analysis

Unit Tests

Overview

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 from statecharts.dev)

Why should you use Statecharts?

Statecharts offer a surprising array of benefits

• It’s easier to understand a statechart than many other forms of code.
• The behaviour is decoupled from the component in question.
  • This makes it easier to make changes to the behaviour.
  • It also makes it easier to reason about the code.
  • And the behaviour can be tested independently of the component.
• The process of building a statechart causes all the states to be explored.
• Studies have shown that statechart based code has lower bug counts than traditional code.
• Statecharts lends itself to dealing with exceptional situations that might otherwise be overlooked.
• As complexity grows, statecharts scale well.
• A statechart is a great communicator: Non-developers can understand the statecharts, while QA can use a statecharts as an exploratory tool.

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

Why should you not use statecharts?

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

• Programmers typically need 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 the number of lines of code might increase with smaller statecharts.

Why are they not used?

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

What are the main arguments against statecharts?

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

• It’s simply not needed.
• It goes against the grain of [insert name of technology].
• It increases 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 a net positive.

Key Features

Generic

• visual state machine editors (through thirdparty editors)
• code generation based on W3C 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 to implement your own dispatcher
• visual debugger to help analyze state machine behavior

State machine related

• 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

Documentation is available online.

HSM GUI Editors

Check out documentation to learn more about available editors.

hsmdebugger

Read documentation for details on how to use debugger.

Installation

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.

Dependencies

• 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)

Creating a simple State Machine

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.

Notable FSM/HSM libraries

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