hm-simulator 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -3,6 +3,24 @@
 All notable changes of hm-simulator. The release workflow takes each version's section from here for the
 GitHub release notes.
 
+## 1.3.0
+
+- The calls Homematic Manager makes, measured on rfd and hmipserver of firmware 3.89.11:
+  `getKeyMismatchDevice` with the scenario call `scriptKeyMismatch` (a device that holds another
+  system's key: heard at the next install mode, paired once `setTempKey` offers its key) and rfd's
+  `addDevice(serial)`; `suppressServiceMessages` and `getSuppressedServiceMessages` on hmipserver
+  (a suppressed message is left out of `getServiceMessages` and reports the value that raises
+  none); `getMetadata`, `setMetadata` and rfd's `getAllMetadata`, seeded with the new `metadata`
+  option; `listReplaceableDevices`; `getVersion` (`interfaces.<iface>.version`); `getLGWStatus`
+  (only with `interfaces.<iface>.lgwStatus` - rfd 3.89.11 does not know it); `setInterfaceClock`
+  (recorded in `sim.interfaceClocks`).
+- TypeScript declarations: `sim.d.ts` (the `types` of the package), `sim.d.mts` for `sim.mjs` and
+  `lib/faults.d.ts`, covering the options, the scenario API, the introspection calls and the
+  description types. `npm test` type-checks them against a file that uses every export
+  (`test/types/`), and a test fails when an option or scenario call is missing from them.
+- `interfaces.<iface>.getServiceMessagesFault: true` answers `getServiceMessages` with
+  `Invalid XML-RPC message`, as VirtualDevices, CUxD and hmipserver were seen to on 3.89.x.
+
 ## 1.2.0
 
 - The README is rewritten for the test author (quick start, connecting a client, the scenario API

package/README.md

@@ -38,6 +38,10 @@ Prerequisites: [Node.js](https://nodejs.org) >= 20.19.
 npm install --save-dev hm-simulator
 ```
 
+TypeScript declarations ship with the package (`sim.d.ts`, `sim.d.mts`, `lib/faults.d.ts`): the
+options, the scenario API, the introspection calls and the description types are under the `HmSim`
+namespace (`HmSim.Options`, `HmSim.DeviceDescription`, `HmSim.ParamsetDescription`, ...).
+
 A test file with `node:test` - the same shape works with mocha (`before`/`after`) and vitest
 (`beforeAll`/`afterAll`):
 
@@ -118,15 +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`, `setInstallMode`, `getInstallMode`                                            |
-| 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` |
-| 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`, `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
@@ -179,30 +185,31 @@ UTF-8. BIN-RPC strings go out as ISO-8859-1, as rfd sends them.
 
 `new HmSim(options)`; everything is optional.
 
-| option                     | default                                              |                                                                                              |
-| -------------------------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| `devices`                  | `{rfd: {devices: []}, hmip: {devices: []}}`          | device descriptions per interface, `{<iface>: {devices: [...]}}`                             |
-| `paramsetDescriptions`     | the bundled 8.4 MB `data/paramset-descriptions.json` | replaces the bundled descriptions, see [Device data and fixtures](#device-data-and-fixtures) |
-| `paramsetFallback`         | `true`                                               | a firmware without a description uses the nearest one; `false` for exact keys only           |
-| `links`                    | `{}`                                                 | links per interface, `[{SENDER, RECEIVER, FLAGS, NAME, DESCRIPTION}]`                        |
-| `bidcosInterfaces`         | one per interface                                    | what `listBidcosInterfaces` answers, per interface                                           |
-| `serviceMessages`          | `{}`                                                 | extra service messages per interface, `[[address, datapoint, value]]`                        |
-| `newDevices`               | `{}`                                                 | devices that appear when the install mode is switched on, `{<iface>: {devices, delay}}`      |
-| `defaultRssi`              | `-65`                                                | what `rssiInfo` answers where a device has no RSSI datapoint                                 |
-| `config.listenAddress`     | all interfaces                                       | `'127.0.0.1'` in tests                                                                       |
-| `config.binrpcListenPort`  | –                                                    | rfd                                                                                          |
-| `config.xmlrpcListenPort`  | –                                                    | hmipserver                                                                                   |
-| `config.wiredListenPort`   | –                                                    | BidCos-Wired, started when `devices.wired` exists                                            |
-| `config.virtualListenPort` | off                                                  | VirtualDevices                                                                               |
-| `config.virtualPath`       | `/groups`                                            | the path VirtualDevices answers on                                                           |
-| `config.cuxdListenPort`    | off                                                  | CUxD                                                                                         |
-| `interfaces`               | see below                                            | behaviour per interface, `{<iface>: {...}}`                                                  |
-| `faults`                   | hmipserver's table                                   | overrides for the fault table, see [Fault codes](#fault-codes)                               |
-| `behaviorPath`             | `behaviors/` of the package                          | directory with [behaviour scripts](#behaviour-scripts), `false` for none                     |
-| `rega`                     | off                                                  | the [ReGa mock](#rega-mock)                                                                  |
-| `tls`                      | off                                                  | `true` or `{key, cert}`, see [TLS and basic auth](#tls-and-basic-auth)                       |
-| `auth`                     | off                                                  | `{username, password}`, HTTP basic auth                                                      |
-| `log`                      | silent                                               | an object with `debug`, `info`, `warn`, `error` (`console` will do)                          |
+| option                     | default                                              |                                                                                               |
+| -------------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `devices`                  | `{rfd: {devices: []}, hmip: {devices: []}}`          | device descriptions per interface, `{<iface>: {devices: [...]}}`                              |
+| `paramsetDescriptions`     | the bundled 8.4 MB `data/paramset-descriptions.json` | replaces the bundled descriptions, see [Device data and fixtures](#device-data-and-fixtures)  |
+| `paramsetFallback`         | `true`                                               | a firmware without a description uses the nearest one; `false` for exact keys only            |
+| `links`                    | `{}`                                                 | links per interface, `[{SENDER, RECEIVER, FLAGS, NAME, DESCRIPTION}]`                         |
+| `bidcosInterfaces`         | one per interface                                    | what `listBidcosInterfaces` answers, per interface                                            |
+| `serviceMessages`          | `{}`                                                 | extra service messages per interface, `[[address, datapoint, value]]`                         |
+| `newDevices`               | `{}`                                                 | devices that appear when the install mode is switched on, `{<iface>: {devices, delay}}`       |
+| `defaultRssi`              | `-65`                                                | what `rssiInfo` answers where a device has no RSSI datapoint                                  |
+| `metadata`                 | `{}`                                                 | what `getMetadata` answers before any `setMetadata`, `{<iface>: {<address>: {<key>: value}}}` |
+| `config.listenAddress`     | all interfaces                                       | `'127.0.0.1'` in tests                                                                        |
+| `config.binrpcListenPort`  | –                                                    | rfd                                                                                           |
+| `config.xmlrpcListenPort`  | –                                                    | hmipserver                                                                                    |
+| `config.wiredListenPort`   | –                                                    | BidCos-Wired, started when `devices.wired` exists                                             |
+| `config.virtualListenPort` | off                                                  | VirtualDevices                                                                                |
+| `config.virtualPath`       | `/groups`                                            | the path VirtualDevices answers on                                                            |
+| `config.cuxdListenPort`    | off                                                  | CUxD                                                                                          |
+| `interfaces`               | see below                                            | behaviour per interface, `{<iface>: {...}}`                                                   |
+| `faults`                   | hmipserver's table                                   | overrides for the fault table, see [Fault codes](#fault-codes)                                |
+| `behaviorPath`             | `behaviors/` of the package                          | directory with [behaviour scripts](#behaviour-scripts), `false` for none                      |
+| `rega`                     | off                                                  | the [ReGa mock](#rega-mock)                                                                   |
+| `tls`                      | off                                                  | `true` or `{key, cert}`, see [TLS and basic auth](#tls-and-basic-auth)                        |
+| `auth`                     | off                                                  | `{username, password}`, HTTP basic auth                                                       |
+| `log`                      | silent                                               | an object with `debug`, `info`, `warn`, `error` (`console` will do)                           |
 
 **Per interface** (`interfaces: {hmip: {...}, rfd: {...}}`):
 
@@ -220,6 +227,9 @@ UTF-8. BIN-RPC strings go out as ISO-8859-1, as rfd sends them.
 | `startDelay`                   | `0`                                                                            | milliseconds after `whenReady()` until the port accepts connections: a process that starts late (`sim.ports` knows the port from the start)                                                                   |
 | `unreachWrites`                | `'accept'`                                                                     | what `setValue`/`putParamset` to an unreachable device answer: `'accept'`, or `'fault'` (`notReachable`). The simulator's model, not a measurement                                                            |
 | `firmwareUpdateDelay`          | `0`                                                                            | milliseconds per step of a firmware update                                                                                                                                                                    |
+| `getServiceMessagesFault`      | `false`                                                                        | answer `getServiceMessages` with the unknown-method fault (`Invalid XML-RPC message`), as VirtualDevices, CUxD and hmipserver were seen to on 3.89.x                                                          |
+| `version`                      | `'2.6.0'` for `rfd` and `wired`, `'3.89.11.20260919'` for `hmip`               | what `getVersion` answers; the rest has no `getVersion`                                                                                                                                                       |
+| `lgwStatus`                    | –                                                                              | BidCos only: what `getLGWStatus` answers; without it the method is unknown, as on rfd 3.89.11                                                                                                                 |
 
 ## Scenario API
 
@@ -233,6 +243,9 @@ sim.addDevice('rfd', device, channel0, channel1); // pairs a device: newDevices
 sim.removeDevice('rfd', 'LAB0000002'); // deleteDevices, with its values and links
 sim.scriptNewDevices('rfd', [device, channel0, channel1], 500); // appear 500 ms after setInstallMode
 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]});
 ```
 
 **Values and events**
@@ -285,6 +298,8 @@ sim.getTempKey('rfd'); // what setTempKey set
 sim.getInstallMode('rfd'); // seconds of install mode left
 sim.keyChanges; // every changeKey: [{iface, key, ts}]
 sim.firmwareListRefreshes; // every refreshDeployedDeviceFirmwareList: [{iface, ts}]
+sim.interfaceClocks; // every setInterfaceClock: [{iface, utc, offset, ts}]
+sim.metadata; // what setMetadata stored: {<iface>: {<address>: {<key>: value}}}
 sim.ports; // {rfd, hmip, wired, virtual, cuxd, ...}: the ports once whenReady() resolved
 sim.regaSim.scripts; // every script the ReGa mock received
 ```
@@ -543,6 +558,20 @@ nothing is pending (measured); `serviceMessagesEmptyAsString: true` does the sam
 because it breaks every client that assumes an array, which is why a client should be tested with it
 once. Teams (`listTeams`) have the shape rfd was read to have on a CCU3.
 
+**Suppression** (hmipserver only, eQ-3's HmIP addendum): `suppressServiceMessages(channelAddress,
+parameter, suppress)` takes one of the channel's service parameters or `''` for all of them, and
+ignores a parameter without the service flag; `getSuppressedServiceMessages(channelAddress)`
+answers the suppressed ones (`[]` for an address it does not know). Measured on 3.89.11. A
+suppressed message is left out of `getServiceMessages` and its datapoint reports the value that
+raises no message (`false`), in `getValue`, `getParamset` and events, while the stored value stays;
+a new occurrence stays suppressed until the suppression is lifted. That a change of the suppression
+sends that value as an event is the simulator's model.
+
+VirtualDevices, CUxD and hmipserver were seen to answer `getServiceMessages` with the fault
+`Invalid XML-RPC message` on 3.89.x (hmipserver answered it on 3.89.11);
+`interfaces.<iface>.getServiceMessagesFault: true` does the same, for a client that has to survive
+it.
+
 ### A callback server that hangs
 
 `interfaces.<iface>.listenerModel: 'measured'`. Measured on firmware 3.89.8 (2026-09-25) with a
@@ -563,6 +592,28 @@ measurement; so is everything with the default `'isolated'`, where every client
 (rfd, hmipserver; recorded in `sim.firmwareListRefreshes`) answer as the interfaces were measured to
 on firmware 3.89.x; the simulator does no cryptography and loads no firmware.
 
+### The calls of Homematic Manager
+
+Measured on rfd and hmipserver of firmware 3.89.11 (read-only calls, and one suppression set and
+lifted again):
+
+| call                                     | rfd                                                                    | hmipserver                                |
+| ---------------------------------------- | ---------------------------------------------------------------------- | ----------------------------------------- |
+| `getKeyMismatchDevice(reset)`            | `''` when no device holds another key                                  | the same                                  |
+| `getMetadata(address, key)`, key not set | fault `-1 Failure`, for an unknown address too                         | an empty value                            |
+| `getAllMetadata(address)`, nothing set   | fault `-1 Failure`                                                     | not in `system.listMethods`               |
+| `listReplaceableDevices(address)`        | `[]` for its own `BidCoS-RF`, `-2 Unknown instance` for an unknown one | an empty HTTP body, always                |
+| `getVersion()`                           | `2.6.0`                                                                | the firmware, `3.89.11.…`                 |
+| `getLGWStatus()`                         | `unknown method name`, with and without a LAN gateway in the system    | not in `system.listMethods`               |
+| `suppressServiceMessages(…)`             | not in `system.listMethods`                                            | see [Service messages](#service-messages) |
+
+The simulator answers so, with the fault table in force (`-1 Generic error` under hmipserver's
+default table where rfd says `-1 Failure`) and `''` for hmipserver's empty body. Its models:
+`listReplaceableDevices` on rfd lists the other devices of the same `TYPE`; `setMetadata` on rfd
+knows only its own addresses; `setInterfaceClock` is recorded, not measured (it sets the clock the
+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.
+
 ## ReGa mock
 
 `rega: {port: 8181, ...}` starts an HTTP server that answers `POST /<name>.exe` as the CCU's
@@ -674,7 +725,7 @@ 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`, `dropConnection`, `stopInterface`, `startInterface`,
+`setServiceMessage`, `scriptNewDevices`, `scriptKeyMismatch`, `dropConnection`, `stopInterface`, `startInterface`,
 `restartInterface`, `injectFault`, `clearFaults`, `setReachable`, `setLowBattery`, `setDutyCycle`,
 `setCarrierSense`, `offerFirmware`, `schedule`, `getDevice`, `getWriteLog`, `getConfigPending`,
 `getPoisonedChannels`, `getMissingParamsetDescriptions`, `getCallbackLog`, `getTempKey`,

package/lib/control.js

@@ -14,6 +14,7 @@ const SCENARIO_METHODS = new Set([
     'setValue',
     'setServiceMessage',
     'scriptNewDevices',
+    'scriptKeyMismatch',
     'dropConnection',
     'stopInterface',
     'startInterface',

package/lib/faults.d.ts

@@ -0,0 +1,48 @@
+// Type declarations for lib/faults.js (`require('hm-simulator/lib/faults.js')`).
+
+/** An XML-RPC fault: what the interface process answers. */
+export interface FaultEntry {
+    faultCode: number;
+    faultString: string;
+}
+
+/** The names of the fault table's entries. */
+export type FaultName =
+    | 'unknownMethod'
+    | 'unknownInstance'
+    | 'unknownParamset'
+    | 'unknownParameter'
+    | 'unknownLink'
+    | 'readOnly'
+    | 'typeError'
+    | 'outOfRange'
+    | 'invalidValue'
+    | 'notSupported'
+    | 'notReachable'
+    | 'invalidArguments';
+
+/** A fault table: every name above, plus whatever an override added. */
+export type FaultTable = Record<FaultName, FaultEntry> & Record<string, FaultEntry>;
+
+/** hmipserver 3.89.8, measured 2026-09-05 - the default. */
+export declare const DEFAULT_FAULTS: FaultTable;
+/** rfd 3.89.8, measured 2026-09-05. */
+export declare const BIDCOS_FAULTS: FaultTable;
+/** The measured tables by name, for `new HmSim({faults: FAULT_TABLES.bidcos})`. */
+export declare const FAULT_TABLES: {hmip: FaultTable; bidcos: FaultTable};
+
+/** Error carrying an XML-RPC fault. */
+export declare class RpcFault extends Error {
+    constructor(faultCode: number, faultString: string, detail?: string);
+    faultCode: number;
+    faultString: string;
+    detail?: string;
+    /** The struct a BIN-RPC fault carries as its body. */
+    toStruct(): FaultEntry;
+}
+
+/** A fault factory bound to a (possibly overridden) table. */
+export declare function createFaults(overrides?: Partial<Record<FaultName | (string & {}), Partial<FaultEntry>>>): {
+    table: FaultTable;
+    fault: (name: FaultName | (string & {}), detail?: string) => RpcFault;
+};

package/lib/method-help.js

@@ -55,4 +55,18 @@ module.exports = {
     restoreConfigToDevice: 'void restoreConfigToDevice(string address) - write the cached configuration to the device',
     determineParameter:
         'void determineParameter(string address, string paramsetKey, string parameterId) - read a parameter from the device',
+    getKeyMismatchDevice:
+        'string getKeyMismatchDevice(boolean reset) - the serial of a device that holds another key, reset clears it',
+    addDevice: 'struct addDevice(string serialNumber) - pair one device by its serial; BidCos only',
+    suppressServiceMessages:
+        'void suppressServiceMessages(string channelAddress, string parameter, boolean suppress) - suppress a service message, an empty parameter for all; HmIP only',
+    getSuppressedServiceMessages:
+        'array getSuppressedServiceMessages(string channelAddress) - the suppressed service parameters of a channel; HmIP only',
+    getMetadata: 'ValueType getMetadata(string address, string key) - a stored metadata value',
+    setMetadata: 'void setMetadata(string address, string key, ValueType value) - store a metadata value',
+    getAllMetadata: 'struct getAllMetadata(string address) - every metadata value of an address; BidCos only',
+    listReplaceableDevices: 'array listReplaceableDevices(string address) - the devices a device can replace',
+    getVersion: 'string getVersion() - the version of the interface process',
+    getLGWStatus: 'struct getLGWStatus() - the state of the LAN gateways',
+    setInterfaceClock: 'void setInterfaceClock(int utcSeconds, int offsetMinutes) - set the clock sent to the devices',
 };

package/lib/sim.js

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

package/package.json

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

package/sim.d.mts

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

package/sim.d.ts

@@ -0,0 +1,443 @@
+// Type declarations for hm-simulator. The package is plain CommonJS; these are written by hand and
+// checked by `npm run test:types` (test/types/). Every option, scenario call or RPC method that is
+// added to lib/sim.js is added here in the same change.
+
+import type {EventEmitter} from 'node:events';
+
+import type {FaultEntry, FaultName, FaultTable} from './lib/faults.js';
+
+declare namespace HmSim {
+    /** The interfaces the simulator serves; `devices` may name others, which get no port. */
+    type InterfaceName = 'rfd' | 'hmip' | 'wired' | 'virtual' | 'cuxd' | (string & {});
+
+    /** A device or channel, as `listDevices` and `getDeviceDescription` answer it. */
+    interface DeviceDescription {
+        ADDRESS: string;
+        TYPE: string;
+        VERSION?: number;
+        PARENT?: string;
+        PARENT_TYPE?: string;
+        CHILDREN?: string[];
+        PARAMSETS?: string[];
+        FIRMWARE?: string;
+        AVAILABLE_FIRMWARE?: string;
+        FIRMWARE_UPDATE_STATE?: string;
+        UPDATABLE?: number | boolean;
+        FLAGS?: number;
+        INTERFACE?: string;
+        INDEX?: number;
+        DIRECTION?: number;
+        LINK_SOURCE_ROLES?: string;
+        LINK_TARGET_ROLES?: string;
+        RF_ADDRESS?: number;
+        ROAMING?: number;
+        RX_MODE?: number;
+        AES_ACTIVE?: number;
+        TEAM?: string;
+        TEAM_TAG?: string;
+        TEAM_CHANNELS?: string[];
+        [key: string]: unknown;
+    }
+
+    /** One entry of `SPECIAL`: a value with a meaning of its own. */
+    interface SpecialValue {
+        ID: string;
+        VALUE: number;
+    }
+
+    /** One parameter of a paramset description. */
+    interface ParameterDescription {
+        TYPE: 'BOOL' | 'ACTION' | 'INTEGER' | 'FLOAT' | 'ENUM' | 'STRING' | (string & {});
+        /** 1 read, 2 write, 4 event */
+        OPERATIONS: number;
+        /** 1 visible, 2 internal, 4 transform, 8 service, 16 sticky */
+        FLAGS?: number;
+        DEFAULT?: unknown;
+        MIN?: unknown;
+        MAX?: unknown;
+        VALUE_LIST?: string[];
+        UNIT?: string;
+        SPECIAL?: SpecialValue[];
+        ID?: string;
+        TAB_ORDER?: number;
+        CONTROL?: string;
+        [key: string]: unknown;
+    }
+
+    /** A paramset description: parameter name -> description. */
+    type ParamsetDescription = Record<string, ParameterDescription>;
+
+    /** A direct link. */
+    interface Link {
+        SENDER: string;
+        RECEIVER: string;
+        FLAGS?: number;
+        NAME?: string;
+        DESCRIPTION?: string;
+    }
+
+    /** What `listBidcosInterfaces` answers for one radio interface. */
+    interface BidcosInterface {
+        ADDRESS: string;
+        DESCRIPTION?: string;
+        CONNECTED?: boolean;
+        DEFAULT?: boolean;
+        FIRMWARE_VERSION?: string;
+        TYPE?: string;
+        DUTY_CYCLE?: number;
+        CARRIER_SENSE_LEVEL?: number;
+        [key: string]: unknown;
+    }
+
+    /** `[address, datapoint, value]`, as `getServiceMessages` answers and events carry. */
+    type ServiceMessage = [address: string, datapoint: string, value: unknown];
+    type EventTuple = [address: string, datapoint: string, value: unknown];
+
+    interface Logger {
+        debug(...args: unknown[]): void;
+        info(...args: unknown[]): void;
+        warn(...args: unknown[]): void;
+        error(...args: unknown[]): void;
+    }
+
+    interface BasicAuth {
+        username: string;
+        password: string;
+    }
+
+    /** `true`: a generated self-signed certificate; `{key, cert}`: PEM; otherwise how to generate one. */
+    type TlsOption =
+        | boolean
+        | {key: string; cert: string}
+        | {commonName?: string; hostnames?: string[]; ips?: string[]; days?: number};
+
+    interface Config {
+        /** all interfaces unless set; `'127.0.0.1'` in tests */
+        listenAddress?: string;
+        /** rfd; 0 picks a free port */
+        binrpcListenPort?: number;
+        /** hmipserver */
+        xmlrpcListenPort?: number;
+        /** BidCos-Wired, started when `devices.wired` exists */
+        wiredListenPort?: number;
+        /** VirtualDevices, off unless set */
+        virtualListenPort?: number;
+        /** the path VirtualDevices answers on, `/groups` */
+        virtualPath?: string;
+        /** CUxD, off unless set */
+        cuxdListenPort?: number;
+    }
+
+    /** Behaviour per interface, `interfaces: {<iface>: {...}}`. */
+    interface InterfaceOptions {
+        configPendingMode?: 'hmip' | 'bidcos' | 'strict' | 'pending';
+        configPendingOnWrite?: boolean;
+        configPendingDelay?: number;
+        serviceMessagesEmptyAsString?: boolean;
+        getServiceMessagesFault?: boolean;
+        protocols?: Array<'binrpc' | 'xmlrpc'>;
+        listenerModel?: 'isolated' | 'measured';
+        deliveryTimeout?: number;
+        pong?: boolean;
+        pingDelay?: number;
+        startDelay?: number;
+        unreachWrites?: 'accept' | 'fault';
+        firmwareUpdateDelay?: number;
+        /** what `getVersion` answers */
+        version?: string;
+        /** BidCos only: what `getLGWStatus` answers; unknown method without it */
+        lgwStatus?: unknown;
+    }
+
+    /** The ReGa mock (`rega` option). */
+    interface RegaOptions {
+        port?: number;
+        listenAddress?: string;
+        variables?: unknown[];
+        /** devices and channels, the answer to `getChannels()` */
+        channels?: unknown[];
+        programs?: unknown[];
+        rooms?: unknown[];
+        functions?: unknown[];
+        /** the answer to `getValues()` */
+        values?: unknown[];
+        auth?: BasicAuth;
+        tls?: {key: string; cert: string};
+    }
+
+    interface Options {
+        log?: Logger;
+        devices?: Record<string, {devices: DeviceDescription[]}>;
+        config?: Config;
+        /** directory with behaviour scripts, `false` for none */
+        behaviorPath?: string | false;
+        rega?: RegaOptions;
+        paramsetDescriptions?: Record<string, ParamsetDescription>;
+        paramsetFallback?: boolean;
+        faults?: Partial<Record<FaultName | (string & {}), Partial<FaultEntry>>>;
+        interfaces?: Partial<Record<InterfaceName, InterfaceOptions>>;
+        links?: Record<string, Link[]>;
+        bidcosInterfaces?: Record<string, BidcosInterface[]>;
+        serviceMessages?: Record<string, ServiceMessage[]>;
+        newDevices?: Record<string, {devices: DeviceDescription[]; delay?: number}>;
+        defaultRssi?: number;
+        /** `{<iface>: {<address>: {<key>: value}}}`, what `getMetadata` answers before any `setMetadata` */
+        metadata?: Record<string, Record<string, Record<string, unknown>>>;
+        tls?: TlsOption;
+        auth?: BasicAuth;
+    }
+
+    interface WriteLogEntry {
+        iface: string;
+        address: string;
+        /** MASTER, VALUES, SERVICE or a peer address */
+        paramset: string;
+        values: Record<string, unknown>;
+        rejected?: Array<{name: string; value: unknown; reason: string; faultCode?: number}>;
+        method?: 'activateLinkParamset';
+        longPress?: boolean;
+        ts: number;
+    }
+
+    interface CallbackLogEntry {
+        iface: string;
+        /** the url the client registered with */
+        client: string;
+        method: string;
+        sentAt: number;
+        answeredAt: number | null;
+        error: string | null;
+    }
+
+    interface ConfigPendingEntry {
+        address: string;
+        sticky: boolean;
+    }
+
+    interface MissingParamsetDescription {
+        iface: string;
+        key: string;
+        usedKey: string | null;
+    }
+
+    interface InjectedFault {
+        iface?: string;
+        /** `'*'` for any */
+        method?: string;
+        /** `Infinity` or `-1` for all until `clearFaults()` */
+        times?: number;
+        delayMs?: number;
+        hang?: boolean;
+        closeSocket?: boolean;
+        fault?: FaultName | (string & {}) | {faultCode: number; faultString?: string};
+    }
+
+    interface ScheduleStep {
+        at?: number;
+        call: string;
+        args?: unknown[];
+    }
+
+    interface KeyMismatchScript {
+        /** the passphrase the device was taught in with */
+        key?: string;
+        /** its description and channel descriptions, paired once the temporary key is `key` */
+        devices?: DeviceDescription[];
+        /** milliseconds between the install mode and the device being heard */
+        delay?: number;
+    }
+
+    /** An RPC fault as the simulator throws and answers it. */
+    interface RpcFault extends Error {
+        faultCode: number;
+        faultString: string;
+        detail?: string;
+    }
+
+    /** `method -> handler(iface, params)`, as the servers dispatch it. */
+    type RpcMethodTable = Record<string, (iface: string, params: unknown[]) => unknown>;
+
+    /** The ports once `whenReady()` resolved. */
+    type Ports = Partial<Record<InterfaceName, number>>;
+
+    /** The ReGa mock. */
+    interface RegaSim {
+        port: number;
+        ready: Promise<void>;
+        /** every script it received */
+        scripts: string[];
+        /** every `dom.GetObject(id).Name("…")` among them */
+        renames: Array<{id: number; name: string; script: string}>;
+        variables: unknown[];
+        devices: unknown[];
+        programs: unknown[];
+        rooms: unknown[];
+        functions: unknown[];
+        values: unknown[];
+        close(): void;
+    }
+
+    /** The emitter behaviour scripts get: `emit('setValue', iface, address, datapoint, value)`. */
+    interface BehaviorApi extends EventEmitter {
+        emit(event: 'setValue', iface: string, address: string, datapoint: string, value: unknown): boolean;
+        emit(event: string | symbol, ...args: unknown[]): boolean;
+    }
+}
+
+/**
+ * Simulates the RPC interface processes and the ReGa of a Homematic CCU.
+ */
+declare class HmSim {
+    constructor(options?: HmSim.Options);
+
+    readonly options: HmSim.Options;
+    log: HmSim.Logger;
+    config: HmSim.Config;
+    devices: Record<string, {devices: HmSim.DeviceDescription[]}>;
+    paramsetDescriptions: Record<string, HmSim.ParamsetDescription>;
+    paramsetFallback: boolean;
+    /** the effective fault table */
+    faults: FaultTable;
+    /** builds an {@link HmSim.RpcFault} from an entry of the fault table */
+    fault(name: FaultName | (string & {}), detail?: string): HmSim.RpcFault;
+    /** the port each server listens on, filled in once it listens */
+    ports: HmSim.Ports;
+    /** stored state per interface and address: `{VALUES, MASTER, LINKS, ...}` */
+    values: Record<string, Record<string, Record<string, Record<string, unknown>>>>;
+    links: Record<string, HmSim.Link[]>;
+    serviceMessages: Record<string, HmSim.ServiceMessage[]>;
+    /** every reportValueUsage */
+    valueUsage: Array<{iface: string; address: string; valueId: string; refCounter: number; ts: number}>;
+    /** every updateFirmware/installFirmware */
+    firmwareUpdates: Array<{iface: string; addresses: string[]; method: string; ts: number}>;
+    /** every refreshDeployedDeviceFirmwareList */
+    firmwareListRefreshes: Array<{iface: string; ts: number}>;
+    /** every changeKey */
+    keyChanges: Array<{iface: string; key: string; ts: number}>;
+    /** every setInterfaceClock */
+    interfaceClocks: Array<{iface: string; utc: number; offset: number; ts: number}>;
+    /** what setMetadata stored and the `metadata` option seeded */
+    metadata: Record<string, Record<string, Record<string, unknown>>>;
+    /** the serial getKeyMismatchDevice answers, per interface */
+    keyMismatch: Record<string, string>;
+    /** what scriptKeyMismatch() set up and did not pair yet */
+    keyMismatchScript: Record<string, Required<HmSim.KeyMismatchScript> & {serial: string}>;
+    /** the temporary key per interface, as setTempKey left it */
+    tempKey: Record<string, string>;
+    /** the log level per interface, as logLevel set it */
+    logLevels: Record<string, number>;
+    /** the RPC method table; a test may replace a handler */
+    rpcMethods: HmSim.RpcMethodTable;
+    /** the emitter behaviour scripts get */
+    api: HmSim.BehaviorApi;
+    /** the ReGa mock, when the `rega` option started it */
+    regaSim?: HmSim.RegaSim;
+
+    /** Resolves once every server accepts connections. */
+    whenReady(): Promise<void>;
+    /** Stops every server, timer and client connection. */
+    close(): void;
+
+    /* ---------------------------------------------------------------- scenario api: devices */
+
+    /** Pairs a device with its channels: `newDevices` to every client. Answers the ones that were new. */
+    addDevice(
+        iface: string,
+        ...descriptions: Array<HmSim.DeviceDescription | HmSim.DeviceDescription[]>
+    ): HmSim.DeviceDescription[];
+    addDevices(iface: string, list: HmSim.DeviceDescription[]): HmSim.DeviceDescription[];
+    /** Removes a device with its channels, values and links: `deleteDevices` to every client. */
+    removeDevice(iface: string, address: string): '';
+    /** The description, `false` when the interface does not know the address. */
+    getDevice(iface: string, address: string): HmSim.DeviceDescription | false;
+    /** Devices that appear the next time the install mode is switched on. */
+    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;
+
+    /* ---------------------------------------------------------------- scenario api: values and events */
+
+    /** One event, not checked against the description. Answers the value. */
+    fireEvent(iface: string, address: string, datapoint: string, value: unknown): unknown;
+    /** A burst of events as `system.multicall` batches. Answers how many. */
+    fireEvents(iface: string, events: HmSim.EventTuple[], options?: {batch?: number}): number;
+    /** A value, checked against the description; `internal` is the device reporting it. */
+    setValue(
+        iface: string,
+        address: string,
+        datapoint: string,
+        value: unknown,
+        options?: {strict?: boolean; internal?: boolean},
+    ): void;
+    getValue(iface: string, address: string, datapoint: string): unknown;
+    getParamset(iface: string, address: string, key: string): Record<string, unknown>;
+    putParamset(iface: string, address: string, key: string, set: Record<string, unknown>): '';
+    getParamsetDescription(
+        iface: string,
+        device: string | HmSim.DeviceDescription,
+        paramset: string,
+    ): HmSim.ParamsetDescription | undefined;
+    getDeviceDescription(iface: string, address: string): HmSim.DeviceDescription;
+
+    /* ---------------------------------------------------------------- scenario api: service messages and health */
+
+    /** Raises (or with a falsy value clears) a service message. */
+    setServiceMessage(iface: string, address: string, datapoint: string, value?: unknown): void;
+    getServiceMessages(iface: string): HmSim.ServiceMessage[] | '';
+    setConfigPending(iface: string, address: string, options?: {sticky?: boolean}): void;
+    clearConfigPending(iface: string, address: string): void;
+    setReachable(iface: string, address: string, reachable: boolean): void;
+    setLowBattery(iface: string, address: string, low: boolean): void;
+    setDutyCycle(iface: string, percent: number): void;
+    setCarrierSense(iface: string, percent: number): void;
+    offerFirmware(iface: string, address: string, version: string): void;
+    listBidcosInterfaces(iface: string): HmSim.BidcosInterface[];
+
+    /* ---------------------------------------------------------------- scenario api: interface processes */
+
+    dropConnection(iface: string): Promise<void>;
+    stopInterface(iface: string): Promise<void>;
+    startInterface(iface: string, options?: {forgetClients?: boolean}): Promise<void>;
+    restartInterface(iface: string, options?: {downMs?: number; forgetClients?: boolean}): Promise<void>;
+    injectFault(rule?: HmSim.InjectedFault): HmSim.InjectedFault;
+    clearFaults(): void;
+    /** Scenario calls on the simulator's timer; resolves with their results. */
+    schedule(steps: HmSim.ScheduleStep[]): Promise<unknown[]>;
+
+    /* ---------------------------------------------------------------- introspection */
+
+    getWriteLog(): HmSim.WriteLogEntry[];
+    getConfigPending(iface: string): HmSim.ConfigPendingEntry[];
+    getPoisonedChannels(iface: string): string[];
+    getMissingParamsetDescriptions(): HmSim.MissingParamsetDescription[];
+    getCallbackLog(): HmSim.CallbackLogEntry[];
+    getTempKey(iface: string): string;
+    getInstallMode(iface: string): number;
+    /** The names of every RPC method. */
+    methodNames(): string[];
+    methodHelp(name: string): string;
+
+    /* ---------------------------------------------------------------- rpc, as the servers call it */
+
+    /** One RPC method as a client call would run it; throws the fault. */
+    callMethod(iface: string, method: string, params?: unknown[]): unknown;
+    getLinks(iface: string, params?: unknown[]): Array<HmSim.Link & Record<string, unknown>>;
+    getLinkPeers(iface: string, params: unknown[]): string[];
+    deleteDevice(iface: string, address: string, flags?: number): '';
+    replaceDevice(iface: string, oldAddress: string, newAddress: string): '';
+    getKeyMismatchDevice(iface: string, params?: [reset?: boolean]): string;
+    suppressServiceMessages(
+        iface: string,
+        params: [channelAddress: string, parameter?: string, suppress?: boolean],
+    ): '';
+    getSuppressedServiceMessages(iface: string, params: [channelAddress: string]): string[];
+    getMetadata(iface: string, params: [address: string, key: string]): unknown;
+    setMetadata(iface: string, params: [address: string, key: string, value: unknown]): '';
+    getAllMetadata(iface: string, params: [address: string]): Record<string, unknown>;
+    listReplaceableDevices(iface: string, params: [address: string]): HmSim.DeviceDescription[] | '';
+    getVersion(iface: string): string;
+    /** Sends one `event` to every client of the interface. */
+    event(iface: string, params: HmSim.EventTuple): void;
+}
+
+export = HmSim;