finger563/webgme-hfsm

Metamodel, visualization, simulation, and code generation for Hierarchical Finite State Machines (HFSMs) following the UML State Machine spec.

WebGME HFSM

WebGME App for creating Executable Hierarchical Finite State Machines (HFSMs). Contains metamodel, visualization, simulation, and code generation for Hierarchical Finite State Machines (HFSMs) following the UML State Machine specification, see Wikipedia UML State Machine, another reference, and the UML specification.

Please see the WIKI for further information, including links to relevant Youtube Videos and specific pages about development process and such.

Table of Contents

• Features
• Description
• Getting Started
  • Setting up the WebGME-HFSM Server
  • Creating a HFSM
  • Simulating a HFSM
  • Code Generation
    • Test Bench Code
• Examples

Features

• Complete modeling of State Machines following the UML specification including:
  • States with Hierarchy
  • Events
  • Internal Transitions
  • External Transitions
  • Local Transitions
  • Choice Pseudostates
  • Deep History Pseudostates
  • Shallow History Pseudostates
  • Initial States
  • End States
• Interactive model creation
  • Positions of states are saved
  • Code can be edited directly in the model
  • Simulator automatically updates as model changes
  • Can use multi-select to move groups of states or to edit attributes of multiple objects (e.g. transition events)
  • Can auto-select all transitions by Event
  • Can zoom / pan the model to focus on a specific context
• In-model interactive simulation of the HFSM
  • Highlighting of execution pathways during event handling
  • Can disable / enable transitions
  • User can select which guards are true when transitions have guards
  • Currently active state tree branch shown including all event actions
  • Simulator informs the user if the model is not well formed
• In-model collaborative code attribute editing for the HFSM (using the CodeEditor)
• Model transformation plugin to produce executable C++ code from the HFSM (with more languages coming soon!)
  • Disabled transitions are not generated
  • Model is checked before being generated

Description

This repository contains the plugins, decorators, and visualizers (all of which are WebGME Components) and the base and example seeds for creating HFSMs with embedded c/c++ code in each state. The WebGME app utilizes the CodeEditor to allow users to edit the code for the model as if it were part of an IDE.

Together these components and (meta-)modeling environment make up the State Machine Domain for WebGME.

The Base seed contains just the Meta definitions for the projects and HFSMs following the UML State Diagram specification and the Examples Seed contains a project with three different HFSMs: simple, medium, and complex.

HFSMs are trees, where a state may have zero or more substates.

In this modeling paradigm, Projects can contain any number of State Machines.

State Machines have the following attributes:

• Includes : include statements for the HFSM, will be at the top of the generated header
• Initialization : intialization code run at the beginning of the HFSM, before any of the state initialization code.
• Declarations : variable/function/class declarations within the HFSM's StateMachine namespace, will be within the generated header file
• Definitions : variable/function/class definitions within the HFSM's StateMachine namespace, will be within the generated source file

Getting Started

Setting up the WebGME-HFSM Server

Docker

Build the dockerfile for the webgme-hfsm docker image

docker build -t webgme-hfsm .

Now run the mongodb docker and the webgme-hfsm docker

docker run --name mongo -d -p 27017:27017 mongo
docker run --name webgme-hfsm -d -p 8081:8081 --link mongo:mongo webgme-hfsm:latest

You can also use docker-compose:

docker-compose up -d

Native

Dependencies:

• nodejs ^6.0
• mongodb

git clone https://github.com/finger563/webgme-hfsm
cd webgme-hfsm
npm install -g bower # needed for extra package management
npm install          # installs the required packages for webgme-hfsm
npm start

Which will run the WebGME-HFSM server on PORT 8081 of your local machine, accepting connections on all IP addresses available to it.

Note: this requires a mongodb instance running on the machine, which can be started with:

mongod --dbpath ${path you want for your database}

Once the server has been started, you can navigate (in Chrome) to

localhost:8081

where the server is running. Create a WebGME project there from either the base or the examples seed.

Creating a HFSM

Once a webgme project has been opened, creat a new HFSM project by dragging in a new component from the left panel.

Double click on the project and then drag in a new HFSM component.

In addition to editing the HFSM through webgme, the HFSMViz can also be used. Open an HFSM and click on the HFSMViz on the left side of the screen to use this mode.

Components can be dragged into the visualizer just like in webgme, with addditional operations accessible via the right-click context menu

Simulating a HFSM

In the HFSMViz, the active state of the simulation is highlighted in red, and the user can press the event buttons to see how the state machine will react to that event. If any guards need to be evaluated, a modal dialog will pop up with options for the user to select which guard should evaluate to true at that time. The user has the option of canceling the transition by selecting None. In the case that the guards are associated with exit transitions of a choice pseudostate, the Default Transition will be shown as a guard choice with no text.

The HFSMViz visualizer allows the visualization of the full HFSM. It also provides:

• An interface to see which events will be handled by the HFSM when it is in a selected (or active) state
• Simulation of the HFSM which properly traverses the transitions from the currently active state to the next active state when the user spawns an event into the simulation.
  • The visualization will even pop up dialogs asking the user which guard condition should be evalutated to true when the HFSM passes through a choice pseudostate or when multiple transitions have the same event trigger and different guards.
• Drag and drop external transition creation between two nodes of the HFSM
• Automatic layout and routing of the edges and nodes of the HFSM tree
• Context menu allowing the user to:
  • Toggle the display of a state's children
  • Set the active state
  • Auto-arrange selected nodes into a grid
  • Re-parent selected nodes into the right-clicked node
  • Add a new element (which can also be done by dragging from the Part Browser and dropping onto the visualizer.)

Code Generation

The SoftwareGenerator plugin supports generation of a Project and it's State Machines into executable code, with the option of generating test-bench code for interactively testing out the generated HFSM and tracing through which actions occur in what order when an event is spawned.

You can edit the code attributes for the State Machines, States, Internal Transitions, and External Transitions within the CodeEditor visualizer.

Test Bench Code

When the test code is generated, it generates a Makefile which builds a test and DEBUG target for each of the State Machines in the Project from which the plugin was executed. These test bench codes compile in (using a preprocessor define DEBUG_OUTPUT) logging code which traces when transitions are fired, which guards are true, which actions are executed, and which events are in the State Machine's event queue.

Example Test Bench Output for the Complex Example State Machine

jebKerman@ubuntu  ~/webgme-hfsm/exampleHFSM  make run_Complex_test_DEBUG 
Compiling Complex_test_DEBUG
g++ -o Complex_test_DEBUG Complex_test.cpp Complex_GeneratedStates.cpp    -O3 -std=c++14 -MD -MP -MF .dep/Complex_test_DEBUG.d  -DDEBUG_OUTPUT

Running Complex_test_DEBUG

./Complex_test_DEBUG
INITIAL TRANSITION::ACTION for /3/c/m
ENTRY::Complex::State_1::/3/c/Y
SerialTask :: initializing State 1
Select which event to spawn:
0. ENDEVENT
1. EVENT1
2. EVENT2
3. EVENT3
4. EVENT4
5. INPUTEVENT
6. None
selection: 1
[ EVENT1 ]
GUARD [ someNumber < someValue ] for INTERNAL TRANSITION:/3/c/Y/t evaluated to TRUE
Action iterating: 0
Action iterating: 1
Action iterating: 2
Action iterating: 3
Action iterating: 4
Action iterating: 5
Action iterating: 6
Action iterating: 7
Action iterating: 8
Action iterating: 9
Action iterating: 10
Action iterating: 11
Action iterating: 12
Action iterating: 13
Action iterating: 14
Action iterating: 15
Action iterating: 16
Action iterating: 17
Action iterating: 18
Action iterating: 19
Action iterating: 20
Action iterating: 21
Action iterating: 22
Action iterating: 23
Action iterating: 24
Action iterating: 25
Action iterating: 26
Action iterating: 27
Action iterating: 28
Action iterating: 29
Action iterating: 30
Action iterating: 31
Handled EVENT1
Select which event to spawn:
0. ENDEVENT
1. EVENT1
2. EVENT2
3. EVENT3
4. EVENT4
5. INPUTEVENT
6. None
selection: 4
[ EVENT4 ]
GUARD [ someTest ] for EXTERNAL TRANSITION:/3/c/I evaluated to TRUE
NO GUARD on EXTERNAL TRANSITION:/3/c/o
EXIT::Complex::State_1::/3/c/Y
Exiting State 1
TRANSITION::ACTION for /3/c/I
TRANSITION::ACTION for /3/c/o
ENTRY::Complex::State3::/3/c/T
TRANSITION::ACTION for /3/c/T/I
ENTRY::Complex::State3::ChildState::/3/c/T/W
STATE TRANSITION: Complex::State_1->Complex::State3::ChildState
Handled EVENT4
Select which event to spawn:
0. ENDEVENT
1. EVENT1
2. EVENT2
3. EVENT3
4. EVENT4
5. INPUTEVENT
6. None
selection: 1
[ EVENT1 ]
NO GUARD on EXTERNAL TRANSITION:/3/c/T/L
EXIT::Complex::State3::ChildState::/3/c/T/W
TRANSITION::ACTION for /3/c/T/L
ENTRY::Complex::State3::ChildState2::/3/c/T/0
STATE TRANSITION: Complex::State3::ChildState->Complex::State3::ChildState2
Handled EVENT1
Select which event to spawn:
0. ENDEVENT
1. EVENT1
2. EVENT2
3. EVENT3
4. EVENT4
5. INPUTEVENT
6. None
selection: 2
[ EVENT2 ]
NO GUARD on EXTERNAL TRANSITION:/3/c/T/j
EXIT::Complex::State3::ChildState2::/3/c/T/0
TRANSITION::ACTION for /3/c/T/j
ENTRY::Complex::State3::ChildState3::/3/c/T/w
STATE TRANSITION: Complex::State3::ChildState2->Complex::State3::ChildState3
Handled EVENT2
Select which event to spawn:
0. ENDEVENT
1. EVENT1
2. EVENT2
3. EVENT3
4. EVENT4
5. INPUTEVENT
6. None
selection: 3
[ EVENT3 ]
NO GUARD on EXTERNAL TRANSITION:/3/c/T/p
EXIT::Complex::State3::ChildState3::/3/c/T/w
TRANSITION::ACTION for /3/c/T/p
ENTRY::Complex::State3::ChildState::/3/c/T/W
STATE TRANSITION: Complex::State3::ChildState3->Complex::State3::ChildState
Handled EVENT3
Select which event to spawn:
0. ENDEVENT
1. EVENT1
2. EVENT2
3. EVENT3
4. EVENT4
5. INPUTEVENT
6. None
selection: 4
[ EVENT4 ]
NO GUARD on EXTERNAL TRANSITION:/3/c/w
EXIT::Complex::State3::ChildState::/3/c/T/W
EXIT::Complex::State3::/3/c/T
TRANSITION::ACTION for /3/c/w
ENTRY::Complex::State_2::/3/c/v
ENTRY::Complex::State_2::ChildState::/3/c/v/K
STATE TRANSITION: Complex::State3->Complex::State_2::Deep_History_Pseudostate
Handled EVENT4
Select which event to spawn:
0. ENDEVENT
1. EVENT1
2. EVENT2
3. EVENT3
4. EVENT4
5. INPUTEVENT
6. None
selection: 4
[ EVENT4 ]
NO GUARD on EXTERNAL TRANSITION:/3/c/Q
EXIT::Complex::State_2::ChildState::/3/c/v/K
EXIT::Complex::State_2::/3/c/v
TRANSITION::ACTION for /3/c/Q
ENTRY::Complex::State3::/3/c/T
ENTRY::Complex::State3::ChildState::/3/c/T/W
STATE TRANSITION: Complex::State_2->Complex::State3::Deep_History_Pseudostate
Handled EVENT4
Select which event to spawn:
0. ENDEVENT
1. EVENT1
2. EVENT2
3. EVENT3
4. EVENT4
5. INPUTEVENT
6. None
selection: 6

Finished

Examples

Example HFSMs included in the Examples Seed:

Simple:

Medium:

Complex:

webgme-hfsm's Issues

Create a context menu for moving a set of states and their transitions into another state

There is currently no easy way (from within the hfsmViz) to move states into another state as its children. For the example above, I cannot easily move Standby and Active into No_Error

in HSFMViz, prevent states that are not children of another state from entering the bounds of that state

Visually it looks that Error is a child of Operational along with the other states, instead of being a child of HighLevelController as shown below.

Update to make HFSMViz's toolbar buttons part of the panel's toolbar

see webgme/webgme#1504

Add a button to lock the hsfmViz layout

Right now it redoes the layout every time a new state is added. Some way of locking the layout so this does not occur would be very useful.

Basic Development Process for complex HFSMs

Develop the entire hfsm hierarchy as a roadmap before implementing well-formed sub-hfsms.

Use the Selected State window in the hfsmViz to determine what states have been fully developed. Untouched states will display red for entry/exit. If a field is intentionally blank, add a space.

Define states from the top down and transitions from the bottom up.

With no transitions defined into a state, it is impossible to reach that state, meaning it can be developed/compiled without affecting the behavior of the working portion of the hsfm.

Add support for a library of states within a project

Acts as a folder of states or of other folders of states. Enables specifying state-machines that can be instanced for reusability.

Update event handler generation for run-time efficiency

Immediately return for all events the model knows the state and its parent tree does not handle.

Slow down gifs in the readme

Currently unnecessarily fast

Enable renaming of events using the event list simulator panel.

Would make having to rename all instances of some event much easier

HFSMViz should support (in some way) display of the Internal Transitions a state has.

Probably should be a pop-up or some other qTip-like dialog so that it doesn't clutter up the UI (and mess with compound node layout / visualization).

Update software generator to generate more generic code; not just specifically for BLE113.

properly position the states in the examples now that we're not defaulting to cose-bilkent

Certain edge cases (pun intended) cause auto-layout to not execute

Cases where the edge is along the hierarchy tree, e.g. parent to child and vice-versa

Will be solved when cytoscape/cytoscape.js-cose-bilkent#48 is solved.

Update decorator to only show red action overlays for states if the isComplete attribute is marked false.

Update opacity for drop targets

So it's not so jarring a transition.

Add visualizer to show all the states nested within parent states

something like

Shrink some of the GIFs in the README

Right now they are from such a high resolution screen that most of the GIF is static / whitespace and the text is hard to read

Update what the scope of transitions / guards are

So that transitions are checked leaf -> root instead of root -> leaf

Create HFSM Viz as standalone nodejs app which internally runs the generated state code for more complete simulation

Can generate test bench code for the state machine to include c++ addon for nodejs related libraries and expose an interface to query the active state, events, and spawn new events and such.

Add support for local transitions

Currently we only support External transitions (due to the rendering limitations of cytoscape.js, see cytoscape/cytoscape.js#1897 )

Once that issue is resolved, update the meta and generators to support local transitions.

Separate build system and platform specific generator code from HFSM language generation

How possible is this? Ideally we would have a few plugins:

• one to handle generation of HFSM into language specific source code
• another to handle generation of build system / platform specific code and build files

These plugins would interact through a well-defined interface to produce the combination of language + build system source code when desired by the user.

show drop-ability when hovering with drag info.

Should style the node that will be the parent to show whether the drop is allowed or not.

Add support for simulation of the HFSM to the HFSMViz

Need panel which shows the available guard conditions, events, and such to allow users to configure them. Then provide buttons to set the conditions / events and tick.

Make HFSMViz droppable, so child creation can use drag+drop from part browser

Allow state machine creation in HFSM Vizualizer

Should allow transitions between any arbitrary state objects regardless of level.

Needs to support at minimum:

• State object creation / removal
• External transition creation / removal
• State object / external transition selection (for edit in property editor)

Fix the indentation on generated code

Meta should conform to UML State Machine specification

Start transitioning META and infrastructure to support better conformance with UML state spec:

Changes:

• Function -> Action
• Initialization -> Entry
• Finalization -> Exit
• Periodic Function -> Tick

Additions:

• Transition Base
• Internal Transition
• Extended States

Add support for internal transitions to meta / decorators

Add support for end-states

Would have the semantics that the timer / task for the HFSM would be cancelled. Since that would provide support for cancelling the dynamic task/timer, we should add support for how to trigger the task/timer without necessarily needing to write it all in code.

Better documentation in README

Add support for orthogonal regions to the HFSM

Need to update meta and decorators / visualizers to support editing and display of these orthogonal regions.

Add history state

So that the previous substate can be saved and resumed later.

Refactor HFSMViz/Simulator to actually call the functions from the decorator instead of just having copies

allow users to add / remove /edit internal transitions in the Selected state display of HFSMViz

Properly handle addition of grandchildren and beyond to hidden nodes.

Add context menu event for multi-selection to arrange items similarly to the webgme options

would be helpful for organizing things like internal transitions.

Add events for transitions into the meta

transitions occur because of events, with optional guards on the events (as in real HFSMs). States can also have functions that occur when events are triggered while they're in the state, and can themselves emit events.

Store the position of states when they're moved by the user (or laid out) into the model

This would make viewing in the modelEditor viz show what the user sees in the HFSMviz and would allow the user to arrange their state machine how they like and save it that way.

internally: will update the position registry for the webgme node according to the position relative to the parent in the viz.

Enable context filtering of transitions based on event

Update HFSMViz to show parent states of selected state as well

That way their internal transitions will be shown as well, so that you can know what events will be handled by a given state and how those events will bubble up.

Allow right-clight menu on state info display in HFSMViz to enable deletion of internal events of states.

Show StateMachine SVG in HFSMViz as state background if the state has children that are hidden

Update code generators to support UML meta spec.

Should properly handle:

• Event code generation : turn events into objects that can be emitted / consumed
• Internal transition generation : allow states to perform actions based on events with optional guards
• Message queue for state machine which allows it to receive and consume events in well defined order
• History and choice pseudostate generation

Allow editing of internal transitions from HFSMViz

Initially, just add object selection when clicking on an internal transition displayed in the HFSMViz, so that the webGME property editor can be used to edit the event / guard

Simulator doesn't fully support chaining together of pseudostates

Choice -> (deep/shallow) history pseudostate
Choice -> End state
Choice -> Choice pseudostate (not currently allowed to create such transitions)

Need some refactoring of the simulator code to handle these edge cases.

Add support for multi-selection to make attribute editing easier.

Needs to support context menus as well.

Properly handle removal of elements in hidden trees.

add terminate and restart events

terminate event: finds active state and call all exits

restart: terminate and then reinitialize

HFSMViz doesn't fully support removal / update of nodes.

When dragging and dropping new objects into the HFSM, set their position according to where they were dropped

If possible, we should do this; might be hard because right now we're relying on this kind of pathway:

1. User drags object over Viz
2. User drop object onto Viz -> triggers a drop event
3. Drop event creates a new commit with WebGME that creates the object in the model
4. WebGME notifies Viz that a new object has been created
5. Viz adds new object from WebGME into HFSM graph

Would need to store the drop information (position, type?) so that when we get an addNode event we can try to figure out where it goes