node-red-contrib-ccu 4.6.2 → 4.7.0

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.0 (2026-10-27)
+
+### Added
+
+- **On openccu-lite the interfaces are reached through the system's lite-rpc**
+  (with [occulite-client](https://www.npmjs.com/package/occulite-client))
+  instead of XML-RPC/BIN-RPC clients and callback servers of this node's own -
+  the requests over the system's web port, the events from a stream the
+  connection opens, replayed after a break and re-read after a restart of the
+  system; one subscriber at the interface processes serves every program on
+  the system, and nothing registers with `init`. The credential is the
+  openccu-lite token of the connection node, or on the system itself
+  RedMatic's own token, which the system mints for it. A new setting
+  _openccu-lite interfaces_ in the connection node chooses: _auto_ (the
+  default; the CCU way on a CCU), _openccu-lite_ (lite-rpc only) or _CCU_ (the
+  direct connection with callbacks, on openccu-lite too). An existing
+  connection is moved to lite-rpc once, at its first start on openccu-lite,
+  and the log says so; a choice made in the node is never changed by a later
+  version. The value cache is filled from the system's state store at deploy,
+  so nodes with _cache_ get a value on openccu-lite as well. CUxD and CCU-Jack
+  keep their own connections. On a CCU, RaspberryMatic and OpenCCU nothing
+  changes.
+
+### Changed
+
+- **An interface process that is not up yet is tried every 3 s for the first
+  90 s, then every 15 s.** The 1, 2, 4, 8 s steps and the 15 s after them
+  missed hmipserver's ready moment on a booting system by up to 15 s (measured
+  on an openccu-lite Pi 4: hmipserver answers 50-55 s after the boot, the next
+  attempt came at 61 s). The same holds after a process went away. When one
+  interface appears, the others still waiting are tried at once, and the log
+  line that reports the connection says how long after the start (or after the
+  outage) it came. The metadata API's re-detection on openccu-lite follows the
+  same schedule.
+- **The port of each interface can be set in the connection node**, beside its
+  checkbox: blank is the CCU's port for the transport as before (2001/42001 and
+  so on, the 3xxxx ports on the CCU itself), a number replaces it - for a CCU
+  behind port forwarding, or a simulator on another port.
+- The test suite runs hm-simulator 1.4 on free ports, so it runs beside a CCU
+  or another suite, and drives the simulator's scenario API: devices paired
+  and removed while Node-RED runs, a ramp-time write, a service message, an
+  interface process that restarts and forgets its clients, TLS with basic
+  auth.
+- **On openccu-lite the metadata stream reports as `Metadata`, not as
+  "Interface ReGaHSS".** The system has no ReGaHSS; the connection borrowed
+  that slot for the stream's state, so the log said "Interface ReGaHSS
+  connected" at every start and reconnect, right next to "this box has no
+  ReGaHSS". The log now says "Metadata stream connected", the nodes' status
+  counts the stream under that name, and the editors' interface lists do not
+  offer it.
+
 ## 4.6.2 (2026-10-23)
 
 ### Fixed

package/README.md

@@ -36,8 +36,22 @@ BINRPC/XMLRPC works unchanged. Device, channel, room and function names come fro
 ReGaHSS; the connection node detects this at start (`GET /api/meta/v1/version`), nothing has to be configured, and
 `msg.channelName`, `msg.rooms`, `msg.functions` and the room/function filters keep their shape.
 
-- Node-RED **on the system** (RedMatic from its addon catalogue): the system's own read-only token is used, nothing to do.
-- Node-RED **elsewhere**: an API token of the system goes into the connection node's **openccu-lite token** field.
+Since 4.7.0 the interface processes are reached through the system's **lite-rpc** as well, with
+[occulite-client](https://www.npmjs.com/package/occulite-client): the requests over the system's web port, the events
+from a stream the connection opens (replayed after a break, re-read after a restart of the system), one subscriber at
+the processes for every program on the system, no callback server and no `init` of this node's own; the value cache is
+filled from the system's state store at deploy. The connection node's **openccu-lite interfaces** setting chooses
+_auto_ (the default: lite-rpc on openccu-lite, the CCU way on a CCU), _openccu-lite_ (lite-rpc only) or _CCU_ (the
+direct connection with callbacks, on openccu-lite too); an existing connection is moved to lite-rpc once at its first
+start on openccu-lite, the log says so, and a choice made in the node is never changed by a later version. CUxD and
+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.
+  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
+  `setValue`, `rpc:configure` for paramsets and links, `rpc:admin` for the rest; the rpc node may call anything).
 - **System variables, programs and HM-Script do not exist there.** The `ccu-sysvar`, `ccu-program`, `ccu-script` and
   `ccu-poll` nodes stay in the flows and answer every message with an error.
 

package/nodes/ccu-connection.html

@@ -13,6 +13,12 @@
             cuxdEnabled: {value: false},
             jackEnabled: {value: false},
             jackPort: {value: 2121},
+            regaPort: {value: ''},
+            bcrfPort: {value: ''},
+            bcwiPort: {value: ''},
+            iprfPort: {value: ''},
+            virtPort: {value: ''},
+            cuxdPort: {value: ''},
 
             regaPoll: {value: true},
             regaInterval: {value: 30},
@@ -31,6 +37,7 @@
             username: {value: ''},
 
             metaPort: {value: ''},
+            connectionType: {value: 'auto'},
 
             queueTimeout: {value: 5000, required: true},
             queuePause: {value: 250, required: true},
@@ -223,12 +230,18 @@
     <div class="form-row">
         <label for="node-input-rfdEnabled"><i class="icon-tag"></i> Interfaces</label>
         <div style="width: 70%; display: inline-block; vertical-align: text-top;">
-            <label class="ccu-checkbox"><input type="checkbox" id="node-config-input-regaEnabled"> ReGaHSS</label><br>
-            <label class="ccu-checkbox"><input type="checkbox" id="node-config-input-bcrfEnabled"> BidCos-RF</label><br>
-            <label class="ccu-checkbox"><input type="checkbox" id="node-config-input-bcwiEnabled"> BidCos-Wired</label><br>
-            <label class="ccu-checkbox"><input type="checkbox" id="node-config-input-iprfEnabled"> HmIP-RF</label><br>
-            <label class="ccu-checkbox"><input type="checkbox" id="node-config-input-virtEnabled"> VirtualDevices</label><br>
-            <label class="ccu-checkbox"><input type="checkbox" id="node-config-input-cuxdEnabled"> CUxD</label><br>
+            <label class="ccu-checkbox"><input type="checkbox" id="node-config-input-regaEnabled"> ReGaHSS</label>
+            <input type="text" id="node-config-input-regaPort" class="ccu-port" style="width: 70px;" placeholder="8181"><br>
+            <label class="ccu-checkbox"><input type="checkbox" id="node-config-input-bcrfEnabled"> BidCos-RF</label>
+            <input type="text" id="node-config-input-bcrfPort" class="ccu-port" style="width: 70px;" placeholder="2001"><br>
+            <label class="ccu-checkbox"><input type="checkbox" id="node-config-input-bcwiEnabled"> BidCos-Wired</label>
+            <input type="text" id="node-config-input-bcwiPort" class="ccu-port" style="width: 70px;" placeholder="2000"><br>
+            <label class="ccu-checkbox"><input type="checkbox" id="node-config-input-iprfEnabled"> HmIP-RF</label>
+            <input type="text" id="node-config-input-iprfPort" class="ccu-port" style="width: 70px;" placeholder="2010"><br>
+            <label class="ccu-checkbox"><input type="checkbox" id="node-config-input-virtEnabled"> VirtualDevices</label>
+            <input type="text" id="node-config-input-virtPort" class="ccu-port" style="width: 70px;" placeholder="9292"><br>
+            <label class="ccu-checkbox"><input type="checkbox" id="node-config-input-cuxdEnabled"> CUxD</label>
+            <input type="text" id="node-config-input-cuxdPort" class="ccu-port" style="width: 70px;" placeholder="8701"><br>
             <label class="ccu-checkbox"><input type="checkbox" id="node-config-input-jackEnabled"> CCU-Jack</label>
             <input type="text" id="node-config-input-jackPort" style="width: 70px;" placeholder="2121">
         </div>
@@ -300,10 +313,18 @@
         <label for="node-config-input-password"><i class="icon-tag"></i> Password</label>
         <input type="password" id="node-config-input-password">
     </div>
+    <div class="form-row">
+        <label for="node-config-input-connectionType"><i class="icon-tag"></i> openccu-lite interfaces</label>
+        <select id="node-config-input-connectionType" style="width: 70%;">
+            <option value="auto">auto: through the system's lite-rpc on openccu-lite (the default), the CCU way elsewhere</option>
+            <option value="openccu-lite">openccu-lite: lite-rpc only</option>
+            <option value="ccu">CCU: directly, with callbacks (XML-RPC/BIN-RPC) - on openccu-lite too</option>
+        </select>
+    </div>
     <div class="form-row">
         <label for="node-config-input-metaToken"><i class="icon-tag"></i> openccu-lite token</label>
         <input type="password" id="node-config-input-metaToken" placeholder="olt_...">
-        <small>Only for openccu-lite (a CCU ignores this). Leave empty when Node-RED runs on the box.</small>
+        <small>Only for openccu-lite (a CCU ignores this). Leave empty when Node-RED runs on the system itself (RedMatic).</small>
     </div>
     <div class="form-row">
         <label for="node-config-input-metaPort"><i class="icon-tag"></i> openccu-lite port</label>

package/nodes/ccu-connection.js

@@ -17,7 +17,8 @@ const nextport = require('./lib/nextport.js');
 const hmDiscover = require('./lib/discover.js');
 const {Rega} = require('homematic-rega'); // ES module - require(esm) needs Node >= 20.19 / >= 22.12
 const metaProvider = require('./lib/metaprovider.js');
-const {InitRetry, retryDelay} = require('./lib/initretry.js');
+const {InitRetry, retryDelay, RETRY_INTERVAL} = require('./lib/initretry.js');
+const lite = require('./lib/lite.js');
 const xmlrpc = require('homematic-xmlrpc');
 const binrpc = require('binrpc');
 
@@ -55,8 +56,20 @@ function execToCallback(promise, callback) {
     );
 }
 
-/** B-28: how often an inconclusive metadata api detection is repeated (1, 2, 4, 8 s, then every 15 s) */
-const META_REDETECT_ATTEMPTS = 20;
+/**
+ * task 16: the pseudo-interface that carries the metadata stream's state on openccu-lite in
+ * ifaceTypes/ifaceStatus, where the ReGaHSS slot was borrowed before - the nodes' status logic
+ * works on those tables, and the system has no ReGaHSS to report. Never an RPC interface: no
+ * client, no init, not offered in the editors' interface lists (pseudo).
+ */
+const META_IFACE = 'Metadata';
+
+/**
+ * B-28: how often an inconclusive metadata api detection is repeated on the init retry's schedule
+ * (task 17: every 3 s for 90 s, then every 15 s - 41 attempts reach the same 255 s the 1/2/4/8/15 s
+ * steps covered in 20)
+ */
+const META_REDETECT_ATTEMPTS = 41;
 
 /**
  * task 9: has a device description changed in a way that changes its paramsets?
@@ -167,6 +180,11 @@ module.exports = function (RED) {
             switch (request.query.type) {
                 case 'ifaces': {
                     Object.keys(config.ifaceTypes).forEach((iface) => {
+                        if (config.ifaceTypes[iface].pseudo) {
+                            // task 16: the metadata stream is not an interface a node could address
+                            return;
+                        }
+
                         object[iface] = {
                             enabled: Boolean(config.ifaceTypes[iface].enabled),
                             connected: Boolean(config.ifaceStatus[iface]),
@@ -512,6 +530,8 @@ module.exports = function (RED) {
             const pass = auth ? config.password : undefined;
 
             this.ifaceTypes = {
+                // task 15: a port set in the dialog wins over the default of the transport (a CCU
+                // behind port forwarding, hm-simulator on a free port); blank is the default
                 ReGaHSS: {
                     conf: 'rega',
                     rpc: this.isLocal ? binrpc : xmlrpc,
@@ -523,7 +543,7 @@ module.exports = function (RED) {
                 'BidCos-RF': {
                     conf: 'bcrf',
                     rpc: this.isLocal || transport.bcrfBinRpc ? binrpc : xmlrpc,
-                    port: this.isLocal ? 32001 : tls ? 42001 : 2001,
+                    port: Number(config.bcrfPort) || (this.isLocal ? 32001 : tls ? 42001 : 2001),
                     protocol: this.isLocal || transport.bcrfBinRpc ? 'binrpc' : 'http',
                     auth,
                     user,
@@ -536,7 +556,7 @@ module.exports = function (RED) {
                 'BidCos-Wired': {
                     conf: 'bcwi',
                     rpc: this.isLocal ? binrpc : xmlrpc,
-                    port: this.isLocal ? 32000 : tls ? 42000 : 2000,
+                    port: Number(config.bcwiPort) || (this.isLocal ? 32000 : tls ? 42000 : 2000),
                     protocol: this.isLocal ? 'binrpc' : 'http',
                     auth,
                     user,
@@ -549,7 +569,7 @@ module.exports = function (RED) {
                 'HmIP-RF': {
                     conf: 'iprf',
                     rpc: xmlrpc,
-                    port: this.isLocal ? 32010 : tls ? 42010 : 2010,
+                    port: Number(config.iprfPort) || (this.isLocal ? 32010 : tls ? 42010 : 2010),
                     protocol: 'http',
                     auth,
                     user,
@@ -567,7 +587,7 @@ module.exports = function (RED) {
                 VirtualDevices: {
                     conf: 'virt',
                     rpc: xmlrpc,
-                    port: this.isLocal ? 39292 : tls ? 49292 : 9292,
+                    port: Number(config.virtPort) || (this.isLocal ? 39292 : tls ? 49292 : 9292),
                     path: 'groups',
                     protocol: 'http',
                     auth,
@@ -581,7 +601,7 @@ module.exports = function (RED) {
                 CUxD: {
                     conf: 'cuxd',
                     rpc: binrpc,
-                    port: 8701,
+                    port: Number(config.cuxdPort) || 8701,
                     protocol: 'binrpc',
                     init: true,
                     ping: true,
@@ -636,8 +656,10 @@ module.exports = function (RED) {
             this.lastRealEvent = {};
             this.ifaceStatus = {};
             // task 11: interfaces whose init failed and is retried (InitRetry per iface),
-            // and which of them are waiting for an unreachable process
+            // and which of them are waiting for an unreachable process; task 17: when this
+            // node started, for the retry's "connected … after the start" line
             this.initRetry = {};
+            this.startedAt = Date.now();
             this.ifaceWaiting = {};
             // B-37: per interface {inFlight, at, reinit} of our own init, and how long after it the
             // process's listDevices/newDevices still answer it (see keptSubscription())
@@ -659,6 +681,17 @@ module.exports = function (RED) {
             this.inSecure = inSecure;
             this.metaPort = Number.parseInt(config.metaPort, 10) || (tls ? 443 : 80);
             this.metaToken = config.metaToken || metaProvider.readLocalToken();
+            // task 14: the way to the interfaces on openccu-lite - `auto` (the default) goes through
+            // the system's lite-rpc where the system is openccu-lite and a credential allows it,
+            // `openccu-lite` insists on it, `ccu` keeps the direct connection with callbacks there
+            // too. The credential for lite-rpc: the node's token, else the addon's own (RedMatic's,
+            // minted by the system); the local token reads names only and is no credential here.
+            this.connectionType = ['ccu', 'openccu-lite'].includes(config.connectionType)
+                ? config.connectionType
+                : 'auto';
+            this.liteToken = config.metaToken || lite.readAddonToken();
+            this.lite = null;
+            this.liteIfaces = [];
             this.metaMode = false;
             this.meta = null;
             // #167: minutes between re-reads of channel names, rooms and
@@ -742,6 +775,12 @@ module.exports = function (RED) {
                 RED.settings.userDir || path.join(__dirname, '..'),
                 'ccu_values_' + this.host + '.json',
             );
+            // task 14: written once, when a connection of type `auto` first went through lite-rpc -
+            // the one-time move is said in the log once, not at every start
+            this.liteMarkerFile = path.join(
+                RED.settings.userDir || path.join(__dirname, '..'),
+                'ccu_lite_' + this.host + '.json',
+            );
 
             this.loadMetadata();
             this.loadRegadata();
@@ -752,7 +791,7 @@ module.exports = function (RED) {
 
             this.rega = new Rega({
                 host: this.host,
-                port: this.isLocal ? 8183 : tls ? 48181 : 8181,
+                port: Number(config.regaPort) || (this.isLocal ? 8183 : tls ? 48181 : 8181),
                 tls,
                 insecure: inSecure,
                 username: user,
@@ -804,7 +843,7 @@ module.exports = function (RED) {
 
         /**
          * B-31: the password and the token, from the credentials or - once - from the
-         * plain properties of a flow written before 4.4.6.
+         * plain properties of a flow written before 4.5.0.
          * @param {object} config the node's configuration as deployed
          * @returns {{password: string, metaToken: string}}
          */
@@ -967,7 +1006,10 @@ module.exports = function (RED) {
             const waitingChanged = Boolean(this.ifaceWaiting[iface]) !== waiting;
             if (this.ifaceStatus[iface] !== connected || waitingChanged) {
                 if (this.ifaceStatus[iface] !== connected) {
-                    if (iface === 'ReGaHSS') {
+                    if (this.ifaceTypes[iface].pseudo) {
+                        // task 16: the stream of the system's metadata api, not an interface process
+                        this.logger.info(iface, 'stream', connected ? 'connected' : 'disconnected');
+                    } else if (iface === 'ReGaHSS') {
                         this.logger.info('Interface', iface, connected ? 'connected' : 'disconnected');
                     } else if (waiting) {
                         // task 11: the retry logs the one warn line, this stays quiet
@@ -977,7 +1019,9 @@ module.exports = function (RED) {
                             'Interface',
                             iface,
                             connected
-                                ? this.ifaceTypes[iface].protocol +
+                                ? this.lite && this.lite.has(iface)
+                                    ? 'lite-rpc connected'
+                                    : this.ifaceTypes[iface].protocol +
                                       ' port ' +
                                       this.ifaceTypes[iface].port +
                                       ' connected'
@@ -993,11 +1037,7 @@ module.exports = function (RED) {
                     delete this.ifaceWaiting[iface];
                 }
 
-                Object.keys(this.users).forEach((id) => {
-                    if (typeof this.users[id].setStatus === 'function') {
-                        this.users[id].setStatus({ifaceStatus: this.ifaceStatus, ifaceWaiting: this.ifaceWaiting});
-                    }
-                });
+                this.pushStatus();
             }
         }
 
@@ -1011,6 +1051,7 @@ module.exports = function (RED) {
                 this.initRetry[iface] = new InitRetry({
                     iface,
                     logger: this.logger,
+                    startedAt: this.startedAt,
                     attempt: () => this.rpcInit(iface, {retry: true}),
                     onState: (state) => {
                         if (state === 'connected') {
@@ -1026,6 +1067,15 @@ module.exports = function (RED) {
             return this.initRetry[iface];
         }
 
+        /** the interface tables as they are now, to every node of this connection */
+        pushStatus() {
+            Object.keys(this.users).forEach((id) => {
+                if (typeof this.users[id].setStatus === 'function') {
+                    this.users[id].setStatus({ifaceStatus: this.ifaceStatus, ifaceWaiting: this.ifaceWaiting});
+                }
+            });
+        }
+
         /**
          * An init succeeded (the first one, a retry, or a re-init after a ping timeout).
          * @param iface
@@ -1036,6 +1086,21 @@ module.exports = function (RED) {
             } else {
                 this.setIfaceStatus(iface, true);
             }
+
+            this.retryMissingNow(iface);
+        }
+
+        /**
+         * task 17: an interface appeared - every other one whose init retry is waiting on its timer
+         * is tried at once (rfd and hmipserver come up close together on a booting system).
+         * @param {string} iface the one that appeared
+         */
+        retryMissingNow(iface) {
+            Object.keys(this.initRetry).forEach((other) => {
+                if (other !== iface) {
+                    this.initRetry[other].poke();
+                }
+            });
         }
 
         /**
@@ -1266,6 +1331,7 @@ module.exports = function (RED) {
             this.logger.debug('ccu-connection destructor');
             this.closing = true;
             this.stopInitRetries();
+            this.stopLite();
             this.stats(false);
 
             this.logger.debug('clear regaPollTimeout');
@@ -1396,9 +1462,10 @@ module.exports = function (RED) {
         /**
          * B-28: an inconclusive detection (the box busy or still starting) used
          * to leave the connection in ReGa mode for good - the only re-detection
-         * ran from rare error paths, at most every five minutes. Ask again after
-         * 1, 2, 4, 8 s, then every 15 s, up to META_REDETECT_ATTEMPTS times;
-         * after that the five-minute rule of recheckMeta() applies.
+         * ran from rare error paths, at most every five minutes. Ask again on the
+         * init retry's schedule (every 3 s for 90 s, then every 15 s - task 17), up
+         * to META_REDETECT_ATTEMPTS times; after that the five-minute rule of
+         * recheckMeta() applies.
          * @param {{inconclusive: boolean, reason?: string}} outcome
          */
         scheduleMetaRedetect(outcome) {
@@ -1420,7 +1487,7 @@ module.exports = function (RED) {
                 return;
             }
 
-            const delay = retryDelay(this.metaRedetectAttempt);
+            const delay = retryDelay((this.metaRedetectAttempt - 1) * RETRY_INTERVAL);
             const line =
                 'meta api detection inconclusive (' +
                 outcome.reason +
@@ -1487,6 +1554,21 @@ module.exports = function (RED) {
                 this.closeClient('ReGaHSS');
             }
 
+            // task 16: the metadata stream's state is the Metadata pseudo-interface's, not the
+            // ReGaHSS slot's - the system has none, and "Interface ReGaHSS connected" misled
+            this.ifaceTypes[META_IFACE] = {
+                conf: 'meta',
+                pseudo: true,
+                init: false,
+                ping: false,
+                protocol: this.tlsEnabled ? 'https' : 'http',
+                port: this.metaPort,
+                enabled: true,
+            };
+            delete this.ifaceStatus.ReGaHSS;
+            delete this.ifaceWaiting.ReGaHSS;
+            this.ifaceStatus[META_IFACE] = null;
+
             this.logger.info(
                 'openccu-lite detected (' +
                     (info.implementation || 'meta api') +
@@ -1529,12 +1611,29 @@ module.exports = function (RED) {
                         resolve();
                     },
                     onStatus: (connected) => {
-                        this.setIfaceStatus('ReGaHSS', connected);
+                        this.setIfaceStatus(META_IFACE, connected);
                     },
                     onGone: () => {
                         this.metaMode = false;
                         this.meta = null;
                         this.lastMetaProbe = 0;
+                        if (this.lite) {
+                            // task 14: lite-rpc went with the system's answer; the CCU way needs a deploy
+                            this.stopLite();
+                            this.liteIfaces.forEach((iface) => this.setIfaceStatus(iface, false));
+                            this.logger.warn(
+                                'lite-rpc closed: the system no longer answers as openccu-lite - deploy again to reach the interfaces the CCU way',
+                            );
+                        }
+
+                        // task 16: the ReGaHSS slot is the interface again
+                        delete this.ifaceTypes[META_IFACE];
+                        delete this.ifaceStatus[META_IFACE];
+                        if (this.ifaceTypes.ReGaHSS.enabled) {
+                            this.ifaceStatus.ReGaHSS = null;
+                        }
+
+                        this.pushStatus();
                         this.logger.warn('this box no longer answers as openccu-lite - detecting again');
                         this.detectMetaOutcome().then((outcome) => {
                             if (outcome.info) {
@@ -2217,9 +2316,16 @@ module.exports = function (RED) {
          * @param config
          */
         initIfaces(config) {
+            // task 14: the interfaces that go through lite-rpc get no client and no init of their own
+            const liteIfaces = this.liteInterfaces(config);
+            this.liteIfaces = liteIfaces;
             Object.keys(this.ifaceTypes).forEach((iface) => {
                 const enabled = config[this.ifaceTypes[iface].conf + 'Enabled'];
                 this.ifaceTypes[iface].enabled = enabled;
+                if (enabled && liteIfaces.includes(iface)) {
+                    return;
+                }
+
                 if (enabled && iface === 'ReGaHSS' && this.metaMode) {
                     // B-27: openccu-lite has no ReGaHSS, nothing listens on 31999.
                     // A client would only reconnect forever (with binrpc < 4.3.0
@@ -2249,6 +2355,249 @@ module.exports = function (RED) {
                 }
             });
             this.logger.info('Interfaces:', this.enabledIfaces.join(', '));
+            if (liteIfaces.length > 0) {
+                this.startLite(liteIfaces);
+            }
+        }
+
+        /**
+         * task 14: which of the enabled interfaces go through the system's lite-rpc - the ones
+         * lite-rpc carries (not CUxD, not CCU-Jack), on an openccu-lite system, with a credential,
+         * unless the connection type says `ccu`.
+         * @param {object} config the node's config
+         * @returns {string[]}
+         */
+        liteInterfaces(config) {
+            const enabled = lite.LITE_INTERFACES.filter((iface) => config[this.ifaceTypes[iface].conf + 'Enabled']);
+            if (this.connectionType === 'ccu') {
+                if (this.metaMode) {
+                    this.logger.info(
+                        'openccu-lite: the direct connection with callbacks by choice (connection type CCU) - the interfaces are reached on their own ports',
+                    );
+                }
+
+                return [];
+            }
+
+            if (!this.metaMode) {
+                if (this.connectionType === 'openccu-lite') {
+                    this.logger.warn(
+                        'connection type openccu-lite, but the system did not answer as openccu-lite - the interfaces are reached the CCU way until it does',
+                    );
+                }
+
+                return [];
+            }
+
+            if (!this.liteToken) {
+                this.logger.info(
+                    'openccu-lite without a credential for lite-rpc (no token in the connection node, no addon token in ' +
+                        lite.ADDON_TOKEN_FILE +
+                        ') - the interfaces are reached directly, with callbacks',
+                );
+                return [];
+            }
+
+            if (enabled.length === 0) {
+                return [];
+            }
+
+            return enabled;
+        }
+
+        /**
+         * task 14: the init id the callback table expects for an interface - the same shape rpcInit
+         * registers, so getIfaceFromIdInit() recognises the stream's calls.
+         * @param {string} iface
+         * @returns {string}
+         */
+        liteInitId(iface) {
+            const hash = base62(crypto.createHash('sha1').update(this.initUrl(iface)).digest()).slice(0, 6);
+            return 'nr_' + hash + '_' + iface;
+        }
+
+        /**
+         * task 14: the interfaces through the system's lite-rpc with occulite-client - one client,
+         * the stream's events into the same rpcMethods table the callback servers feed, the
+         * requests through methodCall. The one-time move of an `auto` connection is said once
+         * (the marker file); `ccu` in the connection node is never moved.
+         * @param {string[]} ifaces
+         */
+        startLite(ifaces) {
+            if (this.connectionType === 'auto') {
+                let marker = null;
+                try {
+                    marker = JSON.parse(fs.readFileSync(this.liteMarkerFile, 'utf8'));
+                } catch {
+                    marker = null;
+                }
+
+                if (!marker) {
+                    this.logger.info(
+                        'openccu-lite: ' +
+                            ifaces.join(', ') +
+                            " go through the system's lite-rpc from now on, the default on openccu-lite - moved once; connection type CCU in the connection node keeps the direct connection with callbacks, and is never changed again",
+                    );
+                    try {
+                        fs.writeFileSync(
+                            this.liteMarkerFile,
+                            JSON.stringify({migrated: new Date().toISOString(), host: this.host}),
+                        );
+                    } catch (error) {
+                        this.logger.warn('cannot write ' + this.liteMarkerFile + ': ' + error.message);
+                    }
+                }
+            }
+
+            const url = (this.tlsEnabled ? 'https' : 'http') + '://' + this.host + ':' + this.metaPort;
+            const running = (iface) => this.lite && this.lite.running(iface) !== false;
+            this.lite = new lite.LiteConnection({
+                url,
+                token: this.liteToken,
+                insecure: Boolean(this.inSecure),
+                interfaces: ifaces,
+                initId: (iface) => this.liteInitId(iface),
+                logger: this.logger,
+                createClient: this.liteCreateClient,
+                onCallback: (method, err, parameters, callback) => {
+                    if (err) {
+                        this.logger.error('rpc <', 'lite', method, err);
+                    }
+
+                    this.logger.debug('rpc <', 'lite', method, JSON.stringify(parameters));
+                    const handler = method === 'event' ? 'eventSingle' : method;
+                    if (isIterable(parameters)) {
+                        this.callRpcMethod(handler, err, parameters, callback);
+                    } else {
+                        this.logger.error(
+                            'rpc <',
+                            'lite',
+                            'method',
+                            method,
+                            'params not iterable',
+                            JSON.stringify(parameters),
+                        );
+                        callback(null, this.rpcDefaultAnswer(method));
+                    }
+                },
+                onInterface: (iface, state) => {
+                    if (!ifaces.includes(iface) || this.closing) {
+                        return;
+                    }
+
+                    this.logger.debug('lite-rpc interface', iface, state);
+                    if (state === 'up' || state === 'added' || state === 'restarted') {
+                        this.lastEvent[iface] = now();
+                        this.setIfaceStatus(iface, true);
+                        if (state === 'restarted' || state === 'added') {
+                            this.getDevices(iface).catch(() => {});
+                        }
+                    } else {
+                        this.setIfaceStatus(iface, false, true);
+                    }
+                },
+                onStatus: (state) => {
+                    if (this.closing) {
+                        return;
+                    }
+
+                    this.logger.debug('lite-rpc client', state);
+                    if (state === 'ready') {
+                        ifaces.forEach((iface) => this.setIfaceStatus(iface, running(iface), !running(iface)));
+                    } else if (state === 'degraded' || state === 'offline' || state === 'connecting') {
+                        ifaces.forEach((iface) => this.setIfaceStatus(iface, false, true));
+                    } else if (state === 'closed') {
+                        ifaces.forEach((iface) => this.setIfaceStatus(iface, false));
+                    }
+                },
+                onValues: (values) => this.applyLiteValues(values),
+            });
+            this.logger.info(
+                'lite-rpc: ' + ifaces.join(', ') + ' through ' + url + ' (occulite-client), no callback server',
+            );
+            ifaces.forEach((iface) => this.setIfaceStatus(iface, false, true));
+            this.lite
+                .start()
+                .then(() => {
+                    if (this.closing || !this.lite) {
+                        return;
+                    }
+
+                    const up = ifaces.filter((iface) => running(iface));
+                    this.logger.info('lite-rpc connected: ' + (up.join(', ') || 'no interface running'));
+                    return Promise.all(
+                        up.map((iface) =>
+                            this.getDevices(iface)
+                                .then(() => {
+                                    if (['BidCos-RF', 'BidCos-Wired', 'HmIP-RF'].includes(iface)) {
+                                        return this.methodCall(iface, 'getLinks', [], {quiet: true})
+                                            .then((res) => {
+                                                this.links[iface] = res;
+                                            })
+                                            .catch(() => {});
+                                    }
+                                })
+                                .catch((error) => {
+                                    this.logger.warn('lite-rpc ' + iface + ' listDevices: ' + error.message);
+                                }),
+                        ),
+                    );
+                })
+                .catch((error) => {
+                    if (this.closing) {
+                        return;
+                    }
+
+                    this.logger.warn('lite-rpc: ' + (error.message || error) + ' - the client keeps trying');
+                    ifaces.forEach((iface) => this.setIfaceStatus(iface, false, true));
+                });
+        }
+
+        /**
+         * task 14: the state store's picture into the values cache at connect (what a CCU's ReGa
+         * getValues gave): the nodes with "cache" get a value at deploy on openccu-lite as well.
+         * @param {Map<string, {value: *, ts: number, lc?: number, confirmed: boolean}>} values box.values
+         */
+        applyLiteValues(values) {
+            if (!values || typeof values.forEach !== 'function') {
+                return;
+            }
+
+            let count = 0;
+            values.forEach((entry, ref) => {
+                const [iface, channel, datapoint] = String(ref).split('.');
+                if (!this.liteIfaces.includes(iface) || !channel || !datapoint) {
+                    return;
+                }
+
+                const ts = entry.ts || 0;
+                const message = this.createMessage(iface, channel, datapoint, entry.value, {
+                    cache: true,
+                    change: false,
+                    working: false,
+                    uncertain: entry.confirmed === false,
+                    ts,
+                    lc: entry.lc || ts,
+                });
+                this.values[message.datapointName] = message;
+                count += 1;
+                if (!datapoint.startsWith('PRESS_')) {
+                    this.callCallbacks(message);
+                }
+            });
+            this.logger.debug('lite-rpc: ' + count + ' values from the state store');
+            this.cachedValuesReceived = true;
+            this.saveValues();
+            this.scheduleValuesPrune();
+        }
+
+        /** task 14: close the lite-rpc client, if any */
+        stopLite() {
+            if (this.lite) {
+                this.logger.debug('lite-rpc client closing');
+                this.lite.close();
+                this.lite = null;
+            }
         }
 
         /**
@@ -4141,6 +4490,31 @@ module.exports = function (RED) {
          */
         methodCall(iface, method, parameters, {quiet = false} = {}) {
             return new Promise((resolve, reject) => {
+                if (this.lite && this.lite.has(iface)) {
+                    // task 14: through the system's lite-rpc; a fault keeps its code, a scope the
+                    // token lacks is said as such - the interface stays connected either way
+                    this.logger.debug('rpc >', iface, method, JSON.stringify(parameters));
+                    this.lite.call(iface, method, parameters).then(
+                        (res) => {
+                            this.logger.debug('    <', iface, method, JSON.stringify(res));
+                            resolve(res);
+                        },
+                        (error) => {
+                            this.logger[quiet ? 'debug' : 'error'](
+                                '    <',
+                                iface,
+                                method,
+                                JSON.stringify(parameters),
+                                error.faultCode === undefined
+                                    ? error.message
+                                    : 'fault ' + error.faultCode + ' ' + error.faultString,
+                            );
+                            reject(error);
+                        },
+                    );
+                    return;
+                }
+
                 if (this.clients[iface]) {
                     this.logger.debug('rpc >', iface, method, JSON.stringify(parameters));
                     this.clients[iface].methodCall(method, parameters, (err, res) => {

package/nodes/lib/initretry.js

@@ -5,8 +5,13 @@
  * 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, 1 s, 2 s, 4 s, 8 s and then every 15 s (task 12), until it
- * succeeds or the node is closed.
+ * own retry (task 12) until it succeeds or the node is closed: every 3 s for
+ * the first 90 s after the interface was first missed (the start, or the
+ * moment a connected process went away), then every 15 s (task 17 - the
+ * 1/2/4/8/15 s steps of before hit hmipserver's ready moment, ~50-55 s after
+ * an openccu-lite boot, only at their 61 s tick). When one interface appears
+ * the others that are waiting are tried at once (poke): rfd and hmipserver
+ * come up close together.
  *
  * While the process is unreachable the interface is "waiting": one line, then
  * debug. Before the interface was ever connected, a refused connection is
@@ -17,20 +22,22 @@
  * distinct fault.
  */
 
-const RETRY_DELAYS = [1000, 2000, 4000, 8000];
+const RETRY_INTERVAL = 3000;
+const RETRY_WINDOW = 90000;
 const RETRY_MAX_DELAY = 15000;
 
 /**
- * The delay before the next attempt.
- * @param {number} failures failed attempts so far (1 after the first failure)
- * @returns {number} milliseconds
+ * The delay before the next attempt (task 17).
+ * @param {number} elapsed milliseconds since the interface was first missed
+ * @returns {number} milliseconds: 3 s within the first 90 s, then 15 s
  */
-function retryDelay(failures) {
-    if (failures >= 1 && failures <= RETRY_DELAYS.length) {
-        return RETRY_DELAYS[failures - 1];
-    }
+function retryDelay(elapsed) {
+    return elapsed < RETRY_WINDOW ? RETRY_INTERVAL : RETRY_MAX_DELAY;
+}
 
-    return RETRY_MAX_DELAY;
+/** @param {number} ms @returns {string} seconds with one decimal, e.g. "54.0 s" */
+function seconds(ms) {
+    return (Math.max(0, ms) / 1000).toFixed(1) + ' s';
 }
 
 /**
@@ -92,14 +99,19 @@ class InitRetry {
      * @param {object} options.logger {debug, info, warn, error}
      * @param {function(string)} options.onState 'waiting' | 'failed' | 'connected'
      * @param {object} [options.timers] {setTimeout, clearTimeout}, for tests
+     * @param {function(): number} [options.now] the clock, for tests
+     * @param {number} [options.startedAt] when the program (the connection node) started, for the log line
      */
-    constructor({iface, attempt, logger, onState, timers}) {
+    constructor({iface, attempt, logger, onState, timers, now, startedAt}) {
         this.iface = iface;
         this.attempt = attempt;
         this.logger = logger;
         this.onState = onState || (() => {});
         this.timers = timers || {setTimeout, clearTimeout};
+        this.now = now || Date.now;
+        this.startedAt = startedAt === undefined ? this.now() : startedAt;
         this.timer = null;
+        this.running = false;
         this.stopped = false;
         this.everConnected = false;
         this.reset();
@@ -109,6 +121,8 @@ class InitRetry {
         this.failures = 0;
         this.warned = false;
         this.faults = new Set();
+        // task 17: when the process was first missed - the 90 s of 3 s steps count from here
+        this.missedAt = null;
     }
 
     /** true while a retry is scheduled */
@@ -125,8 +139,12 @@ class InitRetry {
             return;
         }
 
+        if (this.failures === 0) {
+            this.missedAt = this.now();
+        }
+
         this.failures += 1;
-        const delay = retryDelay(this.failures);
+        const delay = retryDelay(this.now() - this.missedAt);
         const seconds = delay / 1000;
         const reason = describeError(error);
         if (isFault(error)) {
@@ -177,14 +195,38 @@ class InitRetry {
             return Promise.resolve();
         }
 
+        this.running = true;
         return Promise.resolve()
             .then(() => this.attempt())
             .then(
-                () => this.succeeded(),
-                (error) => this.failed(error),
+                () => {
+                    this.running = false;
+                    this.succeeded();
+                },
+                (error) => {
+                    this.running = false;
+                    this.failed(error);
+                },
             );
     }
 
+    /**
+     * task 17: another interface just appeared - try this one now instead of at its timer
+     * (rfd and hmipserver come up close together). Nothing while an attempt is running or
+     * none is scheduled.
+     * @returns {boolean} whether an attempt was started
+     */
+    poke() {
+        if (this.stopped || this.running || this.timer === null) {
+            return false;
+        }
+
+        this.clear();
+        this.logger.debug(this.iface + ': another interface appeared, trying now');
+        this.run();
+        return true;
+    }
+
     /** an init attempt succeeded */
     succeeded() {
         if (this.stopped) {
@@ -193,7 +235,11 @@ class InitRetry {
 
         this.clear();
         if (this.failures > 0) {
-            this.logger.info(this.iface + ' connected after ' + (this.failures + 1) + ' attempts');
+            // task 17: one line with the time, so a log shows how close the start got to the process's ready moment
+            const since = this.everConnected
+                ? seconds(this.now() - this.missedAt) + ' after it went missing'
+                : seconds(this.now() - this.startedAt) + ' after the start';
+            this.logger.info(this.iface + ' connected after ' + (this.failures + 1) + ' attempts, ' + since);
         }
 
         this.everConnected = true;
@@ -215,4 +261,13 @@ class InitRetry {
     }
 }
 
-module.exports = {InitRetry, retryDelay, isFault, isRefused, describeError, RETRY_DELAYS, RETRY_MAX_DELAY};
+module.exports = {
+    InitRetry,
+    retryDelay,
+    isFault,
+    isRefused,
+    describeError,
+    RETRY_INTERVAL,
+    RETRY_WINDOW,
+    RETRY_MAX_DELAY,
+};

package/nodes/lib/lite.js

@@ -0,0 +1,309 @@
+/*
+ * task 14: the interfaces of an openccu-lite system through its lite-rpc, with occulite-client,
+ * instead of XML-RPC/BIN-RPC clients and callback servers of our own.
+ *
+ * One client per connection node: the requests go to /api/rpc/v1 with the credential, the events
+ * come from the stream the client opens (resumed after a break, re-read after a restart of the
+ * system), and `callbackEvents` turns them into the very calls a callback server would make -
+ * event, system.multicall, newDevices, deleteDevices, updateDevice, replaceDevice, readdedDevice
+ * with the same argument lists - so the connection's rpcMethods table feeds from it unchanged.
+ * No init, no ping, no callback ports for these interfaces. CUxD and CCU-Jack are not carried by
+ * lite-rpc and keep their own clients.
+ *
+ * The credential: the openccu-lite token of the connection node, else the addon's own token the
+ * system mints for RedMatic from its manifest (/run/occulite/addon-tokens/redmatic.api). The local
+ * token (meta:read alone) is no credential for lite-rpc.
+ *
+ * occulite-client is ESM; it is loaded here, lazily, so a CCU user never loads it and a Node too
+ * old for require(esm) gets a message instead of a crash (B-32's lesson).
+ */
+
+const fs = require('fs');
+
+const LITE_INTERFACES = ['BidCos-RF', 'BidCos-Wired', 'HmIP-RF', 'VirtualDevices'];
+const ADDON_TOKEN_FILE = '/run/occulite/addon-tokens/redmatic.api';
+
+/** the stream's events as the callback server's methods, see callbackEvents() */
+const CALLBACK_METHODS = [
+    'event',
+    'system.multicall',
+    'newDevices',
+    'deleteDevices',
+    'updateDevice',
+    'replaceDevice',
+    'readdedDevice',
+];
+
+let modules = null;
+
+/**
+ * occulite-client, loaded once. Throws with a readable message where it cannot be loaded.
+ * @returns {{OccuLite: Function, callbackEvents: Function, nodeTransport: Function}}
+ */
+function load() {
+    if (!modules) {
+        try {
+            const {OccuLite} = require('occulite-client');
+            const {callbackEvents} = require('occulite-client/callbacks');
+            const {nodeTransport} = require('occulite-client/node');
+            modules = {OccuLite, callbackEvents, nodeTransport};
+        } catch (error) {
+            throw new Error(
+                'occulite-client cannot be loaded (' +
+                    (error.message || error) +
+                    '): lite-rpc needs Node.js 20.19, 22.12 or newer; the direct connection is used instead',
+            );
+        }
+    }
+
+    return modules;
+}
+
+/**
+ * The addon's own token on an openccu-lite system (RedMatic's, minted from its manifest), or
+ * undefined where there is none.
+ * @param {string} [file] the token file, for tests
+ * @returns {string|undefined}
+ */
+function readAddonToken(file = module.exports.ADDON_TOKEN_FILE) {
+    try {
+        const token = fs.readFileSync(file, 'utf8').trim();
+        return token === '' ? undefined : token;
+    } catch {
+        return undefined;
+    }
+}
+
+/**
+ * Whether an error of the client is an RPC fault of the interface process (the process answered).
+ * @param {*} error
+ * @returns {boolean}
+ */
+function isFault(error) {
+    return Boolean(error) && error.kind === 'rpc-fault' && error.faultCode !== undefined;
+}
+
+/**
+ * The client's error as the connection reports it: a fault keeps its code and string, a refused
+ * scope says which, everything else its kind.
+ * @param {*} error
+ * @returns {Error}
+ */
+function translateError(error) {
+    if (isFault(error)) {
+        const fault = new Error(error.faultString || error.message);
+        fault.faultCode = error.faultCode;
+        fault.faultString = error.faultString || error.message;
+        return fault;
+    }
+
+    if (error && error.kind === 'forbidden') {
+        const refused = new Error(
+            'the openccu-lite token may not call this method' + (error.scope ? ' (needs ' + error.scope + ')' : ''),
+        );
+        refused.kind = 'forbidden';
+        refused.scope = error.scope;
+        return refused;
+    }
+
+    if (error && error.kind) {
+        const translated = new Error(error.message || error.kind);
+        translated.kind = error.kind;
+        return translated;
+    }
+
+    return error instanceof Error ? error : new Error(String(error));
+}
+
+const RPC_TIERS = ['rpc:operate', 'rpc:configure', 'rpc:admin'];
+
+/**
+ * occulite-client B-3: the client decides "names only" from the literal `rpc:read` in
+ * GET /api/auth/v1/state, but a token made with a higher tier (rpc:admin, say) carries that tier
+ * alone - the system includes the lower ones. The transport spells `rpc:read` out for the client
+ * where a tier implies it. Goes once the package fixes it.
+ * @param {object} transport occulite-client's Transport
+ * @returns {object} the same transport
+ */
+function tierAwareTransport(transport) {
+    return {
+        request: (method, url, headers, body, signal) =>
+            transport.request(method, url, headers, body, signal).then((response) => {
+                if (response.status !== 200 || !/\/api\/auth\/v1\/state(\?|$)/.test(String(url))) {
+                    return response;
+                }
+
+                let parsed;
+                try {
+                    parsed = JSON.parse(response.body);
+                } catch {
+                    return response;
+                }
+
+                const scopes = Array.isArray(parsed && parsed.scopes) ? parsed.scopes : [];
+                if (scopes.includes('rpc:read') || !scopes.some((scope) => RPC_TIERS.includes(scope))) {
+                    return response;
+                }
+
+                return {...response, body: JSON.stringify({...parsed, scopes: [...scopes, 'rpc:read']})};
+            }),
+        stream: (url, headers, signal) => transport.stream(url, headers, signal),
+    };
+}
+
+class LiteConnection {
+    /**
+     * @param {object} options
+     * @param {string} options.url the system, scheme and authority
+     * @param {string} options.token the credential
+     * @param {boolean} [options.insecure] accept any certificate
+     * @param {string[]} options.interfaces the interfaces to follow (the enabled ones lite-rpc carries)
+     * @param {function(string): string} options.initId the init id the connection's callback table expects per interface
+     * @param {function(string, *, Array, Function)} options.onCallback (method, err, params, answer): a callback server's call
+     * @param {function(string, string)} options.onInterface (iface, state): up | down | restarted | added | removed
+     * @param {function(string)} options.onStatus the client's state: connecting | ready | degraded | offline | closed
+     * @param {function(Map)} [options.onValues] box.values once ready (the state store's picture)
+     * @param {object} options.logger {debug, info, warn, error}
+     * @param {number} [options.timeout] per request, ms
+     * @param {Function} [options.createClient] for tests, in place of new OccuLite()
+     */
+    constructor(options) {
+        this.options = options;
+        this.interfaces = [...options.interfaces];
+        this.logger = options.logger;
+        this.box = null;
+        this.server = null;
+        this.closed = false;
+        this.ready = false;
+    }
+
+    /**
+     * @param {string} iface
+     * @returns {boolean} whether this interface goes through lite-rpc
+     */
+    has(iface) {
+        return this.interfaces.includes(iface);
+    }
+
+    /**
+     * Opens the client. Resolves once the first picture is loaded, rejects with the client's
+     * reason (unauthenticated, forbidden, unreachable, timeout ...); the stream keeps trying by
+     * itself afterwards.
+     * @returns {Promise<void>}
+     */
+    start() {
+        const {OccuLite, callbackEvents, nodeTransport} = load();
+        const debug = (message) => this.logger.debug('occulite-client: ' + message);
+        const clientOptions = {
+            url: this.options.url,
+            auth: {token: this.options.token},
+            transport: tierAwareTransport(nodeTransport(this.options.insecure ? {insecure: true} : {})),
+            interfaces: this.interfaces,
+            values: true,
+            meta: false,
+            devices: true,
+            timeout: this.options.timeout || 30000,
+            log: {debug, info: debug, warn: debug, error: debug},
+        };
+        const box = this.options.createClient ? this.options.createClient(clientOptions) : new OccuLite(clientOptions);
+        this.box = box;
+        box.on('status', (event) => {
+            if (this.closed || this.box !== box) {
+                return;
+            }
+
+            const state = event && event.state ? event.state : event;
+            this.ready = state === 'ready';
+            this.options.onStatus(state);
+        });
+        box.on('interface', (event) => {
+            if (!this.closed && this.box === box) {
+                this.options.onInterface(event.interface, event.state);
+            }
+        });
+        box.on('resync', () => {
+            if (!this.closed && this.box === box && this.options.onValues) {
+                this.options.onValues(box.values);
+            }
+        });
+        // the stream's events as a callback server's calls, into the connection's own table
+        this.server = callbackEvents(box, {initId: this.options.initId});
+        CALLBACK_METHODS.forEach((method) => {
+            this.server.on(method, (err, parameters, callback) => {
+                if (this.closed || this.box !== box) {
+                    callback(null, '');
+                    return;
+                }
+
+                this.options.onCallback(method, err, parameters, callback);
+            });
+        });
+
+        return box.ready().then(() => {
+            if (this.closed || this.box !== box) {
+                return;
+            }
+
+            this.ready = true;
+            if (this.options.onValues) {
+                this.options.onValues(box.values);
+            }
+        });
+    }
+
+    /**
+     * Any method of an interface process through lite-rpc; the credential's tier decides.
+     * @param {string} iface
+     * @param {string} method
+     * @param {Array} parameters
+     * @returns {Promise<*>}
+     */
+    call(iface, method, parameters) {
+        if (!this.box) {
+            return Promise.reject(new Error('lite-rpc client not started'));
+        }
+
+        return this.box.call(iface, method, parameters || []).then(
+            (result) => (result === null || result === undefined ? '' : result),
+            (error) => {
+                throw translateError(error);
+            },
+        );
+    }
+
+    /**
+     * Whether the system says this interface runs (the client's live list).
+     * @param {string} iface
+     * @returns {boolean|undefined} undefined while the list is not known
+     */
+    running(iface) {
+        if (!this.box || !Array.isArray(this.box.interfaces)) {
+            return undefined;
+        }
+
+        const entry = this.box.interfaces.find((info) => info.name === iface);
+        return entry ? entry.running !== false : false;
+    }
+
+    /** Closes the stream; nothing is de-registered, because nothing was registered. */
+    close() {
+        this.closed = true;
+        this.ready = false;
+        if (this.box) {
+            this.box.close();
+            this.box = null;
+        }
+    }
+}
+
+module.exports = {
+    LiteConnection,
+    LITE_INTERFACES,
+    ADDON_TOKEN_FILE,
+    CALLBACK_METHODS,
+    readAddonToken,
+    tierAwareTransport,
+    translateError,
+    isFault,
+    load,
+};

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

@@ -33,6 +33,7 @@
                         <li>VirtualDevices: Heizungsgruppen, in CCU eingebundene Systeme wie Osram Lightify</li>
                         <li>CUxD</li>
                         <li>CCU-Jack: XMLRPC-Schnittstelle des <a href="https://github.com/mdzio/ccu-jack" target="_blank">CCU-Jack</a> Addons (Port konfigurierbar, Standard 2121 bzw. 2122 mit TLS)</li>
+                        <li>Das Portfeld neben jeder Schnittstelle: leer ist der Port der CCU für den Transport (2001/42001 usw., die 3xxxx-Ports auf der CCU selbst); eine Zahl ersetzt ihn, etwa für eine CCU hinter einer Portweiterleitung oder einen Simulator auf einem anderen Port.</li>
                     </ul>
 
                 </li>
@@ -65,6 +66,7 @@ Weiteres unter <a target="_blank" href="https://nodered.org/docs/user-guide/cont
             </ul>
             <ul>
                 <li><b>openccu-lite Port</b>: Nur nötig, wenn der Webserver des Systems nicht auf Port 80 bzw. 443 (TLS) läuft.</li>
+                <li><b>openccu-lite Schnittstellen</b>: Wie die Schnittstellenprozesse auf einem openccu-lite-System erreicht werden. <i>auto</i> (Voreinstellung) geht dort über das <b>lite-rpc</b> des Systems - die Aufrufe über seinen Webport, die Ereignisse aus einem Stream, den dieser Node öffnet; ein Abonnent an den Prozessen für alle Programme auf dem System, die Ereignisse werden nach einer Unterbrechung nachgeliefert, kein eigener Callback-Server und kein eigenes <code>init</code> - und auf einer CCU, RaspberryMatic oder OpenCCU den CCU-Weg. Das Zugangsmerkmal ist das openccu-lite-Token oben, auf dem System selbst das eigene Token von RedMatic, das das System dafür erzeugt; ohne eines wird die direkte Verbindung benutzt, das Log sagt es. <i>CCU</i> behält auch auf openccu-lite die direkte Verbindung mit Rückrufen (CUxD geht immer so; lite-rpc trägt es nicht). Ein Flow aus einer Version vor 4.7.0 wird beim ersten Start auf openccu-lite einmal auf lite-rpc umgestellt - das Log sagt es - und eine hier getroffene Wahl ändert keine spätere Version mehr. Die Nodes sysvar, program, script und poll bleiben auf openccu-lite so oder so ohne Funktion.</li>
             </ul>
             <ul>
                 <li><b>Device data / Re-read device data</b>: Liest die Geräteliste jeder verbundenen Schnittstelle neu ein.
@@ -91,7 +93,7 @@ Weiteres unter <a target="_blank" href="https://nodered.org/docs/user-guide/cont
                     solange die CCU ihr selbst ausgestelltes Zertifikat verwendet.</li>
                     <li>Username: Ein Benutzer der sich an der CCU anmelden darf.</li>
                     <li>Password: Das Passwort des Benutzers. Es wird in den Node-RED-Credentials gespeichert
-                    (verschlüsselt in <code>flows_cred.json</code>), nicht im Flow. Ein Flow aus einer Version vor 4.4.6,
+                    (verschlüsselt in <code>flows_cred.json</code>), nicht im Flow. Ein Flow aus einer Version vor 4.5.0,
                     der es noch im Klartext enthält, wird beim ersten Start übernommen; der nächste Deploy entfernt es aus
                     <code>flows.json</code>.</li>
                 </ul>

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

@@ -18,6 +18,7 @@
                 <li>VirtualDevices: heating groups and systems the CCU integrates, such as Osram Lightify</li>
                 <li>CUxD</li>
                 <li>CCU-Jack: the XML-RPC interface of the <a href="https://github.com/mdzio/ccu-jack" target="_blank">CCU-Jack</a> addon (port configurable, 2121 by default, 2122 with TLS)</li>
+                <li>The port field beside each interface: blank is the CCU's port for the transport (2001/42001 and so on, the 3xxxx ports on the CCU itself); a number replaces it, for a CCU behind port forwarding or a simulator on another port.</li>
             </ul>
         </li>
         <li><b>RPC ping</b> and <b>RPC ping timeout (s)</b>: How often the connection to the interface processes is checked with a ping, and after how many seconds without an answer it subscribes again. Off means no pings and no timeout-triggered re-init for this connection.</li>
@@ -27,6 +28,7 @@
         <li><b>Context Store</b>: The Node-RED context store the states of all devices and variables are kept in. See <a target="_blank" href="https://nodered.org/docs/user-guide/context">Working with context</a> in the Node-RED documentation.</li>
         <li><b>openccu-lite token</b>: Only for <a href="https://github.com/hobbyquaker/openccu-lite" target="_blank">openccu-lite</a>, a CCU firmware without ReGaHSS. Names, rooms and functions come from the system's metadata API there, which needs a token made under <i>Users</i> on the system. When Node-RED runs on the system itself (RedMatic) the field stays empty: the local token is read automatically. The token is kept, like the password, in Node-RED's credentials (encrypted in <code>flows_cred.json</code>, never in the flow, never in an export). A CCU, RaspberryMatic or OpenCCU ignores the field. openccu-lite has no system variables, programs or HM-Script; those nodes stay in the flow and report an error per message.</li>
         <li><b>openccu-lite port</b>: Only needed when the system's web server is not on port 80 (443 with TLS).</li>
+        <li><b>openccu-lite interfaces</b>: How the interface processes are reached on an openccu-lite system. <i>auto</i> (the default) goes through the system's <b>lite-rpc</b> there - the requests over its web port, the events from a stream this node opens, one subscriber at the processes for every program on the system, the events replayed after a break, no callback server and no <code>init</code> of its own - and the CCU way on a CCU, RaspberryMatic or OpenCCU. The credential is the openccu-lite token above, or on the system itself RedMatic's own token, which the system mints for it; without one the direct connection is used and the log says so. <i>CCU</i> keeps the direct connection with callbacks on openccu-lite as well (CUxD always goes that way; lite-rpc does not carry it). A flow from before 4.7.0 is moved to lite-rpc once at its first start on openccu-lite - the log says so - and a choice made here is never changed by a later version. The sysvar, program, script and poll nodes stay unavailable on openccu-lite either way.</li>
         <li><b>Device data / Re-read device data</b>: Reads the device list of every connected interface again. New and changed devices (a channel whose type changed, say) get their datapoints fetched anew, removed ones leave the table. A device the CCU reports with a changed type or version is re-read without the button as well. The button needs a deployed connection.</li>
         <li><b>Authentication</b>: Encryption and login for a CCU on the network (Node-RED not on the CCU). Both belong to the CCU's web server, which fronts the interface processes: on a CCU3 TLS and authentication are switched on in the firewall settings, on openccu-lite under <i>Remote access</i> (classic RPC). When Node-RED runs on the system itself (RedMatic; address <code>localhost</code> / <code>127.0.0.1</code>) the processes are reached directly on the loopback, BidCos over BIN-RPC, without TLS and without a login; these settings are then not used.
             <ul>
@@ -34,7 +36,7 @@
                 <li>TLS/SSL: Transport encryption. The interfaces are reached over the CCU's TLS ports (42000, 42001, 42010, 49292, ReGaHSS 48181, CCU-Jack 2122), openccu-lite's metadata API over 443. BIN-RPC has no TLS: with TLS on, BidCos-RF always goes over XML-RPC.</li>
                 <li>Ignore invalid TLS Certificates: Node-RED accepts an untrusted certificate too. Needed as long as the CCU uses its self-signed certificate.</li>
                 <li>Username: A user allowed to log in to the CCU.</li>
-                <li>Password: The user's password. It is kept in Node-RED's credentials (encrypted in <code>flows_cred.json</code>), not in the flow. A flow from a version before 4.4.6 that still carries it in plain text is taken over at the first start; the next deploy removes it from <code>flows.json</code>.</li>
+                <li>Password: The user's password. It is kept in Node-RED's credentials (encrypted in <code>flows_cred.json</code>), not in the flow. A flow from a version before 4.5.0 that still carries it in plain text is taken over at the first start; the next deploy removes it from <code>flows.json</code>.</li>
             </ul>
             The other direction stays unencrypted: the CCU sends its events to the XML-RPC or BIN-RPC server Node-RED opens for it (<i>Listen Address</i>, <i>BINRPC</i> and <i>XMLRPC listening port</i>) without TLS and without a login - it cannot log in there or verify our certificate. Those ports should be open in the Node-RED host's firewall for the CCU only.</li>
     </ul>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-red-contrib-ccu",
-  "version": "4.6.2",
+  "version": "4.7.0",
   "license": "MIT",
   "main": "none",
   "keywords": [
@@ -53,7 +53,8 @@
     "binrpc": "^4.3.0",
     "homematic-rega": "^2.0.1",
     "homematic-xmlrpc": "^2.0.0",
-    "mqtt-wildcard": "^3.0.9"
+    "mqtt-wildcard": "^3.0.9",
+    "occulite-client": "^0.3.0"
   },
   "deprecated": false,
   "description": "Node-RED Nodes for the Homematic CCU",
@@ -64,7 +65,7 @@
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-html": "^8.2.0",
     "globals": "^16.5.0",
-    "hm-simulator": "^1.3.1",
+    "hm-simulator": "^1.4.0",
     "mocha": "^11.7.1",
     "node-red": "^4.1.0",
     "node-red-node-test-helper": "^0.3.6",