hm-simulator 1.3.2 → 1.4.0

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 All notable changes of hm-simulator. The release workflow takes each version's section from here for the
 GitHub release notes.
 
+## 1.4.0 — 2026-10-03
+
+- `setInstallModeWithWhitelist(on, time, [{ADDRESS, KEY_MODE, KEY}])` on hmipserver, which answered
+  the unknown-method fault: it opens the install mode for the listed SGTINs (Homematic Manager's
+  pairing with the key from the sticker), `on: false` closes it. The scenario call `scriptInclusion`
+  puts an HmIP device in reach of the next install mode: it joins, or - with a whitelist `LOCAL` key
+  that is not its own - is declined, nothing joins and the device stays in reach; `getInclusions`
+  answers every request with its result (`paired`, `declined`, `ignored`), `getInstallWhitelist` the
+  open install mode's list. The simulator's model, not a measurement (Homematic Manager task 88).
+
 ## 1.3.2
 
 - `getParamsetDescription` of an address the interface does not know answers the `unknownInstance`

package/README.md

@@ -122,17 +122,17 @@ that starts with the bytes `Bin` is BIN-RPC, anything else XML-RPC over HTTP.
 
 **Incoming RPC methods.**
 
-|                  |                                                                                                                                                                                                                                                   |
-| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| session          | `init` (register and de-register a logic layer), `ping`, `system.listMethods`, `system.methodHelp`, `system.multicall`                                                                                                                            |
-| devices          | `listDevices`, `getDeviceDescription`, `deleteDevice`, `replaceDevice`, `listReplaceableDevices`, `setInstallMode`, `getInstallMode`, `addDevice` (BidCos only), `getKeyMismatchDevice` (rfd, hmipserver)                                         |
-| paramsets        | `getParamsetDescription`, `getParamset`, `putParamset`, `getValue`, `setValue`, `determineParameter`, `reportValueUsage`                                                                                                                          |
-| links            | `getLinks`, `getLinkPeers`, `getLinkInfo`, `setLinkInfo`, `addLink`, `removeLink`, `activateLinkParamset`                                                                                                                                         |
-| interface        | `rssiInfo`, `listBidcosInterfaces`, `setBidcosInterface`, `getServiceMessages`, `setTempKey` (BidCos only), `changeKey` (rfd, hmipserver), `logLevel`, `getVersion`, `setInterfaceClock` (rfd, hmipserver), `getLGWStatus` (only when configured) |
-| metadata         | `getMetadata`, `setMetadata` (rfd, hs485d, hmipserver), `getAllMetadata` (BidCos only)                                                                                                                                                            |
-| service messages | `suppressServiceMessages`, `getSuppressedServiceMessages` (hmipserver only)                                                                                                                                                                       |
-| teams            | `listTeams`, `setTeam` (BidCos only): the smoke detector teams as rfd keeps them, pseudo devices `*<serial>`                                                                                                                                      |
-| maintenance      | `clearConfigCache`, `restoreConfigToDevice`, `updateFirmware`, `installFirmware`, `refreshDeployedDeviceFirmwareList` (rfd, hmipserver)                                                                                                           |
+|                  |                                                                                                                                                                                                                                                       |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| session          | `init` (register and de-register a logic layer), `ping`, `system.listMethods`, `system.methodHelp`, `system.multicall`                                                                                                                                |
+| devices          | `listDevices`, `getDeviceDescription`, `deleteDevice`, `replaceDevice`, `listReplaceableDevices`, `setInstallMode`, `setInstallModeWithWhitelist` (hmipserver), `getInstallMode`, `addDevice` (BidCos only), `getKeyMismatchDevice` (rfd, hmipserver) |
+| paramsets        | `getParamsetDescription`, `getParamset`, `putParamset`, `getValue`, `setValue`, `determineParameter`, `reportValueUsage`                                                                                                                              |
+| links            | `getLinks`, `getLinkPeers`, `getLinkInfo`, `setLinkInfo`, `addLink`, `removeLink`, `activateLinkParamset`                                                                                                                                             |
+| interface        | `rssiInfo`, `listBidcosInterfaces`, `setBidcosInterface`, `getServiceMessages`, `setTempKey` (BidCos only), `changeKey` (rfd, hmipserver), `logLevel`, `getVersion`, `setInterfaceClock` (rfd, hmipserver), `getLGWStatus` (only when configured)     |
+| metadata         | `getMetadata`, `setMetadata` (rfd, hs485d, hmipserver), `getAllMetadata` (BidCos only)                                                                                                                                                                |
+| service messages | `suppressServiceMessages`, `getSuppressedServiceMessages` (hmipserver only)                                                                                                                                                                           |
+| teams            | `listTeams`, `setTeam` (BidCos only): the smoke detector teams as rfd keeps them, pseudo devices `*<serial>`                                                                                                                                          |
+| maintenance      | `clearConfigCache`, `restoreConfigToDevice`, `updateFirmware`, `installFirmware`, `refreshDeployedDeviceFirmwareList` (rfd, hmipserver)                                                                                                               |
 
 Every write is checked against the paramset description (type, range, `VALUE_LIST`,
 `OPERATIONS`) and answered the way the interface process answers it - see
@@ -246,6 +246,14 @@ sim.getDevice('rfd', 'LAB0000002:1'); // the description, false when unknown
 // a device that holds another system's key: the next install mode hears it (getKeyMismatchDevice
 // names it) until setTempKey('their-key') lets it pair; addDevice('LAB0000009') does the same
 sim.scriptKeyMismatch('rfd', 'LAB0000009', {key: 'their-key', devices: [device, channel0, channel1]});
+// an HmIP device in factory state asks the next install mode to join; with a whitelist whose LOCAL
+// key is not its key it is declined, and stays in reach for the next one
+sim.scriptInclusion('hmip', '3014F711A000000000000088', {
+  key: '00112233445566778899AABBCCDDEEFF',
+  devices: [hmipDevice],
+});
+sim.getInclusions('hmip'); // [{sgtin, result: 'paired' | 'declined' | 'ignored', ts}]
+sim.getInstallWhitelist('hmip'); // the open install mode's [{ADDRESS, KEY_MODE, KEY}], [] without one
 ```
 
 **Values and events**
@@ -649,6 +657,17 @@ knows only its own addresses; `setInterfaceClock` is recorded, not measured (it
 devices get). `addDevice(serial)` pairs only the device of `scriptKeyMismatch`, with the right
 temporary key; any other serial is `unknownInstance`, the mismatch a `notSupported` fault.
 
+`setInstallModeWithWhitelist(on, time, [{ADDRESS, KEY_MODE, KEY}])` (hmipserver only; the others
+answer the unknown-method fault) opens the install mode for the listed SGTINs, as Homematic Manager
+sends it for a device paired with the key from its sticker (`KEY_MODE: 'LOCAL'`, `KEY` the 32 hex
+digits of the QR code), and `on: false` closes it; a list that is not an array of structs with an
+`ADDRESS` is `invalidArguments`. Which devices it admits is the simulator's model, not a
+measurement: a device of `scriptInclusion` joins when it is on the list and the entry's `LOCAL` key
+is its own (or the entry names another key mode, the key server's), is **declined** when the `LOCAL`
+key is another - nothing joins, no RPC client is told, `getInclusions` records it, the device stays
+in reach - and is not admitted (`ignored`) when it is not on the list. Opened with `setInstallMode`,
+the device joins.
+
 ## ReGa mock
 
 `rega: {port: 8181, ...}` starts an HTTP server that answers `POST /<name>.exe` as the CCU's
@@ -760,7 +779,8 @@ there. The flags win over the file:
 arguments. The answer is `{"result": ...}`; a fault is `400` with `faultCode` and `faultString`, an
 unknown call `404`. `GET /ports` answers the ports. The calls: `addDevice`, `removeDevice`,
 `fireEvent`, `fireEvents`, `setValue` (the device reporting a value, as a behaviour script does),
-`setServiceMessage`, `scriptNewDevices`, `scriptKeyMismatch`, `dropConnection`, `stopInterface`, `startInterface`,
+`setServiceMessage`, `scriptNewDevices`, `scriptKeyMismatch`, `scriptInclusion`, `getInclusions`,
+`getInstallWhitelist`, `dropConnection`, `stopInterface`, `startInterface`,
 `restartInterface`, `injectFault`, `clearFaults`, `setReachable`, `setLowBattery`, `setDutyCycle`,
 `setCarrierSense`, `offerFirmware`, `schedule`, `getDevice`, `getWriteLog`, `getConfigPending`,
 `getPoisonedChannels`, `getMissingParamsetDescriptions`, `getCallbackLog`, `getTempKey`,

package/lib/control.js

@@ -15,6 +15,9 @@ const SCENARIO_METHODS = new Set([
     'setServiceMessage',
     'scriptNewDevices',
     'scriptKeyMismatch',
+    'scriptInclusion',
+    'getInclusions',
+    'getInstallWhitelist',
     'dropConnection',
     'stopInterface',
     'startInterface',

package/lib/method-help.js

@@ -40,6 +40,8 @@ module.exports = {
     getServiceMessages: 'array getServiceMessages() - the pending service messages',
     setInstallMode: 'void setInstallMode(boolean on, int time, int mode) - switch the install mode',
     getInstallMode: 'int getInstallMode() - remaining seconds of the install mode',
+    setInstallModeWithWhitelist:
+        'void setInstallModeWithWhitelist(boolean on, int time, array whitelist) - the install mode for [{ADDRESS, KEY_MODE, KEY}] only; HmIP only',
     setTempKey: 'void setTempKey(string passphrase) - the temporary key the next BidCos pairings use; BidCos only',
     listTeams: 'array listTeams() - the team pseudo devices (smoke detector teams) with their channels; BidCos only',
     setTeam:

package/lib/sim.js

@@ -49,6 +49,13 @@ const BIDCOS_INTERFACES = new Set(['rfd', 'wired']);
 const LINK_SENDER_BROKEN = 1;
 
 /** 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);
@@ -285,6 +292,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}}} */
@@ -1190,13 +1203,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 +1264,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 */
 
     /**
@@ -2482,6 +2623,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),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hm-simulator",
-  "version": "1.3.2",
+  "version": "1.4.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

@@ -238,6 +238,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 +374,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 +412,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 */