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.

New in Version 1.3

This version adds logging capabilities. Logging occurs on the following events:

1. when a relay state changes
2. when a relay timer starts
3. when a relay timer ends

See the Logging section below for more details.

This version also fixes a bug introduced in v1.2 which can stop the plugin from shutting down gracefully under certain conditions.

User Interface

The Relay Manager Interface shows the defined sections, their relays, and current states. Relays can be manually controlled on the interface and each section provides global on/off controls for all relays. Relays can also be controlled remotely by sending this plugin control messages as discussed below, and the relay states in the interface will reflect such changes accordingly. Relays can also optionally set a relayResetTime (in milliseconds) which will return the relay to its configured default state after the specified relayResetTime expires. When this setting is configured to a non-negative value (-1 disables the feature), a yellow led with ... inside indicates that the timer is active for that relay. The time shown beside it when active is the time left before resetting to the default value. See the Relay Reset Time section below for more details.

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
                }
            ]
        }
    }
}

Publishing

Message are published and logged when relay states change, and also both when a relay timer is first activated and when the timer ends. Each published message includes the relay states for all configured relays.

Relay states change on following boundaries:

1. once initially when relay default values are applied (a single message is published after all relays are updated here)
2. when any relay state is changed (a message is published for each individual relay state change, as those changes may be substantially time separated even when enable all, disable all, or a relay state change message is received.)
3. once on shutdown with final relay states

Below is an example of a published message where two relay sections have been configured (ROTV Relays and Science Relays), each with two relays:

{
    "instanceName": "Relay Manager",
    "ROTV Relays": {
        "CTD 1": {
            "relayLocation": "Board1.banks.Bank2.relays.R8",
            "relayDefault": false,
            "relayResetTime": -1,
            "sectionIndex": 0,
            "relayIndex": 0,
            "relayState": true,
            "isTimerActive": false,
            "timeLeft": "no timer",
            "risingEdges": 4,
            "fallingEdges": 3
        },
        "CTD 2": {
            "relayLocation": "Board1.banks.Bank1.relays.R7",
            "relayDefault": false,
            "relayResetTime": -1,
            "sectionIndex": 0,
            "relayIndex": 1,
            "relayState": false,
            "isTimerActive": false,
            "timeLeft": "no timer",
            "risingEdges": 3,
            "fallingEdges": 3
        }
    },
    "Science Relays": {
        "PAR": {
            "relayLocation": "Board1.banks.Bank1.relays.R6",
            "relayDefault": false,
            "relayResetTime": -1,
            "sectionIndex": 1,
            "relayIndex": 2,
            "relayState": false,
            "isTimerActive": false,
            "timeLeft": "no timer",
            "risingEdges": 0,
            "fallingEdges": 0
        },
        "SUNA (Nitrate)": {
            "relayLocation": "Board1.banks.Bank2.relays.R2",
            "relayDefault": false,
            "relayResetTime": -1,
            "sectionIndex": 1,
            "relayIndex": 3,
            "relayState": false,
            "isTimerActive": false,
            "timeLeft": "no timer",
            "risingEdges": 0,
            "fallingEdges": 0
        }
    }
}

Note that the instanceName is also included here, and is treated as a keyword meaning you cannot name a relay section “instanceName” or it will be overwritten by the actual instanceName.

Relay Reset Time

When configuring relay connections, you can specify a relayResetTime in milliseconds which will return the relay to its default value after that specified period of time. Setting this value to -1 disables the feature, and this is the default value of this configuration option. When the relayResetTime is non-negative and a relay value changes from it’s default value (ex. from false to true, where false is the default value), then a lightweight timer sidecar is spun up to monitor the elapsed time. When the relay’s relayResetTime expires, the timer sidecar will reset the relay’s value back to the default value. The period with which the timer sidecar checks to see if the relayResetTime has expired is set by the relayResetTimeCheckPeriod option. If the plugin instance is shut down while any relay timer sidecars are still running, the timer sidecars will be shut down so the plugin instance can shut down.

Notably, only one timer sidecar will be spawned for a given relay at a given time. For example, suppose the default relay state is false for some relay and you quickly toggle that relay state from false to true to false to true within the relayResetTime. In this case, the second transition from false to true would NOT spawn a second timer sidecar because the timer sidecar spawned by the first transition would still be running - and would still reset the relay state to false again after the original relayResetTime period expired. After the initial timer sidecar finished, a subsequent false to true transition would indeed spawn another timer sidcar. Importantly, the “single sidecar at a time” discussed here does NOT prevent the user (or incoming messages) from changing the relay state while timers are running. Just keep in mind that the timer sidecare is a little concurrently running element which will reset the relay state back to the default value when the relayResetTime expires.

You can observe whether a relay’s timer sidcar is still active for a given relay on the interface (a yellow led will display with ... inside while a timer sidecar is active). In most cases this is not an issue, as the feature is intended to be used in scenarios where the goal is to change the relay state and then allow it to toggle back to it’s default state automatically when the relayResetTime expires.

Logging

Logging occurs on the following events:

1. when a relay state changes
2. when a relay timer starts
3. when a relay timer ends

The log file contains the following information (columns) in CSV format:

• Timestamp - time since LabVIEW epoch (the number of seconds elapsed since 12:00 a.m., Friday, January 1, 1904, Universal Time [01-01-1904 00:00:00])
• Event Type - indicates what kind of event generated the log entry: StateUpdate-Initialize | StateUpdate-User | StateUpdate-Message | StateUpdate-Timer | StateUpdate-Shutdown | TimerStart | TimerEnd
• Section - the section name of the relay
• Relay - the relay name
• State - the state of the relay
• Reset Time - the reset time (-1 when the relay timer is disabled)
• Timer Active - true or false indicating whether the timer is active
• Time Left - the time left on the timer
• Rising Edges - the number of rising edges so far
• Falling Edges - the number of falling edges so far

Configuration Example

Configuration Details

[]

[]

{
    "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])"
                            }
                        }
                    }
                }
            }
        }
    }
}