@sixclear/serial-publisher
Serial Publisher v1.1.0
Overview
The Serial Publisher plugin communicates with a device over a serial port. The plugin-specific options include full serial port configuration, a serial communication initialization sequence (sent before the plugin enters its main operation), simulation mode, expression handling (including for simulation mode), regular expressions for response parsing, data publishing, and data logging. As with all plugins, the common panel and channel sections are also available in configuration. See below for an example editor with default values and full configuration documentation details.
User Interface
The Serial Publisher user interface is exceedingly simple by design. In most applications, Serial Publisher instances run in the background (with panels closed) and any subscribed plugins will receive their data for presentation, control, or other purposes. In that sense, the Serial Publisher interface is often used simply for debugging (i.e. making sure the data is being received as expected from the serial device and is being published and logged with the desired formats). Below is an example Serial Publisher interface:
Configuration Example
Configuration Details
ROOT object
This top level object holds all configuration information for a Serial Publisher plugin instance.
Required: true
Default: (not specified; see any element defaults within)
options object
Configuration options specific to the Serial Publisher plugin. Note that variables and expressions are generally allowed in this section.
Required: true
Default: (not specified; see any element defaults within)
options.initializationSequence array
An array of initial communication to perform.
Required: true
Default:
[
{
"enable": false,
"timeout": 2000,
"writeCommand": false,
"performRead": true,
"bytesToRead": 1000,
"responseRegex": ".+",
"ignoreErrors": [
-1073807253,
-1073807339
]
}
] options.initializationSequence[n] object
Required: false
Default: (not specified; see any element defaults within)
options.initializationSequence[n].enable boolean
Whether to enable this element of the sequence.
Required: true
Default: false
options.initializationSequence[n].timeout integer
The timeout used for this element's write and/or read operations.
Required: true
Default: 0
options.initializationSequence[n].writeCommand stringboolean
The string command to write, or boolean false to prevent the write operation.
Required: true
Default: ""
options.initializationSequence[n].performRead boolean
Whether to perform the read operation.
Required: true
Default: false
options.initializationSequence[n].bytesToRead integer
The number of bytes to read.
Required: true
Default: 0
options.initializationSequence[n].responseRegex stringboolean
The string regular expression to validate against the response, or boolean false to perform no validation.
Required: true
Default: ""
options.initializationSequence[n].ignoreErrors array
An array of VISA error codes to ignore. For example, we may receive an initial framing error (-1073807253) for devices which simply publish data to the serial port even prior to a connection being opened or a command being sent. In such cases, there's a chance that the first bit seen upon opening the serial port might be in the middle of a serial packet which likely result in a framing error. Another common error to handle here is the timeout error (-1073807339).
Required: true
Default:
[]
options.initializationSequence[n].ignoreErrors[n] integer
undefined
Required: false
Default: 0
options.enableExpressionsInWriteCommand boolean
Whether to look for and parse expressions in the writeCommand.
Required: true
Default: true
options.enableExpressionsInSimulationResponse boolean
Whether to look for and parse expressions in the simulationResponse.
Required: true
Default: true
options.writeCommandPeriod integer
The period with which to write the writeCommand to the serial device.
Required: true
Default: 1000
options.writeCommand stringboolean
The command to write to the serial device, or false not to write a command at all (ex. if the device simply streams data where only a read operation is required.)
Required: true
Default: "*IDN?"
options.simulationLoopDelay integer
The query / read loop delay to apply in simulation mode (note: this is distinct from the writeCommandPeriod which may in fact be 0 for devices which simply 'publish' data on the serial port, where we simply want to read continuously and let the natural publish rate dictate how fast/often we read).
Required: true
Default: 100
options.simulationResponse string
The response to use when serialPortConfiguration.simulationMode is true.
Required: true
Default: "RAND(0,1)"
options.accumulateResponses boolean
Whether to accumulate responses into a buffer which is ultimately checked for matches to the responseRegex. If no match is found, data is simply put into a buffer and subsequent response data is appended. If a match is found, all content up to and including the match is removed from this buffer. At all times, the size of this buffer is constrained to the accompanying accumlateMaxBytes setting here.
Required: true
Default: false
options.accumulateMaxBytes integer
Only valid when accumulateResponses is true, this sets the maximum buffer size which holds the accumulated responses. See the accumulatedResponses description for details on how this buffer is otherwise maintained.
Required: true
Default: 5000
options.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.mode enum (string)
Specifies whether the response is hex-encoded (often to prevent breaking json underneath due to illegal json characters returned as part of a binary protocol) or simply left alone (interpreted as ascii).
Required: false
Default: "ascii"
Enum Items: "ascii" | "hexEncode"
options.publishDataFormat object
This object specifies the format of the published data. Publishing only occurs when the responseRegex matches the incoming response (or the accumulation buffer if accumulateResponses is true). Any variables in the VAR container are available here, including the submatch array generated by the responseRegex. Other variables provided here are: instanceName (same as the configured instanceName), msTick (integer, millisecond timer value), timestamp (float, epoch time), numSamples (integer, number of published data artifacts), matchString (string, the match to the regular expression if matched, empty string otherwise), and accumulatedResponse (string, will be an empty string if accumulateResponses is false, otherwise holds the current accumulation buffer with as-yet unmatched accumulated responses content).
Required: true
Default: (not specified; see any element defaults within)
options.serialPortConfiguration object
Defines the serial port configuration.
Required: true
Default: (not specified; see any element defaults within)
options.serialPortConfiguration.SimulationMode boolean
Whether to run the plugin in simulation mode. See simulationLoopDelay and simluationResponse above, as well as responseRegex.
Required: true
Default: true
options.serialPortConfiguration.Address string
The address of the serial port.
Required: true
Default: "COM1"
options.serialPortConfiguration.Timeout integer
The timeout duration in milliseconds used for write and read operations.
Required: true
Default: 2000
options.serialPortConfiguration.TerminationEnable boolean
Whether to look for termination characters in responses.
Required: true
Default: true
options.serialPortConfiguration.TerminationCharacter string
The termination character to look for (if termination is enabled).
Required: true
Default: "\n"
options.serialPortConfiguration.TrimResponseWhiteSpace boolean
Whether to trim whitespace from responses.
Required: true
Default: true
options.serialPortConfiguration.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.serialPortConfiguration.ReadToFileEnable boolean
Wehther to enable reading responses directly to a specified file.
Required: true
Default: false
options.serialPortConfiguration.ReadToFilePath string
The file path to read responses into (if ReadToFileEnable is true).
Required: true
Default: ""
options.serialPortConfiguration.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.serialPortConfiguration.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.serialPortConfiguration.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.serialPortConfiguration.Parity enum (string)
The parity or error checking convention to use.
Required: true
Default: "None"
Enum Items: "None" | "Odd" | "Even" | "Mark" | "Space"
options.serialPortConfiguration.FlowControl string
The flow control convention to use.
Required: true
Default: "None"
options.logger 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}, and @VAR{instanceName} are available variables. note: @LOG{LOGGERNAME} is equal to the @VAR{instanceName} here.
Required: false
Default: (not specified; see any element defaults within)
options.logger.Enable boolean
Whether to enable the logger.
Required: true
Default: true
options.logger.LogFolder string
The folder in which to write log files.
Required: true
Default: "\\JADE_LOGS\\@VAR{instanceName}"
options.logger.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.logger.ErrorsOnly boolean
Whether to log only errors.
Required: true
Default: false
options.logger.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.logger.FileSizeLimit integer
The file size at which to create new files.
Required: true
Default: 1000000
options.logger.StartLogFormat string
The initial string to put into the log file when opened for the first time.
Required: true
Default: "Timestamp,Value"
options.logger.EndLogFormat string
The final string to put in the log file when closed.
Required: true
Default: ""
options.logger.LogEntryFormat string
The format to use when writing log entries when errors are not present.
Required: true
Default: "@LOG{LOGMESSAGE}"
options.logger.LogMessageFormat string
The message format used to construct non-error log entries. This is what gets assigned as the @LOG{LOGMESSAGE}. Note: this is an extension of the core logger configuration.
Required: true
Default: "\n@VAR{timestamp},@VAR{value}"
options.logger.ErrorLogEntryFormat string
The message format used to construct error log entries.
Required: true
Default: "@LOG{ERRORMESSAGE}"
options.logger.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: 100
channel.SendBreakEnqueueType enum (string)
The enqueue strategy employed on the underlying queue for standard messages.
Required: true
Default: "LossyEnqueue"
Enum Items: "Enqueue" | "EnqueueAtFront" | "LossyEnqueue" | "LossyEnqueueAtFront"
channel.SendErrorEnqueueType enum (string)
The enqueue strategy employed on the underlying queue for error messages.
Required: true
Default: "LossyEnqueue"
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