node-red-contrib-ccu 4.2.0 → 4.3.0

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

package/nodes/lib/dynconfig.js

@@ -0,0 +1,81 @@
+/* Per-message dynamic node configuration (B-2, issues #172 #71 #103 #80
+   #56 #148 #133).
+
+   Two mechanisms, in increasing precedence:
+
+   1. Flat properties (`msg.channel`, `msg.rooms`, ...). Long-standing
+      behaviour of ccu-set-value/ccu-value/ccu-get-value: they fill in
+      configuration the node itself leaves empty. Kept as-is because
+      messages coming straight from an event node carry exactly these
+      names, which is what makes it convenient - and, for the same
+      reason, only ever used for the nodes that already did it.
+   2. `msg.config`, an object of overrides. Always wins, works for every
+      configurable field including lists, and cannot collide with the
+      properties an event message carries (`msg.ccu` is the CCU host, so
+      it is not available as a namespace). This is what makes the
+      settings of the signal/display/switch/sysvar nodes reachable from
+      a flow.
+
+   The old inline implementation in ccu-set-value wrote message
+   properties into the node's own `config` object, so only the *first*
+   message ever configured the node: every later message hit the
+   `if (!config[key])` guard and was ignored (#133). Nothing here mutates
+   the stored configuration. */
+
+/**
+ * Build the effective configuration for one message.
+ *
+ * @param {object} config the node's stored configuration (never mutated)
+ * @param {object} message the incoming message
+ * @param {string[]} keys the keys that may be overridden; anything else
+ *        in `msg.config` is ignored, so a stray property cannot reach
+ *        node internals
+ * @param {object} [options]
+ * @param {boolean} [options.flat=false] also fill empty keys from
+ *        top-level message properties (mechanism 1)
+ * @returns {{config: object, dynamic: boolean}} effective config plus
+ *          whether anything actually came from the message
+ */
+function effectiveConfig(config, message, keys, options) {
+    const effective = {...config};
+    let dynamic = false;
+
+    if (!message || typeof message !== 'object') {
+        return {config: effective, dynamic};
+    }
+
+    if (options && options.flat) {
+        keys.forEach((key) => {
+            if (!effective[key] && key in message) {
+                effective[key] = message[key];
+                dynamic = true;
+            }
+        });
+    }
+
+    const overrides = message.config;
+    if (overrides && typeof overrides === 'object' && !Array.isArray(overrides)) {
+        keys.forEach((key) => {
+            if (key in overrides) {
+                effective[key] = overrides[key];
+                dynamic = true;
+            }
+        });
+    }
+
+    return {config: effective, dynamic};
+}
+
+/**
+ * A stable identity for a set of configuration keys, used to decide
+ * whether a cache derived from them is still valid. Two effective configs
+ * that produce the same key select the same devices/datapoints.
+ * @param {object} config
+ * @param {string[]} keys
+ * @returns {string}
+ */
+function configCacheKey(config, keys) {
+    return keys.map((key) => JSON.stringify(config[key] === undefined ? null : config[key])).join(' ');
+}
+
+module.exports = {effectiveConfig, configCacheKey};

package/nodes/lib/localccu.js

@@ -0,0 +1,81 @@
+/* Detecting "Node-RED runs on the CCU itself" (B-4).
+
+   When it does, the interface processes can be reached directly on their
+   3xxxx ports (BINRPC where available) instead of going through the CCU's
+   lighttpd proxy on 1999/2000/2001/2010/9292 - fewer hops, and BINRPC
+   instead of XML-RPC for BidCos.
+
+   The old test grepped /etc/lighttpd/conf.d/proxy.conf for
+   `"port" => 32001`. On current firmware that file is a one-line
+   `include "/var/etc/lighttpd_proxy.conf"`, which itself only includes
+   proxy_normal.conf - the port markers are two levels down, so the regex
+   has not matched since (verified on CCU3 firmware 3.89.8, where 31999,
+   32001, 32010 and 39292 are all listening while proxy.conf says nothing
+   about them). Every local install has silently been running through the
+   proxy.
+
+   Rather than chasing lighttpd's include chain, ask the kernel: a
+   listener on the direct port is exactly the condition that makes using
+   it correct. /proc/net/tcp is a plain file, so this stays synchronous -
+   the interface table is built in the connection node's constructor. */
+
+const fs = require('fs');
+
+/** rfd's direct BINRPC port on firmware >= 3.41; the marker for "on the CCU". */
+const LOCAL_PROBE_PORTS = [32001, 31999];
+
+const PROC_NET_TCP = ['/proc/net/tcp', '/proc/net/tcp6'];
+
+/** /proc/net/tcp connection state 0A = TCP_LISTEN. */
+const TCP_LISTEN = '0A';
+
+/**
+ * The TCP ports something is listening on, from /proc/net/tcp{,6}.
+ * @param {string[]} [files] override, for tests
+ * @returns {Set<number>} empty when /proc is unavailable (non-Linux)
+ */
+function listeningPorts(files) {
+    const ports = new Set();
+
+    (files || PROC_NET_TCP).forEach((file) => {
+        let content;
+        try {
+            content = fs.readFileSync(file, 'utf8');
+        } catch {
+            return;
+        }
+
+        content.split('\n').forEach((line) => {
+            // sl  local_address rem_address st ...
+            const columns = line.trim().split(/\s+/);
+            if (columns.length < 4 || columns[3] !== TCP_LISTEN) {
+                return;
+            }
+
+            const port = Number.parseInt(String(columns[1]).split(':')[1], 16);
+            if (Number.isInteger(port)) {
+                ports.add(port);
+            }
+        });
+    });
+
+    return ports;
+}
+
+/**
+ * Are we talking to a CCU we are running on, with the direct ports open?
+ * @param {string} host the configured CCU host
+ * @param {object} [options]
+ * @param {string[]} [options.files] /proc files to read, for tests
+ * @returns {boolean}
+ */
+function isLocalCcu(host, options) {
+    if (!host || !(String(host).startsWith('127.') || host === 'localhost' || host === '::1')) {
+        return false;
+    }
+
+    const ports = listeningPorts(options && options.files);
+    return LOCAL_PROBE_PORTS.some((port) => ports.has(port));
+}
+
+module.exports = {isLocalCcu, listeningPorts, LOCAL_PROBE_PORTS};

package/nodes/lib/message.js

@@ -18,6 +18,8 @@
  * @param {object} [additions] merged into the message (cache, working, uncertain, ts, lc, ...)
  * @returns {object} the message
  */
+const {enumList} = require('./cast.js');
+
 function createMessage(ccu, iface, channel, datapoint, payload, additions) {
     const datapointName = iface + '.' + channel + '.' + datapoint;
     if (!ccu.values[datapointName]) {
@@ -73,12 +75,14 @@ function createMessage(ccu, iface, channel, datapoint, payload, additions) {
         datapointType: description.TYPE,
         datapointMin: description.MIN,
         datapointMax: description.MAX,
-        datapointEnum: description.ENUM,
+        // the CCU sends the names in VALUE_LIST; reading description.ENUM
+        // meant both of these were always undefined (B-3, ROADMAP 8.2)
+        datapointEnum: enumList(description),
         datapointDefault: description.DEFAULT,
         datapointControl: description.CONTROL,
         value: payload,
         valuePrevious: ccu.values[datapointName].value,
-        valueEnum: description.ENUM ? description.ENUM[Number(payload)] : undefined,
+        valueEnum: enumList(description) ? enumList(description)[Number(payload)] : undefined,
         valueStable,
         rooms: ccu.channelRooms[channel] || [],
         room:

package/nodes/lib/valuestatus.js

@@ -0,0 +1,145 @@
+/* Node status line showing the last known value and how old it is
+   (B-5, issues #54 and #52).
+
+   The data was always there - the connection keeps value, ts and lc for
+   every datapoint and system variable - the nodes just never showed it,
+   and the sysvar node only showed anything at all when "emit value on
+   start" was enabled. The age is re-rendered on a timer so the line does
+   not silently become stale between events. */
+
+/** Node-RED status lines are narrow - keep them readable. */
+const MAX_TEXT = 45;
+
+const MINUTE = 60;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+
+/** How often the age is re-rendered, matched to the resolution shown. */
+function refreshInterval(seconds) {
+    if (seconds < MINUTE) {
+        return 5000;
+    }
+
+    if (seconds < HOUR) {
+        return 30000;
+    }
+
+    return 300000;
+}
+
+/**
+ * Compact age of a timestamp, in the style Node-RED status lines use.
+ * @param {number} ts epoch milliseconds
+ * @param {number} now epoch milliseconds
+ * @returns {string} e.g. '5s', '12m', '3h', '2d'
+ */
+function relativeTime(ts, now) {
+    const seconds = Math.max(0, Math.round((now - ts) / 1000));
+    if (seconds < MINUTE) {
+        return seconds + 's';
+    }
+
+    if (seconds < HOUR) {
+        return Math.floor(seconds / MINUTE) + 'm';
+    }
+
+    if (seconds < DAY) {
+        return Math.floor(seconds / HOUR) + 'h';
+    }
+
+    return Math.floor(seconds / DAY) + 'd';
+}
+
+/**
+ * The status text for a value with a timestamp.
+ * @param {*} value
+ * @param {number} [ts] epoch milliseconds; omitted renders the value alone
+ * @param {number} now epoch milliseconds
+ * @returns {string}
+ */
+function formatValueStatus(value, ts, now) {
+    let text = String(value);
+    if (text.length > MAX_TEXT) {
+        text = text.slice(0, MAX_TEXT - 1) + '…';
+    }
+
+    if (!ts) {
+        return text;
+    }
+
+    return text + ' (' + relativeTime(ts, now) + ')';
+}
+
+/**
+ * Keeps a node's status line showing the last value and its age.
+ *
+ * @param {object} node the Node-RED node (needs .status())
+ * @param {object} [options]
+ * @param {Function} [options.now] clock, for tests
+ * @returns {{set: Function, clear: Function, stop: Function}}
+ */
+function valueStatus(node, options) {
+    const now = (options && options.now) || Date.now;
+    let timer = null;
+    let current = null;
+
+    function render() {
+        if (!current) {
+            return;
+        }
+
+        node.status({
+            fill: 'green',
+            shape: 'ring',
+            text: formatValueStatus(current.value, current.ts, now()),
+        });
+    }
+
+    function schedule() {
+        if (timer) {
+            clearInterval(timer);
+            timer = null;
+        }
+
+        if (!current || !current.ts) {
+            return;
+        }
+
+        const interval = refreshInterval(Math.round((now() - current.ts) / 1000));
+        timer = setInterval(() => {
+            render();
+            // the resolution coarsens as the value ages - re-arm accordingly
+            schedule();
+        }, interval);
+        if (typeof timer.unref === 'function') {
+            timer.unref();
+        }
+    }
+
+    return {
+        /**
+         * @param {*} value
+         * @param {number} [ts] epoch milliseconds
+         */
+        set(value, ts) {
+            current = {value, ts};
+            render();
+            schedule();
+        },
+        clear() {
+            current = null;
+            if (timer) {
+                clearInterval(timer);
+                timer = null;
+            }
+        },
+        stop() {
+            if (timer) {
+                clearInterval(timer);
+                timer = null;
+            }
+        },
+    };
+}
+
+module.exports = {valueStatus, formatValueStatus, relativeTime};

package/nodes/locales/de/ccu-display.html

@@ -4,4 +4,21 @@
     als Nachricht übergeben werden diese
     anstelle der Konfiguration genutzt.</p>
     <p>Mit <code>msg.disbleX</code> kann explizit gesetzt werden, dass keine Daten für die Zeile übertragen werden.</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>channelType</code></li>
+        <li><code>sound</code></li>
+        <li><code>repeat</code></li>
+        <li><code>pause</code></li>
+        <li><code>signal</code></li>
+        <li><code>line1 ... line6</code></li>
+        <li><code>color1 ... color6</code></li>
+        <li><code>icon1 ... icon6</code></li>
+        <li><code>disable1 ... disable6</code></li>
+    </ul>
+    <p><code>msg.line1</code> usw. funktionieren unverändert weiter.</p>
 </script>

package/nodes/locales/de/ccu-rpc-event.json

@@ -4,5 +4,6 @@
     "change": "Nur geänderte Werte ausgeben",
     "cache": "Beim Start letzten bekannten Wert ausgeben",
     "working": "Während WORKING keine Werte ausgeben",
+    "certainOnly": "Unsichere Werte verwerfen"
   }
 }

package/nodes/locales/de/ccu-sysvar.json

@@ -2,6 +2,7 @@
   "ccu-sysvar": {
     "tip": "Wird keine Variable ausgewählt kann der Variablen-Name über msg.topic übergeben werden.",
     "change": "Nur geänderte Werte ausgeben",
-    "cache": "Beim Start aktuellen Wert ausgeben"
+    "cache": "Beim Start aktuellen Wert ausgeben",
+    "property": "Wert aus"
   }
-}
+}

package/nodes/locales/de/ccu-value.json

@@ -8,6 +8,7 @@
     "change": "Nur geänderte Werte ausgeben",
     "cache": "Beim Start letzten bekannten Wert ausgeben",
     "working": "Während WORKING keine Werte ausgeben",
-    "queue": "Queue"
+    "queue": "Queue",
+    "certainOnly": "Unsichere Werte verwerfen"
   }
 }

package/nodes/locales/en-US/ccu-display.html

@@ -3,4 +3,21 @@
     <p>If <code>msg.lineX</code>, <code>msg.iconX</code> or <code>msg.colorX</code>
     are set in the message these are used instead of the configuration.</p>
     <p> With <code>msg.disbleX</code> you can explicitly set that no data is transferred for the line.</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>channelType</code></li>
+        <li><code>sound</code></li>
+        <li><code>repeat</code></li>
+        <li><code>pause</code></li>
+        <li><code>signal</code></li>
+        <li><code>line1 ... line6</code></li>
+        <li><code>color1 ... color6</code></li>
+        <li><code>icon1 ... icon6</code></li>
+        <li><code>disable1 ... disable6</code></li>
+    </ul>
+    <p><code>msg.line1</code> and friends keep working unchanged.</p>
 </script>

package/nodes/locales/en-US/ccu-rpc-event.json

@@ -3,6 +3,7 @@
     "tip": "Tip: ",
     "change": "Emit only changed values",
     "cache": "Emit cached value on start",
-    "working": "Don't emit values while actuator is in WORKING state"
+    "working": "Don't emit values while actuator is in WORKING state",
+    "certainOnly": "Discard uncertain values"
   }
-}
+}

package/nodes/locales/en-US/ccu-switch.html

@@ -0,0 +1,12 @@
+<script type="text/html" data-help-name="ccu-switch">
+    <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>
+        <li><code>datapointProperty</code></li>
+        <li><code>sysvar</code></li>
+        <li><code>sysvarProperty</code></li>
+    </ul>
+</script>

package/nodes/locales/en-US/ccu-sysvar.json

@@ -2,6 +2,7 @@
   "ccu-sysvar": {
     "tip": "Omit the variable name to supply it via msg.payload",
     "change": "Emit changed values only",
-    "cache": "Emit value on start"
+    "cache": "Emit value on start",
+    "property": "Value from"
   }
-}
+}

package/nodes/locales/en-US/ccu-value.json

@@ -8,6 +8,7 @@
     "change": "Emit changed values only",
     "cache": "Emit cached value on start",
     "working": "Don't emit values while actuator is in WORKING state",
-    "queue": "Queue Commands"
+    "queue": "Queue Commands",
+    "certainOnly": "Discard uncertain values"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-red-contrib-ccu",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "license": "MIT",
   "main": "none",
   "keywords": [

package/patch-certainonly.py

@@ -0,0 +1,51 @@
+import io
+import json
+
+# --- editors: certainOnly checkbox (#96) -----------------------------------
+for name, default_anchor in (
+    ("ccu-value", "            cache: {value: false},\n"),
+    ("ccu-rpc-event", "            cache: {value: false},\n"),
+):
+    p = "nodes/%s.html" % name
+    s = io.open(p, encoding="utf-8").read()
+
+    assert default_anchor in s, "defaults anchor in " + p
+    s = s.replace(default_anchor, default_anchor + "            certainOnly: {value: false},\n", 1)
+
+    old = """            <label class="ccu-checkbox">
+                <input type="checkbox" id="node-input-cache">
+                <span data-i18n="%s.cache"></span>
+            </label>
+        </div>
+    </div>""" % name
+    new = """            <label class="ccu-checkbox">
+                <input type="checkbox" id="node-input-cache">
+                <span data-i18n="%s.cache"></span>
+            </label>
+
+            <label class="ccu-checkbox">
+                <input type="checkbox" id="node-input-certainOnly">
+                <span data-i18n="%s.certainOnly"></span>
+            </label>
+        </div>
+    </div>""" % (name, name)
+    assert old in s, "checkbox block in " + p
+    s = s.replace(old, new, 1)
+
+    io.open(p, "w", encoding="utf-8", newline="\n").write(s)
+    print("patched", p)
+
+# --- locales ---------------------------------------------------------------
+LABELS = {
+    "de": "Unsichere Werte verwerfen",
+    "en-US": "Discard uncertain values",
+}
+for loc, label in LABELS.items():
+    for name in ("ccu-value", "ccu-rpc-event"):
+        p = "nodes/locales/%s/%s.json" % (loc, name)
+        d = json.load(io.open(p, encoding="utf-8"))
+        d[name]["certainOnly"] = label
+        io.open(p, "w", encoding="utf-8", newline="\n").write(
+            json.dumps(d, indent=2, ensure_ascii=False) + "\n"
+        )
+        print("locale", p)