node-red-contrib-simple-gate/README.md

A gate node for node-RED

# node-red-contrib-simple-gate
A Node-RED node for controlling message flow.

## Install

Use the Node-RED `Manage Palette` command or run the following in your Node-RED user directory (typically `~/.node-red`):

    npm install node-red-contrib-simple-gate

## Usage

The `gate` node will transmit the input message to its output when in the `open` state and block it when `closed`. Messages that arrive when the gate is `closed` are discarded. If it is desired to save those messages for future delivery, the `q-gate` node, published as [node-red-contrib-queue-gate](https://flows.nodered.org/node/node-red-contrib-queue-gate) is available.

Messages with the user-defined topic `Control Topic` (set when the node is deployed) are not passed through but are used to control the state of the gate.

Control messages can have values representing commands for `open`, `close`, `toggle`, `default`, and `status`. The (case-insensitive) strings representing these commands are set by the user when the node is deployed. The `status` command (added in version 0.4.0) causes the node status to be refreshed, so that it can be caught by a `status` node. Since version 0.3.0, if a control message is received with a payload that is a number or boolean, the payload is converted to a string and then tested against the command definitions. If a command is not recognized, there is no output or change of state, and the node reports a warning.

When first deployed or after a `default` command, the gate is in the user-selected state defined by `Default State` (see below regarding persistence).


## Node status
The state of the gate is indicated by a status object: text and either a green dot (`open`) or a red ring (`closed`).

## State persistence
By default, the node enters the `Default State` on startup, either when first deployed in the editor, re-deployed as part of a modified flow or entire workspace, or when Node-RED is restarted by the user or by a system service. The state of the node is maintained in the node context, and if a persistent (non-volatile) form of context storage is available, the user has the option of restoring the state from that storage. This is done by activating the `Restore from state saved in` option (checkbox) in the edit dialog and choosing a non-volatile storage module from the adjacent dropdown list. (The list shows all the storage modules enabled in the Node-RED `settings.js` file.) If for any reason the node is unable to retrieve valid state information, it will enter the `Default State`. (Note: versions prior to 0.5.0 were able to use only the default context store, so that state persistence was possible only when that store was non-volatile.)

## Version History
Please refer to the [CHANGELOG](https://github.com/drmibell/node-red-contrib-simple-gate/blob/master/CHANGELOG.md) document.

## Examples
### Basic Operation
This flow demonstrates the basic operation of the `gate` node and the commands that can be used to change its state.

```
[{"id":"b464bbaa.5be868","type":"gate","z":"7886adba.5d75d4","name":"gate demo","controlTopic":"control","defaultState":"open","openCmd":"open","closeCmd":"close","toggleCmd":"toggle","defaultCmd":"default","statusCmd":"status","persist":false,"x":450,"y":200,"wires":[["8ba20475.bd1c28"]]},{"id":"f61b4c1c.d6f8","type":"inject","z":"7886adba.5d75d4","name":"input","repeat":"","crontab":"","once":false,"onceDelay":0.1,"topic":"","payload":"","payloadType":"date","x":150,"y":200,"wires":[["b464bbaa.5be868"]]},{"id":"57c0705e.2b648","type":"inject","z":"7886adba.5d75d4","name":"open","repeat":"","crontab":"","once":false,"onceDelay":0.1,"topic":"control","payload":"open","payloadType":"str","x":250,"y":100,"wires":[["b464bbaa.5be868"]]},{"id":"e56d6ef2.db15b8","type":"inject","z":"7886adba.5d75d4","name":"close","repeat":"","crontab":"","once":false,"onceDelay":0.1,"topic":"control","payload":"close","payloadType":"str","x":250,"y":140,"wires":[["b464bbaa.5be868"]]},{"id":"310d032f.aa197c","type":"inject","z":"7886adba.5d75d4","name":"toggle","repeat":"","crontab":"","once":false,"onceDelay":0.1,"topic":"control","payload":"toggle","payloadType":"str","x":250,"y":260,"wires":[["b464bbaa.5be868"]]},{"id":"c5e19f28.1e37d","type":"inject","z":"7886adba.5d75d4","name":"reset","props":[{"p":"payload"},{"p":"topic","vt":"str"}],"repeat":"","crontab":"","once":false,"onceDelay":0.1,"topic":"control","payload":"default","payloadType":"str","x":250,"y":300,"wires":[["b464bbaa.5be868"]]},{"id":"8ba20475.bd1c28","type":"debug","z":"7886adba.5d75d4","name":"output","active":true,"tosidebar":true,"console":false,"tostatus":false,"complete":"true","targetType":"full","statusVal":"","statusType":"auto","x":590,"y":200,"wires":[]},{"id":"7f423eb5.3d6508","type":"inject","z":"7886adba.5d75d4","name":"status","props":[{"p":"payload"},{"p":"topic","vt":"str"}],"repeat":"","crontab":"","once":false,"onceDelay":0.1,"topic":"control","payload":"status","payloadType":"str","x":250,"y":340,"wires":[["b464bbaa.5be868"]]},{"id":"516d9d16.30ddac","type":"status","z":"7886adba.5d75d4","name":"gate status","scope":["b464bbaa.5be868"],"x":440,"y":260,"wires":[["f66030c4.9dce28"]]},{"id":"f66030c4.9dce28","type":"debug","z":"7886adba.5d75d4","name":"status text","active":true,"tosidebar":true,"console":false,"tostatus":false,"complete":"status.text","targetType":"msg","statusVal":"","statusType":"auto","x":590,"y":260,"wires":[]}]
```
<img src="https://github.com/drmibell/node-red-contrib-gate/blob/master/screenshots/gate-demo.png?raw=true"/>

### Dashboard Control
This flow shows how the `gate` node can be controlled from the dashboard using buttons and switches.

```
[{"id":"d81194ef.313d6","type":"gate","z":"389e6e43.7ac652","name":"gate 1","controlTopic":"control","defaultState":"open","openCmd":"open","closeCmd":"close","toggleCmd":"toggle","defaultCmd":"default","x":450,"y":140,"wires":[["f2823cc0.7548c"]]},{"id":"a2c1bfc0.3be47","type":"status","z":"389e6e43.7ac652","name":"status 1","scope":["d81194ef.313d6"],"x":590,"y":180,"wires":[["4e7accb1.6a1244","c7ba6981.1c5ca8"]]},{"id":"ffac76df.157138","type":"inject","z":"389e6e43.7ac652","name":"timestamp","topic":"","payload":"","payloadType":"date","repeat":"","crontab":"","once":false,"onceDelay":0.1,"x":140,"y":100,"wires":[["717d6cd.b967594"]]},{"id":"5f1d51af.3f9ef8","type":"gate","z":"389e6e43.7ac652","name":"gate 2","controlTopic":"control","defaultState":"open","openCmd":"open","closeCmd":"close","toggleCmd":"toggle","defaultCmd":"default","x":450,"y":320,"wires":[["9b2a6a4.c99b098"]]},{"id":"10481de0.41060a","type":"ui_switch","z":"389e6e43.7ac652","name":"open/close","label":"open/close","group":"5cfe21d2.307938","order":3,"width":0,"height":0,"passthru":false,"decouple":"false","topic":"control","style":"","onvalue":"open","onvalueType":"str","onicon":"","oncolor":"","offvalue":"close","offvalueType":"str","officon":"","offcolor":"","x":290,"y":340,"wires":[["5f1d51af.3f9ef8"]]},{"id":"dbc56c5c.9a499","type":"ui_button","z":"389e6e43.7ac652","name":"toggle","group":"fdb6c31c.4f2818","order":3,"width":0,"height":0,"passthru":true,"label":"toggle","color":"","bgcolor":"","icon":"","payload":"toggle","payloadType":"str","topic":"control","x":310,"y":140,"wires":[["d81194ef.313d6"]]},{"id":"fb3862a9.febaa8","type":"ui_button","z":"389e6e43.7ac652","name":"reset","group":"fdb6c31c.4f2818","order":4,"width":0,"height":0,"passthru":true,"label":"reset","color":"","bgcolor":"","icon":"","payload":"default","payloadType":"str","topic":"control","x":310,"y":180,"wires":[["d81194ef.313d6"]]},{"id":"717d6cd.b967594","type":"ui_button","z":"389e6e43.7ac652","name":"message 1","group":"fdb6c31c.4f2818","order":5,"width":0,"height":0,"passthru":true,"label":"Send","color":"","bgcolor":"","icon":"","payload":"","payloadType":"date","topic":"anything","x":290,"y":100,"wires":[["d81194ef.313d6"]]},{"id":"cf3d94f3.62e01","type":"ui_button","z":"389e6e43.7ac652","name":"message 2","group":"5cfe21d2.307938","order":4,"width":0,"height":0,"passthru":false,"label":"Send","color":"","bgcolor":"","icon":"","payload":"","payloadType":"date","topic":"","x":290,"y":300,"wires":[["5f1d51af.3f9ef8"]]},{"id":"f2823cc0.7548c","type":"ui_text","z":"389e6e43.7ac652","group":"fdb6c31c.4f2818","order":2,"width":0,"height":0,"name":"display 1","label":"Message","format":"{{msg.payload}}","layout":"row-spread","x":600,"y":140,"wires":[]},{"id":"4e7accb1.6a1244","type":"ui_text","z":"389e6e43.7ac652","group":"fdb6c31c.4f2818","order":1,"width":0,"height":0,"name":"status 1","label":"Status","format":"{{msg.status.text}}","layout":"row-spread","x":740,"y":180,"wires":[]},{"id":"9b2a6a4.c99b098","type":"ui_text","z":"389e6e43.7ac652","group":"5cfe21d2.307938","order":2,"width":0,"height":0,"name":"display 2","label":"Message","format":"{{msg.payload}}","layout":"row-spread","x":600,"y":320,"wires":[]},{"id":"9fdf32be.f66568","type":"ui_text","z":"389e6e43.7ac652","group":"5cfe21d2.307938","order":1,"width":0,"height":0,"name":"status 2","label":"Status","format":"{{msg.status.text}}","layout":"row-spread","x":720,"y":360,"wires":[]},{"id":"d3b465d7.ab11d","type":"inject","z":"389e6e43.7ac652","name":"timestamp","topic":"","payload":"","payloadType":"date","repeat":"","crontab":"","once":false,"onceDelay":0.1,"x":140,"y":300,"wires":[["cf3d94f3.62e01"]]},{"id":"7378029e.0e7004","type":"status","z":"389e6e43.7ac652","name":"status 2","scope":["5f1d51af.3f9ef8"],"x":590,"y":360,"wires":[["9fdf32be.f66568"]]},{"id":"66b1fc61.8e356c","type":"inject","z":"389e6e43.7ac652","name":"toggle","topic":"","payload":"","payloadType":"date","repeat":"","crontab":"","once":false,"onceDelay":0.1,"x":150,"y":140,"wires":[["dbc56c5c.9a499"]]},{"id":"c7bd73e3.460f","type":"inject","z":"389e6e43.7ac652","name":"reset","topic":"","payload":"","payloadType":"date","repeat":"","crontab":"","once":false,"onceDelay":0.1,"x":150,"y":180,"wires":[["fb3862a9.febaa8"]]},{"id":"c7ba6981.1c5ca8","type":"debug","z":"389e6e43.7ac652","name":"","active":true,"tosidebar":true,"console":false,"tostatus":false,"complete":"status","x":750,"y":220,"wires":[]},{"id":"5cfe21d2.307938","type":"ui_group","z":"","name":"Gate #2","tab":"3616a722.b89bc8","order":2,"disp":true,"width":"6","collapse":false},{"id":"fdb6c31c.4f2818","type":"ui_group","z":"","name":"Gate #1","tab":"3616a722.b89bc8","order":1,"disp":true,"width":"6","collapse":false},{"id":"3616a722.b89bc8","type":"ui_tab","z":"","name":"Home","icon":"dashboard"}]
```

<img src="https://github.com/drmibell/node-red-contrib-gate/blob/master/screenshots/gate-dashboard-demo.png?raw=true"/>