hm-simulator 1.4.0 → 1.5.0

package/lib/sim.js

@@ -48,6 +48,32 @@ 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) {
@@ -73,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.
  *
@@ -103,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
@@ -122,6 +155,7 @@ const INTERFACE_DEFAULTS = {
     deliveryTimeout: 10000,
     // device health, see setReachable() and offerFirmware()
     unreachWrites: 'accept',
+    stickyWriteEvents: true,
     firmwareUpdateDelay: 0,
     configPendingMode: 'strict',
     configPendingOnWrite: false,
@@ -217,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 = {}) {
@@ -233,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;
@@ -375,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);
@@ -389,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')) {
@@ -568,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]};
     }
@@ -606,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]) {
@@ -2606,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]);
@@ -3115,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.4.0",
+  "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;
     }
@@ -500,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;