Sixclear JADE

Overview

The State Machine plugin serves as a configurable programming point for JADE systems by supporting a state machine implementation in configuration. State machines are composed of states which generally can take some “actions” and define logic for if and how to transition to other states. For the State Machine plugin, the “actions” one can specify in a given state are:

• performing computations
• sending messages to:
  – specific plugins (any which support such messages)
  – subscribers (any plugins which have subscribed to the State Machine instance)
  – the command line

This plugin can subscribe to any other plugins and will maintain a cache of that data for use when performing computations or sending messages This overall setup allows the state machine to flow through a defined set of logically controlled states which use any subscription data and any of its own computations.

New to Version 1.2

Version 1.1 adds the ability to delete variables from either the SUB or VAR container. This is provided in the computations section, which now allows for two kinds of objects - one for computing variables (as before) and the new form for deleting variables. Below is an example computation object which would delete variables at paths obj.a and obj.b from the VAR container:

{
    "enable": true,
    "mode": "Delete",
    "container": "VAR",
    "variables": ["obj.a", "obj.b"]
}

User Interface

The State Machine interface is simple by design, containing three strings: one for the Latest Message (displayed on top left), one for the Merged Messages (displayed on the bottom left), and one for displaying the @VAR{} variable container with all computations in it (displayed on the right). The first two are updated as messages are received, the latter is updated whenever computations are performed, and a splitter provides the ability to change how much of each JSON object is shown at a given time. Below we show the State Machine interface with example data:

Subscription Data Handling

The State Machine plugin accepts published JSON messages and displays both the Latest Message and Merged Messages. As data arrives, the State Machine plugin aggregates that data into the Merged Messages object, which is available to states in an @SUB{} variable container. Let’s look at an example to help build our mental model for how subscription data is handled. Suppose the State Machine plugin subscribes to two plugins named MySerialPublisher1 and MySerialPublisher2 which publish temperature and pressure data respectively.

Suppose MySerialPublisher1 publishes:

{
    "instanceName": "MySerialPublisher1",
    "temperature": 22.4,
    "unit": "Celcius"
}

Suppose MySerialPublisher2 publishes:

{
    "instanceName": "MySerialPublisher2",
    "pressure": 148.7,
    "unit": "PSI"
}

When those published messages arrive, the State Machine will look for the special key instanceName which uniquely identifies the source of the data and use its value as a top level key name for storing the incoming data. It does this “namespacing” of sorts to avoid naming collisions in the Merged Messages object. Don’t worry, you can configure the list of such “special keys” in the State Machine’s messageSourceKeyNames configuration option, but almost all publishing plugins use instanceName. In this case, the incoming data results in the following Merged Messages object:

{
    "MySerialPublisher1": {
        "instanceName": "MySerialPublisher1",
        "temperature": 22.4,
        "unit": "Celcius"
    },
    "MySerialPublisher2": {
        "instanceName": "MySerialPublisher2",
        "pressure": 148.7,
        "unit": "PSI"
    }
}

With that data in the @SUB{} variable container, we could - for example - access the temperature from MySerialPublisher1 as @SUB{MySerialPublisher1.temperature}.

Subscription Data Special Cases

Ok, so we know we can handle messages published from plugins who use a special key to identify themselves. Let’s cover some special cases:

1. What happens if data comes in without the special instaneName key?
   In that case, the State Machine will simply put that data under a top level key named __UNKNOWN_MESSAGE__.

2. I know the Worker can publish data such as the statuses of all plugins. How do I subscribe to that data and how does it get set in the Merged Messages object?
   First, the State Machine would need to subscribe to __PLUGIN_INFO__ (literally just add __PLUGIN_INFO__ to the subscribesTo array in configuration). Then the question becomes, what special key does the Worker use to identify itself. The answer is workerName. So as long as the messageSourceKeyNames array in the State Machine’s configuration has workerName in it, you’re all set.

3. What if I want my plugin data to go under a different top level key in Merged Messages?
   Well, the list of special keys are be configured in messageSourceKeyNames. The messageSourceKeyNames (string array) defaults to ["instanceName", "workerName"] to cover the common/standard cases right “out of the box”, but you have full control over this just in case.

4. What if my plugin publishes both an instanceName as well as a uniqueId key, but I want to use the uniqueId instead of the instanceName for the top level key in Merged Messages?
   In this case, you’d just add uniqueId to the front of the messageSourceKeyNames array. When incoming messages are processed, the order of the strings in messageSourceKeyNames determines the order of precedence for which special key gets used. In other words, the first one in the array to be found in the incoming subscription message gets used.

Example

Below is an example of a simple machine definition (the machine snippet of the overall plugin configuration) with two states (Initialize and ToggleRelays) which toggles the states of two relays. The form of the message sent to the Relay Manager instance (below named “Relay Manager”) is of course defined by the Relay Manager itself. Notice the initialState defines where we enter the machine and the states object allows defining the machine’s states.

{
    "initialState": "Initialize",
    "states": {
        "Initialize": {
            "computations": [
                {
                    "enable": true,
                    "mode": "Merge",
                    "variables": {
                        "relayState": false
                    }
                }
            ],
            "messages": [],
            "nextState": "ToggleRelays",
            "transitionDelay": 0
        },
        "ToggleRelays": {
            "computations": [
                {
                    "enable": true,
                    "mode": "Merge",
                    "variables": {
                        "relayState": "Boolean:( !@VAR{relayState} )"
                    }
                }
            ],
            "messages": [
                {
                    "enable": true,
                    "target": "Relay Manager",
                    "message": {
                        "operation": "Update Relays",
                        "data": {
                            "relayStates": [
                                {
                                    "relay": "All Relays.Relay 1",
                                    "state": "Boolean:( @VAR{relayState} )"
                                },
                                {
                                    "relay": "All Relays.Relay 2",
                                    "state": "Boolean:( !@VAR{relayState} )"
                                }
                            ]
                        }
                    }
                }
            ],
            "nextState": "ToggleRelays",
            "transitionDelay": 1000
        }
    }
}

Notice that each state has elements:

• computations is an array of computation objects
• messages is an array of messages to send)
• nextState is a string defining the next state to which to transition
• transitionDelay is the delay to wait until transitioning to the next state

Notice that each message has a target which defines where each message goes:

• __WORKER__ to send a message to the worker
• __SUBSCRIBERS__ to send a message to any subscribers of the state machine
• __TERMINAL__ to issue a command to the command line
• <any plugin instance name> to send a message to any specific plugin by its instance name (but do not include the < and > characters ;-)

Notably, when using the __TERMINAL__ target, the following variables are set and available in the @VAR variable container: __TERMINAL_STANDARD_OUTPUT__, __TERMINAL_STANDARD_ERROR__, __TERMINAL_RETURN_CODE__.

An enable option is also available on computations and messages so that they can be conditionally computed/sent as needed in the application. Also, owing to expression support throughout the entire state machine definition, any option under the machine option can be specified as a string expression with a return type: see the Expression Language documenation for more on this. Further details of the state machine configuration options are captured in the detailed documentation below.

Configuration Example

Configuration Details

[]

[
    "workerName",
    "instanceName"
]

{
    "initialState": "Initialize",
    "states": {
        "Initialize": {
            "computations": [
                {
                    "enable": true,
                    "mode": "Merge",
                    "variables": {
                        "ready": true
                    }
                }
            ],
            "messages": [],
            "nextState": "DoSomething",
            "transitionDelay": 0
        },
        "DoSomething": {
            "computations": [
                {
                    "enable": true,
                    "mode": "Merge",
                    "variables": {
                        "timestamp": "GetDateTime(\"SecondsSinceEpoch\")"
                    }
                }
            ],
            "messages": [],
            "nextState": "DoSomething",
            "transitionDelay": 1000
        }
    }
}

[]

[]

[]

{}