node-red-contrib-ccu 4.2.0 → 4.3.0

package/nodes/ccu-switch.html

@@ -239,7 +239,9 @@
                     arr.sort((a, b) => a.localeCompare(b));
                     $nodeInputChannel.autocomplete('option', 'source', arr);
 
-                    if (!data[$nodeInputChannel.val().split(' ')[0]]) {
+                    // ${ENV} placeholders are substituted by Node-RED before the node is
+                    // constructed (subflow parameters, #158) - do not clear them
+                    if (!/^\$\{[^}]+\}$/.test($nodeInputChannel.val()) && !data[$nodeInputChannel.val().split(' ')[0]]) {
                         $nodeInputChannel.val('');
                         $nodeInputDatapoint.val('');
                     }
@@ -345,12 +347,12 @@
                                 selectField.append($('<option></option>').val(operators[d].v).text(node._(operators[d].t)));
                             }
                         }
-                        const valueField = $('<input/>', {class: 'node-input-rule-value', type: 'text', style: 'margin-left: 5px;'}).appendTo(row).typedInput({default: 'str', types: ['msg', 'flow', 'global', 'str', 'num', 'jsonata', 'env', previousValueType]});
+                        const valueField = $('<input/>', {class: 'node-input-rule-value', type: 'text', style: 'margin-left: 5px;'}).appendTo(row).typedInput({default: 'str', types: ['msg', 'flow', 'global', 'str', 'num', 'bool', 'jsonata', 'env', previousValueType]});
                         const numValueField = $('<input/>', {class: 'node-input-rule-num-value', type: 'text', style: 'margin-left: 5px;'}).appendTo(row).typedInput({default: 'num', types: ['flow', 'global', 'num', 'jsonata', 'env']});
                         const expValueField = $('<input/>', {class: 'node-input-rule-exp-value', type: 'text', style: 'margin-left: 5px;'}).appendTo(row).typedInput({default: 'jsonata', types: ['jsonata']});
-                        const btwnValueField = $('<input/>', {class: 'node-input-rule-btwn-value', type: 'text', style: 'margin-left: 5px;'}).appendTo(row).typedInput({default: 'num', types: ['msg', 'flow', 'global', 'str', 'num', 'jsonata', 'env', previousValueType]});
+                        const btwnValueField = $('<input/>', {class: 'node-input-rule-btwn-value', type: 'text', style: 'margin-left: 5px;'}).appendTo(row).typedInput({default: 'num', types: ['msg', 'flow', 'global', 'str', 'num', 'bool', 'jsonata', 'env', previousValueType]});
                         const btwnAndLabel = $('<span/>', {class: 'node-input-rule-btwn-label'}).text(' ' + andLabel + ' ').appendTo(row3);
-                        const btwnValue2Field = $('<input/>', {class: 'node-input-rule-btwn-value2', type: 'text', style: 'margin-left:2px;'}).appendTo(row3).typedInput({default: 'num', types: ['msg', 'flow', 'global', 'str', 'num', 'jsonata', 'env', previousValueType]});
+                        const btwnValue2Field = $('<input/>', {class: 'node-input-rule-btwn-value2', type: 'text', style: 'margin-left:2px;'}).appendTo(row3).typedInput({default: 'num', types: ['msg', 'flow', 'global', 'str', 'num', 'bool', 'jsonata', 'env', previousValueType]});
                         const typeValueField = $('<input/>', {class: 'node-input-rule-type-value', type: 'text', style: 'margin-left: 5px;'}).appendTo(row)
                             .typedInput({default: 'string', types: [
                                     {value: 'string', label: 'string', hasValue: false},
@@ -801,6 +803,17 @@
     <p>Der ccu switch Node verhält sich ähnlich wie der switch Node von Node-RED. Er leitet eine Nachricht abhängig von einem Zustand eines Aktors oder einer Systemvariablen weiter, wahlweise auch je nach Zustand an unterschiedliche Ausgänge.</p>
     <h4>Dokumentation</h4>
     <a target="_blank" href="https://github.com/rdmtc/RedMatic/wiki/CCU-Nodes#ccu-switch-node">ccu switch node im RedMatic Wiki</a>
+
+    <h3>Dynamische Konfiguration</h3>
+    <p><code>msg.config</code> ist ein Objekt, dessen Eigenschaften die Konfiguration dieses Nodes für genau diese Nachricht überschreiben. Die gespeicherte Konfiguration bleibt unverändert.</p>
+    <ul>
+        <li><code>iface</code></li>
+        <li><code>channel</code></li>
+        <li><code>datapoint</code></li>
+        <li><code>datapointProperty</code></li>
+        <li><code>sysvar</code></li>
+        <li><code>sysvarProperty</code></li>
+    </ul>
 </script>
 
 

package/nodes/ccu-switch.js

@@ -14,6 +14,13 @@
  * limitations under the License.
  **/
 
+const path = require('path');
+
+const {effectiveConfig} = require(path.join(__dirname, '/lib/dynconfig.js'));
+
+/** Source selection a message may override through msg.config (B-2, #103). */
+const DYNAMIC_KEYS = ['iface', 'channel', 'datapoint', 'datapointProperty', 'sysvar', 'sysvarProperty'];
+
 module.exports = function (RED) {
     'use strict';
 
@@ -132,11 +139,28 @@ module.exports = function (RED) {
 
     function getProperty(node, msg) {
         return new Promise((resolve, reject) => {
-            if (node.iface === 'ReGaHSS') {
-                resolve(node.ccu.sysvar[node.sysvar] && node.ccu.sysvar[node.sysvar][node.sysvarProperty]);
+            // which datapoint or variable to look at can come from the
+            // message, so one switch node can serve a whole subflow (#103)
+            const {config} = effectiveConfig(
+                {
+                    iface: node.iface,
+                    channel: node.channel,
+                    datapoint: node.datapoint,
+                    datapointProperty: node.datapointProperty,
+                    sysvar: node.sysvar,
+                    sysvarProperty: node.sysvarProperty
+                },
+                msg,
+                DYNAMIC_KEYS
+            );
+
+            if (config.iface === 'ReGaHSS') {
+                const sysvar = node.ccu.sysvar[config.sysvar];
+                resolve(sysvar && sysvar[config.sysvarProperty || 'value']);
             } else {
-                const address = node.iface + '.' + String(node.channel).split(' ')[0] + '.' + node.datapoint;
-                resolve(node.ccu.values[address] && node.ccu.values[address][node.datapointProperty]);
+                const address = config.iface + '.' + String(config.channel).split(' ')[0] + '.' + config.datapoint;
+                const value = node.ccu.values[address];
+                resolve(value && value[config.datapointProperty || 'value']);
             }
         });
     }

package/nodes/ccu-sysvar.html

@@ -7,7 +7,9 @@
             ccuConfig: {value: 'localhost', type: 'ccu-connection', required: true},
             topic: {value: 'ReGaHSS/${Name}'},  
             change: {value: true},
-            cache: {value: true}
+            cache: {value: true},
+            property: {value: 'payload'},
+            propertyType: {value: 'msg'}
         },
         inputs: 1,
         outputs: 1,
@@ -24,6 +26,24 @@
         oneditprepare() {
             const cname = this.name;
 
+            // Where the value to write comes from (#56). Older nodes have no
+            // property/propertyType - default them to msg.payload, which is
+            // what the node always used.
+            if (!this.property) {
+                this.property = 'payload';
+                $('#node-input-property').val('payload');
+            }
+
+            if (!this.propertyType) {
+                this.propertyType = 'msg';
+            }
+
+            $('#node-input-property').typedInput({
+                default: this.propertyType,
+                types: ['msg', 'flow', 'global', 'str', 'num', 'bool', 'json', 'env'],
+                typeField: $('#node-input-propertyType')
+            });
+
             // Migration
             if (typeof this.change === 'undefined') {
                 $('#node-input-change').attr('checked', true);
@@ -97,6 +117,11 @@
         <select id="select-input-name" style="display:none" class="ccu-dropdown">
         </select>
     </div>
+    <div class="form-row">
+        <label for="node-input-property"><i class="fa fa-sign-in"></i> <span data-i18n="ccu-sysvar.property"></span></label>
+        <input type="text" id="node-input-property" placeholder="payload" style="width:70%;">
+        <input type="hidden" id="node-input-propertyType">
+    </div>
     <div class="form-row">
         <label for="node-input-change"><i class="icon-bookmark"></i> </label>
         <div style="width: 70%; display: inline-block; vertical-align: text-top;">
@@ -148,6 +173,13 @@
                </code></pre>
          </li>
      </ol>
+
+    <h3>Dynamische Konfiguration</h3>
+    <p><code>msg.config</code> ist ein Objekt, dessen Eigenschaften die Konfiguration dieses Nodes für genau diese Nachricht überschreiben. Die gespeicherte Konfiguration bleibt unverändert.</p>
+    <ul>
+        <li><code>name</code></li>
+    </ul>
+    <p>Woher der zu schreibende Wert kommt, stellt das Feld <em>Wert aus</em> ein (msg/flow/global/env) — er muss nicht mehr in <code>msg.payload</code> stehen.</p>
 </script>
 
 <script type="text/x-red" data-help-name="ccu-sysvar" lang="en-US">
@@ -161,4 +193,11 @@
             The value that should be assigned to the variable.
         </dd>
     </dl>
+
+    <h3>Dynamic configuration</h3>
+    <p><code>msg.config</code> is an object whose properties override this node's configuration for that one message. The stored configuration is never modified.</p>
+    <ul>
+        <li><code>name</code></li>
+    </ul>
+    <p>The <em>Value from</em> field selects where the value to write comes from (msg/flow/global/env); it no longer has to be <code>msg.payload</code>.</p>
 </script>

package/nodes/ccu-sysvar.js

@@ -1,6 +1,11 @@
 const path = require('path');
 
 const statusHelper = require(path.join(__dirname, '/lib/status.js'));
+const {effectiveConfig} = require(path.join(__dirname, '/lib/dynconfig.js'));
+const {valueStatus} = require(path.join(__dirname, '/lib/valuestatus.js'));
+
+/** What a message may override through msg.config (B-2). */
+const DYNAMIC_KEYS = ['name'];
 
 module.exports = function (RED) {
     class CcuSysvarNode {
@@ -28,27 +33,53 @@ module.exports = function (RED) {
             this.name = config.name;
             this.topic = config.topic;
 
+            // Where the value to write comes from. Defaults to msg.payload,
+            // which is what the node has always used (#56).
+            this.property = config.property || 'payload';
+            this.propertyType = config.propertyType || 'msg';
+
+            this.valueStatus = valueStatus(this);
+
             this.idSubscription = this.ccu.subscribeSysvar(
                 {name: this.name, cache: config.cache, change: config.change},
                 (message) => {
-                    this.status({fill: 'green', shape: 'ring', text: String(message.payload)});
+                    this.valueStatus.set(message.payload, message.ts);
                     message.topic = this.ccu.topicReplace(config.topic, message);
                     this.send(message);
                 },
             );
 
+            // Show the current value even when "emit value on start" is off:
+            // the connection knows it either way (#54)
+            if (!config.cache && this.name) {
+                const known = this.ccu.sysvar[this.name];
+                if (known) {
+                    this.valueStatus.set(known.value, known.ts);
+                }
+            }
+
             this.on('input', this._input);
             this.on('close', this._destructor);
         }
 
         _input(message, send, done) {
-            const name = this.name || message.topic;
-            const value = message.payload;
-            this.ccu
-                .setVariable(name, value)
-                .then(() => {
-                    this.status({fill: 'green', shape: 'ring', text: String(value)});
-                    done();
+            done = done || ((error) => error && this.error(error, message));
+            const {config} = effectiveConfig({name: this.name}, message, DYNAMIC_KEYS);
+            const name = config.name || message.topic;
+
+            this.getValue(message)
+                .then((value) => {
+                    if (value === undefined) {
+                        // nothing to write - do not turn an empty message into
+                        // a variable write (same guard as the value node)
+                        done();
+                        return;
+                    }
+
+                    return this.ccu.setVariable(name, value).then(() => {
+                        this.valueStatus.set(value, Date.now());
+                        done();
+                    });
                 })
                 .catch((error) => {
                     this.currentStatus = 'red';
@@ -57,7 +88,46 @@ module.exports = function (RED) {
                 });
         }
 
+        /**
+         * The value to write, from the configured source (#56).
+         * @param {object} message
+         * @returns {Promise<*>}
+         */
+        getValue(message) {
+            return new Promise((resolve, reject) => {
+                switch (this.propertyType) {
+                    case 'flow':
+                    case 'global': {
+                        const contextKey = RED.util.parseContextStore(this.property);
+                        this.context()[this.propertyType].get(contextKey.key, contextKey.store, (err, res) => {
+                            if (err) {
+                                reject(err);
+                            } else {
+                                resolve(res);
+                            }
+                        });
+                        break;
+                    }
+
+                    case 'str':
+                    case 'num':
+                    case 'bool':
+                    case 'json':
+                    case 'env':
+                        resolve(RED.util.evaluateNodeProperty(this.property, this.propertyType, this, message));
+                        break;
+
+                    default:
+                        resolve(RED.util.getMessageProperty(message, this.property));
+                }
+            });
+        }
+
         _destructor(done) {
+            if (this.valueStatus) {
+                this.valueStatus.stop();
+            }
+
             if (this.idSubscription) {
                 this.debug('unsubscribe');
                 this.ccu.unsubscribeSysvar(this.idSubscription);

package/nodes/ccu-value.html

@@ -15,6 +15,7 @@
             start: {value: true},
             change: {value: true},
             cache: {value: false},
+            certainOnly: {value: false},
             queue: {value: false},
             on: {value: ''},
             onType: {value: 'undefined'},
@@ -176,7 +177,9 @@
                 arr.sort((a, b) => a.localeCompare(b));
                 $nodeInputChannel.autocomplete('option', 'source', arr);
 
-                if (!data[$nodeInputChannel.val().split(' ')[0]]) {
+                // ${ENV} placeholders are substituted by Node-RED before the node is
+                // constructed (subflow parameters, #158) - do not clear them
+                if (!/^\$\{[^}]+\}$/.test($nodeInputChannel.val()) && !data[$nodeInputChannel.val().split(' ')[0]]) {
                     $nodeInputChannel.val('');
                     $nodeInputDatapoint.val('');
                 }
@@ -480,6 +483,11 @@
                 <input type="checkbox" id="node-input-cache">
                 <span data-i18n="ccu-value.cache"></span>
             </label>
+
+            <label class="ccu-checkbox">
+                <input type="checkbox" id="node-input-certainOnly">
+                <span data-i18n="ccu-value.certainOnly"></span>
+            </label>
         </div>
     </div>
 
@@ -580,8 +588,26 @@
     <h3>Output</h3>
     <p>Der Value Node gibt nur Events aus, wenn Interface, Channel und Datapoint gesetzt sind.</p>
 
+
+    <h3>Dynamische Konfiguration</h3>
+    <p><code>msg.config</code> ist ein Objekt, dessen Eigenschaften die Konfiguration dieses Nodes für genau diese Nachricht überschreiben. Die gespeicherte Konfiguration bleibt unverändert.</p>
+    <ul>
+        <li><code>iface</code></li>
+        <li><code>channel</code></li>
+        <li><code>datapoint</code></li>
+    </ul>
+    <p>Eine Nachricht ohne <code>payload</code> schreibt nichts, richtet aber die Ausgabe-Seite des Nodes neu aus.</p>
 </script>
 
 <script type="text/x-red" data-help-name="ccu-value" lang="en-US">
     <p>Set and read channel datapoints.</p>
+
+    <h3>Dynamic configuration</h3>
+    <p><code>msg.config</code> is an object whose properties override this node's configuration for that one message. The stored configuration is never modified.</p>
+    <ul>
+        <li><code>iface</code></li>
+        <li><code>channel</code></li>
+        <li><code>datapoint</code></li>
+    </ul>
+    <p>A message without a <code>payload</code> writes nothing but retargets the node's output side.</p>
 </script>

package/nodes/ccu-value.js

@@ -1,6 +1,10 @@
 const path = require('path');
 
 const statusHelper = require(path.join(__dirname, '/lib/status.js'));
+const {effectiveConfig, configCacheKey} = require(path.join(__dirname, '/lib/dynconfig.js'));
+
+/** What a message may supply or override (B-2, #172). */
+const DYNAMIC_KEYS = ['iface', 'channel', 'datapoint'];
 
 module.exports = function (RED) {
     class CcuValue {
@@ -15,37 +19,33 @@ module.exports = function (RED) {
 
             this.iface = config.iface;
             this.queue = config.queue;
+            this.config = config;
 
             this.ccu.register(this);
 
-            if (config.iface && config.channel && config.datapoint) {
-                const filter = {
-                    cache: config.cache,
-                    change: config.change,
-                    stable: config.working,
-                    iface: config.iface,
-                    channel: String(config.channel).split(' ')[0],
-                    datapoint: config.datapoint,
-                };
-
-                this.idSubscription = this.ccu.subscribe(filter, (message) => {
-                    this.status({fill: 'green', shape: 'ring', text: String(message.payload)});
-                    message.topic = this.ccu.topicReplace(config.topic, message);
-                    this.send(message);
-                });
-            }
+            this.subscriptionKey = null;
+            this.subscribeTo({
+                iface: config.iface,
+                channel: config.channel,
+                datapoint: config.datapoint,
+            });
 
             this.on('input', (message, send, done) => {
                 const [tIface, tChannel, tDatapoint] = (message.topic || '').split('.');
-                const iface = config.iface || message.interface || message.iface || tIface;
+                // msg.config wins over the node's own configuration; the flat
+                // msg.iface/channel/datapoint chain below is unchanged
+                const {config: over} = effectiveConfig({}, message, DYNAMIC_KEYS);
+
+                const iface = over.iface || config.iface || message.interface || message.iface || tIface;
                 const channel = (
+                    over.channel ||
                     config.channel ||
                     this.ccu.findChannel(message.channelName, true) ||
                     message.channel ||
                     tChannel ||
                     ''
                 ).split(' ')[0];
-                const datapoint = config.datapoint || message.datapoint || tDatapoint;
+                const datapoint = over.datapoint || config.datapoint || message.datapoint || tDatapoint;
 
                 if (!iface) {
                     this.error('interface undefined');
@@ -63,7 +63,13 @@ module.exports = function (RED) {
                 }
 
                 if (message.payload === undefined) {
-                    // don't write to the CCU when the incoming msg carries no payload (PR #173)
+                    // don't write to the CCU when the incoming msg carries no
+                    // payload (PR #173). Such a message may still retarget the
+                    // output side, which is what "configure through message"
+                    // asked for (#172) - for a node with its own channel and
+                    // datapoint configured this is a no-op unless msg.config
+                    // explicitly overrides them.
+                    this.subscribeTo({iface, channel, datapoint});
                     done();
                     return;
                 }
@@ -146,6 +152,50 @@ module.exports = function (RED) {
             this.on('close', this._destructor);
         }
 
+        /**
+         * (Re-)subscribe the output side. A no-op when the target is
+         * unchanged, so a node configured in the editor keeps exactly one
+         * subscription for its lifetime as before (#172).
+         * @param {{iface: string, channel: string, datapoint: string}} target
+         */
+        subscribeTo(target) {
+            const {config} = this;
+            if (!target.iface || !target.channel || !target.datapoint) {
+                return;
+            }
+
+            const filter = {
+                cache: config.cache,
+                change: config.change,
+                stable: config.working,
+                iface: target.iface,
+                channel: String(target.channel).split(' ')[0],
+                datapoint: target.datapoint,
+            };
+
+            // opt-in: only present when the option is enabled, so existing
+            // subscriptions keep receiving uncertain values (#96)
+            if (config.certainOnly) {
+                filter.uncertain = false;
+            }
+
+            const key = configCacheKey(filter, ['iface', 'channel', 'datapoint']);
+            if (key === this.subscriptionKey) {
+                return;
+            }
+
+            if (this.idSubscription) {
+                this.ccu.unsubscribe(this.idSubscription);
+            }
+
+            this.subscriptionKey = key;
+            this.idSubscription = this.ccu.subscribe(filter, (message) => {
+                this.status({fill: 'green', shape: 'ring', text: String(message.payload)});
+                message.topic = this.ccu.topicReplace(config.topic, message);
+                this.send(message);
+            });
+        }
+
         _destructor(done) {
             if (this.idSubscription) {
                 this.debug('ccu-value close');

package/nodes/lib/cast.js

@@ -1,20 +1,57 @@
-/* Pure value casting against a paramset description (TYPE/ENUM/MIN/MAX),
-   extracted unchanged from ccu-connection.js paramCast (Phase 3).
+/* Pure value casting against a paramset description (TYPE/VALUE_LIST/MIN/MAX),
+   extracted from ccu-connection.js paramCast (Phase 3) and unified with the
+   ccu-mqtt node's divergent copy (B-3): that one clamped to MIN/MAX and cast
+   INTEGER slightly differently, which is now the `clamp` option rather than a
+   second implementation.
 
-   Note: nodes/ccu-mqtt.js still carries its own divergent variant (with
-   MIN/MAX clamping and different INTEGER handling) — unifying that one is
-   roadmap item B-3, deliberately not done in this behavior-preserving
-   extraction. */
+   Note on enum names: the CCU returns them in `VALUE_LIST`, not `ENUM`. The
+   old code read `description.ENUM`, which no interface process ever sends -
+   all 9494 ENUM-typed datapoints in the shipped paramsets.json carry
+   VALUE_LIST and none carries ENUM - so casting an enum by name never worked
+   and message.datapointEnum/valueEnum were always undefined (B-3, ROADMAP
+   8.2). `ENUM` is still accepted as a fallback for hand-written data. */
+
+/**
+ * The list of enum names for a description, or undefined.
+ * @param {object} [description]
+ * @returns {string[]|undefined}
+ */
+function enumList(description) {
+    if (!description) {
+        return undefined;
+    }
+
+    const list = description.VALUE_LIST || description.ENUM;
+    return Array.isArray(list) ? list : undefined;
+}
+
+function clampNumber(value, description) {
+    if (typeof description.MIN === 'number' && value < description.MIN) {
+        return description.MIN;
+    }
+
+    if (typeof description.MAX === 'number' && value > description.MAX) {
+        return description.MAX;
+    }
+
+    return value;
+}
 
 /**
  * Cast a value according to a paramset description.
  * @param {*} value
- * @param {object} [description] paramset description (TYPE, ENUM, ...);
+ * @param {object} [description] paramset description (TYPE, VALUE_LIST, ...);
  *        when missing, numbers are stringified (works for FLOAT/INTEGER
  *        datapoints) and everything else passes through unchanged.
+ * @param {object} [options]
+ * @param {boolean} [options.clamp=false] limit numbers to MIN/MAX. Off for
+ *        the value nodes (#74), on for the mqtt node, which has clamped
+ *        since it was written.
  * @returns {*} the casted value; FLOAT becomes {explicitDouble: number}
  */
-function castValue(value, description) {
+function castValue(value, description, options) {
+    const clamp = Boolean(options && options.clamp);
+
     if (!description) {
         // Fallback: use string for numbers, this should work for double and integer datapoints
         if (typeof value === 'number') {
@@ -40,14 +77,18 @@ function castValue(value, description) {
         case 'FLOAT':
             value = Number.parseFloat(value) || 0;
             /* Todo: rethink, deactivate boundary check for now (https://github.com/rdmtc/node-red-contrib-ccu/issues/74) */
+            if (clamp) {
+                value = clampNumber(value, description);
+            }
+
             value = {explicitDouble: value};
             break;
-        case 'ENUM':
-            if (typeof value === 'string') {
-                if (description.ENUM && description.ENUM.includes(value)) {
-                    value = description.ENUM.indexOf(value);
-                }
+        case 'ENUM': {
+            const list = enumList(description);
+            if (typeof value === 'string' && list && list.includes(value)) {
+                value = list.indexOf(value);
             }
+        }
 
         // Fallthrough by intention
         case 'INTEGER':
@@ -57,6 +98,10 @@ function castValue(value, description) {
                 value = Number.parseInt(value, 10) || 0;
             }
 
+            if (clamp) {
+                value = clampNumber(value, description);
+            }
+
             break;
         case 'STRING':
             value = String(value);
@@ -103,4 +148,4 @@ function castSysvar(value, sysvar) {
     return value;
 }
 
-module.exports = {castValue, castSysvar};
+module.exports = {castValue, castSysvar, enumList};