node-red-contrib-ccu 4.4.4 → 4.5.0

package/nodes/ccu-sysvar.html

@@ -137,67 +137,3 @@
     </div>
     <div class="form-tips" data-i18n="ccu-sysvar.tip"></div>
 </script>
-
-<script type="text/x-red" data-help-name="ccu-sysvar" lang="de-DE">
-    <p>Setzen und lesen von ReGaHSS Systemvariablen.</p>
-    <h3>Inputs</h3>
-    <dl class="message-properties">
-        <dt>payload
-            <span class="property-type">*</span>
-        </dt>
-        <dd>
-            Der Wert der der Systemvariablen zugewiesen werden soll.
-        </dd>
-    </dl>
-    <h3>Outputs</h3>
-     <ol class="node-ports">
-         <li>Output
-
-               <code>msg</code> Beispiel:<br>
-               <pre><code>
-{
-	"ccu": "localhost",
-	"iface": "ReGaHSS",
-	"type": "SYSVAR",
-	"name": "Anwesenheit",
-	"payload": false,
-	"value": false,
-	"valueType": "boolean",
-	"valueEnum": "nicht anwesend",
-	"ts": 1525197999611,
-	"lc": 1525197999611,
-	"enum": ["nicht anwesend", "anwesend"],
-	"id": 950,
-	"topic": "ReGaHSS/Anwesenheit"
-}
-               </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">
-    <p>Set and read ReGaHSS system variables.</p>
-        <h3>Inputs</h3>
-    <dl class="message-properties">
-        <dt>payload
-            <span class="property-type">*</span>
-        </dt>
-        <dd>
-            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-value.html

@@ -17,6 +17,7 @@
             cache: {value: false},
             certainOnly: {value: false},
             queue: {value: false},
+            force: {value: false},
             on: {value: ''},
             onType: {value: 'undefined'},
             ramp: {value: ''},
@@ -57,6 +58,7 @@
             let ifacesLoaded = false;
             let ifacesPending = false;
             let ifaceLoadRetries = 5;
+            let channelLoadRetries = 30;
 
             function loadIfaces(iface, cb) {
                 if (ifacesPending) {
@@ -100,7 +102,16 @@
 
                 const nodeId = $nodeInputCcuConfig.val();
                 const url = 'ccu?config=' + nodeId + '&type=channels&iface=' + $nodeInputIface.val();
-                $.getJSON(url, d => {
+                $.getJSON(url, (d, _status, xhr) => {
+                    // task 9: an empty list while the connection is still initialising is "not yet",
+                    // not "nothing" - keep what is configured, say so, and ask again
+                    if (Object.keys(d).length === 0 && xhr.getResponseHeader('X-CCU-Loading') && channelLoadRetries-- > 0) {
+                        $nodeInputChannel.attr('placeholder', 'loading device data ...');
+                        setTimeout(loadConfig, 2000);
+                        return;
+                    }
+
+                    $nodeInputChannel.removeAttr('placeholder');
                     data = d;
                     autocompleteChannel();
                     autocompleteDatapoint();
@@ -179,7 +190,7 @@
 
                 // ${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]]) {
+                if (Object.keys(data).length > 0 && !/^\$\{[^}]+\}$/.test($nodeInputChannel.val()) && !data[$nodeInputChannel.val().split(' ')[0]]) {
                     $nodeInputChannel.val('');
                     $nodeInputDatapoint.val('');
                 }
@@ -466,6 +477,16 @@
         </div>
     </div>
 
+    <div class="form-row">
+        <label for="node-input-force"><i class="icon-bookmark"></i> </label>
+        <div style="width: 70%; display: inline-block; vertical-align: text-top;">
+            <label class="ccu-checkbox" for="node-input-force">
+                <input type="checkbox" id="node-input-force">
+                <span data-i18n="ccu-value.force"></span>
+            </label>
+        </div>
+    </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;">
@@ -518,96 +539,3 @@
         <div id="config-lookup-tree"></div>
     </div>
 </script>
-
-
-
-<script type="text/x-red" data-help-name="ccu-value" lang="de-DE">
-    <p>Geräte steuern und/oder Events von einem Gerät empfangen.</p>
-    <h3>Konfiguration</h3>
-    <ul>
-        <li><b>CCU:</b> Die zu verwendende CCU-Konfiguration.</li>
-        <li><b>Topic:</b> <code>msg.topic</code></li>
-        <li><b>Interface</b>: Hier wird das Interface gewählt, über welches das gewüschnte Geräte angebunden ist.</li>
-        <li><b>Channel</b>: Der Kanal dessen Datenpunkte verwendet werden sollen. Er besteht aus der Serien- sowie der Kanalnummer. Eine Autovervollständigung hilft bei der Auswahl anhand der Klarnamen.</li>
-        <li><b>Datapoint</b>: Der Datenpunkt des Kanals, auch hier wird über eine Autovervollständigung die Auswahl vereinfacht.</li>
-        <li><b>ON_TIME</b>:
-            Zeit in Sekunden nach der ein Schaltaktor/Dimmer nach dem anschalten wieder ausgeschaltet werden soll.<br>
-            Dabei ist:
-            <ul>
-                <li><code>undefined</code> Keine automatische Ausschaltung</li>
-                <li><code>number</code> Eine feste Verzögerung in Sekunden</li>
-                <li><code>global</code>, <code>flow</code> Die Verzögerung in Sekunden wird aus einer Context-Variablen übernommen</li>
-                <li><code>msg</code> Die Verzögerung in Sekunden wird kann über eine msg property übergeben werden</li>
-            </ul>
-
-        </li>
-        <li><b>set Mode</b>:
-            Eine Erweiterung für Geräte, die sowohl den rx_mode BURST als auch WAKEUP unterstützen wie z.B.:
-            Batterie-Schaltaktoren oder Rauchmelder mit Sirenenfunktion. Mit dem Parameter kann in diesem Fall angegeben
-            werden, ob der übergebene Wert über BURST oder WAKEUP übertragen werden soll.
-            <ul>
-                <li><b>WAKEUP</b> - Überträgt den Wert sobald sich der entsprechende Empfänger bei der Zentrale meldet.</li>
-                <li><b>BURST</b> - Versucht alle BURST-Empfänger für die Übertragung aufzuwecken was sich negativ auf den DutyCycle und die Batterielaufzeit aller Burst-Empfänger auswirkt.</li>
-            </ul>
-        </li>
-        <li><b>Flags</b>:
-            <ul>
-                <li><b>Nur geänderte Werte ausgeben</b> - Ein Event wird nur dann erzeugt, wenn sich der Wert seit dem letztn Event verändert hat.</li>
-                <li><b>Während WORKING keine Werte ausgeben</b> - Es gibt Aktoren, z.B. Dimmer oder Rolladen, die während einer Rampe (Öffnen/Schließen eines Rollladen, Dimmen einer Lampe) fortwährend den aktuellen Zustand ausgeben. Um nur den End-Status auszugeben kann diese Option benutzt werden. Gebräuchlich auch bei Verwendung mit Dashboard-Nodes um "springende" Slider zu verhindern.</li>
-                <li><b>Beim Start letzten bekannten Wert ausgeben</b> - Wenn Node-RED gestartet wird, dann wird der letzte Wert (sofern in der ReGaHSS bekannt) ausgegeben. Z.B. um beim Start einen korrekten Wert an das Dashboard zu übergeben. <b>Achtung:</b> </li>
-            </ul>
-
-        </li>
-    </ul>
-
-    <h3>Input</h3>
-    <p>
-        Für den Input des Value Node wird <code>msg.payload</code> als der Wert verwendet der in den Datenpunkt geschrieben wird.
-
-        Die Bestimmung des Datenpunkts sowie des Kanals und der Schnittstellen können hier dynamisch sein. Dazu werden die Eingabefelder leer gelassen und über die eingehende <code>msg</code> gesetzt.
-    </p>
-    <b>Option 1</b>: Interface, Channel und Datapoint können in der msg als Properties angegeben werden:
-    <code>
-<pre>{
-  "interface": "BidCos-RF",
-  "channel": "OEQ1868878:1",
-  "datapoint": "STATE",
-  "payload": true
-}</pre>
-    </code>
-
-    <b>Option 2</b>: Der Datenpunkt kann über <code>msg.topic</code> angegeben werden wobei Interface, Channel und Datapoint mit Punkt getrennt werden:
-    <code>
-<pre>{
-  "topic": "BidCos-RF.OEQ1868878:1.STATE",
-  "payload": true
-}</pre>
-    </code>
-
-
-    <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,10 +1,11 @@
+const {parseTopicAddress} = require('./lib/topic.js');
 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'];
+const DYNAMIC_KEYS = ['iface', 'channel', 'datapoint', 'force'];
 
 module.exports = function (RED) {
     class CcuValue {
@@ -31,7 +32,9 @@ module.exports = function (RED) {
             });
 
             this.on('input', (message, send, done) => {
-                const [tIface, tChannel, tDatapoint] = (message.topic || '').split('.');
+                // task 6 (#39): the address may come as `iface.channel.datapoint` or in the
+                // shape the nodes emit, `${CCU}/${Interface}/${channel}/${datapoint}`
+                const {iface: tIface, channel: tChannel, datapoint: tDatapoint} = parseTopicAddress(message.topic);
                 // 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);
@@ -46,6 +49,8 @@ module.exports = function (RED) {
                     ''
                 ).split(' ')[0];
                 const datapoint = over.datapoint || config.datapoint || message.datapoint || tDatapoint;
+                // B-19: force writes through the queue's dedupe (as set-value has it)
+                const force = typeof over.force === 'undefined' ? Boolean(config.force) : Boolean(over.force);
 
                 if (!iface) {
                     this.error('interface undefined');
@@ -119,6 +124,7 @@ module.exports = function (RED) {
                         datapoint,
                         message.payload,
                         config.burst,
+                        force,
                     )
                         .then(() => {
                             done();

package/nodes/lib/initretry.js

@@ -5,16 +5,20 @@
  * addon started before the interfaces, a daemon restart) used to leave the
  * interface without events: rpcCheckInit only runs with cached devices and
  * then waits pingTimeout (600 s for HmIP-RF). Now a failed init schedules its
- * own retry, 2 s, 4 s, 8 s, 16 s and then every 30 s, until it succeeds or the
- * node is closed.
+ * own retry, 1 s, 2 s, 4 s, 8 s and then every 15 s (task 12), until it
+ * succeeds or the node is closed.
  *
- * While the process is unreachable the interface is "waiting": one warn line,
- * then debug. A fault answer (the process is up and refuses the init) stays an
- * error, logged once per distinct fault.
+ * While the process is unreachable the interface is "waiting": one line, then
+ * debug. Before the interface was ever connected, a refused connection is
+ * info - the process is still starting (openccu-lite's early start starts
+ * Node-RED before rfd and hmipserver) - and every other transport error, or a
+ * refusal after it had been connected, is a warning. A fault answer (the
+ * process is up and refuses the init) stays an error, logged once per
+ * distinct fault.
  */
 
-const RETRY_DELAYS = [2000, 4000, 8000, 16000];
-const RETRY_MAX_DELAY = 30000;
+const RETRY_DELAYS = [1000, 2000, 4000, 8000];
+const RETRY_MAX_DELAY = 15000;
 
 /**
  * The delay before the next attempt.
@@ -39,6 +43,15 @@ function isFault(error) {
     return Boolean(error) && typeof error === 'object' && error.faultCode !== undefined;
 }
 
+/**
+ * Whether nothing listens on the port (yet): the process is not started.
+ * @param {*} error
+ * @returns {boolean}
+ */
+function isRefused(error) {
+    return Boolean(error) && (error.code === 'ECONNREFUSED' || /ECONNREFUSED/.test(String(error.message || '')));
+}
+
 /**
  * A short reason for the log line, e.g. "connect ECONNREFUSED".
  * @param {*} error
@@ -57,6 +70,17 @@ function describeError(error) {
         return (error.syscall ? error.syscall + ' ' : 'connect ') + error.code;
     }
 
+    // task 5 (#27): the CCU's web server answers a 401 (authentication on, the
+    // credentials missing or wrong) with an HTML page, and the XML-RPC client
+    // reports only the parser's complaint about it - say what that means
+    if (/^Unknown XML-RPC tag '(HTML|HEAD|META|BODY|TITLE|!DOCTYPE)/i.test(String(error.message || ''))) {
+        return (
+            'the CCU answered a web page instead of XML-RPC (' +
+            error.message +
+            ') - authentication is on and the credentials are missing or wrong, or this is not an RPC port'
+        );
+    }
+
     return error.message || String(error);
 }
 
@@ -77,6 +101,7 @@ class InitRetry {
         this.timers = timers || {setTimeout, clearTimeout};
         this.timer = null;
         this.stopped = false;
+        this.everConnected = false;
         this.reset();
     }
 
@@ -122,7 +147,18 @@ class InitRetry {
                 );
             } else {
                 this.warned = true;
-                this.logger.warn(this.iface + ' not reachable yet (' + reason + '), retrying');
+                if (!this.everConnected && isRefused(error)) {
+                    this.logger.info(
+                        this.iface +
+                            ' not listening yet (' +
+                            reason +
+                            '), waiting for it - retrying in ' +
+                            seconds +
+                            ' s',
+                    );
+                } else {
+                    this.logger.warn(this.iface + ' not reachable yet (' + reason + '), retrying');
+                }
             }
 
             this.onState('waiting');
@@ -160,6 +196,7 @@ class InitRetry {
             this.logger.info(this.iface + ' connected after ' + (this.failures + 1) + ' attempts');
         }
 
+        this.everConnected = true;
         this.reset();
         this.onState('connected');
     }
@@ -178,4 +215,4 @@ class InitRetry {
     }
 }
 
-module.exports = {InitRetry, retryDelay, isFault, describeError, RETRY_DELAYS, RETRY_MAX_DELAY};
+module.exports = {InitRetry, retryDelay, isFault, isRefused, describeError, RETRY_DELAYS, RETRY_MAX_DELAY};

package/nodes/lib/localccu.js

@@ -17,7 +17,15 @@
    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. */
+   the interface table is built in the connection node's constructor.
+
+   A listener alone misses a start before rfd: openccu-lite starts an addon
+   that copes with it before the interface processes (its early start), so
+   the ports are not open yet and the connection went through the proxy for
+   good. The CCU's own interface list, /etc/config/InterfacesList.xml, is
+   there from the first second on every CCU firmware (CCU3, OpenCCU,
+   openccu-lite), so a loopback host with that file is the CCU we run on as
+   well. */
 
 const fs = require('fs');
 
@@ -26,6 +34,9 @@ const LOCAL_PROBE_PORTS = [32001, 31999];
 
 const PROC_NET_TCP = ['/proc/net/tcp', '/proc/net/tcp6'];
 
+/** The CCU firmware's list of its interface processes. */
+const INTERFACES_LIST = '/etc/config/InterfacesList.xml';
+
 /** /proc/net/tcp connection state 0A = TCP_LISTEN. */
 const TCP_LISTEN = '0A';
 
@@ -67,6 +78,7 @@ function listeningPorts(files) {
  * @param {string} host the configured CCU host
  * @param {object} [options]
  * @param {string[]} [options.files] /proc files to read, for tests
+ * @param {string} [options.interfacesList] the CCU's interface list, for tests
  * @returns {boolean}
  */
 function isLocalCcu(host, options) {
@@ -75,7 +87,13 @@ function isLocalCcu(host, options) {
     }
 
     const ports = listeningPorts(options && options.files);
-    return LOCAL_PROBE_PORTS.some((port) => ports.has(port));
+    if (LOCAL_PROBE_PORTS.some((port) => ports.has(port))) {
+        return true;
+    }
+
+    // the interface processes are not up yet (a start before them): the
+    // firmware's interface list still says this is the CCU
+    return fs.existsSync((options && options.interfacesList) || INTERFACES_LIST);
 }
 
-module.exports = {isLocalCcu, listeningPorts, LOCAL_PROBE_PORTS};
+module.exports = {isLocalCcu, listeningPorts, LOCAL_PROBE_PORTS, INTERFACES_LIST};

package/nodes/lib/metaprovider.js

@@ -281,38 +281,65 @@ function readBody(res) {
     });
 }
 
+/** lighttpd answers these while the api behind it is not up yet - the box is starting, nothing is decided */
+const INCONCLUSIVE_STATUS = new Set([502, 503, 504]);
+
 /**
- * Feature detection: `GET /api/meta/v1/version` answers on openccu-lite and
- * needs no credential; a CCU / RaspberryMatic / OpenCCU answers 404 or HTML.
- * Never rejects - a box that is simply unreachable is not openccu-lite either.
+ * Feature detection with its outcome: `GET /api/meta/v1/version` answers on
+ * openccu-lite and needs no credential; a CCU / RaspberryMatic / OpenCCU
+ * answers 404 or HTML - that is a conclusive "no". A timeout, a refused
+ * connection or a 502/503/504 decides nothing (B-28: a busy or still starting
+ * box), so the caller can ask again instead of settling for the ReGa.
+ * Never rejects.
  * @param {object} options host, port, tls, insecure, timeout, logger
- * @returns {Promise<object|null>} the version document, or null
+ * @returns {Promise<{info: object|null, inconclusive: boolean, reason?: string}>}
  */
-async function detect(options) {
+async function detectOutcome(options) {
     const {logger = SILENT} = options;
+    let status;
+    let body;
     try {
-        const {status, res} = await request({
+        const answer = await request({
             ...options,
             path: API_PATH + '/version',
             token: undefined,
             timeout: options.timeout || 5000,
         });
-        const body = await readBody(res);
-        if (status !== 200) {
-            logger.debug('meta api detection: status ' + status);
-            return null;
-        }
-
-        const info = JSON.parse(body);
-        if (!info || info.api !== 'meta' || typeof info.version !== 'number') {
-            return null;
-        }
-
-        return info;
+        status = answer.status;
+        body = await readBody(answer.res);
     } catch (error) {
         logger.debug('meta api detection: ' + error.message);
-        return null;
+        return {info: null, inconclusive: true, reason: error.message};
+    }
+
+    if (status !== 200) {
+        logger.debug('meta api detection: status ' + status);
+        return {info: null, inconclusive: INCONCLUSIVE_STATUS.has(status), reason: 'status ' + status};
     }
+
+    let info = null;
+    try {
+        info = JSON.parse(body);
+    } catch {
+        info = null;
+    }
+
+    if (!info || info.api !== 'meta' || typeof info.version !== 'number') {
+        return {info: null, inconclusive: false, reason: 'not the metadata api'};
+    }
+
+    return {info, inconclusive: false};
+}
+
+/**
+ * Feature detection: the version document of an openccu-lite, or null for
+ * anything else (a CCU, an unreachable box). See detectOutcome() for the
+ * difference between "no" and "not now".
+ * @param {object} options host, port, tls, insecure, timeout, logger
+ * @returns {Promise<object|null>} the version document, or null
+ */
+async function detect(options) {
+    return (await detectOutcome(options)).info;
 }
 
 /**
@@ -708,6 +735,7 @@ module.exports = {
     MetaProvider,
     buildNames,
     detect,
+    detectOutcome,
     flattenEnum,
     memberNames,
     readLocalToken,

package/nodes/lib/party.js

@@ -0,0 +1,103 @@
+/* Party mode on HmIP thermostats (task 2, #156, #161).
+
+   An HmIP HEATING_CLIMATECONTROL_TRANSCEIVER channel carries PARTY_TIME_START,
+   PARTY_TIME_END and PARTY_SET_POINT_TEMPERATURE (and the read-only
+   PARTY_MODE). The device takes the three only together: a setValue of one
+   of them resets the other two - PARTY_TIME_START alone puts PARTY_TIME_END
+   back to `1999_11_30 00:00` (#156). The CCU's WebUI writes them as one
+   putParamset on VALUES, and so do we: a write to one of the three is merged
+   with the current values of the other two into one putParamset.
+
+   The times are strings in the device's own format, `YYYY_MM_DD HH:MM` in
+   local time (minutes in steps of five - the device rounds). A Date, an ISO
+   string or epoch milliseconds are formatted for it; a string already in the
+   format passes through.
+
+   The older HM thermostats (PARTY_MODE_SUBMIT, the PARTY_START_ and PARTY_STOP_ fields)
+   are another protocol and not covered here. Pure. */
+
+const PARTY_DATAPOINTS = ['PARTY_TIME_START', 'PARTY_TIME_END', 'PARTY_SET_POINT_TEMPERATURE'];
+const PARTY_TIMES = ['PARTY_TIME_START', 'PARTY_TIME_END'];
+const TIME_FORMAT = /^\d{4}_\d{2}_\d{2} \d{2}:\d{2}$/;
+
+/**
+ * Is this a write the device only takes together with the other two?
+ * @param {string} datapoint
+ * @param {object} [valuesDescription] the channel's VALUES paramset description
+ * @returns {boolean}
+ */
+function isPartyWrite(datapoint, valuesDescription) {
+    return (
+        PARTY_DATAPOINTS.includes(datapoint) &&
+        Boolean(valuesDescription) &&
+        PARTY_DATAPOINTS.every((name) => Boolean(valuesDescription[name]))
+    );
+}
+
+/**
+ * The device's time string for a value: a Date, epoch milliseconds, an ISO
+ * (or Date-parsable) string, or a string already in the format.
+ * @param {*} value
+ * @returns {string} the formatted time, or the value as a string when it cannot be read as a time
+ */
+function formatPartyTime(value) {
+    if (typeof value === 'string' && TIME_FORMAT.test(value)) {
+        return value;
+    }
+
+    let date;
+    if (value instanceof Date) {
+        date = value;
+    } else if (typeof value === 'number') {
+        date = new Date(value);
+    } else if (typeof value === 'string' && value.trim() !== '') {
+        date = new Date(value);
+    }
+
+    if (!date || Number.isNaN(date.getTime())) {
+        return String(value);
+    }
+
+    const pad = (n) => String(n).padStart(2, '0');
+    return (
+        date.getFullYear() +
+        '_' +
+        pad(date.getMonth() + 1) +
+        '_' +
+        pad(date.getDate()) +
+        ' ' +
+        pad(date.getHours()) +
+        ':' +
+        pad(date.getMinutes())
+    );
+}
+
+/**
+ * The complete VALUES paramset for one party write: the written datapoint
+ * plus the current values of the other two.
+ * @param {string} datapoint the one being written
+ * @param {*} value its new value
+ * @param {object} current the other datapoints' current values by name (undefined when unknown)
+ * @returns {{values: object, missing: string[]}} the merged three, and the names no current value was known for
+ */
+function mergePartyValues(datapoint, value, current) {
+    const values = {};
+    const missing = [];
+    for (const name of PARTY_DATAPOINTS) {
+        let v = name === datapoint ? value : current && current[name];
+        if (v === undefined || v === null) {
+            missing.push(name);
+            continue;
+        }
+
+        if (PARTY_TIMES.includes(name)) {
+            v = formatPartyTime(v);
+        }
+
+        values[name] = v;
+    }
+
+    return {values, missing};
+}
+
+module.exports = {PARTY_DATAPOINTS, isPartyWrite, formatPartyTime, mergePartyValues};

package/nodes/lib/topic.js

@@ -35,4 +35,25 @@ function topicReplace(topic, message) {
     return topic;
 }
 
-module.exports = {topicReplace};
+/**
+ * The datapoint address in an incoming msg.topic (task 6, #39). Two shapes:
+ * the value node's old input form `iface.channel.datapoint` (dots), and the
+ * shape the nodes emit by default, `${CCU}/${Interface}/${channel}/${datapoint}`
+ * or without the CCU part - with slashes, the last three segments count, so
+ * an event's topic can be fed straight back into a value node.
+ * @param {string} topic
+ * @returns {{iface: string|undefined, channel: string|undefined, datapoint: string|undefined}}
+ */
+function parseTopicAddress(topic) {
+    const text = typeof topic === 'string' ? topic : '';
+    if (text.includes('/')) {
+        const parts = text.split('/').filter((part) => part !== '');
+        const [iface, channel, datapoint] = parts.slice(-3);
+        return parts.length >= 3 ? {iface, channel, datapoint} : {};
+    }
+
+    const [iface, channel, datapoint] = text.split('.');
+    return {iface, channel, datapoint};
+}
+
+module.exports = {topicReplace, parseTopicAddress};