Overview

The Port Controller plugin provides a generalized way to quickly and easily integrate devices connected via serial, TCP, GPIB, and USBTMC. It provides both an interface for manually sending commands (backed by a configurable command library) as well as the ability to send an initialization command sequence and a periodically polling command sequence. It also provides subscription handling its own computations for initialization (runs once when the plugin is launched), subscription (runs computations based on specified publishing plugin instances when data arrives), and intermediates (run after every subscription message is handled) sections which allows the plugin to be responsive and dynamic to any subscription data.

When sending initial commands or periodic commands, each command sent can optionally handle a response and compute any important data into a VAR container. An error checking configuration allows specifying a command sequence to run after the initialization command sequence completes and after each periodic polling command sequence pass completes, in order to check the device for errors. A boolean error condition in that section allows for specifying whether an error occurred on the device, where notably that error will be handled by the plugin like any other errors, including writing the error to log files and to the user interface.

If polling is enabled, both publishing and data logging are options. If publishing is enabled, a configurable publish object is provided which may contain any data in the VAR container and of course use inline expressions where helpful. If data logging is enabled, a full logger configuration is provided to store any data in any specified format (ex. in CSV form). Also worth noting is an activity log which tracks the operation of the plugin. This is both stored to file if enabled and also displays in the user interace, including log entries for when the UI has been initialized, when the intiailization command sequence has been sent, the enable state of periodic polling, publishing, data logging, and activity logging, and any commands manually issued by the user. Further operational details are discussed in the Uesr Interface section below.

User Interface

Below we see an example of the plugin’s user interface, which is divided into 3 major sections: left, right, and bottom

The left section is the manual control section. It provides a list of configured commands for the device as helpful documentation for the user, along with a section for sending commands manually and observing any responses.

The right section displays the poll period and also has a button to manually enable/disable polling (this is also configurable of course). Below that we have a view of the current variables which have been computed into the VAR container (the main variable container into which all command, polling, and subscription computations will compute.) And below that we have the latest published data.

The bottom section shows the activity log. This generally tracks the history of important events which occur in the plugin such as initialization, the enable states of polling, publishing, data logging, and activity logging (i.e. whether the plugin is configured to store the activity log to file), as well as any commands and responses issued manually in by the user. It does not capture the poll commands which occur at the poll period, as that would overload the log with periodically sent commands and ultimately make it harder to read (which defeats the purpose of the activity log). If poll commands are enabled, they are occuring at the specified poll period.

Periodic Polling

This plugin may be configured to periodically send commands and/or receive responses from the device or devices connected to the port defined in the connection configuration. The commands specified here effectively call or execute a command from the commandLibrary. More specifically, the polling.commands element is an array of such command calls.

For example, suppose the commandLibrary has the following Fetch Voltage command:

"Fetch Voltage": {
    "description": "Fetches the latest voltage measurement reading from the instrument.",
    "write": {
        "enable": true,
        "template": ":FETCH @PARAM{unit}?\n",
        "example": ":FETCH mV?\n"
    },
    "read": {
        "enable": true,
        "simulationResponse": "+100.234E+00\n",
        "responseRegex": "((?&number))\\s*",
        "responseComputations": [
            {
                "voltage": "@VAR{submatch[0]}"
            }
        ]
    }
}

This command in the commandLibrary takes a single unit parameter, sends a command, and parses the response to extract the returned voltage while assigning it to a variable named voltage into the VAR container. This is a key point: library commands can compute variables directly into the VAR container for us. As we shall see, we have the opportunity to perform further computations when we call such library commands. Below is how we can use this library command in the polling.commands section, where we perform a further computation on the voltage to transform it from units of mV to Volts (just to show this):

{
    "name": "Fetch Voltage",
    "parameters": {
        "unit": "mV" // we ask the instrument for the measurement in millivolts
    },
    "responseComputations": [
        "voltageInVolts": "Float:(@VAR{voltage} / 1000)" // we compute a new variable which stores the voltage in Volts
    ],
    "delayAfter": 0
}

Now, the possible units will be dictated by the instrument, of course, but we get to specify the library function name, parameters, responseComputations, and delayAfter (which is a value in milliseconds).

Incoming Message Handling

This plugin accepts messages to facilitate sending commands to the connected device. For example, we could use a State Machine plugin instance to send a message to this plugin. All messages handled by this plugin must be in JSON format and have a top level data key and should also have an operation key, although messages which do not include it will be treated as arriving subscription data. If the operation key is “Send Library Commands”, then data is an array of “command calls” with the same format as described in the polling section above. If an operation key is either not included, or anything other than “Send Library Commands”, then the incoming message is treated as a subsscription message and is handled by the subscriptionHandling section of configuration described below.

Send Library Command

The Send Library Command message allows sending any command configured in the plugin instance’s commandLibrary. On the one hand, the commandLibrary is intended to ease manually sending commands to the connected device or using the polling section. But those library commands can also be issued remotely (from other plugins) by sending a Send Library Command message to this plugin.

Let’s see an example of the message format the Port Controller plugin expects in order to execute commands sent from some other plugin. Much like the polling section described above, we expect to receive an array of command calls.

{
    "operation": "Send Library Command",
    "data": [
        {
            "name": "Fetch Voltage", // name of a command in the commandLibrary
            "parameters": {
                "unit": "mV" // we ask the instrument for the measurement in millivolts
            },
            "responseComputations": [
                "voltageInVolts": "Float:(@VAR{voltage} / 1000)" // we compute a new variable which stores the voltage in Volts
            ],
            "delayAfter": 0
        }
    ]

Subscription Handling

Any message received from another plugin which doesn’t have an operation key equal to Send Library Command will be treated as a subscription message. For subscription messages, we simply have the opportunity to compute subscription data into our VAR variable container. Suppose we subscribed to a plugin instance named “My Publisher” which sends messages with the form of the example below:

{
    "instanceName": "My Publisher",
    "voltage": 7.5
}

Then in the subscriptionHandling.computations section we could compute the received voltage into our VAR container. Arriving data is placed into a SUB variable container, and we specify how to handle subscriptions from a given source as shown in the example snippet below:

"subscriptionHandling": {
    "computations": {
        ...
        "subscriptions": {

            "My Publisher": {
                "MyPublishervoltage": "Float:(@SUB{voltage})"
            }

        },
        ...
    }
}

Notice that under the subscriptions key we have keys whose names must match the instanceName of the sender. Under that key, we can then assign or compute the incoming subscription values.

Configuration Example

Configuration Details

[]

{
    "Type": "TCP",
    "SimulationMode": true,
    "Address": "TCPIP0::192.168.1.1::54321::SOCKET",
    "Timeout": 2000,
    "TerminationEnable": true,
    "TerminationCharacter": "\n",
    "TrimResponseWhiteSpace": true,
    "BytesToRead": 1000,
    "ReadToFileEnable": false,
    "ReadToFilePath": "",
    "DuplicateSession": false,
    "AccessMode": "VISA Defaults"
}

[]

{}

[]

[]

[]

[]

[]

[]

[]

[]

[]