hm-simulator 1.2.0 → 1.3.1

package/lib/sim.js

@@ -45,6 +45,15 @@ const CALLBACK_LOG_SIZE = 10000;
 /** the interfaces that speak the BidCos protocol, and therefore have setTempKey */
 const BIDCOS_INTERFACES = new Set(['rfd', 'wired']);
 
+/** FLAGS bit of a link whose sender rfd counts as broken (bit 2 is the receiver) */
+const LINK_SENDER_BROKEN = 1;
+
+/** The device part of a channel address: `ABC0000001:1` -> `ABC0000001`. */
+function deviceOf(address) {
+    const colon = String(address).indexOf(':');
+    return colon === -1 ? String(address) : String(address).slice(0, colon);
+}
+
 /** device types of the HmIP radio modules, which carry DUTY_CYCLE_LEVEL and CARRIER_SENSE_LEVEL */
 const RADIO_MODULE_TYPES = new Set(['RPI-RF-MOD', 'HmIP-RFUSB', 'HmIP-RFUSB-TK', 'HMIP-CCU3', 'HmIP-CCU3']);
 
@@ -113,6 +122,9 @@ const INTERFACE_DEFAULTS = {
     // rfd answers the empty string instead of an empty array when it has no service message; the
     // real shape, off by default because it breaks every consumer that assumes an array
     serviceMessagesEmptyAsString: false,
+    // answer getServiceMessages with the unknown-method fault, as VirtualDevices, CUxD and
+    // hmipserver were seen to on 3.89.x ("Invalid XML-RPC message"); off by default
+    getServiceMessagesFault: false,
 };
 
 /**
@@ -121,11 +133,15 @@ const INTERFACE_DEFAULTS = {
  */
 const MEASURED_INTERFACE_DEFAULTS = {
     // hmipserver answers ping without a PONG event, see https://github.com/eq-3/occu/issues/42
-    hmip: {configPendingMode: 'hmip', pong: false},
-    rfd: {configPendingMode: 'bidcos'},
-    wired: {configPendingMode: 'bidcos'},
+    hmip: {configPendingMode: 'hmip', pong: false, version: '3.89.11.20260919'},
+    rfd: {configPendingMode: 'bidcos', version: '2.6.0'},
+    // hs485d's getVersion was not measured; rfd's answer stands in
+    wired: {configPendingMode: 'bidcos', version: '2.6.0'},
 };
 
+/** the interfaces with the metadata methods: rfd and hs485d fault on a key that is not set, hmipserver answers '' */
+const METADATA_INTERFACES = new Set(['rfd', 'wired', 'hmip']);
+
 /** what listBidcosInterfaces answers when the `bidcosInterfaces` option does not say otherwise */
 const DEFAULT_BIDCOS_INTERFACES = {
     rfd: [
@@ -265,6 +281,16 @@ class HmSim {
         this.unreachable = {};
         /** what listBidcosInterfaces reports on top of the configured answer: {<iface>: {DUTY_CYCLE, ...}} */
         this.radio = {};
+        /** a device that holds another system's key: {<iface>: {serial, key, devices, delay}}, see scriptKeyMismatch() */
+        this.keyMismatchScript = {};
+        /** the serial getKeyMismatchDevice answers: {<iface>: serial} */
+        this.keyMismatch = {};
+        /** suppressed service messages (hmipserver): {<iface>: Map<channelAddress, Set<parameter>>} */
+        this.suppressed = {};
+        /** metadata per interface and address: {<iface>: {<address>: {<key>: value}}} */
+        this.metadata = structuredClone(options.metadata || {});
+        /** every setInterfaceClock call: [{iface, utc, offset, ts}] */
+        this.interfaceClocks = [];
 
         this.rpcMethods = this.buildRpcMethods();
 
@@ -550,7 +576,8 @@ class HmSim {
         if (!description[datapoint]) {
             throw this.fault('unknownParameter', `${address}/${datapoint}`);
         }
-        return values[datapoint] === undefined ? defaultValue(description[datapoint]) : values[datapoint];
+        const value = values[datapoint] === undefined ? defaultValue(description[datapoint]) : values[datapoint];
+        return this.reportedValue(iface, address, datapoint, value);
     }
 
     /**
@@ -563,7 +590,14 @@ class HmSim {
             throw this.fault('invalidArguments', 'paramset key');
         }
         const {values} = this.storedParamset(iface, address, key);
-        return {...values};
+        if (key !== 'VALUES' || !this.suppressed[iface] || !this.suppressed[iface].has(address)) {
+            return {...values};
+        }
+        const reported = {};
+        for (const [name, value] of Object.entries(values)) {
+            reported[name] = this.reportedValue(iface, address, name, value);
+        }
+        return reported;
     }
 
     /**
@@ -872,14 +906,24 @@ class HmSim {
             links = links.filter((link) => addresses.has(link.SENDER) || addresses.has(link.RECEIVER));
         }
 
-        return links.map((link) => this.linkStruct(iface, link, flags));
+        // rfd (measured, firmware 3.89.11): the list of *all* links carries FLAGS bit 1 (SENDER_BROKEN)
+        // on every device-internal link - a relay's own button on the relay, a dimmer's channel on its
+        // virtual channels - although the link works; asked for one address, the same link comes with
+        // its stored flags, 0. The simulator does the same on rfd, whatever `flags` asks for.
+        const internalBroken = iface === 'rfd' && !address;
+        return links.map((link) => this.linkStruct(iface, link, flags, internalBroken));
+    }
+
+    /** Sender and receiver on one device: `ABC0000001:1` and `ABC0000001:2`, or the same channel. */
+    isInternalLink(link) {
+        return deviceOf(link.SENDER) === deviceOf(link.RECEIVER);
     }
 
-    linkStruct(iface, link, flags) {
+    linkStruct(iface, link, flags, internalBroken = false) {
         const result = {
             SENDER: link.SENDER,
             RECEIVER: link.RECEIVER,
-            FLAGS: link.FLAGS || 0,
+            FLAGS: (link.FLAGS || 0) | (internalBroken && this.isInternalLink(link) ? LINK_SENDER_BROKEN : 0),
             NAME: link.NAME || '',
             DESCRIPTION: link.DESCRIPTION || '',
         };
@@ -1065,6 +1109,9 @@ class HmSim {
      * plus what was raised through the scenario API.
      */
     getServiceMessages(iface) {
+        if (this.interfaceOption(iface, 'getServiceMessagesFault')) {
+            throw this.fault('unknownMethod', `${iface}/getServiceMessages`);
+        }
         const messages = [];
         for (const address of Object.keys(this.values[iface])) {
             const description = this.getParamsetDescription(iface, address, 'VALUES');
@@ -1073,13 +1120,16 @@ class HmSim {
             }
             for (const [name, value] of Object.entries(this.values[iface][address].VALUES || {})) {
                 const parameter = description[name];
-                if (parameter && parameter.FLAGS & SERVICE_FLAG && value) {
+                if (parameter && parameter.FLAGS & SERVICE_FLAG && value && !this.isSuppressed(iface, address, name)) {
                     messages.push([address, name, value]);
                 }
             }
         }
 
         for (const message of this.serviceMessages[iface] || []) {
+            if (this.isSuppressed(iface, message[0], message[1])) {
+                continue;
+            }
             if (!messages.some((entry) => entry[0] === message[0] && entry[1] === message[1])) {
                 messages.push([...message]);
             }
@@ -1115,6 +1165,297 @@ class HmSim {
             this.timer(() => this.addDevices(iface, scripted.devices), scripted.delay);
         }
 
+        const mismatch = this.keyMismatchScript[iface];
+        if (mismatch) {
+            this.timer(() => this.hearKeyMismatchDevice(iface, mismatch), mismatch.delay);
+        }
+
+        return '';
+    }
+
+    /* ------------------------------------------------------------------ key mismatch */
+
+    /**
+     * A device that holds another system's security key comes into reach of the next install mode
+     * (or of an `addDevice` with its serial) - the case of Homematic Manager task 76.
+     *
+     * rfd hears the device but cannot pair it: nothing joins and nobody is told; the serial is only
+     * what `getKeyMismatchDevice` answers. Once the temporary key (`setTempKey`) is the device's
+     * `key`, the next install mode pairs it: `devices` (the description and its channels) join with
+     * `newDevices`, and the script is used up. Without `devices` the device is never paired.
+     *
+     * @param {string} iface
+     * @param {string} serial
+     * @param {object} [script]
+     * @param {string} [script.key=''] the passphrase the device was taught in with
+     * @param {Array} [script.devices=[]] its description and channel descriptions
+     * @param {number} [script.delay=0] milliseconds between the install mode and the device being heard
+     */
+    scriptKeyMismatch(iface, serial, {key = '', devices = [], delay = 0} = {}) {
+        if (typeof serial !== 'string' || serial === '') {
+            throw new TypeError('scriptKeyMismatch wants a serial');
+        }
+        this.keyMismatchScript[iface] = {serial, key: String(key), devices: devices || [], delay};
+    }
+
+    /** The scripted device is heard: paired when the temporary key is its own, else a key mismatch. */
+    hearKeyMismatchDevice(iface, script) {
+        if (this.keyMismatchScript[iface] !== script) {
+            return undefined;
+        }
+        if (script.key !== '' && this.getTempKey(iface) === script.key && script.devices.length > 0) {
+            delete this.keyMismatchScript[iface];
+            this.addDevices(iface, script.devices);
+            this.log.info(iface, script.serial, 'paired with the temporary key');
+            return this.index[iface].get(script.devices[0].ADDRESS) || script.devices[0];
+        }
+        this.keyMismatch[iface] = script.serial;
+        this.log.info(iface, script.serial, 'heard, but it holds another key');
+        return undefined;
+    }
+
+    /**
+     * `getKeyMismatchDevice(reset)` - the serial of the last device that could not be paired
+     * because it holds another key, `''` when there is none (measured on rfd and hmipserver,
+     * firmware 3.89.11). `true` clears it after the answer.
+     */
+    getKeyMismatchDevice(iface, params) {
+        if (iface !== 'rfd' && iface !== 'hmip') {
+            throw this.fault('unknownMethod', `${iface}/getKeyMismatchDevice`);
+        }
+        const [reset = false] = params || [];
+        const serial = this.keyMismatch[iface] || '';
+        if (reset) {
+            delete this.keyMismatch[iface];
+        }
+        return serial;
+    }
+
+    /**
+     * `addDevice(serial)` - rfd pairs one device by its serial. The simulator knows only the device
+     * of scriptKeyMismatch(): with the right temporary key it joins and its description is the
+     * answer; otherwise it is the key mismatch and the call faults. Any other serial is not in reach
+     * (`unknownInstance`). BidCos only.
+     */
+    addDeviceBySerial(iface, params) {
+        if (!BIDCOS_INTERFACES.has(iface)) {
+            throw this.fault('unknownMethod', `${iface}/addDevice`);
+        }
+        const [serial] = params || [];
+        const script = this.keyMismatchScript[iface];
+        if (!script || script.serial !== serial) {
+            throw this.fault('unknownInstance', `${iface}/${serial}`);
+        }
+        const paired = this.hearKeyMismatchDevice(iface, script);
+        if (!paired) {
+            throw this.fault('notSupported', `${serial} holds another key`);
+        }
+        return paired;
+    }
+
+    /* ------------------------------------------------------------------ service message suppression */
+
+    /**
+     * `suppressServiceMessages(channelAddress, parameter, suppress)` - hmipserver only (eQ-3's HmIP
+     * addendum; rfd does not have it). `parameter` is one of the channel's service parameters, or
+     * `''` for all of them; a parameter without the service flag is ignored. Measured on firmware
+     * 3.89.11: answered with an empty value, `''` suppressed every service parameter of the
+     * channel, `LEVEL` nothing. A suppressed message is left out of `getServiceMessages`, and the
+     * datapoint reports the value that raises no message (`false`, `0`) - the addendum's words; that
+     * a change of the suppression sends that value as an event is the simulator's model.
+     */
+    suppressServiceMessages(iface, params) {
+        if (iface !== 'hmip') {
+            throw this.fault('unknownMethod', `${iface}/suppressServiceMessages`);
+        }
+        const [address, parameter = '', suppress = true] = params || [];
+        if (typeof address !== 'string' || typeof parameter !== 'string') {
+            throw this.fault('invalidArguments', 'suppressServiceMessages wants a channel address and a parameter');
+        }
+        const description = this.getParamsetDescription(iface, address, 'VALUES') || {};
+        const names = Object.keys(description).filter(
+            (name) => description[name].FLAGS & SERVICE_FLAG && (parameter === '' || parameter === name),
+        );
+        const table = (this.suppressed[iface] = this.suppressed[iface] || new Map());
+        const set = table.get(address) || new Set();
+        for (const name of names) {
+            const before = this.reportedValue(iface, address, name);
+            if (suppress) {
+                set.add(name);
+            } else {
+                set.delete(name);
+            }
+            table.set(address, set);
+            const after = this.reportedValue(iface, address, name);
+            if (before !== after && description[name].OPERATIONS & 4) {
+                this.event(iface, [address, name, after]);
+            }
+        }
+        if (set.size === 0) {
+            table.delete(address);
+        }
+        return '';
+    }
+
+    /**
+     * `getSuppressedServiceMessages(channelAddress)` - the suppressed parameters of a channel, sorted;
+     * `[]` for an address hmipserver does not know (measured, firmware 3.89.11). hmipserver only.
+     */
+    getSuppressedServiceMessages(iface, params) {
+        if (iface !== 'hmip') {
+            throw this.fault('unknownMethod', `${iface}/getSuppressedServiceMessages`);
+        }
+        const [address] = params || [];
+        const set = this.suppressed[iface] && this.suppressed[iface].get(address);
+        return set ? [...set].sort() : [];
+    }
+
+    isSuppressed(iface, address, name) {
+        const set = this.suppressed[iface] && this.suppressed[iface].get(address);
+        return Boolean(set && set.has(name));
+    }
+
+    /** The stored value, or for a suppressed service message the value that raises no message. */
+    reportedValue(iface, address, name, value) {
+        const stored =
+            value === undefined
+                ? ((this.values[iface] && this.values[iface][address]) || {VALUES: {}}).VALUES[name]
+                : value;
+        if (!this.isSuppressed(iface, address, name)) {
+            return stored;
+        }
+        return typeof stored === 'boolean' || stored === undefined ? false : 0;
+    }
+
+    /* ------------------------------------------------------------------ metadata */
+
+    requireMetadataInterface(iface, method) {
+        if (!METADATA_INTERFACES.has(iface)) {
+            throw this.fault('unknownMethod', `${iface}/${method}`);
+        }
+    }
+
+    /**
+     * `getMetadata(address, key)` - a value stored with `setMetadata` or the `metadata` option. A key
+     * that is not set: hmipserver answers an empty value, rfd the fault `-1 Failure` - also for an
+     * address it does not know (measured, firmware 3.89.11). rfd, hs485d and hmipserver.
+     */
+    getMetadata(iface, params) {
+        this.requireMetadataInterface(iface, 'getMetadata');
+        const [address, key] = params || [];
+        const stored = this.metadata[iface] && this.metadata[iface][address];
+        if (stored && Object.hasOwn(stored, key)) {
+            return stored[key];
+        }
+        if (iface === 'hmip') {
+            return '';
+        }
+        throw this.fault('notSupported', `no metadata ${key} on ${address}`);
+    }
+
+    /**
+     * `setMetadata(address, key, value)` - stores a value. rfd and hs485d know only their own
+     * addresses (`unknownInstance`); hmipserver takes any (the simulator's model).
+     */
+    setMetadata(iface, params) {
+        this.requireMetadataInterface(iface, 'setMetadata');
+        const [address, key, value] = params || [];
+        if (typeof address !== 'string' || typeof key !== 'string' || key === '') {
+            throw this.fault('invalidArguments', 'setMetadata wants an address and a key');
+        }
+        if (iface !== 'hmip') {
+            this.requireDevice(iface, address);
+        }
+        this.metadata[iface] = this.metadata[iface] || {};
+        this.metadata[iface][address] = this.metadata[iface][address] || {};
+        this.metadata[iface][address][key] = value;
+        return '';
+    }
+
+    /**
+     * `getAllMetadata(address)` - every key of an address. rfd and hs485d only (hmipserver does not
+     * list it); nothing stored is the fault `-1 Failure`, as measured on rfd.
+     */
+    getAllMetadata(iface, params) {
+        if (!BIDCOS_INTERFACES.has(iface)) {
+            throw this.fault('unknownMethod', `${iface}/getAllMetadata`);
+        }
+        const [address] = params || [];
+        const stored = this.metadata[iface] && this.metadata[iface][address];
+        if (!stored || Object.keys(stored).length === 0) {
+            throw this.fault('notSupported', `no metadata on ${address}`);
+        }
+        return {...stored};
+    }
+
+    /* ------------------------------------------------------------------ interface information */
+
+    /**
+     * `listReplaceableDevices(address)` - the devices a device can take the place of. rfd: the other
+     * devices of the same `TYPE` that are unreachable (`setReachable(iface, address, false)`) - a
+     * device that still answers is not replaced (the simulator's model, after what the CCU's WebUI
+     * offers; measured: `[]` for rfd's own `BidCoS-RF`, `-2 Unknown instance` for an address it does
+     * not know). hmipserver answers with an empty HTTP body whatever it is asked (measured, firmware
+     * 3.89.11), which the simulator answers as `''`.
+     */
+    listReplaceableDevices(iface, params) {
+        const [address] = params || [];
+        if (iface === 'hmip') {
+            return '';
+        }
+        if (!BIDCOS_INTERFACES.has(iface)) {
+            throw this.fault('unknownMethod', `${iface}/listReplaceableDevices`);
+        }
+        const device = this.requireDevice(iface, address);
+        if (device.PARENT) {
+            return [];
+        }
+        const unreachable = this.unreachable[iface] || new Set();
+        return this.deviceList(iface).filter(
+            (entry) => entry.TYPE === device.TYPE && entry.ADDRESS !== address && unreachable.has(entry.ADDRESS),
+        );
+    }
+
+    /**
+     * `getVersion()` - the version string of the interface process: `interfaces.<iface>.version`,
+     * by default what rfd (`2.6.0`) and hmipserver (the firmware, `3.89.11.20260919`) answered on
+     * firmware 3.89.11. VirtualDevices and CUxD: unknown-method.
+     */
+    getVersion(iface) {
+        const version = this.interfaceOption(iface, 'version');
+        if (version === undefined) {
+            throw this.fault('unknownMethod', `${iface}/getVersion`);
+        }
+        return version;
+    }
+
+    /**
+     * `getLGWStatus()` - rfd on firmware 3.89.11 answers `unknown method name`, measured on two
+     * systems; `interfaces.rfd.lgwStatus` makes it answer that value instead, for a client that
+     * shows it. BidCos only.
+     */
+    getLGWStatus(iface) {
+        const status = BIDCOS_INTERFACES.has(iface) ? this.interfaceOption(iface, 'lgwStatus') : undefined;
+        if (status === undefined) {
+            throw this.fault('unknownMethod', `${iface}/getLGWStatus`);
+        }
+        return status;
+    }
+
+    /**
+     * `setInterfaceClock(utcSeconds, offsetMinutes)` - rfd and hmipserver set the clock they send the
+     * devices. Recorded in `sim.interfaceClocks` (`{iface, utc, offset, ts}`) and answered with an
+     * empty string (the simulator's model; not measured - it changes the system's clock).
+     */
+    setInterfaceClock(iface, params) {
+        if (iface !== 'rfd' && iface !== 'hmip') {
+            throw this.fault('unknownMethod', `${iface}/setInterfaceClock`);
+        }
+        const [utc, offset = 0] = params || [];
+        if (!Number.isFinite(Number(utc))) {
+            throw this.fault('invalidArguments', 'setInterfaceClock wants the UTC seconds');
+        }
+        this.interfaceClocks.push({iface, utc: Number(utc), offset: Number(offset), ts: Date.now()});
         return '';
     }
 
@@ -1365,6 +1706,12 @@ class HmSim {
             if (this.poisonedChannels[iface]) {
                 this.poisonedChannels[iface].delete(entry);
             }
+            if (this.suppressed[iface]) {
+                this.suppressed[iface].delete(entry);
+            }
+            if (this.metadata[iface]) {
+                delete this.metadata[iface][entry];
+            }
         }
         if (this.configPending[iface]) {
             this.configPending[iface].delete(address);
@@ -1413,7 +1760,7 @@ class HmSim {
         }
 
         this.deleteDevice(iface, oldAddress);
-        return '';
+        return true;
     }
 
     reportValueUsage(iface, params) {
@@ -2111,6 +2458,17 @@ class HmSim {
             logLevel: (iface, params) => this.logLevel(iface, params),
             changeKey: (iface, params) => this.changeKey(iface, params),
             refreshDeployedDeviceFirmwareList: (iface) => this.refreshDeployedDeviceFirmwareList(iface),
+            getKeyMismatchDevice: (iface, params) => this.getKeyMismatchDevice(iface, params),
+            addDevice: (iface, params) => this.addDeviceBySerial(iface, params),
+            suppressServiceMessages: (iface, params) => this.suppressServiceMessages(iface, params),
+            getSuppressedServiceMessages: (iface, params) => this.getSuppressedServiceMessages(iface, params),
+            getMetadata: (iface, params) => this.getMetadata(iface, params),
+            setMetadata: (iface, params) => this.setMetadata(iface, params),
+            getAllMetadata: (iface, params) => this.getAllMetadata(iface, params),
+            listReplaceableDevices: (iface, params) => this.listReplaceableDevices(iface, params),
+            getVersion: (iface) => this.getVersion(iface),
+            getLGWStatus: (iface) => this.getLGWStatus(iface),
+            setInterfaceClock: (iface, params) => this.setInterfaceClock(iface, params),
         };
 
         // the CCU accepts the lower case spelling as well
@@ -2580,7 +2938,11 @@ class HmSim {
             const events =
                 parameter.TYPE === 'ACTION'
                     ? [[address, datapoint, casted]]
-                    : Object.keys(state.VALUES).map((name) => [address, name, state.VALUES[name]]);
+                    : Object.keys(state.VALUES).map((name) => [
+                          address,
+                          name,
+                          this.reportedValue(iface, address, name, state.VALUES[name]),
+                      ]);
             this.eventMulticall(iface, events);
         }
     }

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "hm-simulator",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "Simulates a Homematic CCU (rfd, hmipserver, VirtualDevices, CUxD, ReGa) for automated tests",
   "main": "sim.js",
+  "types": "./sim.d.ts",
   "preferGlobal": true,
   "bin": {
     "hm-simulator": "./index.js"
@@ -13,9 +14,10 @@
   "scripts": {
     "lint": "eslint . && prettier --check .",
     "format": "prettier --write . && eslint --fix .",
-    "test": "node --test test/*.test.js",
+    "test": "node --test test/*.test.js && npm run test:types",
     "test:watch": "node --test --watch test/*.test.js",
-    "fixtures": "node tools/fixtures-from-paramsets.js"
+    "fixtures": "node tools/fixtures-from-paramsets.js",
+    "test:types": "tsc -p test/types"
   },
   "repository": {
     "type": "git",
@@ -44,6 +46,8 @@
     "index.js",
     "sim.js",
     "sim.mjs",
+    "sim.d.ts",
+    "sim.d.mts",
     "lib/",
     "data/",
     "behaviors/",
@@ -57,9 +61,11 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.39.5",
+    "@types/node": "^20.19.43",
     "eslint": "^9.39.5",
     "eslint-config-prettier": "^10.1.8",
     "globals": "^16.5.0",
-    "prettier": "^3.9.6"
+    "prettier": "^3.9.6",
+    "typescript": "^5.9.3"
   }
 }

package/sim.d.mts

@@ -0,0 +1,5 @@
+// Type declarations for sim.mjs, the ESM entry point.
+import HmSim from './sim.js';
+
+export default HmSim;
+export {HmSim};