hsmcpp Documentation

Note

This project is under active development.

Quality Status

Static Code Analysis

Unit Tests

Overview

HSMCPP is a C++ library providing an easy way (hopefully) to add hierarchical (HSM) or finite state machine (FSM) to your project. Main motivation behind making it was lack of suitable alternatives which do not involve large frameworks (often commercial). And even they couldn’t satisfy projects 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, multithreading 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:

• Introduction to Hierarchical State Machines

• Hierarchical Finite State Machine for AI Acting Engine

Key Features

Generic

• 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

  • 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.14+

  • Visual Studio 2015+ (for Windows build)

• For code generator:

  • Python 3

• For hsmdebugger:

  • Python 3

  • PyYaml (pip3 install PyYaml)

Content

• Getting Started
• Features
  • States
  • Events
  • Transitions
  • Substates
  • History
  • Parallel States
  • Timers
  • Variant Type
• Platforms
• Code Generation
  • SCXML Format
  • SCXML editors
  • Build Integration
• Tools
  • HSM Debugger
  • scxml2gen