@sixclear/visa-controller
VISA Controller v1.5.0

New in Version 1.5

This version explicitly mutexes port commmunication across the message handling and polling loops.

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):

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:

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:

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:

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

Plugin Defaults
0
0
0

Configuration Details

Filter:Search in:
ROOT object
This top level object holds all configuration information for this plugin.
Required: true
Default: (not specified; see any element defaults within)
options object
Configuration options specific to this plugin. Note that variables and expressions are generally allowed in this section.
Required: true
Default: (not specified; see any element defaults within)
options.connectionConfiguration object
Defines the VISA connection configuration.
Required: true
Default: 
{
    "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"
}
options.connectionConfiguration::{TCP|GPIB|USBTMC} object
An object defining a VISA connection configuration for a TCP, GPIB, or USBTMC device.
Required: false
Default: (not specified; see any element defaults within)
options.connectionConfiguration::{TCP|GPIB|USBTMC}.Type enum (string)
The type of connection.
Required: true
Default: "TCP"
Enum Items: "TCP" | "GPIB" | "USBTMC"
options.connectionConfiguration::{TCP|GPIB|USBTMC}.SimulationMode boolean
Whether to run the plugin in simulation mode. See simulationLoopDelay and simluationResponse above, as well as responseRegex.
Required: true
Default: true
options.connectionConfiguration::{TCP|GPIB|USBTMC}.Address stringarray
The address of the connection / port (ex. COM1, GPIB1::3::INSTR, TCPIP1::192.168.1.1::54321::SOCKET, USB0::0x2EC7::0x6900::800774011787410049::INSTR, etc.), or an array of such addresses. If an array is specified, the plugin uses the first address in the list to successfully open a connection. If none in the array succeed, an error is generated.
Required: true
Default: "TCPIP1::192.168.1.1::54321::SOCKET"
options.connectionConfiguration::{TCP|GPIB|USBTMC}.Timeout integer
The timeout duration in milliseconds used for write and read operations.
Required: true
Default: 2000
options.connectionConfiguration::{TCP|GPIB|USBTMC}.TerminationEnable boolean
Whether to look for termination characters in responses.
Required: true
Default: true
options.connectionConfiguration::{TCP|GPIB|USBTMC}.TerminationCharacter string
The termination character to look for (if termination is enabled).
Required: true
Default: "\n"
options.connectionConfiguration::{TCP|GPIB|USBTMC}.TrimResponseWhiteSpace boolean
Whether to trim whitespace from responses.
Required: true
Default: true
options.connectionConfiguration::{TCP|GPIB|USBTMC}.BytesToRead integer
The number of bytes to read when reading responses. Note: read operations will terminate on: 1. a termination character, 2. on timeout, 3. on receiving BytesToRead number of bytes.
Required: true
Default: 1000
options.connectionConfiguration::{TCP|GPIB|USBTMC}.ReadToFileEnable boolean
Wehther to enable reading responses directly to a specified file.
Required: true
Default: false
options.connectionConfiguration::{TCP|GPIB|USBTMC}.ReadToFilePath string
The file path to read responses into (if ReadToFileEnable is true).
Required: true
Default: ""
options.connectionConfiguration::{TCP|GPIB|USBTMC}.DuplicateSession boolean
Whether to duplicate the session.
Required: true
Default: true
options.connectionConfiguration::{TCP|GPIB|USBTMC}.AccessMode enum (string)
The access mode to use when opening the VISA session: VISA Defaults, Exclusive Lock, Load Configured Settings.
Required: true
Default: "VISA Defaults"
Enum Items: "VISA Defaults" | "Exclusive Lock" | "Load Configured Settings"
options.connectionConfiguration::{Serial} object
An object defining a VISA connection configuration for a TCP, GPIB, or USBTMC device.
Required: false
Default: (not specified; see any element defaults within)
options.connectionConfiguration::{Serial}.Type enum (string)
The type of connection.
Required: true
Default: "Serial"
Enum Items: "Serial"
options.connectionConfiguration::{Serial}.SimulationMode boolean
Whether to run the plugin in simulation mode. See simulationLoopDelay and simluationResponse above, as well as responseRegex.
Required: true
Default: true
options.connectionConfiguration::{Serial}.Address string
The address of the serial port.
Required: true
Default: "COM1"
options.connectionConfiguration::{Serial}.Timeout integer
The timeout duration in milliseconds used for write and read operations.
Required: true
Default: 2000
options.connectionConfiguration::{Serial}.TerminationEnable boolean
Whether to look for termination characters in responses.
Required: true
Default: true
options.connectionConfiguration::{Serial}.TerminationCharacter string
The termination character to look for (if termination is enabled).
Required: true
Default: "\n"
options.connectionConfiguration::{Serial}.TrimResponseWhiteSpace boolean
Whether to trim whitespace from responses.
Required: true
Default: true
options.connectionConfiguration::{Serial}.BytesToRead integer
The number of bytes to read when reading responses. Note: read operations will terminate on: 1. a termination character, 2. on timeout, 3. on receiving BytesToRead number of bytes.
Required: true
Default: 1000
options.connectionConfiguration::{Serial}.ReadToFileEnable boolean
Wehther to enable reading responses directly to a specified file.
Required: true
Default: false
options.connectionConfiguration::{Serial}.ReadToFilePath string
The file path to read responses into (if ReadToFileEnable is true).
Required: true
Default: ""
options.connectionConfiguration::{Serial}.BaudRate integer
The baud rate to use for serial communication. The available baud rates depend on the serial interface. Common baud rates include: 300, 600, 1200, 2400, 4800, 9600, 38400, 14400, 19200, 57600, 230400, 115200, 460800. Less common though not terrifically uncommon baud rates include: 100, 28800, 56000, 128000, 153600, 256000, 921600.
Required: true
Default: 9600
options.connectionConfiguration::{Serial}.DataBits enum (integer)
The number of data bits used for underlying character encoding for transmission.
Required: true
Default: 8
Enum Items: 5 | 6 | 7 | 8
options.connectionConfiguration::{Serial}.StopBits enum (string)
The number of bits which indicate the end of a given character transmission.
Required: true
Default: "1.0"
Enum Items: "1.0" | "1.5" | "2.0"
options.connectionConfiguration::{Serial}.Parity enum (string)
The parity or error checking convention to use.
Required: true
Default: "None"
Enum Items: "None" | "Odd" | "Even" | "Mark" | "Space"
options.connectionConfiguration::{Serial}.FlowControl string
The flow control convention to use.
Required: true
Default: "None"
options.connectionConfiguration::{Serial}.DuplicateSession boolean
Whether to duplicate the session.
Required: true
Default: true
options.connectionConfiguration::{Serial}.AccessMode enum (string)
The access mode to use when opening the VISA session: VISA Defaults, Exclusive Lock, Load Configured Settings.
Required: true
Default: "VISA Defaults"
Enum Items: "VISA Defaults" | "Exclusive Lock" | "Load Configured Settings"
options.commandLibrary array
An array of commands to load into the dropdown in the user interface.
Required: true
Default: 
[
    {
        "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"
    }
]
options.commandLibrary[n] object
A command to include in the dropdown on the user interface.
Required: false
Default: ""
options.commandLibrary[n].name string
A semantic name for the command to show in the dropdown.
Required: false
Default: ""
options.commandLibrary[n].template string
A template for the command. For example, a command that sets a voltage on a device might have a template such as `SETVOLT @voltage` where `SETVOLT` is the name of the command which takes a paramter (presumably some number) represented in the template as @voltage.
Required: false
Default: ""
options.commandLibrary[n].description string
The description of the command. This should include information about which parameters are accepted and the expected format of any response.
Required: false
Default: ""
options.commandLibrary[n].example string
A example of valid syntax using this command.
Required: false
Default: ""
options.commandLibrary[n].sampleResponse string
An example of a response to this command.
Required: false
Default: ""
options.initialization object
An object containing initialization options.
Required: true
Default: (not specified; see any element defaults within)
options.initialization.variables object
A computation object where keys are JSON paths and values can be of any type and use expressions and functions, and is computed one time when the plugin launches. For example: { "exmapleVar1": 10, "exampleVar2": "kitty" } would make available variables @VAR{exampleVar1} with value 10 and @VAR{exampleVar2} with value "kitty". Note that `instanceName` and `startTimestamp` are already in the container.
Required: true
Default: 
{
    "initialValue1": 10,
    "initialValue2": "interesting_thing"
}
options.initialization.variables.{Valid JSON Set Path} stringnumberbooleanarrayobject
undefined
Required: false
Default: ""
options.initialization.commands array
An array of initialization commands to send. These commands are only sent once when the plugin initializes.
Required: true
Default: 
[
    {
        "command": "*CLS",
        "hasResponse": false,
        "simulationResponse": "",
        "responseRegex": "",
        "responseComputations": [],
        "delayAfter": 0
    },
    {
        "command": "*IDN?",
        "hasResponse": true,
        "simulationResponse": "Instrument ABC v1.3",
        "responseRegex": "(.+)",
        "responseComputations": [
            {
                "instrumentName": "@VAR{submatch[0]}"
            }
        ],
        "delayAfter": 0
    }
]
options.initialization.commands[n] object
An object defining an initialization command to send.
Required: false
Default: (not specified; see any element defaults within)
options.initialization.commands[n].command string
A command.
Required: true
Default: ""
options.initialization.commands[n].hasResponse boolean
Whether the command has a response.
Required: true
Default: false
options.initialization.commands[n].simulationResponse string
The response to return when in simulation mode.
Required: true
Default: ""
options.initialization.commands[n].responseRegex string
The regular expression to use to parse the response. The group / submatches defined in the regex are then available to computations below as variables such as: @VAR{submatch[n]) where n is an integer index representing the 0-based order in which the submatches occurred in the regex. For example, if we have a regex like (ABC)(.+) then @VAR{submatch[0]} is ABC and @VAR{submatch[1]} is whatever matched the .+ part of the regex. Note that the named regex (?&number) is available for use and matches numbers flexibly in integer, floating point, and scientific notation' formats. For example, (?&number) would match each of the following: 12, 12.5, 1.25E1. Note that this setting also applies to the simluationResponse when in simulation mode.
Required: true
Default: ""
options.initialization.commands[n].responseComputations array
An array of computation objects to be performed after both the command is sent and (if there is a response) the response is received. Parsed @VAR{submatch[n]} variables are available here. All data is put into a VAR container for subsequent access.
Required: true
Default: 
[]
options.initialization.commands[n].responseComputations[n] object
A computation object where keys are JSON paths and values can be of any type and use expressions, functions, and variables.
Required: false
Default: (not specified; see any element defaults within)
options.initialization.commands[n].responseComputations[n].{Valid JSON Set Path} stringnumberbooleanarrayobject
undefined
Required: false
Default: ""
options.initialization.commands[n].delayAfter integer
The time in milliseconds to delay after sending the command and processing any response. This can be useful in some applications where, for example, an instrument requires a delay between consecutive commands.
Required: true
Default: 0
options.shutdown object
An object containing shutdown options.
Required: true
Default: (not specified; see any element defaults within)
options.shutdown.commands array
An array of shutdown commands to send. These commands are only sent once when the plugin shuts down.
Required: true
Default: 
[
    {
        "command": "*CLS",
        "hasResponse": false,
        "simulationResponse": "",
        "responseRegex": "",
        "responseComputations": [],
        "delayAfter": 0
    },
    {
        "command": "*IDN?",
        "hasResponse": true,
        "simulationResponse": "Instrument ABC v1.3",
        "responseRegex": "(.+)",
        "responseComputations": [
            {
                "instrumentName": "@VAR{submatch[0]}"
            }
        ],
        "delayAfter": 0
    }
]
options.shutdown.commands[n] object
An object defining an initialization command to send.
Required: false
Default: (not specified; see any element defaults within)
options.shutdown.commands[n].command string
A command.
Required: true
Default: ""
options.shutdown.commands[n].hasResponse boolean
Whether the command has a response.
Required: true
Default: false
options.shutdown.commands[n].simulationResponse string
The response to return when in simulation mode.
Required: true
Default: ""
options.shutdown.commands[n].responseRegex string
The regular expression to use to parse the response. The group / submatches defined in the regex are then available to computations below as variables such as: @VAR{submatch[n]) where n is an integer index representing the 0-based order in which the submatches occurred in the regex. For example, if we have a regex like (ABC)(.+) then @VAR{submatch[0]} is ABC and @VAR{submatch[1]} is whatever matched the .+ part of the regex. Note that the named regex (?&number) is available for use and matches numbers flexibly in integer, floating point, and scientific notation' formats. For example, (?&number) would match each of the following: 12, 12.5, 1.25E1. Note that this setting also applies to the simluationResponse when in simulation mode.
Required: true
Default: ""
options.shutdown.commands[n].responseComputations array
An array of computation objects to be performed after both the command is sent and (if there is a response) the response is received. Parsed @VAR{submatch[n]} variables are available here. All data is put into a VAR container for subsequent access.
Required: true
Default: 
[]
options.shutdown.commands[n].responseComputations[n] object
A computation object where keys are JSON paths and values can be of any type and use expressions, functions, and variables.
Required: false
Default: (not specified; see any element defaults within)
options.shutdown.commands[n].responseComputations[n].{Valid JSON Set Path} stringnumberbooleanarrayobject
undefined
Required: false
Default: ""
options.shutdown.commands[n].delayAfter integer
The time in milliseconds to delay after sending the command and processing any response. This can be useful in some applications where, for example, an instrument requires a delay between consecutive commands.
Required: true
Default: 0
options.errorChecking object
An object containing error checking options.
Required: true
Default: (not specified; see any element defaults within)
options.errorChecking.commands array
An array of commands which check for errors.
Required: true
Default: 
[
    {
        "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 )"
            }
        ],
        "delayAfter": 0
    }
]
options.errorChecking.commands[n] object
An object defining a command to send to check for errors.
Required: false
Default: (not specified; see any element defaults within)
options.errorChecking.commands[n].command string
A command.
Required: true
Default: ""
options.errorChecking.commands[n].hasResponse boolean
Whether the command has a response.
Required: true
Default: false
options.errorChecking.commands[n].simulationResponse string
The response to return when in simulation mode.
Required: true
Default: ""
options.errorChecking.commands[n].responseRegex string
The regular expression to use to parse the response. The group / submatches defined in the regex are then available to computations below as variables such as: @VAR{submatch[n]) where n is an integer index representing the 0-based order in which the submatches occurred in the regex. For example, if we have a regex like (ABC)(.+) then @VAR{submatch[0]} is ABC and @VAR{submatch[1]} is whatever matched the .+ part of the regex. Note that the named regex (?&number) is available for use and matches numbers flexibly in integer, floating point, and scientific notation' formats. For example, (?&number) would match each of the following: 12, 12.5, 1.25E1. Note that this setting also applies to the simluationResponse when in simulation mode.
Required: true
Default: ""
options.errorChecking.commands[n].responseComputations array
An array of computation objects to be performed after both the command is sent and (if there is a response) the response is received. Parsed @VAR{submatch[n]} variables are available here. All data is put into a VAR container for subsequent access.
Required: true
Default: 
[]
options.errorChecking.commands[n].responseComputations[n] object
A computation object where keys are JSON paths and values can be of any type and use expressions, functions, and variables.
Required: false
Default: (not specified; see any element defaults within)
options.errorChecking.commands[n].responseComputations[n].{Valid JSON Set Path} stringnumberbooleanarrayobject
undefined
Required: false
Default: ""
options.errorChecking.commands[n].delayAfter integer
The time in milliseconds to delay after sending the command and processing any response. This can be useful in some applications where, for example, an instrument requires a delay between consecutive commands.
Required: true
Default: 0
options.errorChecking.condition stringboolean
An expression which evaluates to true if the device has an error, or false otherwise.
Required: true
Default: "Boolean:( @VAR{errorStatus} )"
options.polling object
An object containing polling options.
Required: true
Default: (not specified; see any element defaults within)
options.polling.enable boolean
Whether to poll the device.
Required: false
Default: true
options.polling.period integer
The period with which the plugin polls the device with the specified commands. Use -1 here to disable polling.
Required: true
Default: 1000
options.polling.commands array
An array of commands to send at the poll period.
Required: true
Default: 
[
    {
        "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\")"
            }
        ],
        "delayAfter": 0
    },
    {
        "command": "MEASure:CURRent:DC?",
        "hasResponse": true,
        "simulationResponse": "RAND(0,1)",
        "responseRegex": "((?&number))",
        "responseComputations": [
            {
                "current": "@VAR{submatch[0]}"
            }
        ],
        "delayAfter": 0
    }
]
options.polling.commands[n] object
An object defining a command to send at the poll period.
Required: false
Default: (not specified; see any element defaults within)
options.polling.commands[n].command string
A command.
Required: true
Default: ""
options.polling.commands[n].hasResponse boolean
Whether the command has a response.
Required: true
Default: false
options.polling.commands[n].simulationResponse string
The response to return when in simulation mode.
Required: true
Default: ""
options.polling.commands[n].responseRegex string
The regular expression to use to parse the response. The group / submatches defined in the regex are then available to computations below as variables such as: @VAR{submatch[n]) where n is an integer index representing the 0-based order in which the submatches occurred in the regex. For example, if we have a regex like (ABC)(.+) then @VAR{submatch[0]} is ABC and @VAR{submatch[1]} is whatever matched the .+ part of the regex. Note that the named regex (?&number) is available for use and matches numbers flexibly in integer, floating point, and scientific notation' formats. For example, (?&number) would match each of the following: 12, 12.5, 1.25E1. Note that this setting also applies to the simluationResponse when in simulation mode.
Required: true
Default: ""
options.polling.commands[n].responseComputations array
An array of computation objects to be performed after both the command is sent and (if there is a response) the response is received. Parsed @VAR{submatch[n]} variables are available here. All data is put into a VAR container for subsequent access.
Required: true
Default: 
[]
options.polling.commands[n].responseComputations[n] object
A computation object where keys are JSON paths and values can be of any type and use expressions, functions, and variables.
Required: false
Default: (not specified; see any element defaults within)
options.polling.commands[n].responseComputations[n].{Valid JSON Set Path} stringnumberbooleanarrayobject
undefined
Required: false
Default: ""
options.polling.commands[n].delayAfter integer
The time in milliseconds to delay after sending the command and processing any response. This can be useful in some applications where, for example, an instrument requires a delay between consecutive commands.
Required: true
Default: 0
options.polling.publishing object
An object containing publishing options.
Required: true
Default: (not specified; see any element defaults within)
options.polling.publishing.enable boolean
Whether to publish data.
Required: true
Default: true
options.polling.publishing.dataFormat object
This object specifies the format of the published data. Data is only published if polling is enabled and publishing is enabled.
Required: true
Default: 
{
    "instanceName": "@VAR{instanceName}",
    "data": "`Object:(@VAR{})`",
    "voltage": "@VAR{voltage}",
    "current": "@VAR{current}"
}
options.polling.logging object
Defines the logging (data and errors) for this plugin. Note that a LOG variable space is provided here, as well as the VAR variable space. Available variables are: @LOG{LOGGERNAME}, @LOG{TIMESTAMP}, @LOG{LOGMESSAGE}, @LOG{ERRORMESSAGE}, @VAR{instanceName}. Note: @LOG{LOGGERNAME} is equal to the @VAR{instanceName} here.
Required: false
Default: (not specified; see any element defaults within)
options.polling.logging.Enable boolean
Whether to enable the logger.
Required: true
Default: true
options.polling.logging.LogFolder string
The folder in which to write log files.
Required: true
Default: "\\JADE_LOGS\\@VAR{instanceName}"
options.polling.logging.FileNameFormat string
The filename to use when creating log files. Note: if the filesize limit is reached new files will be created with enumerated suffixes such as: MyLogFile-1.txt, MyLogFile-2.txt, etc.
Required: true
Default: "@VAR{instanceName}-@LOG{TIMESTAMP}.csv"
options.polling.logging.ErrorsOnly boolean
Whether to log only errors.
Required: true
Default: false
options.polling.logging.DiskThrashPeriod integer
The period in milliseconds with which to flush the file buffer to ensure it's committed to the hard drive. Note: This is a performance consideration to prevent writing to disk too frequently.
Required: true
Default: 1000
options.polling.logging.FileSizeLimit integer
The file size at which to create new files.
Required: true
Default: 1000000
options.polling.logging.StartLogFormat string
The initial string to put into the log file (and subsequent files) when opened for the first time.
Required: true
Default: "Timestamp,Voltage,Current"
options.polling.logging.LogMessageFormat string
The message format used to construct non-error log entries. All VAR container data is available here.
Required: true
Default: "\n@VAR{timestamp},@VAR{voltage},@VAR{current}"
options.polling.logging.EndLogFormat string
The final string to put in the log file when closed.
Required: true
Default: ""
options.polling.logging.LogEntryFormat string
The format to use when writing log entries when errors are not present.
Required: true
Default: "@LOG{LOGMESSAGE}"
options.polling.logging.ErrorLogEntryFormat string
The message format used to construct error log entries.
Required: true
Default: "\n\n@LOG{ERRORMESSAGE}\n\n"
options.polling.logging.TimestampFormat string
The format used by the @LOG{TIMESTAMP} variable.
Required: true
Default: "%Y-%m-%d %H-%M-%S%3u"
options.activityLogger object
Defines the logging (data and errors) for this plugin. Note that a LOG variable space is provided here, as well as the VAR variable space. Available variables are: @LOG{LOGGERNAME}, @LOG{TIMESTAMP}, @LOG{LOGMESSAGE}, @LOG{ERRORMESSAGE}, @VAR{instanceName}. Note: @LOG{LOGGERNAME} is equal to the @VAR{instanceName} here.
Required: true
Default: (not specified; see any element defaults within)
options.activityLogger.Enable boolean
Whether to enable the logger.
Required: true
Default: true
options.activityLogger.LogFolder string
The folder in which to write log files.
Required: true
Default: "\\JADE_LOGS\\@VAR{instanceName}"
options.activityLogger.FileNameFormat string
The filename to use when creating log files. Note: if the filesize limit is reached new files will be created with enumerated suffixes such as: MyLogFile-1.txt, MyLogFile-2.txt, etc.
Required: true
Default: "@VAR{instanceName}-@LOG{TIMESTAMP}.csv"
options.activityLogger.ErrorsOnly boolean
Whether to log only errors.
Required: true
Default: false
options.activityLogger.DiskThrashPeriod integer
The period in milliseconds with which to flush the file buffer to ensure it's committed to the hard drive. Note: This is a performance consideration to prevent writing to disk too frequently.
Required: true
Default: 1000
options.activityLogger.FileSizeLimit integer
The file size at which to create new files.
Required: true
Default: 1000000
options.activityLogger.StartLogFormat string
The initial string to put into the log file (and subsequent files) when opened for the first time.
Required: true
Default: "**** START LOGGER - @LOG{LOGGERNAME} (@LOG{TIMESTAMP}) ****"
options.activityLogger.EndLogFormat string
The final string to put in the log file when closed.
Required: true
Default: "\n\n**** END LOGGER - @LOG{LOGGERNAME} (@LOG{TIMESTAMP}) ****"
options.activityLogger.LogEntryFormat string
The format to use when writing log entries when errors are not present.
Required: true
Default: "\n\n@LOG{LOGMESSAGE}"
options.activityLogger.ErrorLogEntryFormat string
The message format used to construct error log entries.
Required: true
Default: "\n\n@LOG{ERRORMESSAGE}\n\n"
options.activityLogger.TimestampFormat string
The format used by the @LOG{TIMESTAMP} variable.
Required: true
Default: "%Y-%m-%d %H-%M-%S%3u"
panel object
Required: true
Default: (not specified; see any element defaults within)
panel.open boolean
Whether to open the front panel immediately when run.
Required: true
Default: true
panel.state enum (string)
The state in which the window will open.
Required: true
Default: "Standard"
Enum Items: "Standard" | "Hidden" | "Closed" | "Minimized" | "Maximized"
panel.transparency integer
The transparency of the window. 0 = opaque, 100 = invisible.
Required: true
Default: 0
panel.title string
The title of the plugin window when it runs. Note that the variable 'instanceName' is provided here in a VAR variable container.
Required: true
Default: "@VAR{instanceName}"
panel.titleBarVisible boolean
Whether the window title bar is visible.
Required: true
Default: true
panel.showMenuBar boolean
Whether the menu bar is visible.
Required: true
Default: false
panel.showToolBar boolean
Whether the toolbar is visible.
Required: true
Default: false
panel.makeActive boolean
Whether the window becomes active when opened.
Required: true
Default: false
panel.bringToFront boolean
Whether the window is brought to the front / top of other windows when opened.
Required: true
Default: false
panel.minimizable boolean
Whether the window is minimizable.
Required: true
Default: true
panel.resizable boolean
Whether the window is resizable.
Required: true
Default: true
panel.closeable boolean
Whether the window is closeable.
Required: true
Default: true
panel.closeWhenDone boolean
Whether to close the window when complete.
Required: true
Default: true
panel.center boolean
Whether to center the window when opened. Note: this property overrides the 'position' property.
Required: true
Default: false
panel.position object
The position of the window when opened the first time.
Required: true
Default: (not specified; see any element defaults within)
panel.position.top integer
The vertical position of the window in pixels from the top edge of the viewport. Note: this property is overriden by the 'center' property.
Required: true
Default: 100
panel.position.left integer
The horizontal position of the window in pixels from the left edge of the viewport. Note: this property is overriden by the 'center' property.
Required: true
Default: 100
panel.size object
The size of the window when opened the first time.
Required: false
Default: (not specified; see any element defaults within)
panel.size.width integer
The width of the window in pixels. -1 means use the default width for the panel. Note that depending on panel features exposed, there may be a limit to how small a panel can become.
Required: true
Default: -1
panel.size.height integer
The height of the window in pixels. -1 means use the default height for the panel. Note that depending on panel features exposed, there may be a limit to how small a panel can become.
Required: true
Default: -1
channel object
The communication channel definition used by this plugin. Note: this section rarely needs modifications. In many cases, the underlying plugin implementation depends on at least some of these settings having the values below. Consult with a JADE expert before making changes to this section if you are unfamiliar with the implications of changes to this section.
Required: true
Default: (not specified; see any element defaults within)
channel.SendBreakTimeout integer
The timeout duration in milliseconds to wait for sending messages.
Required: true
Default: 1000
channel.WaitOnBreakTimeout integer
The timeout duration in milliseconds to wait for receiving messages. Note: -1 means wait indefinitely or until shutdown is signalled.
Required: true
Default: -1
channel.WaitOnShutdownTimeout integer
The timeout duration in milliseconds to wait for shutdown acknowledgment.
Required: true
Default: 2000
channel.ThrowTimeoutErrors boolean
Whether to throw timeout errors vs simply returning a boolean indicating whether a timeout occurred.
Required: true
Default: false
channel.ThrowShutdownUnacknowledgedErrors boolean
Whether to throw 'shutdown unacknowledged' errors.
Required: true
Default: true
channel.QueueSize integer
The size of the underlying communication queue in bytes. Note: -1 means unbounded (i.e. grow as needed with available memory).
Required: true
Default: -1
channel.SendBreakEnqueueType enum (string)
The enqueue strategy employed on the underlying queue for standard messages.
Required: true
Default: "Enqueue"
Enum Items: "Enqueue" | "EnqueueAtFront" | "LossyEnqueue" | "LossyEnqueueAtFront"
channel.SendErrorEnqueueType enum (string)
The enqueue strategy employed on the underlying queue for error messages.
Required: true
Default: "Enqueue"
Enum Items: "Enqueue" | "EnqueueAtFront" | "LossyEnqueue" | "LossyEnqueueAtFront"
channel.SendShutdownEnqueueType enum (string)
The enqueue strategy employed on the underlying queue for the shutdown message.
Required: true
Default: "LossyEnqueueAtFront"
Enum Items: "Enqueue" | "EnqueueAtFront" | "LossyEnqueue" | "LossyEnqueueAtFront"
channel.FlushQueueBeforeWaitingOnBreak boolean
Whether to flush the queue upon waiting for new messages (i.e. whether to clear the queue and wait for the next 'new' message; this has the effect of removing old messages and waiting for the next message.
Required: true
Default: false
channel.FlushQueueAfterBreaking boolean
Whether to flush the queue after receiving a new message (i.e. whether to handle the next message coming in the queue and then flush; this has the effect of handling the oldest message (if it exsits) or the next message before flushing the queue.
Required: true
Default: false