Skip to content

C++ based Hierarchical / Finite State Machine library oriented for embedded and RTOS systems.

License

Notifications You must be signed in to change notification settings

igor-krechetov/hsmcpp

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

MIT License Changelog Documentation Status

Releases

Latest Release PlatformIO Registry arduino-library-badge

Quality Status

Build Status

Static Code Analysis

SCA: MISRA SCA: CodeQL SCA: Coverity

Unit Tests

Coverage Status

Tests: STD Tests: Glib Tests: GLibmm Tests: Qt

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:

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 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.

Why are they not used?

What are the main arguments against statecharts?

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

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

Key Features

Generic

State machine related

Documentation

Documentation is available online.

HSM GUI Editors

Check out documentation to learn more about available editors.

Editing HSM in Qt Creator

Editing HSM in scxmlgui

hsmdebugger

Read documentation for details on how to use debugger.

hsmdebugger demo

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:

Hello Wolrd HSM

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: