hm-simulator 1.3.1 → 1.4.0

package/CHANGELOG.md

@@ -3,6 +3,30 @@
 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`
+  fault - `-2 Invalid device` under hmipserver's default table, `-2 Unknown instance` under rfd's -
+  as both interface processes do on 3.89.11; it answered `''`. A paramset the channel does not list
+  answers the new table entry `unknownParamsetDescription` (`-3 Unknown Paramset` / `-3 Unknown
+paramset`, measured); a paramset the channel has but the description set lacks still answers `''`
+  (B-5, found through node-red-contrib-ccu's handling of the fault on a real CCU).
+- `getLinkPeers` of a device address faults on `rfd` with the `notSupported` entry (`-1 Failure`
+  under rfd's table, as rfd 3.89.11 answers; `-1 Generic error` under the default one), where it
+  answered the peers of all channels; on hmipserver and the other interfaces it answers the channels'
+  lists one after the other, a peer linked with two of the channels twice, as hmipserver 3.89.11 does
+  (B-4).
+
 ## 1.3.1
 
 - `getLinks` without an address reports `FLAGS: 1` (`SENDER_BROKEN`) on every device-internal link of

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**
@@ -496,8 +504,13 @@ information there. Asked for one address, `getLinks("ABC0000001:1", 0)` and `get
 0)` answer the same link with `FLAGS: 0`, and `getLinkPeers` names the own channel once. The simulator
 does the same on `rfd`: `addLink` stores `FLAGS: 0`, the unfiltered list adds bit 1 to internal links
 (seeded flags are kept and or-ed), the filtered one reports what is stored. hmipserver is not
-measured and reports the stored flags. rfd also refuses `getLinkPeers` of a device address (`-1
-Failure`); the simulator answers the peers of all its channels.
+measured and reports the stored flags.
+
+`getLinkPeers` of a **device** address (measured 2026-10-02, 3.89.11): rfd refuses it with `-1
+Failure`; hmipserver answers the channels' peer lists one after the other, so a peer linked with two
+of the channels is named twice. The simulator does the same: on `rfd` the `notSupported` entry of the
+fault table in force (`-1 Generic error` under hmipserver's default table, `-1 Failure` under
+`FAULT_TABLES.bidcos`), on every other interface the channels' lists in channel order.
 
 ### CONFIG_PENDING
 
@@ -535,20 +548,21 @@ The two models are the explanations that competed before the measurement (Homema
 The default table is **hmipserver's**, because that is the one an application has to survive
 (measured):
 
-| key                | code | string                          | when                                                                               |
-| ------------------ | ---- | ------------------------------- | ---------------------------------------------------------------------------------- |
-| `unknownMethod`    | -1   | Invalid XML-RPC message         | no handler for the method name (hmipserver answers this without a faultCode)       |
-| `unknownInstance`  | -2   | Invalid device                  | address not known to this interface                                                |
-| `unknownParamset`  | -2   | Invalid device                  | the device has no such paramset                                                    |
-| `unknownLink`      | -2   | Invalid device                  | the two channels are not linked                                                    |
-| `unknownParameter` | -5   | Unknown Parameter for value key | the paramset has no such parameter                                                 |
-| `readOnly`         | -5   | Invalid parameter or value      | `OPERATIONS & 2` is not set                                                        |
-| `typeError`        | -5   | Invalid parameter or value      | value does not fit the parameter's `TYPE`                                          |
-| `outOfRange`       | -5   | Invalid parameter or value      | ENUM value not in `VALUE_LIST`                                                     |
-| `invalidValue`     | -5   | Invalid parameter or value      | the stored channel configuration cannot be transferred                             |
-| `notSupported`     | -1   | Generic error                   | a method this interface does not implement                                         |
-| `notReachable`     | -1   | Generic error (UNREACH)         | a sleeping battery device                                                          |
-| `invalidArguments` | -321 | Invalid arguments               | wrong number of arguments; hmipserver really answers a Java exception message here |
+| key                          | code | string                          | when                                                                                                                    |
+| ---------------------------- | ---- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `unknownMethod`              | -1   | Invalid XML-RPC message         | no handler for the method name (hmipserver answers this without a faultCode)                                            |
+| `unknownInstance`            | -2   | Invalid device                  | address not known to this interface                                                                                     |
+| `unknownParamset`            | -2   | Invalid device                  | `getParamset`/`putParamset` of a paramset the device does not have                                                      |
+| `unknownParamsetDescription` | -3   | Unknown Paramset                | `getParamsetDescription` of a paramset the channel does not list (3.89.11 appends the name: `Unknown Paramset: NOSUCH`) |
+| `unknownLink`                | -2   | Invalid device                  | the two channels are not linked                                                                                         |
+| `unknownParameter`           | -5   | Unknown Parameter for value key | the paramset has no such parameter                                                                                      |
+| `readOnly`                   | -5   | Invalid parameter or value      | `OPERATIONS & 2` is not set                                                                                             |
+| `typeError`                  | -5   | Invalid parameter or value      | value does not fit the parameter's `TYPE`                                                                               |
+| `outOfRange`                 | -5   | Invalid parameter or value      | ENUM value not in `VALUE_LIST`                                                                                          |
+| `invalidValue`               | -5   | Invalid parameter or value      | the stored channel configuration cannot be transferred                                                                  |
+| `notSupported`               | -1   | Generic error                   | a method this interface does not implement                                                                              |
+| `notReachable`               | -1   | Generic error (UNREACH)         | a sleeping battery device                                                                                               |
+| `invalidArguments`           | -321 | Invalid arguments               | wrong number of arguments; hmipserver really answers a Java exception message here                                      |
 
 Over XML-RPC a fault is an XML-RPC fault, over BIN-RPC a message of type `0xff` with a
 `faultCode`/`faultString` struct. rfd's table is exported as `BIDCOS_FAULTS` and differs in more
@@ -561,6 +575,22 @@ new HmSim({faults: FAULT_TABLES.bidcos});
 new HmSim({faults: {unknownParameter: {faultCode: -4, faultString: 'Unknown parameter'}}}); // one entry
 ```
 
+### Unknown addresses and paramsets
+
+Measured 2026-10-02 on rfd and hmipserver of firmware 3.89.11, with a device address and a channel
+address alike: an address the interface does not know is a fault from every method that takes one -
+`getDeviceDescription`, `getParamsetDescription`, `getParamset`, `getLinks`, `getLinkPeers` - rfd's
+`-2 Unknown instance`, hmipserver's `-2 Invalid device`. The simulator answers `unknownInstance` of
+the table in force everywhere (until 1.3.1 `getParamsetDescription` answered `''` there).
+
+`getParamsetDescription` of a paramset the channel does not have: hmipserver answers `-3 Unknown
+Paramset: <name>`; rfd answers `-3 Unknown paramset` on a channel without a `LINK` paramset and the
+`LINK` description on a channel that has one (the name is taken as a peer address, as `getParamset`
+does). The simulator answers `unknownParamsetDescription` whenever the channel's `PARAMSETS` lacks
+the name. A paramset the channel lists but the description set has no entry for still answers `''`:
+that is a gap in the fixture (logged once, see
+[Device data and fixtures](#device-data-and-fixtures)), not something an interface process does.
+
 ### Service messages
 
 `getServiceMessages` answers `[[address, datapoint, value]]`: every datapoint whose description
@@ -627,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
@@ -738,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/faults.d.ts

@@ -11,6 +11,7 @@ export type FaultName =
     | 'unknownMethod'
     | 'unknownInstance'
     | 'unknownParamset'
+    | 'unknownParamsetDescription'
     | 'unknownParameter'
     | 'unknownLink'
     | 'readOnly'

package/lib/faults.js

@@ -35,8 +35,11 @@ const DEFAULT_FAULTS = {
     unknownMethod: {faultCode: -1, faultString: 'Invalid XML-RPC message'},
     // device or channel address not known to this interface process
     unknownInstance: {faultCode: -2, faultString: 'Invalid device'},
-    // the device/channel exists but does not have the requested paramset
+    // the device/channel exists but does not have the requested paramset (getParamset, putParamset)
     unknownParamset: {faultCode: -2, faultString: 'Invalid device'},
+    // getParamsetDescription of a paramset the channel does not have. hmipserver 3.89.11 appends the
+    // name it was asked for (`Unknown Paramset: NOSUCH`); measured 2026-10-02
+    unknownParamsetDescription: {faultCode: -3, faultString: 'Unknown Paramset'},
     // the paramset exists but does not contain the requested parameter (getValue/setValue)
     unknownParameter: {faultCode: -5, faultString: 'Unknown Parameter for value key'},
     // the two channels are not linked with each other
@@ -68,6 +71,10 @@ const BIDCOS_FAULTS = {
     // rfd does not fault here at all: an unknown paramset name is taken as a peer channel address
     // and the link defaults come back. The entry covers what the simulator cannot model.
     unknownParamset: {faultCode: -2, faultString: 'Unknown instance'},
+    // getParamsetDescription of a paramset the channel does not have, on a channel without a LINK
+    // paramset; a channel that has one answers the LINK description for any unknown name (rfd
+    // 3.89.11, measured 2026-10-02)
+    unknownParamsetDescription: {faultCode: -3, faultString: 'Unknown paramset'},
     unknownParameter: {faultCode: -5, faultString: 'Unknown parameter'},
     unknownLink: {faultCode: -1, faultString: 'Failure'},
     // rfd accepts a setValue on a read-only datapoint, so this is never raised against it

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}}} */
@@ -571,6 +584,28 @@ class HmSim {
         return this.requireDevice(iface, address);
     }
 
+    /**
+     * The RPC `getParamsetDescription`: unlike {@link getParamsetDescription}, which the simulator
+     * calls for itself, an address the interface does not know is a fault (rfd `-2 Unknown instance`,
+     * hmipserver `-2 Invalid device`, measured on 3.89.11), and so is a paramset the channel does not
+     * list in `PARAMSETS` (`-3` on both). A paramset the channel has but the description set lacks
+     * still answers `''`, logged once by {@link resolveParamsetKey} - that is a gap in the fixture,
+     * not something an interface process does.
+     * @param {string} iface
+     * @param {string} address device or channel address
+     * @param {string} paramset MASTER, VALUES, LINK or SERVICE
+     */
+    describeParamset(iface, address, paramset) {
+        const device = this.requireDevice(iface, address);
+        if (typeof paramset !== 'string' || paramset === '') {
+            throw this.fault('invalidArguments', 'paramset type');
+        }
+        if (Array.isArray(device.PARAMSETS) && !device.PARAMSETS.includes(paramset)) {
+            throw this.fault('unknownParamsetDescription', `${address}/${paramset}`);
+        }
+        return this.getParamsetDescription(iface, device, paramset);
+    }
+
     getValue(iface, address, datapoint) {
         const {description, values} = this.storedParamset(iface, address, 'VALUES');
         if (!description[datapoint]) {
@@ -949,14 +984,31 @@ class HmSim {
         }
     }
 
+    /**
+     * The peers of a channel: the other end of every link it is on, the own channel once for a link
+     * with itself. For a device address rfd answers `-1 Failure` (measured, 3.89.11); hmipserver
+     * answers the channels' lists one after the other, a peer linked with two of the channels twice
+     * (measured, 3.89.11) - the simulator does the same on every interface but `rfd`.
+     * @param {string} iface
+     * @param {Array} params [address]
+     * @returns {string[]} channel addresses
+     */
     getLinkPeers(iface, params) {
-        const addresses = new Set(this.channelsOf(iface, params[0]));
+        const [address] = params || [];
+        const device = this.requireDevice(iface, address);
+        if (iface === 'rfd' && !device.PARENT) {
+            // rfd's -1 Failure; -1 Generic error under hmipserver's default table
+            throw this.fault('notSupported', `getLinkPeers of a device address: ${address}`);
+        }
+
         const peers = [];
-        for (const link of this.links[iface] || []) {
-            if (addresses.has(link.SENDER)) {
-                peers.push(link.RECEIVER);
-            } else if (addresses.has(link.RECEIVER)) {
-                peers.push(link.SENDER);
+        for (const channel of this.channelsOf(iface, address)) {
+            for (const link of this.links[iface] || []) {
+                if (link.SENDER === channel) {
+                    peers.push(link.RECEIVER);
+                } else if (link.RECEIVER === channel) {
+                    peers.push(link.SENDER);
+                }
             }
         }
         return peers;
@@ -1151,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) {
@@ -1170,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 */
 
     /**
@@ -2416,7 +2596,7 @@ class HmSim {
             'system.multicall': (iface, params) => this.multicall(iface, params),
             init: (iface, params) => this.init(iface, params),
             listDevices: (iface) => this.devices[iface].devices,
-            getParamsetDescription: (iface, params) => this.getParamsetDescription(iface, params[0], params[1]),
+            getParamsetDescription: (iface, params) => this.describeParamset(iface, params[0], params[1]),
             getDeviceDescription: (iface, params) => this.getDeviceDescription(iface, params[0]),
             ping: (iface, params) => this.ping(iface, params),
             setValue: (iface, params) => {
@@ -2443,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.1",
+  "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 */
 
@@ -405,6 +442,8 @@ declare class HmSim {
         paramset: string,
     ): HmSim.ParamsetDescription | undefined;
     getDeviceDescription(iface: string, address: string): HmSim.DeviceDescription;
+    /** the RPC `getParamsetDescription`: faults for an unknown address or a paramset the channel lacks */
+    describeParamset(iface: string, address: string, paramset: string): HmSim.ParamsetDescription | undefined;
 
     /* ---------------------------------------------------------------- scenario api: service messages and health */