CHSM - Hierarchical State Machine (HSM) Framework for C

⚠️ Experimental code, expect breaking changes.

The project consists of two main parts: an editor (CHSM) to draw state machines and a C library (CRF) that is able to drive the C code generated by the editor.

CHSM (editor) features:

• Written in Python and Vanilla Javascript. (Tested with Python 3.7+ and Chromium on RPi4 and with Chrome and Firefox on Win10.)
• The editor can generate C code from the drawings.
• Application file format is Html. Can be opened without the editor in view-only mode with any browser.
• Comments can be added to any string.
• Comments are displayed as tooltips on mouse hover and added as actual C comments to the generated code.
• Mostly follows the UML statecharts specification (event deferral is an exception).

The CRF (C Reactive Framework) design was heavily influenced by Miro Samek's excellent book: Practical UML Statecharts in C/C++. If you are not familiar with UML statechars then I recommend reading it. All the important concepts are explained very clearly in a first few chapters with easy to understand examples.

CRF features:

• Run-to-completion (RTC) execution model
• Written in C99. (Uses C11 atomics when available, if not, than the application must define two simple atomic functions.)
• State transitions are precalculated at code generation to avoid the runtime cost of hierarchy discovery.
• All states are represented by functions that process events with a switch statement.
• Optional event pools that provide simple O(1) dynamic memory handling to releive modules from buffering.
• Wait-free multi-producer single-consumer event queues for each state machines.
• Events can be deferred and recalled.
• Events can be safely generated and distributed by interrupts.
• Optional event generators for "analog" int32 values and uint8_t bitfields.
• Unit tests (using the Unity framework).

Dependencies

Of the GUI and code generation

1. Chrome. Theoretically other browsers can be used, but only Chrome was tested.

2. Python 3.7+ The following packages are required:

   • eel
   • docopt

   You can install the packages like this: pip3 install eel docopt

Of the C unit tests

The C code uses the Unity unit testing framework for running the tests. The CMake script that builds the tests assumes that the Unity and the CHSM repos are in the same directory.

Cloning: git clone https://github.com/ThrowTheSwitch/Unity.git

Usage

1. Clone the repo
2. Checkout the master branch
3. Navigate into the chsm folder, open a command prompt and run this command: python3 cgen/chsm_backend.py

The result should be a new window with a simple state machine already in it.

Compile modules

To run one individual test, build and run it

cd build
cmake --build . -t lm73_test; ctest -VV -R lm73_test

Build and run all tests with one command

cd build
cmake --build . -t ; ctest -VV -R 

To listout all target

cd build
make help