hm-simulator 1.1.0 → 1.3.0

package/lib/sim.js

@@ -16,9 +16,11 @@ const {
     hmipStoredValue,
     bidcosStoredValue,
 } = require('./validate.js');
-const {createBinrpcServer, createXmlrpcServer} = require('./servers.js');
+const {createBinrpcServer, createXmlrpcServer, createDualServer} = require('./servers.js');
 const {resolveTls} = require('./tls.js');
 const RegaSim = require('./rega.js');
+const {ParamsetIndex} = require('./paramset-index.js');
+const {SCENARIO_METHODS} = require('./control.js');
 const METHOD_HELP = require('./method-help.js');
 
 const NOOP_LOG = {
@@ -37,9 +39,18 @@ const PARAMSET_PREFIX = {
     cuxd: 'CUxD',
 };
 
+/** how many calls to registered clients getCallbackLog() keeps */
+const CALLBACK_LOG_SIZE = 10000;
+
 /** the interfaces that speak the BidCos protocol, and therefore have setTempKey */
 const BIDCOS_INTERFACES = new Set(['rfd', 'wired']);
 
+/** device types of the HmIP radio modules, which carry DUTY_CYCLE_LEVEL and CARRIER_SENSE_LEVEL */
+const RADIO_MODULE_TYPES = new Set(['RPI-RF-MOD', 'HmIP-RFUSB', 'HmIP-RFUSB-TK', 'HMIP-CCU3', 'HmIP-CCU3']);
+
+/** the steps of a firmware update after updateFirmware/installFirmware, see offerFirmware() */
+const FIRMWARE_UPDATE_STEPS = ['DO_UPDATE_PENDING', 'PERFORMING_UPDATE', 'UP_TO_DATE'];
+
 /** paramset keys that are not the address of a linked peer channel */
 const STANDARD_PARAMSETS = new Set(['MASTER', 'VALUES', 'SERVICE']);
 
@@ -63,18 +74,48 @@ const SERVICE_FLAG = 8;
  *   'pending' - the write is accepted, the valid parameters are stored, and CONFIG_PENDING is
  *               raised on the device's :0 channel and stays until a valid full MASTER write or
  *               clearConfigCache. The other hypothesis of 1.0; kept so both can still be tested.
+ * listenerModel
+ *   'isolated' - every registered client on its own (the default).
+ *   'measured' - what the interface processes did with a callback server that accepts the
+ *               connection and never answers (measured 2026-09-25 on firmware 3.89.8), see init().
+ * pong, pingDelay
+ *   whether `ping` sends the CENTRAL/PONG event (not on hmip), and after how many milliseconds.
+ * startDelay
+ *   milliseconds after whenReady() until the port accepts connections: a process that starts late.
+ * deliveryTimeout
+ *   'measured' BidCos only: milliseconds after which an unanswered callback drops the client.
+ * unreachWrites
+ *   what a setValue/putParamset to an unreachable device answers: 'accept' (the default) or
+ *   'fault' (notReachable). The simulator's model; not measured yet.
+ * firmwareUpdateDelay
+ *   milliseconds per step of a firmware update, see offerFirmware().
+ * protocols
+ *   rfd and wired only: what their port answers, ['binrpc', 'xmlrpc'] (both, as on a CCU) unless
+ *   set; ['binrpc'] is the BIN-RPC-only server of 1.1.
  * configPendingOnWrite
  *   raise CONFIG_PENDING for every accepted MASTER write, the way a BidCos battery device queues
  *   the configuration until it wakes up. Clears after configPendingDelay milliseconds. Implied by
  *   'bidcos', which raises it for every write that changes something.
  */
 const INTERFACE_DEFAULTS = {
+    // interface process lifecycle, see restartInterface() and the listener models in init()
+    listenerModel: 'isolated',
+    pong: true,
+    pingDelay: 0,
+    startDelay: 0,
+    deliveryTimeout: 10000,
+    // device health, see setReachable() and offerFirmware()
+    unreachWrites: 'accept',
+    firmwareUpdateDelay: 0,
     configPendingMode: 'strict',
     configPendingOnWrite: false,
     configPendingDelay: 0,
     // 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,
 };
 
 /**
@@ -82,11 +123,16 @@ const INTERFACE_DEFAULTS = {
  * the value from INTERFACE_DEFAULTS.
  */
 const MEASURED_INTERFACE_DEFAULTS = {
-    hmip: {configPendingMode: 'hmip'},
-    rfd: {configPendingMode: 'bidcos'},
-    wired: {configPendingMode: 'bidcos'},
+    // hmipserver answers ping without a PONG event, see https://github.com/eq-3/occu/issues/42
+    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: [
@@ -149,9 +195,11 @@ function shortenParams(params) {
  * @param {object} [options.log] object with debug/info/warn/error methods
  * @param {object} [options.devices] {<iface>: {devices: []}} - device descriptions per interface
  * @param {object} [options.config] listenAddress, binrpcListenPort, xmlrpcListenPort
- * @param {string} [options.behaviorPath] directory with behaviour scripts
+ * @param {string|false} [options.behaviorPath] directory with behaviour scripts, `false` for none
  * @param {object} [options.rega] ReGa mock options, see lib/rega.js - omit to not start it
  * @param {object} [options.paramsetDescriptions] replaces the bundled descriptions
+ * @param {boolean} [options.paramsetFallback=true] a device whose firmware has no description uses
+ *        the nearest firmware of the same type and VERSION; `false` for exact keys only
  * @param {object} [options.faults] overrides for the fault table, see lib/faults.js
  */
 class HmSim {
@@ -165,6 +213,10 @@ class HmSim {
 
         this.devices = options.devices || {rfd: {devices: []}, hmip: {devices: []}};
         this.paramsetDescriptions = options.paramsetDescriptions || require('../data/paramset-descriptions.json');
+        this.paramsetFallback = options.paramsetFallback !== false;
+        /** requested key -> the key used for it (a fallback) or null, see resolveParamsetKey() */
+        this.paramsetResolved = new Map();
+        this.paramsetIndex = new ParamsetIndex(this.paramsetDescriptions);
 
         const {table, fault} = createFaults(options.faults);
         this.faults = table;
@@ -192,12 +244,44 @@ class HmSim {
         this.valueUsage = [];
         /** every updateFirmware/installFirmware call */
         this.firmwareUpdates = [];
+        /** every refreshDeployedDeviceFirmwareList call: [{iface, ts}] */
+        this.firmwareListRefreshes = [];
+        /** every changeKey call: [{iface, key, ts}] */
+        this.keyChanges = [];
+        /** the log level of each interface process, see logLevel() */
+        this.logLevels = {};
         /** pending timers, cleared by close() */
         this.timers = new Set();
         /** devices with a pending configuration: {<iface>: Map<deviceAddress, {sticky}>} */
         this.configPending = {};
         /** channels whose stored MASTER carries a parameter the device does not have */
         this.poisonedChannels = {};
+        /** faults waiting for the next matching calls, see injectFault() */
+        this.injectedFaults = [];
+        /** every call the simulator made to a registered client, see getCallbackLog() */
+        this.callbackLog = [];
+        /** per interface: a promise every incoming call waits for while the process is busy */
+        this.gates = {};
+        /** per interface: deliveries held back while a registration hangs, see init() */
+        this.held = {};
+        /** interfaces whose port is closed, see stopInterface() */
+        this.stopped = new Set();
+        /** interfaces that open their port only after `startDelay` */
+        this.delayedStarts = {};
+        /** devices that are unreachable: {<iface>: Set<deviceAddress>}, see setReachable() */
+        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();
 
@@ -231,7 +315,10 @@ class HmSim {
             this.setValue(iface, address, datapoint, value, {internal: true}),
         );
 
-        this.loadBehaviors(options.behaviorPath || path.join(__dirname, '..', 'behaviors'));
+        // `behaviorPath: false`: no behaviour scripts at all
+        if (options.behaviorPath !== false) {
+            this.loadBehaviors(options.behaviorPath || path.join(__dirname, '..', 'behaviors'));
+        }
 
         if (options.rega) {
             // the ReGa mock inherits TLS and basic auth unless its own options say otherwise
@@ -299,10 +386,7 @@ class HmSim {
                 if (this.values[iface][device.ADDRESS].VALUES[name] !== undefined) {
                     continue;
                 }
-                this.values[iface][device.ADDRESS].VALUES[name] =
-                    parameter.TYPE === 'ENUM' && Array.isArray(parameter.VALUE_LIST)
-                        ? parameter.VALUE_LIST.indexOf(parameter.DEFAULT)
-                        : parameter.DEFAULT;
+                this.values[iface][device.ADDRESS].VALUES[name] = defaultValue(parameter);
             }
         }
     }
@@ -345,7 +429,76 @@ class HmSim {
         }
 
         const name = this.paramsetName(iface, device, paramset);
-        return name === undefined ? undefined : this.paramsetDescriptions[name];
+        if (name === undefined) {
+            return undefined;
+        }
+        const key = this.resolveParamsetKey(name);
+        return key === null ? undefined : this.paramsetDescriptions[key];
+    }
+
+    /**
+     * The key whose description stands in for `name`: `name` itself when the set has it, otherwise
+     * the same type, VERSION, channel type and paramset of the nearest firmware (the highest one at
+     * or below the device's, else the lowest above it) unless `paramsetFallback` is off, else null.
+     *
+     * A device reports the firmware it runs, and a description set only has the firmwares somebody
+     * dumped: without this, the bundled `HM-RCV-50` (firmware 2.27.8, descriptions from 2.31.25 on)
+     * answers `Invalid device` for every channel `listDevices` reports (PR #1). Each substitution
+     * and each miss is logged once.
+     *
+     * @param {string} name `<interface>/<type>/<firmware>/<version>/<channelType>/<paramset>`
+     * @returns {string|null}
+     */
+    resolveParamsetKey(name) {
+        if (this.paramsetDescriptions[name]) {
+            return name;
+        }
+        const index = this.currentParamsetIndex();
+        if (this.paramsetResolved.has(name)) {
+            return this.paramsetResolved.get(name);
+        }
+
+        const used = this.paramsetFallback ? index.nearest(name) : null;
+        this.paramsetResolved.set(name, used);
+        if (used) {
+            this.log.warn('paramset description', name, 'missing, using', used);
+        } else {
+            this.log.warn('paramset description', name, 'missing');
+        }
+        return used;
+    }
+
+    /** The firmware index of the descriptions, rebuilt when somebody replaced sim.paramsetDescriptions. */
+    currentParamsetIndex() {
+        if (this.paramsetIndex.descriptions !== this.paramsetDescriptions) {
+            this.paramsetIndex = new ParamsetIndex(this.paramsetDescriptions);
+            this.paramsetResolved.clear();
+        }
+        return this.paramsetIndex;
+    }
+
+    /**
+     * Every paramset the devices announce in `PARAMSETS` whose description is not in the set under
+     * its exact key, with the key the simulator uses instead (`null`: none, the paramset faults).
+     * An empty list means the device data and the descriptions match exactly.
+     *
+     * @returns {Array<{iface: string, key: string, usedKey: string|null}>}
+     */
+    getMissingParamsetDescriptions() {
+        const missing = new Map();
+        for (const iface of this.ifaces) {
+            for (const device of this.devices[iface].devices) {
+                for (const paramset of device.PARAMSETS || []) {
+                    const key = this.paramsetName(iface, device, paramset);
+                    if (key === undefined || this.paramsetDescriptions[key] || missing.has(`${iface} ${key}`)) {
+                        continue;
+                    }
+                    const usedKey = this.paramsetFallback ? this.currentParamsetIndex().nearest(key) : null;
+                    missing.set(`${iface} ${key}`, {iface, key, usedKey});
+                }
+            }
+        }
+        return [...missing.values()];
     }
 
     /* ------------------------------------------------------------------ paramsets */
@@ -414,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);
     }
 
     /**
@@ -427,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;
     }
 
     /**
@@ -905,10 +1066,9 @@ class HmSim {
 
     listBidcosInterfaces(iface) {
         const configured = this.options.bidcosInterfaces && this.options.bidcosInterfaces[iface];
-        if (configured) {
-            return configured;
-        }
-        return DEFAULT_BIDCOS_INTERFACES[iface] || DEFAULT_BIDCOS_INTERFACES.rfd;
+        const list = configured || DEFAULT_BIDCOS_INTERFACES[iface] || DEFAULT_BIDCOS_INTERFACES.rfd;
+        const radio = this.radio[iface];
+        return radio ? list.map((entry) => ({...entry, ...radio})) : list;
     }
 
     setBidcosInterface(iface, params) {
@@ -930,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');
@@ -938,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]);
             }
@@ -980,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 '';
     }
 
@@ -1014,6 +1466,67 @@ class HmSim {
         return '';
     }
 
+    /**
+     * `logLevel(level)` - rfd and hs485d set their log level and answer it; without a level they
+     * answer the one in force (5 on the rfd measured 2026-09-28). hmipserver lists the
+     * method but answers it with an empty HTTP body; the simulator answers an empty string there.
+     * Elsewhere unknown-method.
+     *
+     * @param {string} iface
+     * @param {Array} params [level]
+     */
+    logLevel(iface, params) {
+        if (iface === 'hmip') {
+            return '';
+        }
+        if (!BIDCOS_INTERFACES.has(iface)) {
+            throw this.fault('unknownMethod', `${iface}/logLevel`);
+        }
+        const [level] = params || [];
+        if (level !== undefined) {
+            if (!Number.isInteger(level)) {
+                throw this.fault('invalidArguments', 'logLevel wants an integer');
+            }
+            this.logLevels[iface] = level;
+        }
+        return this.logLevels[iface] === undefined ? 5 : this.logLevels[iface];
+    }
+
+    /**
+     * `changeKey(passphrase)` - the interface's security key. rfd stores it and re-keys every
+     * AES-capable device; hmipserver lists the method too. The simulator does no cryptography: the
+     * call is recorded in `sim.keyChanges` (`{iface, key, ts}`) and answered with an empty string.
+     * BidCos-Wired has no such method (unknown-method).
+     *
+     * @param {string} iface
+     * @param {Array} params [passphrase]
+     */
+    changeKey(iface, params) {
+        if (iface !== 'rfd' && iface !== 'hmip') {
+            throw this.fault('unknownMethod', `${iface}/changeKey`);
+        }
+        const [key] = params || [];
+        if (typeof key !== 'string') {
+            throw this.fault('invalidArguments', 'changeKey wants a string');
+        }
+        this.keyChanges.push({iface, key, ts: Date.now()});
+        this.log.info(iface, 'security key changed');
+        return '';
+    }
+
+    /**
+     * `refreshDeployedDeviceFirmwareList()` - rfd and hmipserver read the directory of deployed
+     * device firmware again and answer an empty value (measured 2026-09-28); hs485d and
+     * VirtualDevices have no such method. Recorded in `sim.firmwareListRefreshes`.
+     */
+    refreshDeployedDeviceFirmwareList(iface) {
+        if (iface !== 'rfd' && iface !== 'hmip') {
+            throw this.fault('unknownMethod', `${iface}/refreshDeployedDeviceFirmwareList`);
+        }
+        this.firmwareListRefreshes.push({iface, ts: Date.now()});
+        return '';
+    }
+
     /* ------------------------------------------------------------------ teams */
 
     /**
@@ -1169,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);
@@ -1237,6 +1756,9 @@ class HmSim {
             this.requireDevice(iface, address);
         }
         this.firmwareUpdates.push({iface, addresses, method: 'updateFirmware', ts: Date.now()});
+        for (const address of addresses) {
+            this.performFirmwareUpdate(iface, address);
+        }
         return true;
     }
 
@@ -1244,6 +1766,7 @@ class HmSim {
         const address = params[0];
         this.requireDevice(iface, address);
         this.firmwareUpdates.push({iface, addresses: [address], method: 'installFirmware', ts: Date.now()});
+        this.performFirmwareUpdate(iface, address);
         return true;
     }
 
@@ -1322,6 +1845,212 @@ class HmSim {
         return added;
     }
 
+    /* ------------------------------------------------------------------ device and radio health */
+
+    /** The device of an address, its maintenance channel `:0` and that channel's VALUES description. */
+    maintenanceOf(iface, address) {
+        const entry = this.requireDevice(iface, address);
+        const device = entry.PARENT ? this.requireDevice(iface, entry.PARENT) : entry;
+        const channel = `${device.ADDRESS}:0`;
+        const description =
+            (this.index[iface].has(channel) && this.getParamsetDescription(iface, channel, 'VALUES')) || {};
+        return {device, channel, description};
+    }
+
+    /**
+     * Reports a datapoint of the maintenance channel: stored and sent the way the description says
+     * (a service message by its FLAGS), or - when the description does not have it - as an event and
+     * a service message raised through setServiceMessage().
+     */
+    reportMaintenance(iface, channel, description, datapoint, value) {
+        if (description[datapoint]) {
+            this.setValue(iface, channel, datapoint, value, {internal: true});
+            return;
+        }
+        if (typeof value === 'boolean') {
+            this.setServiceMessage(iface, channel, datapoint, value);
+        }
+        this.fireEvent(iface, channel, datapoint, value);
+    }
+
+    /**
+     * A device goes out of reach or comes back: `UNREACH` on its `:0` channel, and on the BidCos
+     * interfaces `STICKY_UNREACH`, which stays after the device is back until a client writes it
+     * `false` - as rfd does. What a write to the device answers meanwhile is the `unreachWrites`
+     * option ('accept', or 'fault' with notReachable).
+     *
+     * @param {string} iface
+     * @param {string} address the device or one of its channels
+     * @param {boolean} reachable
+     */
+    setReachable(iface, address, reachable) {
+        const {device, channel, description} = this.maintenanceOf(iface, address);
+        const unreachable = (this.unreachable[iface] = this.unreachable[iface] || new Set());
+        if (reachable) {
+            unreachable.delete(device.ADDRESS);
+        } else {
+            unreachable.add(device.ADDRESS);
+        }
+        this.reportMaintenance(iface, channel, description, 'UNREACH', !reachable);
+        const sticky = description.STICKY_UNREACH || (BIDCOS_INTERFACES.has(iface) && !description.UNREACH);
+        if (!reachable && sticky) {
+            this.reportMaintenance(iface, channel, description, 'STICKY_UNREACH', true);
+        }
+        this.log.info(iface, device.ADDRESS, reachable ? 'reachable again' : 'unreachable');
+    }
+
+    /** Throws notReachable for a write to an unreachable device when `unreachWrites` is 'fault'. */
+    requireReachable(iface, address) {
+        if (this.interfaceOption(iface, 'unreachWrites') !== 'fault' || !this.unreachable[iface]) {
+            return;
+        }
+        const entry = this.index[iface] && this.index[iface].get(address);
+        const deviceAddress = entry ? entry.PARENT || entry.ADDRESS : address;
+        if (this.unreachable[iface].has(deviceAddress)) {
+            throw this.fault('notReachable', address);
+        }
+    }
+
+    /**
+     * Low battery: `LOW_BAT` or `LOWBAT` on the device's `:0` channel, whichever its description has
+     * (`LOW_BAT` on hmip, `LOWBAT` on BidCos without one).
+     */
+    setLowBattery(iface, address, low) {
+        const {channel, description} = this.maintenanceOf(iface, address);
+        let datapoint = iface === 'hmip' ? 'LOW_BAT' : 'LOWBAT';
+        if (description.LOW_BAT) {
+            datapoint = 'LOW_BAT';
+        } else if (description.LOWBAT) {
+            datapoint = 'LOWBAT';
+        }
+        this.reportMaintenance(iface, channel, description, datapoint, Boolean(low));
+    }
+
+    /**
+     * The radio module of an interface, if the device list has it: the device whose address is the
+     * last 14 characters of the interface's address (an SGTIN), or one of a radio module's types.
+     */
+    radioModule(iface) {
+        const address = String((this.listBidcosInterfaces(iface)[0] || {}).ADDRESS || '');
+        const devices = this.deviceList(iface);
+        return (
+            devices.find((device) => device.ADDRESS === address.slice(-14) || device.ADDRESS === address) ||
+            devices.find((device) => RADIO_MODULE_TYPES.has(device.TYPE))
+        );
+    }
+
+    /**
+     * Sets a radio level of an interface: in what `listBidcosInterfaces` answers, and on hmip as
+     * the event of the radio module's `:0` channel, when the device list has a radio module.
+     */
+    setRadioLevel(iface, field, datapoint, percent) {
+        if (typeof percent !== 'number' || Number.isNaN(percent)) {
+            throw new TypeError(`${field} wants a number`);
+        }
+        this.radio[iface] = {...this.radio[iface], [field]: percent};
+        const module = iface === 'hmip' ? this.radioModule(iface) : undefined;
+        if (module) {
+            const {channel, description} = this.maintenanceOf(iface, module.ADDRESS);
+            this.reportMaintenance(iface, channel, description, datapoint, percent);
+        }
+    }
+
+    /** The duty cycle of an interface in percent: `DUTY_CYCLE`, on hmip also `DUTY_CYCLE_LEVEL`. */
+    setDutyCycle(iface, percent) {
+        this.setRadioLevel(iface, 'DUTY_CYCLE', 'DUTY_CYCLE_LEVEL', percent);
+    }
+
+    /** The carrier sense level of an interface in percent: `CARRIER_SENSE_LEVEL`. */
+    setCarrierSense(iface, percent) {
+        this.setRadioLevel(iface, 'CARRIER_SENSE_LEVEL', 'CARRIER_SENSE_LEVEL', percent);
+    }
+
+    /**
+     * A firmware update becomes available for a device: `AVAILABLE_FIRMWARE`,
+     * `FIRMWARE_UPDATE_STATE: 'NEW_FIRMWARE_AVAILABLE'` and `UPDATABLE` in its description,
+     * `UPDATE_PENDING` on `:0` where the description has it, and `updateDevice` to the clients.
+     * A following `updateFirmware`/`installFirmware` walks `FIRMWARE_UPDATE_STATE` through
+     * DO_UPDATE_PENDING, PERFORMING_UPDATE and UP_TO_DATE, one step per `firmwareUpdateDelay`, and
+     * sets `FIRMWARE` at the end. The state names are the RPC specification's; the timing is a model.
+     *
+     * @param {string} iface
+     * @param {string} address the device
+     * @param {string} version
+     */
+    offerFirmware(iface, address, version) {
+        const device = this.requireDevice(iface, address);
+        if (device.PARENT) {
+            throw this.fault('notSupported', 'firmware is offered to a device, not a channel');
+        }
+        device.AVAILABLE_FIRMWARE = String(version);
+        device.FIRMWARE_UPDATE_STATE = 'NEW_FIRMWARE_AVAILABLE';
+        device.UPDATABLE = device.UPDATABLE === undefined ? 1 : device.UPDATABLE;
+        const {channel, description} = this.maintenanceOf(iface, address);
+        if (description.UPDATE_PENDING) {
+            this.setValue(iface, channel, 'UPDATE_PENDING', true, {internal: true});
+        }
+        this.tellClientsParams(iface, 'updateDevice', [address, 0]);
+    }
+
+    performFirmwareUpdate(iface, address) {
+        const device = this.index[iface].get(address);
+        if (!device || device.PARENT || device.FIRMWARE_UPDATE_STATE !== 'NEW_FIRMWARE_AVAILABLE') {
+            return;
+        }
+        const delay = this.interfaceOption(iface, 'firmwareUpdateDelay');
+        const step = (index) => {
+            // the device can be gone by now
+            if (this.index[iface].get(address) !== device) {
+                return;
+            }
+            device.FIRMWARE_UPDATE_STATE = FIRMWARE_UPDATE_STEPS[index];
+            if (index === FIRMWARE_UPDATE_STEPS.length - 1) {
+                device.FIRMWARE = device.AVAILABLE_FIRMWARE;
+                const {channel, description} = this.maintenanceOf(iface, address);
+                if (description.UPDATE_PENDING) {
+                    this.setValue(iface, channel, 'UPDATE_PENDING', false, {internal: true});
+                }
+                this.log.info(iface, address, 'firmware', device.FIRMWARE);
+            } else {
+                this.timer(() => step(index + 1), delay);
+            }
+            this.tellClientsParams(iface, 'updateDevice', [address, 0]);
+        };
+        this.timer(() => step(0), delay);
+    }
+
+    /**
+     * Runs scenario calls on the simulator's timer: `[{at: ms, call: 'setReachable', args: [...]}]`,
+     * `at` counted from now. Resolves with the results once every step ran; `close()` cancels what
+     * did not run yet (and the promise then never resolves).
+     *
+     * @param {Array<{at: number, call: string, args: Array}>} steps
+     * @returns {Promise<Array>}
+     */
+    schedule(steps) {
+        const list = steps || [];
+        for (const step of list) {
+            if (!SCENARIO_METHODS.has(step.call) || step.call === 'schedule' || typeof this[step.call] !== 'function') {
+                throw new Error(`schedule: ${step.call} is no scenario call`);
+            }
+        }
+        return Promise.all(
+            list.map(
+                (step) =>
+                    new Promise((resolve) => {
+                        this.timer(async () => {
+                            try {
+                                resolve(await this[step.call](...(step.args || [])));
+                            } catch (error) {
+                                this.log.error('schedule', step.call, error.message);
+                                resolve(error);
+                            }
+                        }, step.at || 0);
+                    }),
+            ),
+        );
+    }
+
     /* ------------------------------------------------------------------ scenario api */
 
     /**
@@ -1385,7 +2114,10 @@ class HmSim {
 
         const port = this.ports[iface];
         this.log.info(iface, 'dropping all connections');
-        await server.close();
+        if (!this.stopped.has(iface)) {
+            await server.close();
+        }
+        this.stopped.delete(iface);
 
         this.ready = [];
         this.servers[iface] = factory(port);
@@ -1393,6 +2125,109 @@ class HmSim {
         await this.whenReady();
     }
 
+    /**
+     * Stops an interface process: its port refuses connections, open connections are reset. The
+     * registered clients stay known until startInterface() decides what the process remembers.
+     *
+     * @param {string} iface
+     * @returns {Promise<void>} once the port is closed
+     */
+    async stopInterface(iface) {
+        const server = this.servers[iface];
+        if (!server || this.stopped.has(iface)) {
+            return;
+        }
+        this.stopped.add(iface);
+        this.log.info(iface, 'interface process stopped');
+        await server.close();
+    }
+
+    /**
+     * Starts a stopped interface process again on the same port.
+     *
+     * With `forgetClients` (the default) the registered clients are forgotten, as by a process
+     * that keeps no list of them: no event reaches a client until it calls `init` again, and
+     * nothing tells it. Without, the process remembers them and calls each back the way rfd does
+     * when it starts with its handlers file: `system.listMethods`, then `listDevices`, and
+     * `newDevices`/`deleteDevices` as at an init - a client sees calls it did not ask for, which is
+     * how it can tell that the process restarted.
+     *
+     * @param {string} iface
+     * @param {object} [options]
+     * @param {boolean} [options.forgetClients=true]
+     * @returns {Promise<void>} once the port accepts connections again
+     */
+    async startInterface(iface, {forgetClients = true} = {}) {
+        const factory = this.serverFactories[iface];
+        if (!factory || !this.stopped.has(iface)) {
+            return;
+        }
+        if (forgetClients) {
+            for (const key of Object.keys(this.clients[iface] || {})) {
+                this.forgetClient(iface, key);
+            }
+        }
+
+        const before = this.ready.length;
+        this.servers[iface] = factory(this.ports[iface]);
+        this.exposeServer(iface);
+        const ready = this.ready.slice(before);
+        this.ready.splice(before);
+        await Promise.all(ready);
+        this.stopped.delete(iface);
+        this.log.info(iface, 'interface process started');
+
+        for (const client of Object.values(this.clients[iface] || {})) {
+            const listDevices = () => this.startInit(iface, client);
+            if (BIDCOS_INTERFACES.has(iface)) {
+                client.methodCall('system.listMethods', [client.id], listDevices);
+            } else {
+                listDevices();
+            }
+        }
+    }
+
+    /**
+     * An interface process restarts: stopInterface(), `downMs` with the port closed,
+     * startInterface(). See startInterface() for `forgetClients`.
+     *
+     * @param {string} iface
+     * @param {object} [options]
+     * @param {number} [options.downMs=0]
+     * @param {boolean} [options.forgetClients=true]
+     * @returns {Promise<void>} once the port accepts connections again
+     */
+    async restartInterface(iface, {downMs = 0, forgetClients = true} = {}) {
+        await this.stopInterface(iface);
+        if (downMs > 0) {
+            await new Promise((resolve) => this.timer(resolve, downMs));
+        }
+        await this.startInterface(iface, {forgetClients});
+    }
+
+    /**
+     * Sends a burst of events the way the interface processes do, as `system.multicall` batches.
+     *
+     * @param {string} iface
+     * @param {Array<Array>} events `[[address, datapoint, value], ...]`, not validated
+     * @param {object} [options]
+     * @param {number} [options.batch] events per multicall, all in one when omitted
+     */
+    fireEvents(iface, events, {batch} = {}) {
+        const list = events || [];
+        for (const [address, datapoint, value] of list) {
+            const state = this.values[iface] && this.values[iface][address];
+            if (state) {
+                state.VALUES[datapoint] = value;
+            }
+        }
+        const size = batch > 0 ? batch : list.length;
+        for (let index = 0; index < list.length; index += size) {
+            this.eventMulticall(iface, list.slice(index, index + size));
+        }
+        return list.length;
+    }
+
     /**
      * Raises or clears a service message. If the channel has the datapoint in its VALUES
      * description the value is written as well, so that the logic layer sees the event too.
@@ -1439,10 +2274,88 @@ class HmSim {
     tellClientsParams(iface, method, params) {
         for (const key of Object.keys(this.clients[iface] || {})) {
             const client = this.clients[iface][key];
-            client.methodCall(method, [client.id, ...params]);
+            this.deliver(iface, client, method, [client.id, ...params]);
+        }
+    }
+
+    /**
+     * One call to one registered client: held back while a registration of the interface hangs
+     * (the 'measured' hmip model), and under the 'measured' BidCos model the client is dropped when
+     * it does not answer within `deliveryTimeout`.
+     */
+    deliver(iface, client, method, params) {
+        const held = this.held[iface];
+        if (held && held.count > 0) {
+            held.queue.push(() => this.deliver(iface, client, method, params));
+            return;
+        }
+        const measuredBidcos =
+            BIDCOS_INTERFACES.has(iface) && this.interfaceOption(iface, 'listenerModel') === 'measured';
+        if (!measuredBidcos) {
+            client.methodCall(method, params);
+            return;
+        }
+        client.methodCall(
+            method,
+            params,
+            (error) => {
+                if (error && this.clients[iface][client.key] === client) {
+                    this.log.warn(iface, 'client', client.url, 'did not take', method, '- dropped:', error.message);
+                    this.forgetClient(iface, client.key);
+                }
+            },
+            {timeout: this.interfaceOption(iface, 'deliveryTimeout')},
+        );
+    }
+
+    forgetClient(iface, key) {
+        const client = this.clients[iface] && this.clients[iface][key];
+        if (client) {
+            closeClient(client.client);
+            delete this.clients[iface][key];
         }
     }
 
+    /** Holds every delivery of an interface back until the returned function is called. */
+    hold(iface) {
+        const held = (this.held[iface] = this.held[iface] || {count: 0, queue: []});
+        held.count++;
+        let released = false;
+        return () => {
+            if (released) {
+                return;
+            }
+            released = true;
+            held.count--;
+            if (held.count === 0) {
+                const queue = held.queue.splice(0);
+                for (const send of queue) {
+                    send();
+                }
+            }
+        };
+    }
+
+    /**
+     * Makes every incoming call of an interface wait until the returned function is called - the
+     * interface process is busy with something that does not return.
+     */
+    closeGate(iface) {
+        let release;
+        const gate = new Promise((resolve) => {
+            release = resolve;
+        });
+        const previous = this.gates[iface];
+        const combined = previous ? Promise.all([previous, gate]) : gate;
+        this.gates[iface] = combined;
+        return () => {
+            release();
+            if (this.gates[iface] === combined) {
+                delete this.gates[iface];
+            }
+        };
+    }
+
     /** A timer that never keeps the process alive and is cleared by close(). */
     timer(callback, ms) {
         const handle = setTimeout(() => {
@@ -1456,6 +2369,13 @@ class HmSim {
         return handle;
     }
 
+    clearTimer(handle) {
+        if (handle) {
+            clearTimeout(handle);
+            this.timers.delete(handle);
+        }
+    }
+
     /**
      * Every putParamset the simulator accepted, oldest first.
      * @returns {Array<{iface: string, address: string, paramset: string, values: object, ts: number}>}
@@ -1476,12 +2396,16 @@ class HmSim {
             getDeviceDescription: (iface, params) => this.getDeviceDescription(iface, params[0]),
             ping: (iface, params) => this.ping(iface, params),
             setValue: (iface, params) => {
+                this.requireReachable(iface, params[0]);
                 this.setValue(iface, params[0], params[1], params[2], {strict: true});
                 return '';
             },
             getValue: (iface, params) => this.getValue(iface, params[0], params[1]),
             getParamset: (iface, params) => this.getParamset(iface, params[0], params[1]),
-            putParamset: (iface, params) => this.putParamset(iface, params[0], params[1], params[2]),
+            putParamset: (iface, params) => {
+                this.requireReachable(iface, params[0]);
+                return this.putParamset(iface, params[0], params[1], params[2]);
+            },
             'system.methodHelp': (iface, params) => this.methodHelp(params[0]),
             getLinks: (iface, params) => this.getLinks(iface, params),
             getLinkPeers: (iface, params) => this.getLinkPeers(iface, params),
@@ -1507,6 +2431,20 @@ class HmSim {
             clearConfigCache: (iface, params) => this.clearConfigCache(iface, params[0]),
             restoreConfigToDevice: (iface, params) => this.restoreConfigToDevice(iface, params[0]),
             determineParameter: (iface, params) => this.determineParameter(iface, params),
+            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
@@ -1521,15 +2459,17 @@ class HmSim {
 
     multicall(iface, params) {
         const calls = (params && params[0]) || [];
+        const asFault = (error) => ({faultCode: error.faultCode, faultString: error.faultString});
         const results = [];
         for (const call of calls) {
             try {
-                results.push([this.callMethod(iface, call.methodName, call.params || [])]);
+                const result = this.callMethod(iface, call.methodName, call.params || []);
+                results.push(isThenable(result) ? result.then((value) => [value], asFault) : [result]);
             } catch (error) {
-                results.push({faultCode: error.faultCode, faultString: error.faultString});
+                results.push(asFault(error));
             }
         }
-        return results;
+        return results.some(isThenable) ? Promise.all(results) : results;
     }
 
     callMethod(iface, method, params) {
@@ -1548,32 +2488,158 @@ class HmSim {
      * @param {Array} params
      * @param {function} callback (fault, result)
      */
-    dispatch(iface, method, params, callback) {
+    dispatch(iface, method, params, callback, context = {}) {
         this.log.debug('rpc', iface, '<', method, shortenParams(params));
-        let result;
-        try {
-            result = this.callMethod(iface, method, params);
-        } catch (error) {
+        const gate = this.gates[iface];
+        if (gate) {
+            gate.then(() => this.dispatchNow(iface, method, params, callback, context));
+            return;
+        }
+        this.dispatchNow(iface, method, params, callback, context);
+    }
+
+    dispatchNow(iface, method, params, callback, context) {
+        const injected = this.takeInjectedFault(iface, method);
+        if (!injected) {
+            this.execute(iface, method, params, callback);
+            return;
+        }
+
+        const act = () => {
+            if (injected.hang) {
+                this.log.info('rpc', iface, method, 'injected: never answered');
+                return;
+            }
+            if (injected.closeSocket) {
+                this.log.info('rpc', iface, method, 'injected: connection closed');
+                if (context.socket) {
+                    context.socket.destroy();
+                }
+                return;
+            }
+            if (injected.fault !== undefined) {
+                callback(this.injectedFaultOf(injected.fault, method));
+                return;
+            }
+            this.execute(iface, method, params, callback);
+        };
+        if (injected.delayMs > 0) {
+            this.timer(act, injected.delayMs);
+        } else {
+            act();
+        }
+    }
+
+    execute(iface, method, params, callback) {
+        const failed = (error) => {
             if (error.faultCode === undefined) {
                 this.log.error('rpc', iface, method, error.stack || error.message);
                 callback(this.fault('invalidArguments', error.message));
                 return;
             }
             callback(error);
+        };
+        let result;
+        try {
+            result = this.callMethod(iface, method, params);
+        } catch (error) {
+            failed(error);
+            return;
+        }
+        if (isThenable(result)) {
+            result.then((value) => callback(null, value === undefined ? '' : value), failed);
             return;
         }
         callback(null, result);
     }
 
-    init(iface, params) {
-        const [url, id] = params;
-        let [protocol, host, port] = String(url).split(':');
-        host = host.replace(/^\/\//, '');
-        if (protocol === 'xmlrpc_bin') {
-            protocol = 'binrpc';
+    /* ------------------------------------------------------------------ fault injection */
+
+    /**
+     * Makes the next calls of a method misbehave.
+     *
+     * @param {object} rule
+     * @param {string} [rule.iface] the interface, every one when omitted
+     * @param {string} [rule.method='*'] the method, `'*'` for any
+     * @param {number} [rule.times=1] how many calls, `Infinity` or `-1` for all until clearFaults()
+     * @param {number} [rule.delayMs] answer (or misbehave) only after this many milliseconds
+     * @param {boolean} [rule.hang] never answer; the connection stays open
+     * @param {boolean} [rule.closeSocket] close the connection instead of answering
+     * @param {object|string} [rule.fault] answer this fault: `{faultCode, faultString}` or the name
+     *        of an entry of the fault table (`'unknownInstance'`, `'notReachable'`, ...)
+     */
+    injectFault(rule = {}) {
+        const entry = {method: '*', times: 1, ...rule};
+        if (entry.fault !== undefined) {
+            // check now, not when the call arrives
+            this.injectedFaultOf(entry.fault, entry.method);
+        }
+        this.injectedFaults.push(entry);
+        return entry;
+    }
+
+    /** Removes every injected fault that did not happen yet. */
+    clearFaults() {
+        this.injectedFaults = [];
+    }
+
+    takeInjectedFault(iface, method) {
+        const index = this.injectedFaults.findIndex(
+            (rule) =>
+                (rule.iface === undefined || rule.iface === iface) && (rule.method === '*' || rule.method === method),
+        );
+        if (index === -1) {
+            return undefined;
+        }
+        const rule = this.injectedFaults[index];
+        // Infinity or a negative number: until clearFaults() (-1 is what JSON can carry)
+        if (rule.times !== Infinity && rule.times >= 0) {
+            rule.times--;
+            if (rule.times <= 0) {
+                this.injectedFaults.splice(index, 1);
+            }
+        }
+        return rule;
+    }
+
+    injectedFaultOf(fault, method) {
+        if (typeof fault === 'string') {
+            if (!this.faults[fault]) {
+                throw new Error(`no fault ${fault} in the fault table`);
+            }
+            return this.fault(fault, `injected into ${method}`);
         }
+        if (!fault || typeof fault.faultCode !== 'number') {
+            throw new Error('an injected fault is a name of the fault table or {faultCode, faultString}');
+        }
+        return {faultCode: fault.faultCode, faultString: fault.faultString || ''};
+    }
 
-        const clientId = [host, port].join(':');
+    /**
+     * Every call the simulator made to a registered client, oldest first (the last 10000):
+     * `{iface, client, method, sentAt, answeredAt, error}`. `answeredAt` is null while the client
+     * has not answered, `error` the transport error or timeout.
+     */
+    getCallbackLog() {
+        return this.callbackLog.map((entry) => ({...entry}));
+    }
+
+    /**
+     * `init(url, interfaceId)` - registers a logic layer, or with an empty id removes it.
+     *
+     * The url is `xmlrpc_bin://host:port` or `binrpc://…` for BIN-RPC callbacks, `http://` or
+     * `https://host:port/path` for XML-RPC ones (the path is kept: a callback server may serve
+     * several interfaces on one port). A registration is identified by the url exactly, scheme and
+     * path included, as the interface processes do: `init('http://h:1', '')` does not remove a
+     * `xmlrpc_bin://h:1` registration.
+     */
+    init(iface, params) {
+        const [url, id] = params || [];
+        const parsed = parseCallbackUrl(url);
+        if (!parsed) {
+            throw this.fault('invalidArguments', `init url ${url}`);
+        }
+        const clientId = String(url);
 
         if (id === '' || id === undefined) {
             const client = this.clients[iface][clientId];
@@ -1583,21 +2649,12 @@ class HmSim {
                 delete this.clients[iface][clientId];
             }
         } else {
-            const transport = protocol === 'binrpc' ? binrpc : xmlrpc;
-            const client = {
-                id,
-                url,
-                client: transport.createClient({host, port}),
-                methodCall: (methodName, methodParams, callback) => {
-                    this.log.debug('rpc >', url, methodName, shortenParams(methodParams));
-                    client.client.methodCall(methodName, methodParams, (error, result) => {
-                        this.log.debug('rpc <', url, shortenParams(result));
-                        if (typeof callback === 'function') {
-                            callback(error, result);
-                        }
-                    });
-                },
-            };
+            const client = this.createClient(iface, parsed, url, id, clientId);
+            if (this.interfaceOption(iface, 'listenerModel') === 'measured') {
+                return BIDCOS_INTERFACES.has(iface)
+                    ? this.initMeasuredBidcos(iface, client)
+                    : this.initMeasuredHmip(iface, client);
+            }
             this.clients[iface][clientId] = client;
             this.startInit(iface, client);
         }
@@ -1605,14 +2662,134 @@ class HmSim {
         return '';
     }
 
+    /** A registered logic layer: its RPC client, and a methodCall that logs and can time out. */
+    createClient(iface, {protocol, host, port, path}, url, id, key) {
+        let rpcClient;
+        if (protocol === 'binrpc') {
+            rpcClient = binrpc.createClient({host, port});
+        } else if (protocol === 'https') {
+            rpcClient = xmlrpc.createSecureClient({host, port, path, rejectUnauthorized: false});
+        } else {
+            rpcClient = xmlrpc.createClient({host, port, path});
+        }
+        const client = {
+            id,
+            url,
+            key,
+            client: rpcClient,
+            methodCall: (methodName, methodParams, callback, {timeout} = {}) => {
+                this.log.debug('rpc >', url, methodName, shortenParams(methodParams));
+                const entry = {
+                    iface,
+                    client: url,
+                    method: methodName,
+                    sentAt: Date.now(),
+                    answeredAt: null,
+                    error: null,
+                };
+                this.logCallback(entry);
+                let done = false;
+                let timer;
+                const finish = (error, result) => {
+                    if (done) {
+                        return;
+                    }
+                    done = true;
+                    this.clearTimer(timer);
+                    entry.answeredAt = Date.now();
+                    entry.error = error ? String(error.message || error) : null;
+                    this.log.debug('rpc <', url, error ? error.message : shortenParams(result));
+                    if (typeof callback === 'function') {
+                        callback(error, result);
+                    }
+                };
+                if (timeout > 0) {
+                    timer = this.timer(() => finish(new Error(`no answer within ${timeout} ms`)), timeout);
+                }
+                client.client.methodCall(methodName, methodParams, finish);
+            },
+        };
+        return client;
+    }
+
+    logCallback(entry) {
+        this.callbackLog.push(entry);
+        if (this.callbackLog.length > CALLBACK_LOG_SIZE) {
+            this.callbackLog.splice(0, this.callbackLog.length - CALLBACK_LOG_SIZE);
+        }
+    }
+
+    /**
+     * rfd's `init`, as measured with a callback server that never answers (firmware 3.89.8,
+     * 2026-09-25): rfd calls `system.listMethods` back *before* it answers the `init`, and until
+     * that callback returns, rfd answers nothing else at all - every other client's calls wait.
+     * When the callback fails (the connection ended), rfd tries it three more times at once and
+     * registers the client anyway. A registered client that does not take a callback within
+     * `deliveryTimeout` (10 s measured) is dropped. That `listDevices` also comes before the
+     * answer is the model of the simulator, as the rest of the init sequence.
+     */
+    initMeasuredBidcos(iface, client) {
+        const release = this.closeGate(iface);
+        return new Promise((resolve) => {
+            const listMethods = (attempt) => {
+                client.methodCall('system.listMethods', [client.id], (error) => {
+                    if (error && attempt < 4) {
+                        listMethods(attempt + 1);
+                        return;
+                    }
+                    this.clients[iface][client.key] = client;
+                    client.methodCall('listDevices', [client.id], (listError, clientDevices) => {
+                        release();
+                        resolve('');
+                        if (!listError) {
+                            this.checkDevices(iface, client, clientDevices);
+                        }
+                    });
+                });
+            };
+            listMethods(1);
+        });
+    }
+
+    /**
+     * hmipserver's `init`, as measured (firmware 3.89.8, 2026-09-25): the call is answered at
+     * once and `listDevices` is called back afterwards. While that callback hangs, hmipserver
+     * delivers **no event to any client** of the interface - they are queued and follow when the
+     * connection ends, and the client that hung is not called again. After a registration
+     * finished, a client that stops answering holds up only itself.
+     */
+    initMeasuredHmip(iface, client) {
+        this.clients[iface][client.key] = client;
+        const release = this.hold(iface);
+        client.methodCall('listDevices', [client.id], (error, clientDevices) => {
+            if (error) {
+                this.log.warn(iface, 'client', client.url, 'failed at listDevices - not registered:', error.message);
+                if (this.clients[iface][client.key] === client) {
+                    this.forgetClient(iface, client.key);
+                }
+            } else {
+                this.checkDevices(iface, client, clientDevices);
+            }
+            release();
+        });
+        return '';
+    }
+
+    /**
+     * `ping(callerId)` - the BidCos processes answer with a `CENTRAL`/`PONG` event to *every*
+     * registered client, hmipserver sends none (`pong: false`). `pingDelay` delays the event.
+     */
     ping(iface, params) {
-        if (iface === 'hmip') {
-            // hmipserver does not answer ping with a PONG event, see
-            // https://github.com/eq-3/occu/issues/42
+        if (!this.interfaceOption(iface, 'pong')) {
             return '';
         }
-
-        this.event(iface, ['CENTRAL', 'PONG', params[0]]);
+        const pong = () => this.event(iface, ['CENTRAL', 'PONG', (params || [])[0]]);
+        const delay = this.interfaceOption(iface, 'pingDelay');
+        if (delay > 0) {
+            this.timer(pong, delay);
+        } else {
+            pong();
+        }
         return '';
     }
 
@@ -1626,7 +2803,7 @@ class HmSim {
     event(iface, params) {
         for (const key of Object.keys(this.clients[iface] || {})) {
             const client = this.clients[iface][key];
-            client.methodCall('event', [client.id, ...params]);
+            this.deliver(iface, client, 'event', [client.id, ...params]);
         }
     }
 
@@ -1637,7 +2814,7 @@ class HmSim {
                 methodName: 'event',
                 params: [client.id, singleEvent[0], singleEvent[1], singleEvent[2]],
             }));
-            client.methodCall('system.multicall', [multicall]);
+            this.deliver(iface, client, 'system.multicall', [multicall]);
         }
     }
 
@@ -1737,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);
         }
     }
@@ -1764,7 +2945,8 @@ class HmSim {
             return createBinrpcServer({
                 host: listenAddress,
                 port,
-                dispatch: (method, params, callback) => this.dispatch(iface, method, params, callback),
+                dispatch: (method, params, callback, context) =>
+                    this.dispatch(iface, method, params, callback, context),
                 onListening,
                 onError,
             });
@@ -1778,7 +2960,28 @@ class HmSim {
                 path,
                 tls: this.tls,
                 auth,
-                dispatch: (method, params, callback) => this.dispatch(iface, method, params, callback),
+                dispatch: (method, params, callback, context) =>
+                    this.dispatch(iface, method, params, callback, context),
+                onListening,
+                onError,
+            });
+        };
+
+        // rfd and hs485d answer BIN-RPC and XML-RPC on the same port; `protocols` narrows it
+        const bidcosServer = (iface, port, label) => {
+            const protocols = this.interfaceOption(iface, 'protocols') || ['binrpc', 'xmlrpc'];
+            if (protocols.length === 1 && protocols[0] === 'binrpc') {
+                return binrpcServer(iface, port, `${label} binrpc`);
+            }
+            const {onListening, onError} = this.listeningCallbacks(iface, label, listenAddress);
+            return createDualServer({
+                host: listenAddress,
+                port,
+                protocols,
+                tls: this.tls,
+                auth,
+                dispatch: (method, params, callback, context) =>
+                    this.dispatch(iface, method, params, callback, context),
                 onListening,
                 onError,
             });
@@ -1786,17 +2989,20 @@ class HmSim {
 
         // the factory of an interface is kept so that dropConnection() can restart its server
         const start = (iface, port, factory) => {
+            if (this.interfaceOption(iface, 'startDelay') > 0) {
+                this.delayedStarts[iface] = this.interfaceOption(iface, 'startDelay');
+            }
             this.serverFactories[iface] = factory;
             this.servers[iface] = factory(port);
             this.exposeServer(iface);
         };
 
         if (this.devices.rfd) {
-            start('rfd', binrpcListenPort, (port) => binrpcServer('rfd', port, 'rfd binrpc'));
+            start('rfd', binrpcListenPort, (port) => bidcosServer('rfd', port, 'rfd'));
         }
 
         if (this.devices.wired) {
-            start('wired', this.config.wiredListenPort, (port) => binrpcServer('wired', port, 'wired binrpc'));
+            start('wired', this.config.wiredListenPort, (port) => bidcosServer('wired', port, 'wired'));
         }
 
         if (this.devices.hmip) {
@@ -1839,6 +3045,15 @@ class HmSim {
                 const port = serverPort(server);
                 this.ports[iface] = port;
                 this.log.info(label, 'server listening on', host, port);
+                const delay = this.delayedStarts[iface];
+                if (delay !== undefined) {
+                    // the port is known now; it refuses connections until the delay is over
+                    delete this.delayedStarts[iface];
+                    this.stopped.add(iface);
+                    server.close();
+                    this.log.info(label, 'starts in', delay, 'ms');
+                    this.timer(() => this.startInterface(iface, {forgetClients: false}), delay);
+                }
                 resolve();
             },
             onError: (error) => {
@@ -1881,8 +3096,9 @@ class HmSim {
             clearTimeout(handle);
         }
         this.timers.clear();
-        for (const server of Object.values(this.servers)) {
-            if (typeof server.close === 'function') {
+        for (const [iface, server] of Object.entries(this.servers)) {
+            // a stopped server is closed already, and binrpc's close() rejects a second time
+            if (typeof server.close === 'function' && !this.stopped.has(iface)) {
                 server.close();
             }
         }
@@ -1907,6 +3123,32 @@ function serverPort(server) {
     return address ? address.port : undefined;
 }
 
+/**
+ * The parts of a callback url: `{protocol: 'binrpc'|'http'|'https', host, port, path}`, or
+ * undefined when it is none.
+ */
+function parseCallbackUrl(url) {
+    const match = /^([A-Za-z_]+):\/\/(\[[^\]]+\]|[^/:]+):(\d+)(\/.*)?$/.exec(String(url));
+    if (!match) {
+        return undefined;
+    }
+    const scheme = match[1].toLowerCase();
+    const protocol = scheme === 'xmlrpc_bin' || scheme === 'binrpc' ? 'binrpc' : scheme;
+    if (!['binrpc', 'http', 'https', 'xmlrpc'].includes(protocol)) {
+        return undefined;
+    }
+    return {
+        protocol: protocol === 'xmlrpc' ? 'http' : protocol,
+        host: match[2].replace(/^\[|\]$/g, ''),
+        port: Number(match[3]),
+        path: match[4] || '/',
+    };
+}
+
+function isThenable(value) {
+    return value !== null && typeof value === 'object' && typeof value.then === 'function';
+}
+
 /** Closes a binrpc or xmlrpc client so that it stops holding the event loop open. */
 function closeClient(client) {
     if (!client) {