node-red-contrib-ccu 4.1.0 → 4.3.0

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

package/nodes/lib/channelfilter.js

@@ -0,0 +1,136 @@
+/* Channel matching for the filter form shared by ccu-set-value (and, from
+   4.3.0, reusable by anything else that resolves a filter to channels).
+
+   Extracted from ccu-set-value.js as part of B-2 so the matching is pure
+   and unit-testable, and so the per-message effective config (see
+   dynconfig.js) can be applied without the node caching the wrong thing.
+
+   Each criterion has a companion `<name>Rx` selector: 'str' compares
+   literally, 're' treats the configured value as a regular expression. */
+
+/** The filter criteria, in the order they are evaluated. */
+const FILTER_KEYS = [
+    'device',
+    'deviceType',
+    'deviceName',
+    'channel',
+    'channelType',
+    'channelIndex',
+    'channelName',
+    'rooms',
+    'functions',
+];
+
+/** All configuration keys that make up a filter, including the Rx selectors. */
+const CONFIG_KEYS = ['iface', ...FILTER_KEYS, 'datapoint', ...FILTER_KEYS.map((key) => key + 'Rx'), 'datapointRx'];
+
+function matches(value, pattern, rx) {
+    if (typeof value !== 'string') {
+        return false;
+    }
+
+    return rx === 're' ? Boolean(value.match(new RegExp(pattern))) : value === pattern;
+}
+
+function matchesList(list, pattern, rx) {
+    if (!Array.isArray(list)) {
+        return false;
+    }
+
+    return rx === 're' ? list.some((item) => matches(item, pattern, 're')) : list.includes(pattern);
+}
+
+/**
+ * Does one channel address pass the configured filter?
+ *
+ * @param {object} ccu connection-shaped dependency: metadata.devices,
+ *        channelNames, channelRooms, channelFunctions
+ * @param {string} iface
+ * @param {string} address channel address, e.g. `ABC1234567:1`
+ * @param {object} config effective configuration (see dynconfig.js)
+ * @returns {boolean} true when the channel is selected by the filter
+ */
+function channelMatches(ccu, iface, address, config) {
+    const channel = ccu.metadata.devices[iface] && ccu.metadata.devices[iface][address];
+
+    // Device-level entries (no PARENT) are never targets, only their channels
+    if (!channel || !channel.PARENT) {
+        return false;
+    }
+
+    const device = ccu.metadata.devices[iface][channel.PARENT] || {};
+
+    if (config.device && !matches(channel.PARENT, config.device, config.deviceRx)) {
+        return false;
+    }
+
+    if (config.deviceType && !matches(device.TYPE, config.deviceType, config.deviceTypeRx)) {
+        return false;
+    }
+
+    // Note: this used to test whether the *channel* had a ReGa name while
+    // comparing the *device* name, so channels without a name of their own
+    // were dropped even when their device matched (fixed in 4.3.0).
+    if (config.deviceName && !matches(ccu.channelNames[channel.PARENT], config.deviceName, config.deviceNameRx)) {
+        return false;
+    }
+
+    if (config.channel && !matches(address, config.channel, config.channelRx)) {
+        return false;
+    }
+
+    if (config.channelType && !matches(channel.TYPE, config.channelType, config.channelTypeRx)) {
+        return false;
+    }
+
+    if (config.channelIndex) {
+        const index = address.split(':')[1];
+        if (config.channelIndexRx === 're') {
+            if (!matches(index, String(config.channelIndex), 're')) {
+                return false;
+            }
+        } else if (!address.endsWith(':' + config.channelIndex)) {
+            return false;
+        }
+    }
+
+    if (config.channelName && !matches(ccu.channelNames[address], config.channelName, config.channelNameRx)) {
+        return false;
+    }
+
+    if (config.rooms && !matchesList(ccu.channelRooms[address], config.rooms, config.roomsRx)) {
+        return false;
+    }
+
+    if (config.functions && !matchesList(ccu.channelFunctions[address], config.functions, config.functionsRx)) {
+        return false;
+    }
+
+    return true;
+}
+
+/**
+ * The datapoints of one channel that pass the datapoint filter.
+ * @param {object} ccu connection-shaped dependency: paramsetName, paramsetDescriptions
+ * @param {string} iface
+ * @param {string} address
+ * @param {object} config effective configuration
+ * @returns {string[]} datapoint names (empty when the channel has no VALUES description)
+ */
+function datapointsOf(ccu, iface, address, config) {
+    const channel = ccu.metadata.devices[iface] && ccu.metadata.devices[iface][address];
+    const psKey = channel && ccu.paramsetName(iface, channel, 'VALUES');
+    const description = psKey && ccu.paramsetDescriptions[psKey];
+    if (!description) {
+        return [];
+    }
+
+    // No special case for an empty datapoint filter: with str it selects
+    // nothing (a literal comparison against undefined) and with re it
+    // selects everything, exactly as before the extraction. Silently
+    // widening str to "all datapoints" would write the payload to every
+    // datapoint of every matched channel.
+    return Object.keys(description).filter((dp) => matches(dp, config.datapoint, config.datapointRx));
+}
+
+module.exports = {channelMatches, datapointsOf, FILTER_KEYS, CONFIG_KEYS};