New in Version 1.2

• fixes a bug where initialization code was expecting initialization.computations instead of initialization.variables as was defined in schema.
• now, if a command in the initialization or shutdown command sequence is an empty string, the command will not be sent but the computations defined for that command will be processed.
• adds a shutdown command sequence which is similar to the initialization command sequence but instead runs once when the plugin is shut down. Commands have the same form as the initialization sequence and the shutdown sequence is defind under shutdown.commands (currently, commands is the only key under the new shutdowns).

Overview

The VISA 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 periodically polling command sequence. When initializing or periodically polling, 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 (ex. in CSV form). Also worth noting is an activity log which tracks the operation of the plugin. This is stored to file if enabled but also updates the user interace with indications of 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 resizable sections.

The top 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. Note that the poll period displayed there applies to the configured poll commands as discussed above.

The top right section shows the current published data. This is configurable as discussed above.

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.

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 this plugin a message. All messages handled by this plugin are in JSON format and have top level operation and data keys.

The operation is simply the name of the message (telling the plugin what kind of action it should take) and data is any data needed by the operation. Data is often a JSON object but needn’t be in the general case.

Let’s see an example message to help set our mental model (notice the top level operation and data elements below):

{
     <span style="color:yellow">"operation"</span>: "Send Library Command",
     <span style="color:yellow">"data"</span>: {
        "name": "Set Voltage DC",
        "parameters": {
            "channel": "1",
            "voltage": "5.2"
        },
        "hasReponse": false
    }
}

Below are the messages or “operations” currently handled by this plugin.

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. But those library commands can also be issued remotely (from other plugins) by sending a Send Library Command message to this plugin.

Let’s take another look at the example we showed above where we’ll highlight important values:

{
    "operation": <span style="color:yellow">"Send Library Command"</span>,
    "data": {
        "name": <span style="color:yellow">"Set Voltage DC"</span>,
        "parameters": {
            <span style="color:yellow">"channel": "1"</span>,
            <span style="color:yellow">"voltage": "5.2</span>"
        },
        "hasReponse": false
    }
}

Observe that the operation is Send Library Command. Also observe that the data seems to want to send a command named Set Voltage DC with channel and voltage parameters set to 1 and 5.2 repsectively.

The question becomes: how does the plugin know what precise command syntax to send to the device? The answer lies in the commandLibrary configuration, an example of which we show here:

[
    {
        "name": "Query Identification String",
        "template": "*IDN?",
        "description": "Queries for the device's identification string.",
        "example": "*IDN?",
        "sampleResponse": "KORAD KC4305 v2.1"
    },
    {
        "name": <span style="color:yellow">"Set Voltage DC"</span>,
        "template": "VSET<span style="color:yellow">@VAR{channel}</span>:<span style="color:yellow">@VAR{voltage}</span>",
        "description": "Gets the DC voltage of the specified channel.",
        "example": "VSET1:1.0",
        "sampleResponse": ""
    }
]

Notice the last configured library command seems to allow us to set the DC voltage on the device. Furthermore, notice that the name of the command is Set Voltage DC and the template element has a device command with variables in it, @VAR{channel} and @VAR{voltage}, where the command can be parameterized.

We now see how the message corresponds to a Command Library entry:

1. The name uniquely identifies the command in the library, and
2. The template has the command syntax with variables in places where the command can be parameterized.

Said differently, the parameters object specified in the message acts as a little variable container to use with the template. In this case the template is VSET@VAR{channel}:@VAR{voltage} resulting in the command syntax: VSET1:5.2.

Send Raw Command

The Send Raw Command message allows sending any raw command to the device. With that in mind, let’s see how we could send the same command to the device we saw above, but this time assuming this plugin has received a Send Raw Command message:

{
    "operation": <span style="color:yellow">"Send Raw Command"</span>,
    "data": {
        <span style="color:yellow">"command"</span>: "VSET1:5.2",
        "hasReponse": false
    }
}

Notice that we’ve simply specified the precise command to send to the device. In a sense it’s simpler than the Send Library Command message because we aren’t worried about getting the name and parameters matched up to the Command Library entry. On the other hand, it requires that we encode the precise device command syntax into the message and therefore isn’t as interchangeable (it’s not uncommon to support the same library command “surface area” for multiple devices of the same “kind” so that they can be interchangeable in the system).

What about the hasResponse key we see in message data?

In the above message examples, the hasResponse element is set to false. This is because the device does not return a response to the messages in those examples. If the device had returned a response, we would want to set this to true to ensure that the response is read from the underlying “read buffer”. Failing to do so would cause this response to “hang around” in the read buffer and would then be incorrectly returned as the response to any future command.

Importantly, responses from the connnected device are not currently relayed to the sender of the message. That is, if a State Machine plugin instance had sent a Send Library Command or Send Raw Command message to this plugin with a device command that solicited a response from the connected device, that response would not be returned to the State Machine plugin instance. This feature is coming soon and will be facilitated by a later release of this plugin (along with updates to other plugins).

Configuration Example

Configuration Details

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

[
    {
        "name": "Query Identification String",
        "template": "*IDN?",
        "description": "Queries for the device's identification string.",
        "example": "*IDN?",
        "sampleResponse": "Instrument ABC v1.3"
    },
    {
        "name": "Reset",
        "template": "*RST",
        "description": "Resets the device but does not necessarily clear out errors.",
        "example": "*RST",
        "sampleResponse": "(no response)"
    },
    {
        "name": "Clear Errors",
        "template": "*CLS",
        "description": "Clears device errors.",
        "example": "*CLS",
        "sampleResponse": "(no response)"
    },
    {
        "name": "Get Voltage (DC)",
        "template": "MEASure:VOLTage:DC?",
        "description": "Gets the DC voltage.",
        "example": "MEASure:VOLTage:DC?",
        "sampleResponse": "1.5 V"
    },
    {
        "name": "Get Current (DC)",
        "template": "MEASure:CURRent:DC?",
        "description": "Gets the DC current.",
        "example": "MEASure:CURRent:DC?",
        "sampleResponse": "0.25 mA"
    }
]

{
    "initialValue1": 10,
    "initialValue2": "interesting_thing"
}

[
    {
        "command": "*CLS",
        "hasResponse": false,
        "simulationResponse": "",
        "responseRegex": "",
        "responseComputations": []
    },
    {
        "command": "*IDN?",
        "hasResponse": true,
        "simulationResponse": "Instrument ABC v1.3",
        "responseRegex": "(.+)",
        "responseComputations": [
            {
                "instrumentName": "@VAR{submatch[0]}"
            }
        ]
    }
]

[]

[
    {
        "command": "*CLS",
        "hasResponse": false,
        "simulationResponse": "",
        "responseRegex": "",
        "responseComputations": []
    },
    {
        "command": "*IDN?",
        "hasResponse": true,
        "simulationResponse": "Instrument ABC v1.3",
        "responseRegex": "(.+)",
        "responseComputations": [
            {
                "instrumentName": "@VAR{submatch[0]}"
            }
        ]
    }
]

[]

[
    {
        "command": "SYSTem:ERRor?",
        "hasResponse": true,
        "simulationResponse": "0 No Error",
        "responseRegex": "(-?\\d+)\\s*(.*)",
        "responseComputations": [
            {
                "errorCode": "@VAR{submatch[0]}",
                "errorMessage": "@VAR{submatch[1]}"
            },
            {
                "errorStatus": "Boolean:( @VAR{errorCode} != 0 )"
            }
        ]
    }
]

[]

[
    {
        "command": "MEASure:VOLTage:DC?",
        "hasResponse": true,
        "simulationResponse": "RAND(0,1)",
        "responseRegex": "((?&number))",
        "responseComputations": [
            {
                "voltage": "@VAR{submatch[0]}",
                "timestamp": "GetDateTime(\"%Y-%m-%d %H-%M-%S%3u\")"
            }
        ]
    },
    {
        "command": "MEASure:CURRent:DC?",
        "hasResponse": true,
        "simulationResponse": "RAND(0,1)",
        "responseRegex": "((?&number))",
        "responseComputations": [
            {
                "current": "@VAR{submatch[0]}"
            }
        ]
    }
]

[]

{
    "instanceName": "@VAR{instanceName}",
    "data": "`Object:(@VAR{})`",
    "voltage": "@VAR{voltage}",
    "current": "@VAR{current}"
}