hsmcpp Documentation
Note
This project is under active development.
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:
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?
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
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.
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)
Content