hm-simulator 1.3.2 → 1.5.0

package/lib/sim.js

@@ -48,7 +48,40 @@ 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;
 
+/** data/paramset-ids.json, read on the first getParamsetId of a BidCos interface */
+let bundledParamsetIds;
+
+/**
+ * The paramset ids of a BidCos device type and version from the device files
+ * (`tools/paramset-ids.js`); a version the files lack takes the highest one below it, else the
+ * lowest. `undefined` for a type they do not describe.
+ */
+function bidcosParamsetIds(prefix, type, version) {
+    if (!bundledParamsetIds) {
+        bundledParamsetIds = require('../data/paramset-ids.json');
+    }
+    const versions = (bundledParamsetIds[prefix] || {})[type];
+    if (!versions) {
+        return undefined;
+    }
+    if (versions[String(version)]) {
+        return versions[String(version)];
+    }
+    const known = Object.keys(versions)
+        .map(Number)
+        .sort((a, b) => a - b);
+    const below = known.filter((entry) => entry <= Number(version));
+    return versions[String(below.length > 0 ? below.at(-1) : known[0])];
+}
+
 /** The device part of a channel address: `ABC0000001:1` -> `ABC0000001`. */
+/** An SGTIN or an HmIP device key as the comparisons take it: no dashes or blanks, upper case. */
+function normaliseHex(text) {
+    return String(text || '')
+        .replace(/[\s-]/g, '')
+        .toUpperCase();
+}
+
 function deviceOf(address) {
     const colon = String(address).indexOf(':');
     return colon === -1 ? String(address) : String(address).slice(0, colon);
@@ -66,6 +99,9 @@ const STANDARD_PARAMSETS = new Set(['MASTER', 'VALUES', 'SERVICE']);
 /** FLAGS bit of a datapoint that is a service message (1 visible, 2 internal, 4 transform, 8 service) */
 const SERVICE_FLAG = 8;
 
+/** FLAGS bit of a datapoint that keeps its value until a client acknowledges it (STICKY_UNREACH) */
+const STICKY_FLAG = 16;
+
 /**
  * Per interface behaviour, overridable with the `interfaces` option.
  *
@@ -96,6 +132,10 @@ const SERVICE_FLAG = 8;
  * unreachWrites
  *   what a setValue/putParamset to an unreachable device answers: 'accept' (the default) or
  *   'fault' (notReachable). The simulator's model; not measured yet.
+ * stickyWriteEvents
+ *   whether a client's write to a sticky datapoint (FLAGS & 16: the acknowledgement of
+ *   STICKY_UNREACH) is answered with the channel's events like every other write (true, the
+ *   default), or with none (false): a registered client on rfd 3.89.11 got no event for it.
  * firmwareUpdateDelay
  *   milliseconds per step of a firmware update, see offerFirmware().
  * protocols
@@ -115,6 +155,7 @@ const INTERFACE_DEFAULTS = {
     deliveryTimeout: 10000,
     // device health, see setReachable() and offerFirmware()
     unreachWrites: 'accept',
+    stickyWriteEvents: true,
     firmwareUpdateDelay: 0,
     configPendingMode: 'strict',
     configPendingOnWrite: false,
@@ -210,6 +251,10 @@ function shortenParams(params) {
  * @param {boolean} [options.paramsetFallback=true] a device whose firmware has no description uses
  *        the nearest firmware of the same type and VERSION; `false` for exact keys only
  * @param {object} [options.faults] overrides for the fault table, see lib/faults.js
+ * @param {object} [options.paramsets] stored values to start with,
+ *        `{<iface>: {<address>: {<MASTER|VALUES|SERVICE|peer address>: {}}}}`
+ * @param {object} [options.paramsetIds] what `getParamsetId` answers before the bundled ids,
+ *        `{<iface>: {<address>: {<paramset>: id}}}`
  */
 class HmSim {
     constructor(options = {}) {
@@ -226,6 +271,10 @@ class HmSim {
         /** requested key -> the key used for it (a fallback) or null, see resolveParamsetKey() */
         this.paramsetResolved = new Map();
         this.paramsetIndex = new ParamsetIndex(this.paramsetDescriptions);
+        /** stored values a paramset starts with, on top of its defaults: {<iface>: {<address>: {<key>: {}}}} */
+        this.seededParamsets = structuredClone(options.paramsets || {});
+        /** getParamsetId answers given in the options: {<iface>: {<address>: {<paramset>: id}}} */
+        this.paramsetIdOverrides = options.paramsetIds || {};
 
         const {table, fault} = createFaults(options.faults);
         this.faults = table;
@@ -285,6 +334,12 @@ class HmSim {
         this.keyMismatchScript = {};
         /** the serial getKeyMismatchDevice answers: {<iface>: serial} */
         this.keyMismatch = {};
+        /** the whitelist of the open install mode (setInstallModeWithWhitelist): {<iface>: [{ADDRESS, KEY_MODE, KEY}]} */
+        this.installWhitelist = {};
+        /** HmIP devices in reach of the next install mode: {<iface>: Map<sgtin, {sgtin, key, devices, delay}>}, see scriptInclusion() */
+        this.inclusionScripts = {};
+        /** every inclusion request a scripted device made: {<iface>: [{sgtin, result, ts}]}, see getInclusions() */
+        this.inclusions = {};
         /** suppressed service messages (hmipserver): {<iface>: Map<channelAddress, Set<parameter>>} */
         this.suppressed = {};
         /** metadata per interface and address: {<iface>: {<address>: {<key>: value}}} */
@@ -362,6 +417,7 @@ class HmSim {
             this.newDevicesScript[iface] = {delay: 0, ...this.options.newDevices[iface]};
         }
         this.reindex(iface);
+        this.seedValues(iface);
         this.setDefaultValues(iface);
         if (!this.ifaces.includes(iface)) {
             this.ifaces.push(iface);
@@ -376,6 +432,22 @@ class HmSim {
         this.index[iface] = index;
     }
 
+    /** The VALUES of `options.paramsets`, before setDefaultValues fills in the rest. */
+    seedValues(iface) {
+        for (const [address, paramsets] of Object.entries(this.seededParamsets[iface] || {})) {
+            if (paramsets.VALUES && this.index[iface].has(address)) {
+                const state = this.stateOf(iface, address);
+                state.VALUES = {...state.VALUES, ...paramsets.VALUES};
+            }
+        }
+    }
+
+    /** What `options.paramsets` gives a paramset to start with, or `{}`. */
+    seededParamset(iface, address, key) {
+        const paramsets = this.seededParamsets[iface] && this.seededParamsets[iface][address];
+        return (paramsets && paramsets[key]) || {};
+    }
+
     setDefaultValues(iface) {
         for (const device of this.devices[iface].devices) {
             if (!device.PARENT_TYPE || !device.PARAMSETS || !device.PARAMSETS.includes('VALUES')) {
@@ -555,14 +627,17 @@ class HmSim {
             const description = this.requireParamsetDescription(iface, device, 'LINK');
             state.LINKS = state.LINKS || {};
             if (!state.LINKS[paramset]) {
-                state.LINKS[paramset] = defaultParamset(description);
+                state.LINKS[paramset] = {
+                    ...defaultParamset(description),
+                    ...this.seededParamset(iface, address, paramset),
+                };
             }
             return {device, description, values: state.LINKS[paramset]};
         }
 
         const description = this.requireParamsetDescription(iface, device, paramset);
         if (!state[paramset]) {
-            state[paramset] = defaultParamset(description);
+            state[paramset] = {...defaultParamset(description), ...this.seededParamset(iface, address, paramset)};
         }
         return {device, description, values: state[paramset]};
     }
@@ -593,6 +668,56 @@ class HmSim {
         return this.getParamsetDescription(iface, device, paramset);
     }
 
+    /**
+     * The RPC `getParamsetId(address, paramset)`: the CCU's own name of a paramset, by which its WebUI
+     * picks a form (`easymodes/<id>.tcl`). Measured on firmware 3.89.11:
+     *
+     * - hmipserver builds it: the device type, the channel index and the key, lower case and joined
+     *   by `_` - `hmipw-drbl4_2_link`, `hmipw-drbl4_master` for the device - for every key it is
+     *   given, a peer address too (`hmipw-dri16_1_00000000000102:1`), `null` for none.
+     * - rfd and hs485d answer the `id` the device file gives the paramset (`cc_tc_ch_wsr_link`,
+     *   `hmw_input_ch_master`; `data/paramset-ids.json`): MASTER for a device address and MASTER,
+     *   VALUES, LINK for a channel; any other key on a channel is taken as a peer address and answers
+     *   the LINK id. A paramset the address does not have is `-3 Unknown paramset`
+     *   (`unknownParamsetDescription`). A device type the bundled ids lack answers `''`.
+     *
+     * An unknown address is `unknownInstance` on all of them. `options.paramsetIds` answers first.
+     * @param {string} iface
+     * @param {Array} params [address, paramset]
+     */
+    getParamsetId(iface, params) {
+        const [address, key] = params || [];
+        const device = this.requireDevice(iface, address);
+        const overrides = this.paramsetIdOverrides[iface] && this.paramsetIdOverrides[iface][address];
+        if (overrides && typeof key === 'string' && overrides[key] !== undefined) {
+            return overrides[key];
+        }
+        const parent = (device.PARENT ? this.index[iface].get(device.PARENT) : device) || {};
+
+        if (!BIDCOS_INTERFACES.has(iface)) {
+            const name = key === undefined || key === null ? 'null' : String(key).toLowerCase();
+            const type = String(parent.TYPE || '').toLowerCase();
+            return device.PARENT ? `${type}_${device.INDEX}_${name}` : `${type}_${name}`;
+        }
+
+        const name = !device.PARENT || ['MASTER', 'VALUES', 'LINK'].includes(key) ? key : 'LINK';
+        const has = Array.isArray(device.PARAMSETS) ? device.PARAMSETS.includes(name) : name === 'MASTER';
+        if (!has || (!device.PARENT && name !== 'MASTER')) {
+            throw this.fault('unknownParamsetDescription', `${address}/${key}`);
+        }
+        const ids = bidcosParamsetIds(PARAMSET_PREFIX[iface], parent.TYPE, parent.VERSION);
+        if (!ids) {
+            return '';
+        }
+        if (!device.PARENT) {
+            return ids.device.MASTER || '';
+        }
+        const channel = ids.channels.find(
+            (entry) => device.INDEX >= entry.index && device.INDEX < entry.index + entry.count,
+        );
+        return (channel && channel[name]) || '';
+    }
+
     getValue(iface, address, datapoint) {
         const {description, values} = this.storedParamset(iface, address, 'VALUES');
         if (!description[datapoint]) {
@@ -1190,13 +1315,55 @@ class HmSim {
      */
     setInstallMode(iface, params) {
         const [on, time = 60, mode = 1] = params || [];
+        delete this.installWhitelist[iface];
         if (!on) {
             this.installMode[iface] = 0;
             return '';
         }
 
-        this.installMode[iface] = Date.now() + Number(time) * 1000;
         this.log.info(iface, 'install mode on for', time, 'seconds, mode', mode);
+        return this.openInstallMode(iface, time);
+    }
+
+    /**
+     * `setInstallModeWithWhitelist(on, time, whitelist)` - hmipserver only. Opens the install mode
+     * for the devices of the whitelist, `[{ADDRESS: <SGTIN>, KEY_MODE, KEY}]`: `KEY_MODE: 'LOCAL'`
+     * with the device key as `KEY` (32 hex digits, as the QR code holds it), any other mode without
+     * one (the key server's key). `on: false` closes the install mode. The simulator's model: a
+     * device of scriptInclusion() that is not on the list is not admitted, one with a `LOCAL` key
+     * that is not its own is declined (nothing joins, getInclusions() records it), any other joins.
+     */
+    setInstallModeWithWhitelist(iface, params) {
+        if (iface !== 'hmip') {
+            throw this.fault('unknownMethod', `${iface}/setInstallModeWithWhitelist`);
+        }
+        const [on, time = 60, whitelist = []] = params || [];
+        if (!on) {
+            delete this.installWhitelist[iface];
+            this.installMode[iface] = 0;
+            return '';
+        }
+        if (
+            !Array.isArray(whitelist) ||
+            !whitelist.every((entry) => entry && typeof entry === 'object' && typeof entry.ADDRESS === 'string')
+        ) {
+            throw this.fault(
+                'invalidArguments',
+                `${iface}/setInstallModeWithWhitelist wants [{ADDRESS, KEY_MODE, KEY}]`,
+            );
+        }
+        this.installWhitelist[iface] = whitelist.map((entry) => ({
+            ADDRESS: normaliseHex(entry.ADDRESS),
+            KEY_MODE: typeof entry.KEY_MODE === 'string' ? entry.KEY_MODE : '',
+            KEY: typeof entry.KEY === 'string' ? entry.KEY : '',
+        }));
+        this.log.info(iface, 'install mode on for', time, 'seconds, whitelist of', whitelist.length);
+        return this.openInstallMode(iface, time);
+    }
+
+    /** The install mode opens: the scripted devices come into reach. */
+    openInstallMode(iface, time) {
+        this.installMode[iface] = Date.now() + Number(time) * 1000;
 
         const scripted = this.newDevicesScript[iface];
         if (scripted) {
@@ -1209,9 +1376,95 @@ class HmSim {
             this.timer(() => this.hearKeyMismatchDevice(iface, mismatch), mismatch.delay);
         }
 
+        for (const script of (this.inclusionScripts[iface] || new Map()).values()) {
+            this.timer(() => this.hearInclusion(iface, script), script.delay);
+        }
+
         return '';
     }
 
+    /* ------------------------------------------------------------------ HmIP inclusion */
+
+    /**
+     * An HmIP device in factory state comes into reach of the next install mode and asks to join
+     * (Homematic Manager task 88). `key` is its device key as the QR code holds it (32 hex digits;
+     * case and dashes do not matter). Opened with setInstallMode, it joins (the key server knows its
+     * key); opened with setInstallModeWithWhitelist, it joins when it is on the list and its entry's
+     * `LOCAL` key is `key` or the entry asks the key server, is declined with another `LOCAL` key,
+     * and is not admitted when it is not on the list. Declined and not admitted, it stays in reach
+     * for the next install mode; joined, `devices` go out with `newDevices` and the script is used
+     * up. Each request is recorded (getInclusions()).
+     *
+     * @param {string} iface
+     * @param {string} sgtin
+     * @param {object} [script]
+     * @param {string} [script.key=''] its device key
+     * @param {Array} [script.devices=[]] its description and channel descriptions
+     * @param {number} [script.delay=0] milliseconds between the install mode and the request
+     */
+    scriptInclusion(iface, sgtin, {key = '', devices = [], delay = 0} = {}) {
+        if (typeof sgtin !== 'string' || sgtin === '') {
+            throw new TypeError('scriptInclusion wants an SGTIN');
+        }
+        if (!this.inclusionScripts[iface]) {
+            this.inclusionScripts[iface] = new Map();
+        }
+        const normalised = normaliseHex(sgtin);
+        this.inclusionScripts[iface].set(normalised, {
+            sgtin: normalised,
+            key: normaliseHex(key),
+            devices: devices || [],
+            delay,
+        });
+    }
+
+    /** The scripted device asks to join: joined, declined for its key, or not admitted. */
+    hearInclusion(iface, script) {
+        const scripts = this.inclusionScripts[iface];
+        if (!scripts || scripts.get(script.sgtin) !== script || this.getInstallMode(iface) === 0) {
+            return;
+        }
+        let result = 'paired';
+        const whitelist = this.installWhitelist[iface];
+        if (whitelist) {
+            const entry = whitelist.find((candidate) => candidate.ADDRESS === script.sgtin);
+            if (!entry) {
+                result = 'ignored';
+            } else if (entry.KEY_MODE === 'LOCAL' && normaliseHex(entry.KEY) !== script.key) {
+                result = 'declined';
+            }
+        }
+        if (!this.inclusions[iface]) {
+            this.inclusions[iface] = [];
+        }
+        this.inclusions[iface].push({sgtin: script.sgtin, result, ts: Date.now()});
+        this.log.info(
+            iface,
+            script.sgtin,
+            result === 'paired'
+                ? 'joined'
+                : result === 'declined'
+                  ? 'declined, the key does not match'
+                  : 'not on the whitelist',
+        );
+        if (result === 'paired') {
+            scripts.delete(script.sgtin);
+            if (script.devices.length > 0) {
+                this.addDevices(iface, script.devices);
+            }
+        }
+    }
+
+    /** Every inclusion request of a scripted device, oldest first: `[{sgtin, result, ts}]`, result `paired`, `declined` or `ignored`. */
+    getInclusions(iface) {
+        return [...(this.inclusions[iface] || [])];
+    }
+
+    /** The whitelist of the open install mode, `[]` when it was opened without one or is closed. */
+    getInstallWhitelist(iface) {
+        return this.getInstallMode(iface) === 0 ? [] : structuredClone(this.installWhitelist[iface] || []);
+    }
+
     /* ------------------------------------------------------------------ key mismatch */
 
     /**
@@ -2465,6 +2718,7 @@ class HmSim {
             },
             getValue: (iface, params) => this.getValue(iface, params[0], params[1]),
             getParamset: (iface, params) => this.getParamset(iface, params[0], params[1]),
+            getParamsetId: (iface, params) => this.getParamsetId(iface, params),
             putParamset: (iface, params) => {
                 this.requireReachable(iface, params[0]);
                 return this.putParamset(iface, params[0], params[1], params[2]);
@@ -2482,6 +2736,7 @@ class HmSim {
             setBidcosInterface: (iface, params) => this.setBidcosInterface(iface, params),
             getServiceMessages: (iface) => this.getServiceMessages(iface),
             setInstallMode: (iface, params) => this.setInstallMode(iface, params),
+            setInstallModeWithWhitelist: (iface, params) => this.setInstallModeWithWhitelist(iface, params),
             getInstallMode: (iface) => this.getInstallMode(iface),
             setTempKey: (iface, params) => this.setTempKey(iface, params),
             listTeams: (iface) => this.listTeams(iface),
@@ -2973,7 +3228,11 @@ class HmSim {
         const state = this.stateOf(iface, address);
         state.VALUES[datapoint] = casted;
 
-        if (parameter.OPERATIONS & 4) {
+        // a client's acknowledgement of a sticky datapoint: the value goes, and with
+        // stickyWriteEvents false nobody is told (a strict write is one that came over RPC)
+        const silent = strict && parameter.FLAGS & STICKY_FLAG && !this.interfaceOption(iface, 'stickyWriteEvents');
+
+        if (parameter.OPERATIONS & 4 && !silent) {
             const events =
                 parameter.TYPE === 'ACTION'
                     ? [[address, datapoint, casted]]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hm-simulator",
-  "version": "1.3.2",
+  "version": "1.5.0",
   "description": "Simulates a Homematic CCU (rfd, hmipserver, VirtualDevices, CUxD, ReGa) for automated tests",
   "main": "sim.js",
   "types": "./sim.d.ts",

package/sim.d.ts

@@ -142,6 +142,8 @@ declare namespace HmSim {
         pingDelay?: number;
         startDelay?: number;
         unreachWrites?: 'accept' | 'fault';
+        /** `false`: a client's write to a sticky datapoint (FLAGS & 16) sends no event, as observed on rfd */
+        stickyWriteEvents?: boolean;
         firmwareUpdateDelay?: number;
         /** what `getVersion` answers */
         version?: string;
@@ -183,6 +185,13 @@ declare namespace HmSim {
         defaultRssi?: number;
         /** `{<iface>: {<address>: {<key>: value}}}`, what `getMetadata` answers before any `setMetadata` */
         metadata?: Record<string, Record<string, Record<string, unknown>>>;
+        /**
+         * `{<iface>: {<address>: {<MASTER|VALUES|SERVICE|peer address>: {<parameter>: value}}}}`: stored
+         * values a paramset starts with, on top of its description's defaults
+         */
+        paramsets?: Record<string, Record<string, Record<string, Record<string, unknown>>>>;
+        /** `{<iface>: {<address>: {<paramset>: id}}}`, what `getParamsetId` answers before the bundled ids */
+        paramsetIds?: Record<string, Record<string, Record<string, string>>>;
         tls?: TlsOption;
         auth?: BasicAuth;
     }
@@ -238,6 +247,31 @@ declare namespace HmSim {
         args?: unknown[];
     }
 
+    /** scriptInclusion(): an HmIP device in reach of the next install mode */
+    interface InclusionScript {
+        /** its device key as the QR code holds it (32 hex digits) */
+        key?: string;
+        /** its description and channel descriptions, paired when it joins */
+        devices?: DeviceDescription[];
+        /** milliseconds between the install mode and its request */
+        delay?: number;
+    }
+
+    /** One inclusion request of a scripted HmIP device. */
+    interface Inclusion {
+        sgtin: string;
+        /** joined; declined because the whitelist's LOCAL key is not its key; not on the whitelist */
+        result: 'paired' | 'declined' | 'ignored';
+        ts: number;
+    }
+
+    /** One entry of setInstallModeWithWhitelist's list, as the simulator keeps it. */
+    interface WhitelistEntry {
+        ADDRESS: string;
+        KEY_MODE: string;
+        KEY: string;
+    }
+
     interface KeyMismatchScript {
         /** the passphrase the device was taught in with */
         key?: string;
@@ -349,6 +383,12 @@ declare class HmSim {
     keyMismatch: Record<string, string>;
     /** what scriptKeyMismatch() set up and did not pair yet */
     keyMismatchScript: Record<string, Required<HmSim.KeyMismatchScript> & {serial: string}>;
+    /** the whitelist the install mode was last opened with (setInstallModeWithWhitelist), per interface */
+    installWhitelist: Record<string, HmSim.WhitelistEntry[]>;
+    /** the HmIP devices scriptInclusion() put in reach and that did not join yet, per interface and SGTIN */
+    inclusionScripts: Record<string, Map<string, Required<HmSim.InclusionScript> & {sgtin: string}>>;
+    /** every inclusion request of a scripted device, per interface */
+    inclusions: Record<string, HmSim.Inclusion[]>;
     /** the temporary key per interface, as setTempKey left it */
     tempKey: Record<string, string>;
     /** the log level per interface, as logLevel set it */
@@ -381,6 +421,12 @@ declare class HmSim {
     scriptNewDevices(iface: string, devices: HmSim.DeviceDescription[], delay?: number): void;
     /** A device that holds another system's key: heard at the next install mode, paired with its key. */
     scriptKeyMismatch(iface: string, serial: string, script?: HmSim.KeyMismatchScript): void;
+    /** An HmIP device in reach of the next install mode: joins, or is declined for a whitelist key that is not its own. */
+    scriptInclusion(iface: string, sgtin: string, script?: HmSim.InclusionScript): void;
+    /** Every inclusion request of a scripted device, oldest first. */
+    getInclusions(iface: string): HmSim.Inclusion[];
+    /** The whitelist of the open install mode, `[]` without one. */
+    getInstallWhitelist(iface: string): HmSim.WhitelistEntry[];
 
     /* ---------------------------------------------------------------- scenario api: values and events */
 
@@ -463,6 +509,8 @@ declare class HmSim {
     ): void;
     getLinks(iface: string, params?: unknown[]): Array<HmSim.Link & Record<string, unknown>>;
     getLinkPeers(iface: string, params: unknown[]): string[];
+    /** `getParamsetId(address, paramset)`: hmipserver's built id, or the BidCos device file's */
+    getParamsetId(iface: string, params: [address: string, paramset?: string]): string;
     deleteDevice(iface: string, address: string, flags?: number): '';
     replaceDevice(iface: string, oldAddress: string, newAddress: string): true;
     getKeyMismatchDevice(iface: string, params?: [reset?: boolean]): string;