node-red-contrib-ccu 4.7.0 → 4.7.2

package/.mocharc.json

@@ -0,0 +1,4 @@
+{
+  "require": "test/hooks.js",
+  "exit": true
+}

package/CHANGELOG.md

@@ -5,6 +5,57 @@ Notable changes to node-red-contrib-ccu. Format follows
 user-visible symptom and the cause, not the commit list (the release notes
 append commits automatically).
 
+## 4.7.2 (2026-10-29)
+
+### Fixed
+
+- **On openccu-lite the metadata file was written once per interface at every
+  start** (`metadata saved to …/ccu_<host>.json`, four lines within a second
+  on a system with four interfaces), although nothing had changed. The
+  system's stream hands the connection every interface's whole device list
+  when it connects, in the shape of a `newDevices` call, and the connection
+  saved whenever that list was not empty - on a CCU `newDevices` only ever
+  names devices the connection did not know. The file is now written only
+  when a device is new or its data changed, a burst of changes is one write
+  (and one log line), and the cache files (metadata, names, values) are
+  written atomically - a temporary file and a rename - so a power cut while
+  writing leaves the old file, not a truncated one.
+- **On openccu-lite the start log's `Interfaces:` line listed ReGaHSS**, right
+  after the line saying the system has no ReGaHSS; it leaves it out now (the
+  mqtt node's per-interface counters as well). Log and dialog texts say "the
+  system" where they said "the box".
+
+### Changed
+
+- The README names RedMatic 9.15.1 as the version whose token makes lite-rpc
+  the default on the system (not 9.13).
+- The release workflow's flow-library step no longer trusts the library's
+  "already at latest version" while its page still shows the previous
+  release; it asks again after 2, 5, 10 and 20 minutes and warns only after
+  that.
+
+## 4.7.1 (2026-10-28)
+
+### Fixed
+
+- **On openccu-lite every write of a decimal value failed** - a dimmer's or a
+  blind's `LEVEL`, a thermostat's set point, an `ON_TIME`, through _value_,
+  _set value_, _rpc_ and the other nodes alike. A `FLOAT` datapoint is sent as
+  a typed double, which over XML-RPC is homematic-xmlrpc's
+  `{explicitDouble: n}`; the lite-rpc connection of 4.7.0 passed that object
+  on as it was, so the interface process got a struct where a number belongs
+  and refused it (`Failure` from rfd and hs485d,
+  `-5 Invalid parameter or value` from hmipserver). The lite-rpc connection
+  now sends lite-rpc's own typed double, `{double: n}` (or the plain number
+  on a system that does not announce it) - in `setValue`, in a paramset of
+  `putParamset` and in a multicall. The direct connection to a CCU is unchanged. Until this version
+  the workaround was _CCU_ in the connection node's _openccu-lite interfaces_.
+- **Errors of the lite-rpc connection said less than they should:** a fault
+  of the interface process was logged as `fault -1 undefined` and reached the
+  flow as `OccuLiteError: Failure`, and a token without the needed rights did
+  not say which right it lacks. The fault now carries its code and text, and a
+  refused call names the missing scope.
+
 ## 4.7.0 (2026-10-27)
 
 ### Added

package/README.md

@@ -47,7 +47,7 @@ start on openccu-lite, the log says so, and a choice made in the node is never c
 CCU-Jack keep their own connections.
 
 - Node-RED **on the system** (RedMatic from its addon catalogue): lite-rpc with RedMatic's own token, which the system
-  mints for it from RedMatic's manifest (RedMatic 9.13 or later); the names come with the system's read-only token.
+  mints for it from RedMatic's manifest (RedMatic 9.15.1 or later); the names come with the system's read-only token.
   Nothing to configure. An older RedMatic has no such token and connects the CCU way, the log says so.
 - Node-RED **elsewhere**: an API token of the system goes into the connection node's **openccu-lite token** field -
   for lite-rpc it needs the `rpc:*` scope of what the flow does (`rpc:read` for events and reads, `rpc:operate` for

package/nodes/ccu-connection.html

@@ -329,6 +329,6 @@
     <div class="form-row">
         <label for="node-config-input-metaPort"><i class="icon-tag"></i> openccu-lite port</label>
         <input type="text" id="node-config-input-metaPort" placeholder="80 / 443">
-        <small>Only needed when the box's web server is not on the default port.</small>
+        <small>Only needed when the system's web server is not on the default port.</small>
     </div>
 </script>

package/nodes/ccu-connection.js

@@ -19,6 +19,7 @@ const {Rega} = require('homematic-rega'); // ES module - require(esm) needs Node
 const metaProvider = require('./lib/metaprovider.js');
 const {InitRetry, retryDelay, RETRY_INTERVAL} = require('./lib/initretry.js');
 const lite = require('./lib/lite.js');
+const {writeJsonAtomic, DebouncedSave} = require('./lib/cachefile.js');
 const xmlrpc = require('homematic-xmlrpc');
 const binrpc = require('binrpc');
 
@@ -781,6 +782,9 @@ module.exports = function (RED) {
                 RED.settings.userDir || path.join(__dirname, '..'),
                 'ccu_lite_' + this.host + '.json',
             );
+            // task 24: the device lists of all interfaces arrive within a second at start -
+            // one write of the metadata file for the burst, flushed at close
+            this.metadataSave = new DebouncedSave(() => this.writeMetadata(), 1000);
 
             this.loadMetadata();
             this.loadRegadata();
@@ -1130,11 +1134,30 @@ module.exports = function (RED) {
          * @returns {Promise<any>}
          */
         saveMetadata() {
-            return new Promise((resolve) => {
-                fs.writeFileSync(this.metadataFile, JSON.stringify(this.metadata));
-                this.logger.info('metadata saved to', this.metadataFile);
-                resolve();
-            });
+            // task 24: a burst (every interface's device list at start) is one write and one line
+            this.metadataSave.request();
+            return Promise.resolve();
+        }
+
+        /** writes the metadata file now (the debounce's write, and the flush at close) */
+        writeMetadata() {
+            this.writeCache(this.metadataFile, 'metadata', this.metadata);
+        }
+
+        /**
+         * task 24: one of the cache files, written atomically; a failure is logged, never thrown
+         * (the caches are a convenience, the connection works without them)
+         * @param {string} file
+         * @param {string} what for the log line
+         * @param {*} data
+         */
+        writeCache(file, what, data) {
+            try {
+                writeJsonAtomic(file, data);
+                this.logger.info(what + ' saved to', file);
+            } catch (error) {
+                this.logger.error(what + ' not saved to ' + file + ': ' + error.message);
+            }
         }
 
         /**
@@ -1142,25 +1165,19 @@ module.exports = function (RED) {
          * @returns {Promise<any>}
          */
         saveRegadata() {
-            return new Promise((resolve) => {
-                fs.writeFileSync(
-                    this.regadataFile,
-                    JSON.stringify({
-                        channelNames: this.channelNames,
-                        regaIdChannel: this.regaIdChannel,
-                        regaChannels: this.regaChannels,
-                        channelRooms: this.channelRooms,
-                        channelFunctions: this.channelFunctions,
-                        rooms: this.rooms,
-                        functions: this.functions,
-                        groups: this.groups,
-                        sysvar: this.sysvar,
-                        program: this.program,
-                    }),
-                );
-                this.logger.info('regadata saved to', this.regadataFile);
-                resolve();
+            this.writeCache(this.regadataFile, 'regadata', {
+                channelNames: this.channelNames,
+                regaIdChannel: this.regaIdChannel,
+                regaChannels: this.regaChannels,
+                channelRooms: this.channelRooms,
+                channelFunctions: this.channelFunctions,
+                rooms: this.rooms,
+                functions: this.functions,
+                groups: this.groups,
+                sysvar: this.sysvar,
+                program: this.program,
             });
+            return Promise.resolve();
         }
 
         /**
@@ -1168,16 +1185,8 @@ module.exports = function (RED) {
          * @returns {Promise<any>}
          */
         saveValues() {
-            return new Promise((resolve) => {
-                fs.writeFileSync(
-                    this.valuesFile,
-                    JSON.stringify({
-                        values: this.values,
-                    }),
-                );
-                this.logger.info('values saved to', this.valuesFile);
-                resolve();
-            });
+            this.writeCache(this.valuesFile, 'values', {values: this.values});
+            return Promise.resolve();
         }
 
         /**
@@ -1353,6 +1362,7 @@ module.exports = function (RED) {
             Object.keys(this.liveness).forEach((iface) => this.stopLiveness(iface));
             clearTimeout(this.valuesPruneTimer);
 
+            this.metadataSave.flush();
             this.saveRegadata();
             this.saveValues();
 
@@ -1491,7 +1501,7 @@ module.exports = function (RED) {
             const line =
                 'meta api detection inconclusive (' +
                 outcome.reason +
-                ') - names come from the ReGaHSS until the box answers, detecting again in ' +
+                ') - names come from the ReGaHSS until the system answers, detecting again in ' +
                 delay / 1000 +
                 ' s';
             if (this.metaRedetectAttempt === 1) {
@@ -1568,6 +1578,8 @@ module.exports = function (RED) {
             delete this.ifaceStatus.ReGaHSS;
             delete this.ifaceWaiting.ReGaHSS;
             this.ifaceStatus[META_IFACE] = null;
+            // task 25: the system has no ReGaHSS - the "Interfaces:" line and the counters leave it out
+            this.enabledIfaces = this.enabledIfaces.filter((iface) => iface !== 'ReGaHSS');
 
             this.logger.info(
                 'openccu-lite detected (' +
@@ -1577,12 +1589,12 @@ module.exports = function (RED) {
                     ') - names, rooms and functions come from its metadata api',
             );
             this.logger.info(
-                'this box has no ReGaHSS: system variables, programs and HM-Script are not available (sysvar, program, poll and script nodes stay idle)',
+                'this system has no ReGaHSS: system variables, programs and HM-Script are not available (sysvar, program, poll and script nodes stay idle)',
             );
 
             if (info.version > 1) {
                 this.logger.warn(
-                    'the box speaks metadata api version ' +
+                    'the system speaks metadata api version ' +
                         info.version +
                         ', this version of node-red-contrib-ccu implements version 1',
                 );
@@ -1590,7 +1602,7 @@ module.exports = function (RED) {
 
             if (!this.metaToken) {
                 this.logger.warn(
-                    'no metadata api token: create one on the box (Users page) and enter it in the connection node, or run on the box where ' +
+                    'no metadata api token: create one on the system (Users page) and enter it in the connection node, or run on the system where ' +
                         metaProvider.LOCAL_TOKEN_FILE +
                         ' is readable. Without it the nodes work with addresses only.',
                 );
@@ -1631,10 +1643,13 @@ module.exports = function (RED) {
                         delete this.ifaceStatus[META_IFACE];
                         if (this.ifaceTypes.ReGaHSS.enabled) {
                             this.ifaceStatus.ReGaHSS = null;
+                            if (!this.enabledIfaces.includes('ReGaHSS')) {
+                                this.enabledIfaces.unshift('ReGaHSS');
+                            }
                         }
 
                         this.pushStatus();
-                        this.logger.warn('this box no longer answers as openccu-lite - detecting again');
+                        this.logger.warn('this system no longer answers as openccu-lite - detecting again');
                         this.detectMetaOutcome().then((outcome) => {
                             if (outcome.info) {
                                 return this.startMeta(outcome.info);
@@ -1717,7 +1732,7 @@ module.exports = function (RED) {
          * @returns {Error}
          */
         regaMissingError(feature) {
-            return new Error(feature + ' are not available on this box (openccu-lite has no ReGaHSS)');
+            return new Error(feature + ' are not available on this system (openccu-lite has no ReGaHSS)');
         }
 
         /**
@@ -3456,9 +3471,12 @@ module.exports = function (RED) {
         }
 
         /**
-         *
+         * Takes a device description into the device table.
          * @param iface
          * @param device
+         * @returns {boolean} whether the table changed: the device is new, or its data changed
+         *   (a description equal to the cached one, as the lite-rpc stream's snapshot sends at
+         *   every connect, changes nothing - task 24)
          */
         newDevice(iface, device) {
             if (!this.metadata.devices[iface]) {
@@ -3497,7 +3515,8 @@ module.exports = function (RED) {
                 this.logger.debug('newDevice', iface, device.ADDRESS);
             }
 
-            if (!known || deviceChanged(known, device)) {
+            const changed = !known || deviceChanged(known, device);
+            if (changed) {
                 // B-36: a device added anew (re-paired, or its data changed) is asked again
                 this.forgetParamsetFailures(iface, device.ADDRESS);
             }
@@ -3522,6 +3541,7 @@ module.exports = function (RED) {
             }
 
             this.paramsetQueuePush(iface, device);
+            return changed;
         }
 
         /**
@@ -3860,8 +3880,9 @@ module.exports = function (RED) {
                     if (iface && Array.isArray(devices)) {
                         devices.forEach((device) => {
                             if (device && typeof device.ADDRESS === 'string' && device.TYPE) {
-                                this.newDevice(iface, device);
-                                changed = true;
+                                if (this.newDevice(iface, device)) {
+                                    changed = true;
+                                }
                             } else {
                                 this.logger.warn(
                                     'newDevices',

package/nodes/lib/cachefile.js

@@ -0,0 +1,105 @@
+/*
+ * The connection's cache files (metadata, regadata, values) on disk.
+ *
+ * Written atomically: the JSON goes to a temporary file beside the target and is renamed over it,
+ * so a crash or a power cut while writing leaves the old file, never a truncated one (the files
+ * are read with JSON.parse at the next start, and a half-written one would throw the cache away).
+ *
+ * A burst of changes is written once: `DebouncedSave` collects the requests of a short window into
+ * one write - at start every interface reports its device list within the same second, and before
+ * there was one full rewrite and one log line per interface.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Writes `data` as JSON to `file` by way of a temporary file and a rename; an existing file's mode
+ * is kept.
+ * @param {string} file
+ * @param {*} data
+ * @param {string|number} [indent] JSON.stringify's third argument
+ */
+function writeJsonAtomic(file, data, indent) {
+    const temporary = path.join(
+        path.dirname(file),
+        '.' + path.basename(file) + '.' + process.pid + '.' + Date.now().toString(36) + '.tmp',
+    );
+    try {
+        fs.writeFileSync(temporary, JSON.stringify(data, null, indent));
+        // the rename replaces the inode: an existing file's mode is kept (0600 on a system that
+        // made it so), a new one gets the umask's
+        let mode;
+        try {
+            mode = fs.statSync(file).mode & 0o777;
+        } catch {}
+
+        if (mode !== undefined) {
+            fs.chmodSync(temporary, mode);
+        }
+
+        fs.renameSync(temporary, file);
+    } catch (error) {
+        try {
+            fs.unlinkSync(temporary);
+        } catch {}
+
+        throw error;
+    }
+}
+
+class DebouncedSave {
+    /**
+     * @param {Function} write does the write; called once per burst
+     * @param {number} [delay] the window, ms (default 1000)
+     */
+    constructor(write, delay = 1000) {
+        this.write = write;
+        this.delay = delay;
+        this.timer = null;
+        this.pending = false;
+    }
+
+    /** asks for a write; one write happens `delay` ms after the first request of a burst */
+    request() {
+        this.pending = true;
+        if (this.timer) {
+            return;
+        }
+
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            this.flush();
+        }, this.delay);
+        if (typeof this.timer.unref === 'function') {
+            this.timer.unref();
+        }
+    }
+
+    /** writes now when a request is pending (close, redeploy) */
+    flush() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+
+        if (!this.pending) {
+            return;
+        }
+
+        this.pending = false;
+        this.write();
+    }
+
+    /** drops a pending request without writing */
+    cancel() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+
+        this.pending = false;
+    }
+}
+
+module.exports = {writeJsonAtomic, DebouncedSave};

package/nodes/lib/lite.js

@@ -80,7 +80,26 @@ function readAddonToken(file = module.exports.ADDON_TOKEN_FILE) {
  * @returns {boolean}
  */
 function isFault(error) {
-    return Boolean(error) && error.kind === 'rpc-fault' && error.faultCode !== undefined;
+    return kindOf(error) === 'rpc-fault' && error.faultCode !== undefined;
+}
+
+/**
+ * The client's error kind: occulite-client's OccuLiteError carries it as `code` (rpc-fault,
+ * forbidden, timeout ...); `kind` is ours, on an error translated before. A Node system error's
+ * `code` (ECONNREFUSED ...) is not a kind.
+ * @param {*} error
+ * @returns {string|undefined}
+ */
+function kindOf(error) {
+    if (!error) {
+        return undefined;
+    }
+
+    if (error.kind) {
+        return error.kind;
+    }
+
+    return error.name === 'OccuLiteError' && typeof error.code === 'string' ? error.code : undefined;
 }
 
 /**
@@ -97,7 +116,8 @@ function translateError(error) {
         return fault;
     }
 
-    if (error && error.kind === 'forbidden') {
+    const kind = kindOf(error);
+    if (kind === 'forbidden') {
         const refused = new Error(
             'the openccu-lite token may not call this method' + (error.scope ? ' (needs ' + error.scope + ')' : ''),
         );
@@ -106,15 +126,47 @@ function translateError(error) {
         return refused;
     }
 
-    if (error && error.kind) {
-        const translated = new Error(error.message || error.kind);
-        translated.kind = error.kind;
+    if (kind) {
+        const translated = new Error(error.message || kind);
+        translated.kind = kind;
         return translated;
     }
 
     return error instanceof Error ? error : new Error(String(error));
 }
 
+/**
+ * B-41: cast.js marks a FLOAT as homematic-xmlrpc's `{explicitDouble: n}` (the XML-RPC client's
+ * `<double>`). lite-rpc's JSON path does not know that marker and would hand the process a struct
+ * where a double belongs - hs485d and hmipserver refuse it. Its own marker is `{double: n}`
+ * (capability `json_double`); a system without it gets the plain number. Walks the whole
+ * parameter list: the top level, structs and paramsets, a multicall's calls.
+ * @param {*} value
+ * @param {boolean} jsonDouble whether the system announces `json_double`
+ * @returns {*} the value for lite-rpc
+ */
+function liteValue(value, jsonDouble) {
+    if (Array.isArray(value)) {
+        return value.map((item) => liteValue(item, jsonDouble));
+    }
+
+    if (value && typeof value === 'object' && Object.getPrototypeOf(value) === Object.prototype) {
+        const keys = Object.keys(value);
+        if (keys.length === 1 && keys[0] === 'explicitDouble') {
+            const number = Number(value.explicitDouble);
+            return jsonDouble ? {double: number} : number;
+        }
+
+        const out = {};
+        keys.forEach((key) => {
+            out[key] = liteValue(value[key], jsonDouble);
+        });
+        return out;
+    }
+
+    return value;
+}
+
 const RPC_TIERS = ['rpc:operate', 'rpc:configure', 'rpc:admin'];
 
 /**
@@ -263,7 +315,8 @@ class LiteConnection {
             return Promise.reject(new Error('lite-rpc client not started'));
         }
 
-        return this.box.call(iface, method, parameters || []).then(
+        const jsonDouble = Boolean(this.box.capabilities && this.box.capabilities.json_double);
+        return this.box.call(iface, method, liteValue(parameters || [], jsonDouble)).then(
             (result) => (result === null || result === undefined ? '' : result),
             (error) => {
                 throw translateError(error);
@@ -302,6 +355,7 @@ module.exports = {
     ADDON_TOKEN_FILE,
     CALLBACK_METHODS,
     readAddonToken,
+    liteValue,
     tierAwareTransport,
     translateError,
     isFault,

package/package.json

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