Overview

The Relay Manager plugin provides control over any number of relay boards, each with any number of banks, where each bank holds any number of relays. Boards, banks, and relays can all be semantically named and then ordered into named sections for access on the user interface. Initial states can be configured for each relay to be set on launch.

User Interface

The Relay Manager Interface shows the defined sections, their relays, and current states. Relays can be manually controlled and each section provides global on/off controls for all relays.

Control Messages

The Relay Manager supports the control messages noted below. Control messages can be sent using the State Machine plugin or by sending TCP message to the TCP Server plugin. In all cases, specify the instance name you supplied for your Relay Manager plugin instance as the “target”.

Update Relays

This control message updates one or more relays specified in an array of relay states to update. The example below shows the complete structure of the message for a Relay Manager plugin instance named My Relay Manager with a relay section named MyRelaySection and a relay in that section named MyRelayName. Valid values for state are true (meaning the relay is allowing voltage and current through) and false (meaning the relay is not allowing voltage and current through). Notably, spaces are indeed allowed in relay section names and relay names if desired.

{
    "target": "My Relay Manager",
    "message": {
        "operation": "Update Relays",
        "data": {
            "relayStates": [
                {
                    "relay": "MyRelaySection.MyRelayName",
                    "state": true
                }
            ]
        }
    }
}

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.enableAllPerRelayDelay integer
The delay to apply in milliseconds between turning on individual relays when the Enable All button is clicked. This is a mechanism to slow down how quickly all relays are enabled which limits the change in current draw at a given time. In many cases this is not an issue at all, but we provide the feature for cases which may depend on this as secondary or sanity precaution.
Required: true
Default: 500
options.disableAllPerRelayDelay integer
The delay to apply in milliseconds between turning off individual relays when the Disable All button is clicked. This value is generally lower than for the Enable All button since offloading current doesn't carry as much theoretical risk.
Required: true
Default: 100
options.defaultPerRelayDelay integer
The minimum delay to apply in milliseconds when updating individual relays manually or not using the Enable All or Disable All buttons. Since this plugin currently does not take incoming messages to modulate its state, this only applies to the manual case, and in such cases there is little reason to have a significant delay here (in fact this can be 0 in such cases).
Required: true
Default: 5
options.resetRelaysToDefaultsOnShutdown boolean
If true, relays will be set to their default values when the plugin is stopped.
Required: true
Default: false
options.relayConnections object
An object containing relay connection information. This object layer is provided primarily for extensibility purposes at this time.
Required: true
Default: (not specified; see any element defaults within)
options.relayConnections.relaySections array
An array of objects where each object defines a relay section. Relay sections are organized left to right, each with a name and relay list which renders top to bottom.
Required: true
Default: 
[]
options.relayConnections.relaySections[n] object
An object defining a relay section. A relay section has a name and relay list which renders top to bottom. The section is intended to allow organizing / grouping relays in the user interface according to function vs the boards and banks to which they are connected.
Required: false
Default: (not specified; see any element defaults within)
options.relayConnections.relaySections[n].relaySectionName string
A semantic name for the relay section. For example "Instrument Relays" or "Control Relays".
Required: true
Default: "My Relay Section"
options.relayConnections.relaySections[n].relayList array
undefined
Required: true
Default: 
[]
options.relayConnections.relaySections[n].relayList[n] object
Defines a relay by specifying the relay location in a board and bank, its default state, and a semantic name to display in the user interface.
Required: false
Default: (not specified; see any element defaults within)
options.relayConnections.relaySections[n].relayList[n].relayName string
A semantic name for the relay, such as the name of the instrument it enables/disables or the purpose it serves in the system.
Required: true
Default: "My Relay"
options.relayConnections.relaySections[n].relayList[n].relayLocation string
The JSON "path" into the relayBoards section of the Relay Manager configuration down to the named relay level.
Required: true
Default: "Board1.banks.Bank1.relays.R4"
options.relayConnections.relaySections[n].relayList[n].relayDefault boolean
The default state of the relay where false means off and true means on. Relays will be set to this value when the plugin is run. If resetRelaysToDefaultsOnShutdown = true, relays will be set to this value when the plugin is stopped.
Required: true
Default: false
options.relayBoards object
An object which captures the definition for any number of relay boards, where each board may have any number of banks, and each bank may have any number of relays. Boards, banks, and relays are allowed semantic names as keys in the object hierarchy. Boards have a serialPortConfiguration object and relays have a commands object where on and off commands are expected to be defined.
Required: true
Default: 
{
    "Board1": {
        "serialPortConfiguration": {
            "SimulationMode": true,
            "Address": "COM3",
            "Timeout": 2000,
            "TerminationEnable": false,
            "TerminationCharacter": "\n",
            "TrimResponseWhiteSpace": false,
            "BytesToRead": 1000,
            "ReadToFileEnable": false,
            "ReadToFilePath": "",
            "BaudRate": 115200,
            "DataBits": 8,
            "StopBits": "1.0",
            "Parity": "None",
            "FlowControl": "None"
        },
        "banks": {
            "Bank1": {
                "relays": {
                    "R1": {
                        "commands": {
                            "off": {
                                "command": "BytesToString([170,3,254,100,1,16])",
                                "response": "BytesToString([170,1,85,0])"
                            },
                            "on": {
                                "command": "BytesToString([170,3,254,108,1,24])",
                                "response": "BytesToString([170,1,85,0])"
                            }
                        }
                    },
                    "R2": {
                        "commands": {
                            "off": {
                                "command": "BytesToString([170,3,254,101,1,17])",
                                "response": "BytesToString([170,1,85,0])"
                            },
                            "on": {
                                "command": "BytesToString([170,3,254,109,1,25])",
                                "response": "BytesToString([170,1,85,0])"
                            }
                        }
                    }
                }
            },
            "Bank2": {
                "relays": {
                    "R1": {
                        "commands": {
                            "off": {
                                "command": "BytesToString([170,3,254,100,2,17])",
                                "response": "BytesToString([170,1,85,0])"
                            },
                            "on": {
                                "command": "BytesToString([170,3,254,108,2,25])",
                                "response": "BytesToString([170,1,85,0])"
                            }
                        }
                    },
                    "R2": {
                        "commands": {
                            "off": {
                                "command": "BytesToString([170,3,254,101,2,18])",
                                "response": "BytesToString([170,1,85,0])"
                            },
                            "on": {
                                "command": "BytesToString([170,3,254,109,2,26])",
                                "response": "BytesToString([170,1,85,0])"
                            }
                        }
                    }
                }
            }
        }
    }
}
options.relayBoards.{Board Name} object
An object defining the boards serial configuraiton and relay banks.
Required: false
Default: (not specified; see any element defaults within)
options.relayBoards.{Board Name}.serialPortConfiguration object
Defines the serial port configuration.
Required: true
Default: (not specified; see any element defaults within)
options.relayBoards.{Board Name}.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.relayBoards.{Board Name}.serialPortConfiguration.Address string
The address of the serial port.
Required: true
Default: "COM1"
options.relayBoards.{Board Name}.serialPortConfiguration.Timeout integer
The timeout duration in milliseconds used for write and read operations.
Required: true
Default: 2000
options.relayBoards.{Board Name}.serialPortConfiguration.TerminationEnable boolean
Whether to look for termination characters in responses.
Required: true
Default: true
options.relayBoards.{Board Name}.serialPortConfiguration.TerminationCharacter string
The termination character to look for (if termination is enabled).
Required: true
Default: "\n"
options.relayBoards.{Board Name}.serialPortConfiguration.TrimResponseWhiteSpace boolean
Whether to trim whitespace from responses.
Required: true
Default: true
options.relayBoards.{Board Name}.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.relayBoards.{Board Name}.serialPortConfiguration.ReadToFileEnable boolean
Wehther to enable reading responses directly to a specified file.
Required: true
Default: false
options.relayBoards.{Board Name}.serialPortConfiguration.ReadToFilePath string
The file path to read responses into (if ReadToFileEnable is true).
Required: true
Default: ""
options.relayBoards.{Board Name}.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.relayBoards.{Board Name}.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.relayBoards.{Board Name}.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.relayBoards.{Board Name}.serialPortConfiguration.Parity enum (string)
The parity or error checking convention to use.
Required: true
Default: "None"
Enum Items: "None" | "Odd" | "Even" | "Mark" | "Space"
options.relayBoards.{Board Name}.serialPortConfiguration.FlowControl string
The flow control convention to use.
Required: true
Default: "None"
options.relayBoards.{Board Name}.banks object
An object defining banks where keys are bank names and values are objects with relay definitions for the bank.
Required: true
Default: (not specified; see any element defaults within)
options.relayBoards.{Board Name}.banks.{Bank Name} object
undefined
Required: false
Default: (not specified; see any element defaults within)
options.relayBoards.{Board Name}.banks.{Bank Name}.relays object
An object where keys are relay names and values are objects defining the commands to switch on/off the relays.
Required: true
Default: (not specified; see any element defaults within)
options.relayBoards.{Board Name}.banks.{Bank Name}.relays.{Relay Name} object
An object with a commands key where the value is an object defining how to switch on/off the relay.
Required: false
Default: (not specified; see any element defaults within)
options.relayBoards.{Board Name}.banks.{Bank Name}.relays.{Relay Name}.commands object
An object defining on/off commands for the relay
Required: true
Default: (not specified; see any element defaults within)
options.relayBoards.{Board Name}.banks.{Bank Name}.relays.{Relay Name}.commands.off object
An object defining the command and response to turn the relay off / disconnected / false state.
Required: true
Default: (not specified; see any element defaults within)
options.relayBoards.{Board Name}.banks.{Bank Name}.relays.{Relay Name}.commands.off.command string
The command to send to turn the relay off / disconnected / false state.
Required: false
Default: ""
options.relayBoards.{Board Name}.banks.{Bank Name}.relays.{Relay Name}.commands.off.response string
The expected response from the relay board for the corresponding command.
Required: false
Default: ""
options.relayBoards.{Board Name}.banks.{Bank Name}.relays.{Relay Name}.commands.on object
An object defining the command and response to turn the relay on / connected / true state.
Required: true
Default: (not specified; see any element defaults within)
options.relayBoards.{Board Name}.banks.{Bank Name}.relays.{Relay Name}.commands.on.command string
The command to send to turn the relay on / connected / true state.
Required: false
Default: ""
options.relayBoards.{Board Name}.banks.{Bank Name}.relays.{Relay Name}.commands.on.response string
The expected response from the relay board for the corresponding command.
Required: false
Default: ""
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: true
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}.log"
options.logger.ErrorsOnly boolean
Whether to log only errors.
Required: true
Default: true
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: "**** START LOGGER - @LOG{LOGGERNAME} (@LOG{TIMESTAMP}) ****"
options.logger.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.logger.LogEntryFormat string
The format to use when writing log entries when errors are not present.
Required: true
Default: "\n\n@LOG{LOGMESSAGE}"
options.logger.ErrorLogEntryFormat string
The message format used to construct error log entries.
Required: true
Default: "\n\n@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: -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