UNPKG

node-red-contrib-toggle

Version:

Toggle switch node for Node-red

github.com/eschava/node-red-contrib-toggle

eschava/node-red-contrib-toggle

130 lines (88 loc) • 5.1 kB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
# node-red-contrib-toggle Toggle switch node for Node-red. This node is a companion for any switch (physical or virtual), storing its state and providing toggle operation without need of using function nodes or flow/global variables. ![node-appearance](assets/node-appearance.png "Node appearance") **Fig. 1:** Node appearance <a name="installation"></a> ## Installation <a name="installation_in_node-red"></a> ### In Node-RED (preferred) * Via Manage Palette -> Search for "node-red-contrib-toggle" <a name="installation_in_a_shell"></a> ### In a shell * go to the Node-RED installation folder, e.g.: `~/.node-red` * run `npm install node-red-contrib-toggle` <a name="usage"></a> ## Usage <a name="node_configuration"></a> ### Node Configuration The node configuration sets the active on/off/toggle keywords as well as optional topic names. ![node-settings](assets/node-settings.png "Node properties") **Fig. 2:** Node properties #### ON value / OFF value / Toggle value These attributes can be of type * string * number * boolean They are set to the values you want to be the keywords within `msg.payload` when the actions **switch to ON**, **switch to OFF** and **toggle** shall take place (*execution command*). **Remark:** If you do not set a value to one of the attributes the according method (e.g. switch ON) can not be executed by the node (it needs a value to compare...). #### On/Off topic resp. Toggle topic (optional) If you set the topic attributes to a value, the input `msg` needs to contain the same topic name to execute **On/Off** resp. **toggle** in addition to the `msg.payload` value containing the execution command. #### Pass through ON/OFF messages The node has three pass through modes: - ***No*** - means that node sends an output `msg` only when state is toggled. ON/OFF input messages just update internal state of the node. - ***If changed*** - sends an output `msg` for ON/OFF input message only once it differs from the previous state. And obviously message is always sent for "toggle" message. - ***Always*** - the output `msg` is always sent as a reaction on an input `msg`. <a name="input"></a> ### Input The input `msg.payload` contains the **execution command** to the node. The value needs to be identical to the values you configured in the configuration dialog. If a (string) value is set to the configuration attributes ***On/Off topic*** or ***Toggle topic***, the `msg.topic` property must contain the same string value to execute the command given in `msg.payload`. An example `msg` contents is shown for ***On/Off topic*** = "onofftopic": ![node-settings](assets/topic-usage.png "Use of topics") **Fig. 3:** Example `msg` when using topics <a name="output"></a> ### Output The input `msg` is forwarded to the output, if a valid switch command was detected. The configuration attribute ***pass through ON/OFF messages*** is taken into account. ### Node status The node status signals: - If the switch status is ***on*** it shows a green dot with the text **ON**. - If the switch status is ***off*** it shows a red dot with the text **OFF**. Initially it shows no state. <a name="examples"></a> ## Examples *** **Remark**: Example flows are present in the examples subdirectory. In Node-RED they can be imported via the import function and then selecting *Examples* in the vertical tab menue. *** <a name="example1"></a> ### Example 1: Basic ON/OFF usage This example shows the basic usage of the on and off commands. The configuration is set to **boolean** `true` resp. `false` to switch on resp. switch off and **no toggle option**. <img src="assets/usage-basic.png" title="Example 1" width="550" /> [**BasicUsage.json**](examples/BasicUsage.json) **Fig. 4:** Basic usage example <a name="example2"></a> ### Example 2: Basic toggle usage This example shows the basic usage of the toggle command. The configuration is set to **boolean** `true` resp. `false` and to toggle with all other `msg.payload`/`msg.topic` combinations. <img src="assets/usage-toggle.png" title="Example 2" width="550" /> [**ToggleUsage.json**](examples/ToggleUsage.json) **Fig. 5:** Toggle usage example <a name="example3"></a> ### Example 3: Usage with topics This example shows the usage of topics. The configuration is set to **strings** (`switchON`, `switchOFF`) to switch on resp. off and a **string** (`toggleSTATE`) to toggle the switch. Additionally, the topics are set to `onofftopic` (for the commands `switchON` and `switchOFF`) and to `toggletopic` for the toggle operation (command `toggleSTATE`). <img src="assets/usage-with-topic.png" title="Example 3" width="600" /> [**TopicUsage.json**](examples/TopicUsage.json) **Fig. 6:** Topic usage example ## Version history v0.1.1 Toggle example added to docu v0.1.0 Docu rework v0.0.2 Docs updated v0.0.1 Initial release ## Credits - [eschava](https://github.com/eschava) - [StephanStS](https://github.com/StephanStS)