node-red-contrib-myhome-bticino-v2
Version:
Control Bticino / Legrand MyHome components from Node-RED
163 lines (160 loc) • 12 kB
HTML
<script type="text/x-red" data-help-name="myhome-thermo-zone">
<style>
#mh-tableinfo {width: 300px;font-size: small;}
#mh-tableinfo td, #mh-tableinfo th {border: 1px solid #ddd; padding: 2px; text-align: center;}
#mh-tableinfo tr:nth-child(even) {background-color: #f2f2f2;}
#mh-tableinfo th {background-color: #A6BBCF; color: white;}
</style>
<p>Adds a MyHome Thermo Zone Node to monitor & apply changes on a thermo-controlled zone.</p>
<ul>
<li><strong>Name</strong> (mandatory) is the name of the node</li>
<li><strong>Topic</strong> is used on received payload to trigger the action on the node (see info in inputs definition)</li>
<li><strong>Gateway</strong> is the gateway to be configured in order to connect to MyHome system</li>
<li><strong>Zone</strong> is the address of the zone in MyHome system (1-99)</li>
<li><strong>Ask for Zone state refresh on connect</strong> : when enabled, current Zone status is gathered when node is loaded (i.e. on deploy or when Node-RED server starts). Data collection will trigger flows accordingly, which can be used to (re)set depending values in your flow on load.
<li><strong>Only ask for current load status</strong> : when enabled, the received payload (being '20', 'AUTO', 'OFF', or whatever) is ignored and a status request is sent to gather current zone state without applying any change.</li>
<li><strong>Skip ALL incoming gateway events</strong> : when enabled, all MyHome status updates received from the gateway about this node will be ignored, which means only Node-RED received payloads will be processed.</li>
<li><strong>Filter incoming gateway events</strong> : when enabled, the node only triggers a new flow (aka output) when a state CHANGED after a MyHome BUS message was received. This is made to avoid multiple flows starting for the same info/command, because MyHome sends the same message multiple times (for status request, response,...)
<br>Note: SmartFilter is only applied for events received from the BUS (not the node-RED flows)
</li>
</ul>
<h3>Inputs</h3>
<p><code>msg.payload</code> can be of 2 types</p>
<ul>
<li>A simple value <em>[string]</em> is a valid zone command</li>
<li>An Object where <code>payload.state</code> is a valid zone command</li>
<p>A valid thermo-controlled <strong>zone command</strong> is :</p>
<ul>
<li>a <strong>number</strong> ('20', '21.5',..) : the zone will be switched to manual mode and specified temperature will be applied (min 2°C, max 43°C).</li>
<li><strong>OFF</strong> : zone will be switched off.</li>
<li><strong>AUTO</strong> : zone will be switched to automatic mode.</li>
<li><strong>PROTECT</strong> : zone will be switched to generic protection mode.</li>
<li><strong>THERMAL_PROTECT</strong> : zone will be switched to thermal protection mode (when in conditioning).</li>
<li><strong>ANTIFREEZE</strong> : zone will be switched to antifreeze mode (when in heating).</li>
</ul>
</ul>
<p><code>msg.topic</code> is required on the received <code>msg</code> to trigger the node action: </p>
<ul>
<li>
in <strong>Write mode</strong> : <code>msg.topic</code> must be set to <code>cmd/xxxx</code> where xxxx is the value defined as Topic in node configuration.
<br>
Note : if the node is configured as being read-only, the content of the msg.payload is ignored and a refresh status will be processed.
</li>
<li>
in <strong>Read-only mode</strong> : <code>msg.topic</code> must be set to <code>state/xxxx</code> where xxxx is the value defined as Topic in node configuration.</li>
<br>
Note : even if the node is NOT configured as being read-only, the content of the msg.payload is ignored and a refresh status will be processed.
</ul>
<h3>Outputs</h3>
<p>The <strong>primary output</strong> is a JSON object <code>msg.payload</code> with</p>
<ul>
<li> <code>payload.state</code> <em>[number]</em> the current measured temperature</li>
<li> <code>payload.setTemperature</code> <em>[number]</em> the current temperature defined as set-point</li>
<li> <code>payload.operationType_ownValue</code> <em>[string]</em> (technical reference : the OpenWebNet value for the operation type)</li>
<li> <code>payload.operationType</code> <em>[string]</em> the current zone operation type
<table id="mh-tableinfo">
<tr> <th>ownValue</th> <th>operationType</th> </tr>
<tr> <td>0</td> <td>Conditioning</td> </tr>
<tr> <td>1</td> <td>Heating</td> </tr>
<tr> <td>102</td> <td>Antifreeze</td> </tr>
<tr> <td>202</td> <td>Thermal Protection</td> </tr>
<tr> <td>303</td> <td>Generic OFF</td> </tr>
</table>
</li>
<li> <code>payload.operationMode_ownValue</code> <em>[string]</em> (technical reference : the OpenWebNet value for the operation mode)</li>
<li> <code>payload.operationMode</code> <em>[string]</em> the current zone operation mode
<table id="mh-tableinfo">
<tr> <th>ownValue</th> <th>operationMode</th> </tr>
<tr> <td>110</td> <td>Manual Heating</td> </tr>
<tr> <td>210</td> <td>Manual Conditioning</td> </tr>
<tr> <td>111</td> <td>Automatic Heating</td> </tr>
<tr> <td>211</td> <td>Automatic Conditioning</td> </tr>
<tr> <td>103</td> <td>Off Heating</td> </tr>
<tr> <td>203</td> <td>Off Conditioning</td> </tr>
<tr> <td>102</td> <td>Antifreeze</td> </tr>
<tr> <td>202</td> <td>Thermal Protection</td> </tr>
</table>
</li>
<li> <code>payload.localOffset_ownValue</code> <em>[string]</em> (technical reference : the OpenWebNet value for the offset)</li>
<li> <code>payload.localOffset</code> <em>[string]</em> value is 'ON' or 'OFF'
<table id="mh-tableinfo">
<tr> <th>ownValue</th> <th>localOffset</th> </tr>
<tr> <td>00</td> <td>0 (no offset)</td> </tr>
<tr> <td>01</td> <td>1 (+1°C)</td> </tr>
<tr> <td>02</td> <td>2 (+2°C)</td> </tr>
<tr> <td>03</td> <td>3 (+3°C)</td> </tr>
<tr> <td>11</td> <td>-1 (-1°C)</td> </tr>
<tr> <td>12</td> <td>-2 (-2°C)</td> </tr>
<tr> <td>13</td> <td>-3 (-3°C)</td> </tr>
<tr> <td>04</td> <td>Local OFF</td> </tr>
<tr> <td>05</td> <td>Local protection</td> </tr>
</table>
</li>
<li> <code>payload.actuatorStates</code> <em>[JSON object]</em> containing all the states of actuators binded to current zone:
<ul>
<li><code>actuatorStates.On</code> <em>[boolean]</em> is 'true' when the last actuator for which info was received is 'ON'</li>
<li><code>actuatorStates.actuator_x</code> <em>[JSON object]</em> (where 'x' is '1-9', i.e. 1 object per binded actuator)
<ul>
<li><code>actuator_x.state_ownValue</code> <em>[string]</em> (technical reference : the OpenWebNet value for the actuator's state)</li>
<li><code>actuator_x.state</code> <em>[string]</em> contains the detailed state of the actuator</li>
<li><code>actuator_x.On</code> <em>[boolean]</em> contains 'true' when actuator is considered as 'active'</li>
<table id="mh-tableinfo">
<tr> <th>ownValue</th> <th>state</th> <th>.On state</th> </tr>
<tr> <td>0</td> <td>OFF</td> <td>false</td> </tr>
<tr> <td>1</td> <td>ON</td> <td>true</td> </tr>
<tr> <td>2</td> <td>Opened</td> <td>true</td> </tr>
<tr> <td>3</td> <td>Closed</td> <td>false</td> </tr>
<tr> <td>4</td> <td>Stop</td> <td>false</td> </tr>
<tr> <td>5</td> <td>OFF Fan Coil</td> <td>false</td> </tr>
<tr> <td>6</td> <td>ON Vel 1</td> <td>true</td> </tr>
<tr> <td>7</td> <td>ON Vel 2</td> <td>true</td> </tr>
<tr> <td>8</td> <td>ON Vel 3</td> <td>true</td> </tr>
<tr> <td>9</td> <td>ON Fan Coil</td> <td>true</td> </tr>
</table>
</ul>
</li>
</ul>
<li> <code>payload.command_sent</code> <em>[array of string]</em> when the node was triggered from Node-RED (i.e. commands were sent to the MyHome gateway), contains the commands which were sent in OpenWebNet protocol (e.g. <em>'*#4*2*#14*0225*3##'</em> to switch zone '2' to Manual mode @22.5°C)</li>
<li> <code>payload.command_received</code> <em>[string]</em> when the node was triggered from the gateway (i.e. a command was detected on the MyHome BUS for the configured load), contains the command which was read in OpenWebNet protocol (ex: <em>'*4*1*2'</em> means zone '2' operation mode is 'Heating')</li>
<li> <code>payload.command_responses</code> <em>[array of strings]</em> when the node was triggered from Node-RED in read-only mode, will contain the returned response(s) from the MyHome BUS in OpenWebNet protocol</li>
<li> <code>payload.command_failed</code> <em>[array of strings]</em> will contain the commands which were refused by the MyHome gateway, in OpenWebNet protocol</li>
</ul>
<p>The <strong>secondary output</strong> can be configured to better suits the needs of other node types you use without having to use an extra function/switch node for each connector
<br>
<u>Samples:</u>
</p>
<ul>
<li><strong>HUEMagic</strong> nodes support :
<ul>
<li><code>payload</code> being a boolean (true/false)</li>
<li><code>payload</code> being a JSON object where <code>.ON</code> is a boolean (true/false)</li>
</ul>
</li>
<li><strong>Homekit-bridge</strong> nodes support :
<ul>
<li><code>payload</code> being a JSON object where <code>.On</code> is a boolean (true/false)</li>
</ul>
<p>(see: <a title="homekit bridged" href="https://www.npmjs.com/package/node-red-contrib-homekit-bridged" target="_blank" rel="noopener">https://www.npmjs.com/package/node-red-contrib-homekit-bridged</a>) allow managing iOS Home App.</p>
</li>
<li><strong>MyHome</strong> nodes support :
<ul>
<li><code>payload</code> being either a boolean (true/false) or a string (ON/OFF/OPEN/CLOSE/...)</li>
<li><code>payload</code> being a JSON object where <code>.state</code> is a string (ON/OFF/OPEN/CLOSE/...)</li>
<li><code>payload</code> being a JSON object where <code>.On</code> is a boolean (true/false)</li>
</ul>
</li>
</ul>
<p>
<strong>Both outputs</strong> also include an additional object <code>msg.mh_nodeConfigInfo</code> which includes data from node configuration.
This can be used in flows to redirect messages based on how (i.e. which node) they come from without having to include 'change nodes' at every stage.
</p>
<p>
The <code>msg.mh_nodeConfigInfo</code> contains node configuration values :
</p>
<ul>
<li> <code>mh_nodeConfigInfo.name</code> <em>[string]</em> : name</li>
<li> <code>mh_nodeConfigInfo.topic</code> <em>[string]</em> : topic</li>
<li> <code>mh_nodeConfigInfo.zoneid</code> <em>[string]</em> : zone ID [1-99]</li>
<li> <code>mh_nodeConfigInfo.gateway</code> <em>[object]</em> : linked gateway info : name (<code>.name</code>), Host/IP (<code>.host</code>) and port (<code>.port</code>)</li>
</ul>
</script>