SSM Framework constitutes two components:

A parser that accepts a user defined hierarchical state machine and generates C++ code
An SSM agent library that links with the generated code and generated state machines. The agent also has the functionality to tie the state machines into a hierarchical structure

Some Definitions

State Machine: A state machine is a labeled directed graph that connects multiple nodes (states) through edges (or transition functions). State machine is an abstract idea on how computations are to be performed against the backdrop of events that can impact the functionality of the system.
Hierarchical State Machine: A state machine design pattern that captures the commonality by reorganizing states into groups in a hierarchy. States that are at the higher level in the hierarchy represent the global states of the parent state machine and the lower-level states represent the individual states of child state machines.
Auto Generated Code: The hierarchical state machine definition is implemented in the form of a JSON file. SSM Framework’s parser tool shall convert the JSON specification into C++ code. This is referred to as the auto generated code.

JSON File Structure

The JSON file captures the following specifications of the state machine hierarchy:

State machine definitions
Hierarchy of state machines
State machine transitions initiated by the parent
Notifications which can be sent between state machines

All the mentioned specifications are captured in a single JSON object:

{
    "StateMachines"     : [<State machine definitions>],
    "Hierarchy"         : [<Hierarchy of the state machines>],
    "ForcedTransitions" : [<State machine transitions initiated by the parent>],
    "Notifications"     : [<Notifications among state machines >]
}

Defining State Machines

State machines are defined in a JSON array under the key "StateMachines". Each object in the array defines a state machine by specifying the following keys:

name: Name of the state machine [String]
states: Array of state names [Strings]
transitions: Array of objects that comprise of ‘from’ and ‘to’ [Strings]
startState: Name of the first state [String]
ipaddress: Default IP address in a multi ECU environment
overrideInit: true; makes the state machine skip the lock stepped init process
broadcastStateChange: indicates that the states of this state machine are important across the system. Interested state machines can subscribe to these updates.
subscribeToStateChanges: Setting this flag to true allows the state machine to subscribe to state change state machines whose “broadcastStateChange” is marked as true.
head: Setting this flag to true sets the respective state machine as the head state machine. There can only be one head state machine in the system

In the following example we define a state machine “SSM” which can have four states (“Standby”, “NormalOperation”, “Degrade”, “UrgentOperation”).

{
    "name": "SSM",
    "states": ["Standby", "NormalOperation", "Degrade", "UrgentOperation"],
    "ipaddress": "127.0.0.1",
    "transitions": [
        {"from":"Standby", "to":"NormalOperation"},
        {"from":"NormalOperation", "to":"Degrade1"},
        {"from":"Degrade1", "to":"UrgentOperation"},
        {"from":"UrgentOperation", "to":"Standby"}
    ],
    "startState": "Standby"
}

Defining Hierarchy of State Machines

State machine hierarchy is defined by providing the mapping between a parent state machine and child state machine by specifying the following keys:

parent: Name of the state machine [String]
childMapping: Array of parent state and children objects
- parentState: Name of the parent’s state [String]
- children: Array of the state machines [Strings]

In the following example we can see how the SSM state machine has been mapped to the SM1 state machine.

[{
    "parent": "SSM",
    "childMapping": [
        {"parentState":"Standby", "children":["SM1"]},
        {"parentState":"NormalOperation", "children":["SM1"]},
        {"parentState":"Degrade1",        "children":["SM1"]},
        {"parentState":"UrgentOperation", "children":["SM1"]}
    ]
}]

Defining Hierarchical Transitions

The following keys specify the transitions a parent state machine can initiate in child state machines:

parent: Name of the state machine [String]
parentState: Name of the parent’s state [String]
child: Name of the child state machine [String]
childStates: Array of objects that contain from and to states [Objects]
from: Child state that a parent can initiate state change from [String]
to: Child state to which the state can change [String]

"HierarchicalTransitions": [{
    "parent": "SM",
    "parentState": "B",
    "child": "AS_B",
    "childStates": [
        {"from":"BB", "to":"BC"},
        {"from":"BC", "to":"BA"}
    ]
}]

Defining Notifications

To specify the messages that a child state machine can send to its parent the following keys must be defined:

origin: Name of the state machine that issues this notification [String]
target: Name of the parent state machine [String]
name: Name of the alert [String]
desc: A string that the child can pass to its parent [String]

"Notifications": [{
    "origin" : "SM",
    "target" : "SSM",
    "name" : "SMAlert",
    "desc" : "desc for the notification"
}]

SSM Framework Library

SSM framework is implemented in the form of a library of classes. The auto generated C++ classes inherit from these classes and provide two interfaces; an SSMClone interface and a Sub Element State Machine (SESM). SSMClone interface is a stateless state machine that simply follows its parent. SESM on the other hand is a stateful state machine that can manage its state while adhering to the state transition semantics of its parent. Refer to the sample code to understand how to use the auto generated code.