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. Core actions are provided and an extension point is provided for creating custom actions.

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 2.0.0

Version 2.0.0 brings a true action semantic to states. Any number of states can be defined (and named as needed), where each state is configured with “actions” and “nextState”. The “actions” config is an array of actions which the state executes in order. All actions can use subscription data in the SUB container and any computed variables in the VAR container. Provided actions include:

• Delay
• Compute
• Send Message to Plugin
• Send Message to Supervisor
• Publish Message
• Execute Command Line
• and more

This version also adds a uiUpdatePeriod which determines the rate at which the user interface is updated.

Custom actions can be created and referenced in a state machine configuration. When this happens, those VIs are laoded into memory when the plugin instance is run and called according to how they are used in the state machine. All actions have configuration elements: “enable”, “name”, “settings” and optionally “returns” (if the action produces some data which you may wish to compute into the VAR variable container for downstream use).

There are two important states, both of which can be named, which get configured as “initialState” and “shutdownState”. The “initialState” is the first state to run. The “shutdownState” runs when the machine shuts down, for example when the state machine plugin instance is asynchronously shut down. Note that the machine can also intentionally / directly transition to the shutdown state, as the next state, which will cause the specified shutdown state to execute and the state machine execution to stop. Also notably, the state machine plugin instance will remain running, showing its final state of data.

Below is an example of a “machine” portion of a state machine’s configuration which shows how we configure “initialState” and “shutdownState” along with a simple “states” (3 states): “Initialize”, “Loop”, and “Shutdown”.

{
    ...
    "machine": {
        "initialState": "Initialize",
        "shutdownState": "Shutdown",
        "states": {
            "Initialize": {
                "actions": [
                    {
                        "name": "Send Message To Supervisor",
                        "enable": true,
                        "settings": {
                            "message": {
                                "operation": "Instance Run",
                                "data": {
                                    "InstanceName": "Plugin A"
                                }
                            }
                        }
                    }
                ],
                "nextState": "Loop"
            },
            "Loop": {
                "actions": [
                    {
                        "name": "Compute",
                        "enable": true,
                        "settings": {
                            "computations": [ 
                                {
                                    "enable": true,
                                    "mode": "Merge",
                                    "variables": {
                                        "computedValue1": "Rand(0,1)",
                                        "computedValue2": 10.5
                                    }
                                },
                                {
                                    "enable": true,
                                    "mode": "Delete",
                                    "container": "VAR",
                                    "variables": [
                                        "computedValue2"
                                    ]
                                }
                            ]
                        }
                    },
                    {
                        "name": "Delay",
                        "enable": true,
                        "settings": {
                            "waitTime": 1000,
                            "waitUntilNextMsMultiple": false
                        },
                        "returns": {
                            "TickCount": "@RETURNS{TickCount}"
                        }
                    }
                ],
                "nextState": "Loop"
            },
            "Shutdown": {
                "actions": [
                    {
                        "name": "Send Message To Supervisor",
                        "enable": true,
                        "settings": {
                            "message": {
                                "operation": "Instance Run",
                                "data": {
                                    "InstanceName": "Plugin B"
                                }
                            }
                        }
                    }
                ],
                "nextState": ""
            }
        }
    }
}

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.

List of Action Examples

Below is a list of examples of provided actions:

Delay

Delays by a specified amount of time in milliseconds, with an option to instead wait until the next millisecond multiple of the underlying millisecond timer

{
    "name": "Delay",
    "enable": true,
    "settings": {
        "waitTime": 1000,
        "waitUntilNextMsMultiple": false
    },
    "returns": {
        "TickCount": "@RETURNS{TickCount}"
    }
}

Compute

Performs computations into the VAR container, or computations or deletions from the VAR or SUB containers

{
    "name": "Compute",
    "enable": true,
    "settings": {
        "computations": [ 
            {
                "enable": true,
                "mode": "Merge",
                "variables": {
                    "computedValue1": "Rand(0,1)",
                    "computedValue2": 10.5
                }
            },
            {
                "enable": true,
                "mode": "Delete",
                "container": "VAR",
                "variables": [
                    "computedValue2"
                ]
            }
        ]
    }
}

Send Message To Supervisor

Sends a message to the supervisor.

{
    "name": "Send Message To Supervisor",
    "enable": true,
    "settings": {
        "message": {
            "operation": "Instance Run",
            "data": {
                "InstanceName": "Some Plugin Instance Name"
            }
        }
    }
}

Command Line Execute

Executes a command in the command line / prompt / terminal. Note that this is akin to using the Run dialog in Windows so you may need to prefix your desired command in some cases with something like “cmd /c”

{
    "name": "Execute Command Line",
    "enable": true,
    "settings": {
        "command": "cmd /c dir",
        "standardInput": "",
        "waitUntilComplete": true,
        "runMinimized": true,
        "outputbufferSize": 10000,
        "workingDirectory": "C:\\"
    },
    "returns": {
        "WindowsDirCmdResponse": "@RETURNS{standardOutput}"
    }
}

File Open

Opens a file.

With a specified file path (notice the configuration option: settings.path):

{
    "name": "File Open",
    "enable": true,
    "settings": {
        "id": "MyFile",
        "path": "[Desktop]\\myFile.txt",
        "operation": "open or create",
        "access": "write-only",
        "disableBuffering": false
    },
    "returns": {
        "path": "@RETURNS{resolvedPath}",
        "cancelled": "@RETURNS{cancelled}"
    }
}

By prompting the user (notice the configuration option: settings.prompt):

{
    "name": "File Open",
    "enable": true,
    "settings": {
        "id": "MyFile",
        "prompt": "Please select a file...",
        "operation": "open or create",
        "access": "write-only",
        "disableBuffering": false
    },
    "returns": {
        "path": "@RETURNS{resolvedPath}",
        "cancelled": "@RETURNS{cancelled}"
    }
}

File Write Text

Writes text to a file.

{
    "name": "File Write Text",
    "enable": true,
    "settings": {
        "id": "MyFile",
        "text": "This is a test."
    }
}

File Read Text

Reads text from a file.

{
    "name": "File Read Text",
    "enable": true,
    "settings": {
        "id": "MyFile",
        "bytesToRead": 4 // -1 means read all bytes
    },
    "returns": {
        "readText": "@RETURNS{text}"
    }
}

File Set Position

Sets the position / pointer in a file.

{
    "name": "File Set Position",
    "enable": true,
    "settings": {
        "id": "MyFile",
        "offset": 0,
        "from": "start"
    }
}

File Get Position

Gets the position / pointer in a file.

{
    "name": "File Get Position",
    "enable": true,
    "settings": {
        "id": "MyFile"
    },
    "returns": {
        "filePosition": "@RETURNS{filePosition}"
    }
}

File Flush

Sends the command to the operating system to flushes the file contents from any intermediate buffers to disk. Note that it is still possible that the operating system may not immediately write all data to disk.

{
    "name": "File Flush",
    "enable": true,
    "settings": {
        "id": "MyFile"
    }
}

File Delete

Deletes a file or folder. Note that safe mode only applies to folders and will only allow deleting an empty folder.

With a specified file path (notice the configuration option: settings.path):

{
    "name": "File Delete",
    "enable": true,
    "settings": {
        "path": "[Desktop]\\myFile.txt",
        "safeMode": false,
        "askForConfirmation": false
    },
    "returns": {
        "path": "@RETURNS{resolvedPath}",
        "cancelled": "@RETURNS{cancelled}"
    }
}

By prompting the user (notice the configuration option: settings.prompt):

{
    "name": "File Delete",
    "enable": true,
    "settings": {
        "prompt": "Please select a file or folder...",
        "operation": "open or create",
        "access": "write-only",
        "disableBuffering": false
    },
    "returns": {
        "path": "@RETURNS{resolvedPath}",
        "cancelled": "@RETURNS{cancelled}"
    }
}

File Exists

Determines whether a file or folder exists.

{
    "name": "File Exists",
    "enable": true,
    "settings": {
        "path": "[Desktop]\\myFile.txt"
    },
    "returns": {
        "path": "@RETURNS{resolvedPath}",
        "fileExists": "@RETURNS{exists}"
    }
}

File Close

Closes a file.

{
    "name": "File Get Position",
    "enable": true,
    "settings": {
        "id": "MyFile"
    },
    "returns": {
        "filePosition": "@RETURNS{filePosition}"
    }
}

Configuration Example

Configuration Details

[]

[
    "workerName",
    "instanceName"
]

[]

{
    "initialState": "Initialize",
    "shutdownState": "Shutdown",
    "states": {
        "Initialize": {
            "actions": [],
            "nextState": "DoSomething"
        },
        "Shutdown": {
            "actions": [],
            "nextState": ""
        }
    }
}

[]

[]

[]

{}

{}