hm2mqtt 3.5.2 → 3.6.1

package/README.md

@@ -259,7 +259,51 @@ the plain format (the second `ccu-mqtt` node of a flow).
 Names come from the ReGa (devices, channels, rooms, functions), are cached in the state
 directory and re-read with `<name>/set/rega/sync`. A `--name-file` overrides single addresses.
 Without the ReGa (`--no-rega`) topics use addresses. Events of channels without a name use the
-address as well.
+address as well. On a box without ReGaHSS they come from the metadata API instead — see
+[openccu-lite](#openccu-lite).
+
+## openccu-lite
+
+[openccu-lite](https://github.com/hobbyquaker/openccu-lite) is a CCU firmware without ReGaHSS.
+hm2mqtt works there without a changed configuration: at start (and again on reconnect) it asks
+`GET http://<ccu-address>/api/meta/v1/version`, and when that answers it takes device and channel
+names, rooms and functions from the box's **metadata API** instead of from the ReGa. A CCU3,
+RaspberryMatic or OpenCCU answers 404 there and everything stays exactly as before — the same
+configuration works on both, which is what a backup restored on the other kind of box needs.
+
+Names arrive as a snapshot at start and then over the box's event stream (`/api/meta/v1/events/sse`):
+a rename in the box's UI is in the topics about a second later, without a poll and without a
+restart. The store is cached in `meta.json` in the state directory, so a start without the box
+still has the names. `<name>/set/rega/sync` re-reads the snapshot here too.
+
+**The credential.** Everything but the version call needs one:
+
+| where hm2mqtt runs | credential                                                                                            |
+| ------------------ | ----------------------------------------------------------------------------------------------------- |
+| on the box (addon) | the box's own read-only token, read from `/usr/local/etc/occulite/local-token` — nothing to configure |
+| anywhere else      | `--meta-token` (`HM2MQTT_META_TOKEN`): an API token (`olt_…`) created on the box under _Benutzer_     |
+
+Without a valid credential hm2mqtt logs one line and runs on addresses; it picks the names up as
+soon as a token works, without a restart. `--meta-url` overrides the base url when the box is
+behind a proxy or on another port. Note that openccu-lite's interface processes listen on loopback
+only, so hm2mqtt normally runs **on** the box (addon package) or goes through its XML-RPC proxy.
+
+**What has no replacement** on such a box (from openccu-lite's `docs/porting-from-rega.md`):
+
+- **System variables** and **programs**: there is no ReGa DOM. Users who need them run automation
+  in Node-RED (RedMatic), Home Assistant, or whatever the addon is bridging to.
+- **`exec()`** of HM-Script, `dom.GetObject`, `system.GetSessionVarStr` from your own code: gone.
+- **ReGa ids** (`dom.GetObject(1234)`): there are none. Refs (`<interface>.<address>`) are the identity.
+- **Service messages / alarms** (variables 40 and 41): interface-level state only.
+- **The CCU WebUI's JSON-RPC API** (`/api/homematic.cgi`, `Session.login`, `Device.listAll`,
+  `Interface.*`): not present.
+
+In hm2mqtt that means: no `status/<variable>` and `status/<program>` topics and no writes to them,
+and no `--publish-cache` (the value cache was ReGa's `getValues`). `--rega-poll-interval`,
+`--rega-poll-trigger` and the `--topic-sysvar-*`/`--topic-program-*` templates stay accepted so one
+configuration serves both kinds of box; on openccu-lite they do nothing and one log line at start
+says so. Rooms and functions are trees there — a channel in `room/eg/wohnzimmer` is reported as
+`Wohnzimmer`, the parent nodes are not added, so `hm.rooms` looks exactly as it did on a CCU.
 
 ## Home Assistant
 
@@ -328,8 +372,8 @@ Same topics for events, variables, programs, counters, `set` and `paramset`. Dif
 ## Development
 
 `npm test` (node:test, no CCU needed), `npm run lint`. `deploy.sh` ships the package (and
-`file:../` siblings) to a host and restarts the `hm2mqtt@*` units. Plan and decisions:
-[ROADMAP.md](ROADMAP.md); changes: [CHANGELOG.md](CHANGELOG.md).
+`file:../` siblings) to a host and restarts the `hm2mqtt@*` units. Plan and decisions: the
+roadmap, kept outside this repository; changes: [CHANGELOG.md](CHANGELOG.md).
 
 ## License
 

package/config.js

@@ -72,6 +72,16 @@ export const OPTIONS = {
         type: 'string',
         describe: 'channel.datapoint whose event triggers a variable/program poll, e.g. BidCoS-RF:50.PRESS_SHORT',
     },
+    'meta-token': {
+        type: 'string',
+        describe:
+            'openccu-lite API token (olt_...) for names, rooms and functions - not needed on the box itself, where the local token is read',
+        secret: true,
+    },
+    'meta-url': {
+        type: 'string',
+        describe: "base url of openccu-lite's metadata api (default: http[s]://<ccu-address>)",
+    },
     'ccu-timezone': {type: 'string', describe: "IANA time zone of the CCU (default: this host's time zone)"},
     'name-file': {
         alias: 'm',

package/index.js

@@ -20,6 +20,7 @@ import {RpcServers, RpcConnection} from './lib/rpc.js';
 import {Metadata} from './lib/metadata.js';
 import {ValueStore, hmBlock, isEvent} from './lib/values.js';
 import {RegaSync} from './lib/rega.js';
+import {MetaSync, detectMeta} from './lib/meta.js';
 import {castValue, isWriteable} from './lib/cast.js';
 import {
     sanitizeName,
@@ -66,6 +67,8 @@ const SET_THROTTLE_MS = 500;
 const DEVICES_WAIT_MS = 10000;
 const STOP_TIMEOUT_MS = 1500;
 const RESOLVE_RETRY_MS = 10000;
+/** how often an unreachable box is probed for the metadata api again (H-47) */
+const REDETECT_MS = 60000;
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 /** the configured CCU address (the `ccu` field of every payload); connections use the resolved ip */
@@ -186,6 +189,7 @@ const adapter = createAdapter({
         interfaces: enabled,
         devices: metadata.count(),
         rega: Boolean(regaSync),
+        names: regaSync ? regaSync.label : 'addresses',
         payload: payloadFormat,
     }),
     /*
@@ -238,8 +242,20 @@ if (localMode) {
 const metadata = new Metadata({stateDir: config.stateDir, seedFile: path.join(here, 'paramsets.json'), log});
 metadata.load();
 
+/*
+ * Where names, rooms and functions come from (H-46): openccu-lite has no ReGaHSS, but a metadata
+ * api that answers `GET /api/meta/v1/version` and nothing else does. That one call is the whole
+ * detection - no new option, no hostname or port heuristics, so a configuration moved between a
+ * CCU and an openccu-lite box keeps working untouched. Explicit --no-rega still means "addresses
+ * only" on both.
+ */
+const metaUrl = config.metaUrl || `${config.ccuTls ? 'https' : 'http'}://${host}`;
+/** true while the box has not answered the probe at all: something may still come up there */
+let redetect = false;
+let redetectTimer = null;
 let regaSync = null;
-if (config.rega) {
+
+function createRega() {
     const rega = new Rega({
         host: ccuIp,
         port: regaPort({tls: config.ccuTls, local: localMode}),
@@ -249,7 +265,37 @@ if (config.rega) {
         password: config.ccuPassword,
         timeZone: config.ccuTimezone,
     });
-    regaSync = new RegaSync({rega, host, metadata, stateDir: config.stateDir, nameFile, log});
+    return new RegaSync({rega, host, metadata, stateDir: config.stateDir, nameFile, log});
+}
+
+function createMeta() {
+    return new MetaSync({
+        url: metaUrl,
+        token: config.metaToken,
+        insecure: config.ccuInsecure,
+        fixedUrl: Boolean(config.metaUrl),
+        metadata,
+        stateDir: config.stateDir,
+        nameFile,
+        log,
+    });
+}
+
+if (config.rega) {
+    const found = await detectMeta(metaUrl, {insecure: config.ccuInsecure});
+    if (found.ok) {
+        log.info(
+            'openccu-lite on',
+            host + ':',
+            found.version.implementation || 'metadata api v' + found.version.version,
+            '- names, rooms and functions from the metadata api',
+        );
+        regaSync = createMeta();
+    } else {
+        log.debug('no metadata api on', host, '(' + found.reason + ') - using ReGa');
+        redetect = !found.reachable;
+        regaSync = createRega();
+    }
     regaSync.load();
 }
 
@@ -806,56 +852,113 @@ function createConnection(iface) {
  */
 
 async function startRega() {
+    if (regaSync instanceof MetaSync) {
+        // one line, once: everything a ReGa box could do and this one cannot (porting invariant 4).
+        // The options stay accepted so a configuration works on both kinds of box.
+        log.info(
+            'occulite: no ReGaHSS on this box - system variables, programs and the value cache are',
+            'not available; --rega-poll-interval, --rega-poll-trigger, --publish-cache and the',
+            'sysvar/program topics do nothing here',
+        );
+    }
     try {
         await regaSync.syncNames();
     } catch (err) {
         log.warn(
-            'rega: names not available (' + err.message + '), using',
+            regaSync.label + ': names not available (' + err.message + '), using',
             Object.keys(regaSync.channelNames).length,
             'cached names',
         );
     }
-    const duplicates = Object.entries(
-        Object.values(regaSync.channelNames).reduce((acc, name) => ((acc[name] = (acc[name] || 0) + 1), acc), {}),
-    )
-        .filter(([, n]) => n > 1)
-        .map(([name]) => name);
-    if (duplicates.length > 0) {
-        log.warn(
-            'duplicate channel names share a topic:',
-            duplicates.slice(0, 20).join(', '),
-            duplicates.length > 20 ? '…' : '',
+    warnDuplicateNames();
+    attachProvider();
+    regaSync.startPolling(config.regaPollInterval);
+    if (regaSync.rega) {
+        loadCache().catch((err) => log.warn('rega getValues failed:', err.message));
+    }
+    if (config.regaNamesInterval > 0) {
+        timers.push(setInterval(() => resyncNames(), config.regaNamesInterval * 1000));
+    }
+    if (redetect) {
+        // nothing answered the probe at start (the box was down or still booting): ReGa was the
+        // fallback, and an openccu-lite that comes up later must not need a restart of this
+        // service to be recognised
+        redetectTimer = setInterval(
+            () => redetectProvider().catch((err) => log.debug('re-detection failed:', err.message)),
+            REDETECT_MS,
         );
+        timers.push(redetectTimer);
     }
+}
+
+/** The provider's events, wired the same way whichever provider it is. */
+function attachProvider() {
     regaSync.on('names', scheduleIndex);
     regaSync.on('sysvar', publishRega);
     regaSync.on('program', publishRega);
     regaSync.on('polled', () => {
         if (!regaOk) {
             regaOk = true;
-            log.info('rega connected');
+            log.info(regaSync.label + ' connected');
             updateConnected();
         }
     });
     regaSync.on('error', () => {
         if (regaOk) {
             regaOk = false;
-            log.warn('rega disconnected');
+            log.warn(regaSync.label + ' disconnected');
             updateConnected();
         }
     });
-    regaSync.startPolling(config.regaPollInterval);
-    loadCache().catch((err) => log.warn('rega getValues failed:', err.message));
-    if (config.regaNamesInterval > 0) {
-        timers.push(
-            setInterval(
-                () => regaSync.syncNames().catch((err) => log.warn('rega names re-sync failed:', err.message)),
-                config.regaNamesInterval * 1000,
-            ),
+}
+
+function warnDuplicateNames() {
+    const duplicates = Object.entries(
+        Object.values(regaSync.channelNames).reduce((acc, name) => ((acc[name] = (acc[name] || 0) + 1), acc), {}),
+    )
+        .filter(([, n]) => n > 1)
+        .map(([name]) => name);
+    if (duplicates.length > 0) {
+        log.warn(
+            'duplicate channel names share a topic:',
+            duplicates.slice(0, 20).join(', '),
+            duplicates.length > 20 ? '…' : '',
         );
     }
 }
 
+function resyncNames() {
+    return regaSync.syncNames().catch((err) => log.warn(regaSync.label + ' names re-sync failed:', err.message));
+}
+
+/** Probes a box that did not answer at start; switches to the metadata api when it now does. */
+async function redetectProvider() {
+    const found = await detectMeta(metaUrl, {insecure: config.ccuInsecure});
+    if (!found.reachable) {
+        return;
+    }
+    // something answers now - whatever it is, this question is settled
+    redetect = false;
+    if (redetectTimer) {
+        clearInterval(redetectTimer);
+        redetectTimer = null;
+    }
+    if (!found.ok) {
+        log.debug('no metadata api on', host, '(' + found.reason + ') - staying with ReGa');
+        return;
+    }
+    log.info('openccu-lite answered on', host + ': switching from ReGa to the metadata api');
+    const previous = regaSync;
+    previous.stopPolling();
+    previous.removeAllListeners();
+    regaSync = createMeta();
+    regaSync.load();
+    attachProvider();
+    regaOk = false;
+    await resyncNames();
+    scheduleIndex();
+}
+
 /** The ReGa's copy of every datapoint value: seeds the value store, published with --publish-cache. */
 async function loadCache() {
     const list = await regaSync.rega.getValues();
@@ -885,10 +988,12 @@ async function loadCache() {
 async function start() {
     adapter.start();
     ccuIp = await resolveCcu();
-    if (regaSync) {
+    if (regaSync && regaSync.rega) {
         regaSync.rega.host = ccuIp;
         regaSync.rega.url = regaSync.rega.url.replace(host, ccuIp);
         regaSync.rega.webUrl = regaSync.rega.webUrl.replace(host, ccuIp);
+    } else if (regaSync) {
+        regaSync.setHost(ccuIp);
     }
     enabled =
         parseInterfaces(config.interfaces) || (await probeInterfaces(ccuIp, {tls: config.ccuTls, local: localMode}));

package/lib/hadiscovery.js

@@ -635,7 +635,10 @@ function deviceBlock({iface, device, list, ctx, t, st, cmd, bridgeId, ignored})
     }
     const avty = [...availability(name, 2)];
     if (maintenance && maintenance.description.UNREACH && !ignored(iface, maintenance.ADDRESS, 'UNREACH')) {
-        avty.push({t: st(iface, maintenance.ADDRESS, 'UNREACH'), avty_tpl: t.bool('offline', 'online')});
+        // the template of an entry of an availability *list* is `val_tpl`; `avty_tpl` expands to
+        // `availability_template`, which Home Assistant's schema for such an entry does not allow
+        // - and it refuses the whole device payload over it (mqtt-interfaces-core 0.15.2)
+        avty.push({t: st(iface, maintenance.ADDRESS, 'UNREACH'), val_tpl: t.bool('offline', 'online')});
     }
     return {
         id,

package/lib/meta.js

@@ -0,0 +1,724 @@
+/**
+ * The openccu-lite side: device and channel names, rooms and functions from the metadata API of a
+ * box that has no ReGaHSS (`GET /api/meta/v1/...`, served by occulited through lighttpd).
+ *
+ * Same public surface as lib/rega.js's `RegaSync` — `channelName()`, `channelAddress()`,
+ * `rooms()`, `functions()`, `syncNames()`, the `names` event — so index.js and everything below it
+ * cannot tell the two apart and the published payloads do not change. What ReGa had and this box
+ * has not (system variables, programs, HM-Script, the value cache) is empty here: `sysvars` and
+ * `programs` stay `{}` and `hasVariable()`/`hasProgram()` answer false, which is what makes the
+ * variable and program topics silently absent instead of failing.
+ *
+ * The startup call is `/snapshot`; everything after it comes from `/events/sse`, so a rename in the
+ * box's UI arrives within a second without polling. Node 20 has no `EventSource` and the package
+ * takes no new dependency for one: the stream is node:http, which also gives us the socket timeout
+ * (the box sends an SSE heartbeat every 30 s) and `--ccu-insecure` for TLS.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import http from 'node:http';
+import https from 'node:https';
+import {EventEmitter} from 'node:events';
+import {indexNames, resolveAddress} from './names.js';
+
+/** everything the metadata API serves lives below this path */
+export const API_PATH = '/api/meta/v1';
+/** the box's own read-only credential, root-readable, for programs running on it */
+export const LOCAL_TOKEN_FILE = '/usr/local/etc/occulite/local-token';
+
+const DETECT_TIMEOUT_MS = 3000;
+const REQUEST_TIMEOUT_MS = 30000;
+/** the box sends an SSE comment every 30 s; three missed heartbeats are a dead connection */
+const STREAM_IDLE_MS = 95000;
+const RECONNECT_MIN_MS = 2000;
+const RECONNECT_MAX_MS = 300000;
+/** a burst of events (a bulk edit, an import) becomes one snapshot read */
+const COALESCE_MS = 250;
+const MAX_BODY = 64 * 1024 * 1024;
+
+/**
+ * @param {string} url
+ * @param {object} [options]
+ * @returns {Promise<import('node:http').IncomingMessage>}
+ */
+function requestStream(url, {headers = {}, insecure = false, timeout = 0, signal} = {}) {
+    return new Promise((resolve, reject) => {
+        let target;
+        try {
+            target = new URL(url);
+        } catch {
+            reject(new Error(`invalid url: ${url}`));
+            return;
+        }
+        const client = target.protocol === 'https:' ? https : http;
+        const request = client.request(
+            target,
+            {method: 'GET', headers, signal, ...(insecure ? {rejectUnauthorized: false} : {})},
+            resolve,
+        );
+        if (timeout > 0) {
+            request.setTimeout(timeout, () => request.destroy(new Error(`no answer for ${timeout} ms`)));
+        }
+        request.on('error', reject);
+        request.end();
+    });
+}
+
+function readBody(res) {
+    return new Promise((resolve, reject) => {
+        let body = '';
+        res.setEncoding('utf8');
+        res.on('data', (chunk) => {
+            body += chunk;
+            if (body.length > MAX_BODY) {
+                res.destroy(new Error('answer too large'));
+            }
+        });
+        res.on('end', () => resolve(body));
+        res.on('error', reject);
+    });
+}
+
+/** GET a JSON document; a non-200 becomes an Error carrying `status` and the API's error code. */
+async function getJson(url, options = {}) {
+    const res = await requestStream(url, {timeout: REQUEST_TIMEOUT_MS, ...options});
+    const body = await readBody(res);
+    if (res.statusCode !== 200) {
+        let code = '';
+        try {
+            code = JSON.parse(body).error || '';
+        } catch {
+            // a proxy or a CCU answering HTML: the status is all we have
+        }
+        const error = new Error(`${url} answered ${res.statusCode}${code ? ' ' + code : ''}`);
+        error.status = res.statusCode;
+        error.code = code;
+        throw error;
+    }
+    return JSON.parse(body);
+}
+
+/**
+ * Feature detection (the one call that needs no credential): openccu-lite answers the version
+ * document here, a CCU/RaspberryMatic/OpenCCU answers 404 or HTML.
+ * @param {string} baseUrl e.g. `http://ccu`
+ * @returns {Promise<{ok: boolean, reachable: boolean, version?: object, reason?: string}>}
+ */
+export async function detectMeta(baseUrl, {insecure = false, timeout = DETECT_TIMEOUT_MS} = {}) {
+    try {
+        const doc = await getJson(`${baseUrl}${API_PATH}/version`, {insecure, timeout});
+        if (doc && doc.api === 'meta' && Number(doc.version) >= 1) {
+            return {ok: true, reachable: true, version: doc};
+        }
+        return {ok: false, reachable: true, reason: 'not the metadata API'};
+    } catch (error) {
+        // an answer we could not parse still proves that something is listening - that is a CCU,
+        // and re-probing it forever would be pointless; a connection error is not.
+        const reachable = typeof error.status === 'number' || error instanceof SyntaxError;
+        return {ok: false, reachable, reason: error.message};
+    }
+}
+
+/** The box's own token, when we are running on the box. */
+export function readLocalToken(file = LOCAL_TOKEN_FILE) {
+    try {
+        const token = fs.readFileSync(file, 'utf8').trim();
+        return token || undefined;
+    } catch {
+        return undefined;
+    }
+}
+
+/** `<enum>/<id>/<id>` -> the name of the node it points at, for every node of every enum. */
+export function enumLabels(enums) {
+    const labels = new Map();
+    const walk = (nodes, prefix) => {
+        for (const node of nodes || []) {
+            if (!node || typeof node.id !== 'string') {
+                continue;
+            }
+            const nodePath = `${prefix}/${node.id}`;
+            labels.set(nodePath, typeof node.name === 'string' && node.name !== '' ? node.name : node.id);
+            walk(node.children, nodePath);
+        }
+    };
+    for (const [id, def] of Object.entries(enums || {})) {
+        walk(def && def.tree, id);
+    }
+    return labels;
+}
+
+/** The address of a ref: `HmIP-RF.0001D3C99C7D4B:3` -> `0001D3C99C7D4B:3`. */
+export function addressOf(ref) {
+    const dot = typeof ref === 'string' ? ref.indexOf('.') : -1;
+    return dot > 0 ? ref.slice(dot + 1) : '';
+}
+
+/**
+ * The metadata document as hm2mqtt sees it: names by address, and rooms and functions as arrays of
+ * names — the shape ReGa's `getRooms()`/`getFunctions()` produced, so nothing downstream changes.
+ *
+ * Rooms and functions are trees here (`room/eg/wohnzimmer`) and a member of a node is implicitly a
+ * member of its parents. Only the node the object is actually in is named, not its ancestors: that
+ * is what a CCU would have reported, and `${room}` in a topic template must not suddenly become
+ * two levels (H-48).
+ */
+export function deriveNames(objects, enums) {
+    const labels = enumLabels(enums);
+    const channelNames = {};
+    const channelRooms = {};
+    const channelFunctions = {};
+    for (const [ref, object] of Object.entries(objects || {})) {
+        if (!object || typeof object !== 'object') {
+            continue;
+        }
+        const address = addressOf(ref);
+        if (!address) {
+            continue;
+        }
+        if (typeof object.name === 'string' && object.name !== '') {
+            channelNames[address] = object.name;
+        }
+        for (const nodePath of object.enums || []) {
+            const name = labels.get(nodePath);
+            if (!name) {
+                continue;
+            }
+            const target = nodePath.startsWith('room/')
+                ? channelRooms
+                : nodePath.startsWith('function/')
+                  ? channelFunctions
+                  : null;
+            if (!target) {
+                // floor and whatever else the user created: hm2mqtt has no field for them
+                continue;
+            }
+            const list = (target[address] = target[address] || []);
+            if (!list.includes(name)) {
+                list.push(name);
+            }
+        }
+    }
+    return {channelNames, channelRooms, channelFunctions};
+}
+
+export class MetaSync extends EventEmitter {
+    /**
+     * @param {object} o
+     * @param {string} o.url base url of the box, e.g. `http://ccu` (no path)
+     * @param {string} [o.token] API token (`olt_…`) or session id; default: the box's local token
+     * @param {string} [o.tokenFile] where the local token lives
+     * @param {boolean} [o.insecure] accept a self-signed certificate (--ccu-insecure)
+     * @param {boolean} [o.fixedUrl] the url was configured explicitly and must not follow the ccu ip
+     * @param {object} [o.metadata] Metadata (to tell an address from a name on set topics)
+     * @param {string} [o.stateDir]
+     * @param {Object<string, string>} [o.nameFile] {address: name} overriding the box's names
+     * @param {object} o.log
+     */
+    constructor({
+        url,
+        token,
+        tokenFile = LOCAL_TOKEN_FILE,
+        insecure = false,
+        fixedUrl = false,
+        metadata,
+        stateDir,
+        nameFile,
+        log,
+    }) {
+        super();
+        this.label = 'occulite';
+        this.url = String(url || '').replace(/\/+$/, '');
+        this.tokenFile = tokenFile;
+        this.token = token || readLocalToken(tokenFile);
+        this.insecure = insecure;
+        this.fixedUrl = fixedUrl;
+        this.metadata = metadata;
+        this.stateDir = stateDir;
+        this.nameFile = nameFile || {};
+        this.log = log;
+        /** the store as served, kept so a restart without the box still has the names */
+        this.objects = {};
+        this.enums = {};
+        this.revision = 0;
+        this.channelNames = {};
+        this.addresses = {};
+        this.channelRooms = {};
+        this.channelFunctions = {};
+        /** ReGa concepts without a counterpart here; kept so the lookups below stay valid */
+        this.sysvars = {};
+        this.programs = {};
+        this.synced = false;
+        this.stopped = false;
+        this.warnedAuth = false;
+        this.backoff = RECONNECT_MIN_MS;
+        this.streamRes = null;
+        this.streamPending = false;
+        this.streamAbort = null;
+        this.streamTimer = null;
+        this.refreshTimer = null;
+        this.applyTimer = null;
+        this.refreshing = false;
+        this.refreshAgain = false;
+    }
+
+    /*
+     * persistence — same place and purpose as rega.json, one file further so switching a
+     * configuration between a CCU and openccu-lite does not overwrite the other one's cache
+     */
+
+    file() {
+        return this.stateDir ? path.join(this.stateDir, 'meta.json') : null;
+    }
+
+    load() {
+        const file = this.file();
+        if (!file) {
+            return;
+        }
+        try {
+            const data = JSON.parse(fs.readFileSync(file, 'utf8'));
+            this.objects = data.objects || {};
+            this.enums = data.enums || {};
+            this.revision = Number(data.revision) || 0;
+            this.rebuild();
+            this.log.info('loaded', Object.keys(this.channelNames).length, 'names from', file);
+        } catch (err) {
+            if (err.code !== 'ENOENT') {
+                this.log.warn('cannot read', file, '-', err.message);
+            }
+        }
+    }
+
+    save() {
+        const file = this.file();
+        if (!file) {
+            return;
+        }
+        try {
+            fs.mkdirSync(this.stateDir, {recursive: true});
+            fs.writeFileSync(file, JSON.stringify({revision: this.revision, objects: this.objects, enums: this.enums}));
+        } catch (err) {
+            this.log.warn('cannot save', file, '-', err.message);
+        }
+    }
+
+    /*
+     * lookups — the surface index.js calls
+     */
+
+    channelName(address) {
+        return this.channelNames[address];
+    }
+
+    channelAddress(nameOrAddress, devices = false) {
+        return resolveAddress(this, nameOrAddress, devices);
+    }
+
+    rooms(address) {
+        return this.channelRooms[address];
+    }
+
+    functions(address) {
+        return this.channelFunctions[address];
+    }
+
+    hasVariable() {
+        return false;
+    }
+
+    hasProgram() {
+        return false;
+    }
+
+    /*
+     * the box
+     */
+
+    /** The CCU address is resolved once at start (H-20); follow it, unless a url was configured. */
+    setHost(ip) {
+        if (this.fixedUrl || !ip) {
+            return;
+        }
+        try {
+            const url = new URL(this.url);
+            url.hostname = ip;
+            this.url = url.toString().replace(/\/+$/, '');
+        } catch {
+            // an unparsable url stays as it is; the requests below will say so
+        }
+    }
+
+    headers(extra = {}) {
+        return {
+            accept: 'application/json',
+            ...(this.token ? {authorization: `Bearer ${this.token}`} : {}),
+            ...extra,
+        };
+    }
+
+    get(endpoint) {
+        return getJson(`${this.url}${API_PATH}${endpoint}`, {headers: this.headers(), insecure: this.insecure});
+    }
+
+    /*
+     * names, rooms, functions
+     */
+
+    /** Reads the snapshot and follows the change stream. Emits 'names'. */
+    async syncNames() {
+        this.stopped = false;
+        this.startStream();
+        await this.refresh({announce: true});
+    }
+
+    /** ReGa's variable/program poll has no counterpart here; the stream is the update path. */
+    async poll() {
+        this.startStream();
+    }
+
+    startPolling() {
+        this.startStream();
+        return Promise.resolve();
+    }
+
+    stopPolling() {
+        this.stopped = true;
+        for (const timer of [this.streamTimer, this.refreshTimer, this.applyTimer]) {
+            if (timer) {
+                clearTimeout(timer);
+            }
+        }
+        this.streamTimer = this.refreshTimer = this.applyTimer = null;
+        this.closeStream();
+    }
+
+    /** Fetches the snapshot and applies it. Throws once, and retries by itself afterwards. */
+    async refresh({announce = false} = {}) {
+        if (this.refreshTimer) {
+            clearTimeout(this.refreshTimer);
+            this.refreshTimer = null;
+        }
+        // one snapshot at a time: the stream and an event burst both ask for one
+        if (this.refreshing) {
+            this.refreshAgain = true;
+            return;
+        }
+        this.refreshing = true;
+        // scheduled in the finally, where `refreshing` is false again: a failure retries with the
+        // backoff, an event that overtook the snapshot as soon as the burst is over
+        let retry = null;
+        try {
+            let doc;
+            try {
+                doc = await this.get('/snapshot');
+            } catch (err) {
+                if (err.status === 401 || err.status === 403) {
+                    this.denied(err);
+                    return;
+                }
+                retry = this.backoff;
+                throw err;
+            }
+            this.accepted();
+            // events that arrived while the snapshot was in flight are newer than it
+            const overtaken = this.revision > (Number(doc.revision) || 0);
+            const changed = this.applySnapshot(doc);
+            this.save();
+            if (announce || changed) {
+                this.logSummary();
+            }
+            this.emit('names');
+            this.emit('polled');
+            if (overtaken) {
+                this.refreshAgain = true;
+            }
+        } finally {
+            this.refreshing = false;
+            if (this.refreshAgain || retry !== null) {
+                this.refreshAgain = false;
+                this.scheduleRefresh(retry === null ? COALESCE_MS : retry);
+            }
+        }
+    }
+
+    applySnapshot(doc) {
+        this.objects = (doc && doc.objects) || {};
+        this.enums = (doc && doc.enums) || {};
+        this.revision = Number(doc && doc.revision) || 0;
+        this.synced = true;
+        return this.rebuild();
+    }
+
+    /** Derives names, rooms and functions from the store; true when anything changed. */
+    rebuild() {
+        const before = JSON.stringify([this.channelNames, this.channelRooms, this.channelFunctions]);
+        const derived = deriveNames(this.objects, this.enums);
+        this.channelNames = derived.channelNames;
+        this.channelRooms = derived.channelRooms;
+        this.channelFunctions = derived.channelFunctions;
+        this.addresses = indexNames(this.channelNames, this.nameFile);
+        return JSON.stringify([this.channelNames, this.channelRooms, this.channelFunctions]) !== before;
+    }
+
+    logSummary() {
+        const labels = [...enumLabels(this.enums).keys()];
+        this.log.info(
+            'occulite:',
+            Object.keys(this.channelNames).length,
+            'names,',
+            labels.filter((p) => p.startsWith('room/')).length,
+            'rooms,',
+            labels.filter((p) => p.startsWith('function/')).length,
+            'functions (revision ' + this.revision + ')',
+        );
+    }
+
+    scheduleRefresh(delay = this.backoff) {
+        if (this.stopped || this.refreshTimer) {
+            return;
+        }
+        if (this.refreshing) {
+            this.refreshAgain = true;
+            return;
+        }
+        this.refreshTimer = setTimeout(() => {
+            this.refreshTimer = null;
+            this.refresh().catch((err) => this.log.debug('occulite: snapshot failed:', err.message));
+        }, delay);
+    }
+
+    /** Rebuild after object events, coalesced: a bulk edit is one 'names'. */
+    scheduleApply() {
+        if (this.stopped || this.applyTimer) {
+            return;
+        }
+        this.applyTimer = setTimeout(() => {
+            this.applyTimer = null;
+            if (this.rebuild()) {
+                this.save();
+                this.log.debug('occulite: names updated (revision', this.revision + ')');
+                this.emit('names');
+            }
+        }, 50);
+    }
+
+    /*
+     * the change stream
+     */
+
+    startStream() {
+        if (this.stopped || this.streamRes || this.streamPending || !this.url) {
+            return;
+        }
+        if (this.streamTimer) {
+            clearTimeout(this.streamTimer);
+            this.streamTimer = null;
+        }
+        this.streamPending = true;
+        // ?since replays what we missed; without a snapshot there is nothing to replay from
+        const since = this.synced && this.revision > 0 ? `?since=${this.revision}` : '';
+        const controller = new AbortController();
+        this.streamAbort = controller;
+        requestStream(`${this.url}${API_PATH}/events/sse${since}`, {
+            headers: this.headers({accept: 'text/event-stream'}),
+            insecure: this.insecure,
+            timeout: STREAM_IDLE_MS,
+            signal: controller.signal,
+        }).then(
+            (res) => this.onStream(res),
+            (err) => this.onStreamEnd(err),
+        );
+    }
+
+    onStream(res) {
+        this.streamPending = false;
+        if (this.stopped) {
+            res.destroy();
+            return;
+        }
+        if (res.statusCode !== 200) {
+            res.resume();
+            const error = new Error(`event stream answered ${res.statusCode}`);
+            error.status = res.statusCode;
+            if (res.statusCode === 401 || res.statusCode === 403) {
+                this.denied(error);
+            }
+            this.onStreamEnd(error);
+            return;
+        }
+        this.streamRes = res;
+        this.backoff = RECONNECT_MIN_MS;
+        this.accepted();
+        this.log.debug('occulite: event stream open');
+        this.emit('polled');
+        if (!this.synced) {
+            // the stream is up before the first snapshot: fetch it, unless syncNames() already is
+            this.scheduleRefresh(0);
+        }
+        let buffer = '';
+        res.setEncoding('utf8');
+        res.on('data', (chunk) => {
+            buffer += chunk;
+            let index;
+            while ((index = buffer.search(/\r?\n\r?\n/)) !== -1) {
+                const [separator] = buffer.slice(index).match(/^\r?\n\r?\n/);
+                const frame = buffer.slice(0, index);
+                buffer = buffer.slice(index + separator.length);
+                this.onFrame(frame);
+            }
+            if (buffer.length > MAX_BODY) {
+                buffer = '';
+            }
+        });
+        const end = (err) => {
+            if (this.streamRes === res) {
+                this.streamRes = null;
+                this.onStreamEnd(err);
+            }
+        };
+        res.on('end', () => end(null));
+        res.on('close', () => end(null));
+        res.on('error', end);
+    }
+
+    onStreamEnd(err) {
+        this.streamPending = false;
+        this.streamRes = null;
+        this.streamAbort = null;
+        if (this.stopped) {
+            return;
+        }
+        this.log.debug('occulite: event stream closed', err ? '(' + err.message + ')' : '');
+        this.emitError(err || new Error('event stream closed'));
+        if (this.streamTimer) {
+            return;
+        }
+        this.streamTimer = setTimeout(() => {
+            this.streamTimer = null;
+            this.startStream();
+        }, this.backoff);
+        this.backoff = Math.min(this.backoff * 2, RECONNECT_MAX_MS);
+    }
+
+    closeStream() {
+        if (this.streamAbort) {
+            this.streamAbort.abort();
+            this.streamAbort = null;
+        }
+        if (this.streamRes) {
+            this.streamRes.destroy();
+            this.streamRes = null;
+        }
+        this.streamPending = false;
+    }
+
+    /** One SSE frame: the `data:` lines are the event, a comment (heartbeat) has none. */
+    onFrame(frame) {
+        const data = frame
+            .split(/\r?\n/)
+            .filter((line) => line.startsWith('data:'))
+            .map((line) => line.slice(5).replace(/^ /, ''))
+            .join('\n');
+        if (data === '') {
+            return;
+        }
+        let event;
+        try {
+            event = JSON.parse(data);
+        } catch {
+            this.log.debug('occulite: unparsable event', data.slice(0, 200));
+            return;
+        }
+        this.onEvent(event);
+    }
+
+    onEvent(event) {
+        if (!event || typeof event !== 'object') {
+            return;
+        }
+        if (event.kind === 'resync') {
+            this.log.debug('occulite: resync requested by the box');
+            this.revision = Number(event.revision) || this.revision;
+            this.scheduleRefresh(0);
+            return;
+        }
+        const revision = Number(event.revision);
+        if (Number.isFinite(revision)) {
+            if (this.synced && this.revision > 0 && revision > this.revision + 1) {
+                this.log.debug('occulite: revision gap', this.revision, '->', revision);
+                this.revision = revision;
+                this.scheduleRefresh(0);
+                return;
+            }
+            this.revision = revision;
+        }
+        switch (event.kind) {
+            case 'object.updated':
+                if (event.ref && event.value) {
+                    this.objects[event.ref] = event.value;
+                    this.scheduleApply();
+                }
+                break;
+            case 'object.deleted':
+                if (event.ref) {
+                    delete this.objects[event.ref];
+                    this.scheduleApply();
+                }
+                break;
+            default:
+                // enum.*, node.* and import change the names of rooms or the paths of their
+                // members: the snapshot is the cheapest correct answer
+                this.scheduleRefresh(COALESCE_MS);
+        }
+    }
+
+    /*
+     * the credential
+     */
+
+    /** 'error' on an EventEmitter with no listener throws; the stream may start before index.js listens */
+    emitError(err) {
+        if (this.listenerCount('error') > 0) {
+            this.emit('error', err);
+        }
+    }
+
+    denied(err) {
+        this.emitError(err);
+        if (this.warnedAuth) {
+            return;
+        }
+        this.warnedAuth = true;
+        this.log.warn(
+            `occulite: the metadata API rejected the credential (${err.status}) - running without names, rooms and functions;`,
+            this.token
+                ? 'the token was revoked or belongs to another box - create a new one on the box under Benutzer and set --meta-token'
+                : `no token configured and none in ${this.tokenFile} - create an API token on the box under Benutzer and set --meta-token`,
+        );
+    }
+
+    accepted() {
+        if (this.warnedAuth) {
+            this.warnedAuth = false;
+            this.log.info('occulite: the metadata API accepts the credential again');
+        }
+    }
+
+    /*
+     * what this box does not have (kept so a misrouted set says why instead of throwing a TypeError)
+     */
+
+    async setVariable() {
+        throw new Error('system variables are not available on this box (no ReGaHSS)');
+    }
+
+    async programActive() {
+        throw new Error('programs are not available on this box (no ReGaHSS)');
+    }
+
+    async programExecute() {
+        throw new Error('programs are not available on this box (no ReGaHSS)');
+    }
+}

package/lib/names.js

@@ -0,0 +1,49 @@
+/**
+ * What every names provider does with its result, whatever it read it from: apply the name file
+ * on top, index the names for the reverse lookup, and resolve a name or address coming in on a
+ * set topic. Shared by lib/rega.js (ReGaHSS) and lib/meta.js (openccu-lite).
+ */
+
+/**
+ * Overrides the names read from the box with the ones from `--name-file` and returns the reverse
+ * index (name -> address). `channelNames` is mutated, as the providers' own state.
+ * @param {Object<string, string>} channelNames
+ * @param {Object<string, string>} [nameFile]
+ * @returns {Object<string, string>} name -> address
+ */
+export function indexNames(channelNames, nameFile = {}) {
+    for (const [address, name] of Object.entries(nameFile)) {
+        if (typeof name === 'string' && name !== '') {
+            channelNames[address] = name;
+        }
+    }
+    const addresses = {};
+    for (const [address, name] of Object.entries(channelNames)) {
+        // the first address of a duplicate name wins; channels win over devices
+        if (!addresses[name] || (address.includes(':') && !addresses[name].includes(':'))) {
+            addresses[name] = address;
+        }
+    }
+    return addresses;
+}
+
+/**
+ * Address of a channel (or device, with `devices`) by name or address.
+ * @param {{addresses: Object<string, string>, metadata?: object}} provider
+ * @param {string} nameOrAddress
+ * @param {boolean} [devices]
+ */
+export function resolveAddress({addresses, metadata}, nameOrAddress, devices = false) {
+    let address;
+    if (metadata && metadata.findIface(nameOrAddress)) {
+        address = nameOrAddress;
+    } else if (addresses[nameOrAddress]) {
+        address = addresses[nameOrAddress];
+    } else if (!metadata && /^[\w-]+(:\d+)?$/.test(nameOrAddress)) {
+        address = nameOrAddress;
+    }
+    if (!address) {
+        return undefined;
+    }
+    return devices || address.includes(':') ? address : undefined;
+}

package/lib/rega.js

@@ -8,6 +8,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import {EventEmitter} from 'node:events';
 import {castVariable} from './cast.js';
+import {indexNames, resolveAddress} from './names.js';
 
 export class RegaSync extends EventEmitter {
     /**
@@ -29,6 +30,7 @@ export class RegaSync extends EventEmitter {
         this.nameFile = nameFile || {};
         this.log = log;
         this.now = now || Date.now;
+        this.label = 'rega';
         this.channelNames = {};
         this.addresses = {};
         this.regaIdChannel = {};
@@ -88,18 +90,7 @@ export class RegaSync extends EventEmitter {
     }
 
     applyNameFile() {
-        for (const [address, name] of Object.entries(this.nameFile)) {
-            if (typeof name === 'string' && name !== '') {
-                this.channelNames[address] = name;
-            }
-        }
-        this.addresses = {};
-        for (const [address, name] of Object.entries(this.channelNames)) {
-            // the first address of a duplicate name wins; channels win over devices
-            if (!this.addresses[name] || (address.includes(':') && !this.addresses[name].includes(':'))) {
-                this.addresses[name] = address;
-            }
-        }
+        this.addresses = indexNames(this.channelNames, this.nameFile);
     }
 
     /*
@@ -112,18 +103,7 @@ export class RegaSync extends EventEmitter {
 
     /** Address of a channel (or device, with `devices`) by ReGa name or address. */
     channelAddress(nameOrAddress, devices = false) {
-        let address;
-        if (this.metadata && this.metadata.findIface(nameOrAddress)) {
-            address = nameOrAddress;
-        } else if (this.addresses[nameOrAddress]) {
-            address = this.addresses[nameOrAddress];
-        } else if (!this.metadata && /^[\w-]+(:\d+)?$/.test(nameOrAddress)) {
-            address = nameOrAddress;
-        }
-        if (!address) {
-            return undefined;
-        }
-        return devices || address.includes(':') ? address : undefined;
+        return resolveAddress(this, nameOrAddress, devices);
     }
 
     rooms(address) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hm2mqtt",
-  "version": "3.5.2",
+  "version": "3.6.1",
   "description": "Interface between Homematic CCU and MQTT",
   "type": "module",
   "main": "index.js",
@@ -27,7 +27,8 @@
     "test": "node --test",
     "test:watch": "node --test --watch",
     "deploy": "bash deploy.sh",
-    "test:e2e": "HM2MQTT_E2E=1 node --test --test-force-exit test/e2e.test.js"
+    "test:e2e": "HM2MQTT_E2E=1 node --test --test-force-exit test/e2e.test.js",
+    "test:occulite": "node --test --test-force-exit test/occulite.test.js"
   },
   "repository": {
     "type": "git",
@@ -69,7 +70,7 @@
     "binrpc": "^3.3.1",
     "homematic-rega": "^2.0.0",
     "homematic-xmlrpc": "^2.0.0",
-    "mqtt-interfaces-core": "^0.15.1"
+    "mqtt-interfaces-core": "^0.15.2"
   },
   "devDependencies": {
     "@eslint/js": "^9.0.0",