hm-simulator 1.3.0 → 1.3.2

package/CHANGELOG.md

@@ -3,6 +3,35 @@
 All notable changes of hm-simulator. The release workflow takes each version's section from here for the
 GitHub release notes.
 
+## 1.3.2
+
+- `getParamsetDescription` of an address the interface does not know answers the `unknownInstance`
+  fault - `-2 Invalid device` under hmipserver's default table, `-2 Unknown instance` under rfd's -
+  as both interface processes do on 3.89.11; it answered `''`. A paramset the channel does not list
+  answers the new table entry `unknownParamsetDescription` (`-3 Unknown Paramset` / `-3 Unknown
+paramset`, measured); a paramset the channel has but the description set lacks still answers `''`
+  (B-5, found through node-red-contrib-ccu's handling of the fault on a real CCU).
+- `getLinkPeers` of a device address faults on `rfd` with the `notSupported` entry (`-1 Failure`
+  under rfd's table, as rfd 3.89.11 answers; `-1 Generic error` under the default one), where it
+  answered the peers of all channels; on hmipserver and the other interfaces it answers the channels'
+  lists one after the other, a peer linked with two of the channels twice, as hmipserver 3.89.11 does
+  (B-4).
+
+## 1.3.1
+
+- `getLinks` without an address reports `FLAGS: 1` (`SENDER_BROKEN`) on every device-internal link of
+  `rfd` - a relay's own button on the relay, a dimmer's channel on its virtual channels - as rfd
+  3.89.11 does although such a link works; filtered by an address the link carries its stored flags,
+  0, as rfd answers there too. A test that shows a client how it handles rfd's flag can now make the
+  link with `addLink` instead of seeding it (B-3, found through Homematic Manager's links list).
+- `replaceDevice` answers `true`, as the specification's `bool` says, where it answered `''` (a
+  client that takes the answer as the success saw a replacement that did happen as failed).
+- rfd's `listReplaceableDevices` names only the devices of the same type that are unreachable
+  (`setReachable(iface, address, false)`); a device that still answers is not replaced.
+- The declarations gain `clients` (the registered logic layers per interface, read-only, `Client`),
+  `dispatch` with its `DispatchContext` (the servers' entry, which a test may wrap to record calls),
+  and `replaceDevice`'s `true` (B-2, found through Homematic Manager's tests on 1.3.0).
+
 ## 1.3.0
 
 - The calls Homematic Manager makes, measured on rfd and hmipserver of firmware 3.89.11:

package/README.md

@@ -487,6 +487,23 @@ Where the simulator imitates an interface process, this says whether the shape w
 CCU or is the simulator's model. The measurements were made for Homematic Manager (tasks 6 and 58)
 on CCUs with firmware 3.89.8 and 3.89.x.
 
+### Direct links
+
+rfd (firmware 3.89.11, 2026-09-30) answers `getLinks("", flags)` - the list of all links - with
+`FLAGS: 1` (`SENDER_BROKEN`) on every **device-internal** link: a relay's own button on the relay
+(`:1` → `:1`), a dimmer's channel on its virtual channels. The link works; the bit carries no
+information there. Asked for one address, `getLinks("ABC0000001:1", 0)` and `getLinks("ABC0000001",
+0)` answer the same link with `FLAGS: 0`, and `getLinkPeers` names the own channel once. The simulator
+does the same on `rfd`: `addLink` stores `FLAGS: 0`, the unfiltered list adds bit 1 to internal links
+(seeded flags are kept and or-ed), the filtered one reports what is stored. hmipserver is not
+measured and reports the stored flags.
+
+`getLinkPeers` of a **device** address (measured 2026-10-02, 3.89.11): rfd refuses it with `-1
+Failure`; hmipserver answers the channels' peer lists one after the other, so a peer linked with two
+of the channels is named twice. The simulator does the same: on `rfd` the `notSupported` entry of the
+fault table in force (`-1 Generic error` under hmipserver's default table, `-1 Failure` under
+`FAULT_TABLES.bidcos`), on every other interface the channels' lists in channel order.
+
 ### CONFIG_PENDING
 
 What a `putParamset MASTER` does, per interface (`interfaces.<iface>.configPendingMode`):
@@ -523,20 +540,21 @@ The two models are the explanations that competed before the measurement (Homema
 The default table is **hmipserver's**, because that is the one an application has to survive
 (measured):
 
-| key                | code | string                          | when                                                                               |
-| ------------------ | ---- | ------------------------------- | ---------------------------------------------------------------------------------- |
-| `unknownMethod`    | -1   | Invalid XML-RPC message         | no handler for the method name (hmipserver answers this without a faultCode)       |
-| `unknownInstance`  | -2   | Invalid device                  | address not known to this interface                                                |
-| `unknownParamset`  | -2   | Invalid device                  | the device has no such paramset                                                    |
-| `unknownLink`      | -2   | Invalid device                  | the two channels are not linked                                                    |
-| `unknownParameter` | -5   | Unknown Parameter for value key | the paramset has no such parameter                                                 |
-| `readOnly`         | -5   | Invalid parameter or value      | `OPERATIONS & 2` is not set                                                        |
-| `typeError`        | -5   | Invalid parameter or value      | value does not fit the parameter's `TYPE`                                          |
-| `outOfRange`       | -5   | Invalid parameter or value      | ENUM value not in `VALUE_LIST`                                                     |
-| `invalidValue`     | -5   | Invalid parameter or value      | the stored channel configuration cannot be transferred                             |
-| `notSupported`     | -1   | Generic error                   | a method this interface does not implement                                         |
-| `notReachable`     | -1   | Generic error (UNREACH)         | a sleeping battery device                                                          |
-| `invalidArguments` | -321 | Invalid arguments               | wrong number of arguments; hmipserver really answers a Java exception message here |
+| key                          | code | string                          | when                                                                                                                    |
+| ---------------------------- | ---- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `unknownMethod`              | -1   | Invalid XML-RPC message         | no handler for the method name (hmipserver answers this without a faultCode)                                            |
+| `unknownInstance`            | -2   | Invalid device                  | address not known to this interface                                                                                     |
+| `unknownParamset`            | -2   | Invalid device                  | `getParamset`/`putParamset` of a paramset the device does not have                                                      |
+| `unknownParamsetDescription` | -3   | Unknown Paramset                | `getParamsetDescription` of a paramset the channel does not list (3.89.11 appends the name: `Unknown Paramset: NOSUCH`) |
+| `unknownLink`                | -2   | Invalid device                  | the two channels are not linked                                                                                         |
+| `unknownParameter`           | -5   | Unknown Parameter for value key | the paramset has no such parameter                                                                                      |
+| `readOnly`                   | -5   | Invalid parameter or value      | `OPERATIONS & 2` is not set                                                                                             |
+| `typeError`                  | -5   | Invalid parameter or value      | value does not fit the parameter's `TYPE`                                                                               |
+| `outOfRange`                 | -5   | Invalid parameter or value      | ENUM value not in `VALUE_LIST`                                                                                          |
+| `invalidValue`               | -5   | Invalid parameter or value      | the stored channel configuration cannot be transferred                                                                  |
+| `notSupported`               | -1   | Generic error                   | a method this interface does not implement                                                                              |
+| `notReachable`               | -1   | Generic error (UNREACH)         | a sleeping battery device                                                                                               |
+| `invalidArguments`           | -321 | Invalid arguments               | wrong number of arguments; hmipserver really answers a Java exception message here                                      |
 
 Over XML-RPC a fault is an XML-RPC fault, over BIN-RPC a message of type `0xff` with a
 `faultCode`/`faultString` struct. rfd's table is exported as `BIDCOS_FAULTS` and differs in more
@@ -549,6 +567,22 @@ new HmSim({faults: FAULT_TABLES.bidcos});
 new HmSim({faults: {unknownParameter: {faultCode: -4, faultString: 'Unknown parameter'}}}); // one entry
 ```
 
+### Unknown addresses and paramsets
+
+Measured 2026-10-02 on rfd and hmipserver of firmware 3.89.11, with a device address and a channel
+address alike: an address the interface does not know is a fault from every method that takes one -
+`getDeviceDescription`, `getParamsetDescription`, `getParamset`, `getLinks`, `getLinkPeers` - rfd's
+`-2 Unknown instance`, hmipserver's `-2 Invalid device`. The simulator answers `unknownInstance` of
+the table in force everywhere (until 1.3.1 `getParamsetDescription` answered `''` there).
+
+`getParamsetDescription` of a paramset the channel does not have: hmipserver answers `-3 Unknown
+Paramset: <name>`; rfd answers `-3 Unknown paramset` on a channel without a `LINK` paramset and the
+`LINK` description on a channel that has one (the name is taken as a peer address, as `getParamset`
+does). The simulator answers `unknownParamsetDescription` whenever the channel's `PARAMSETS` lacks
+the name. A paramset the channel lists but the description set has no entry for still answers `''`:
+that is a gap in the fixture (logged once, see
+[Device data and fixtures](#device-data-and-fixtures)), not something an interface process does.
+
 ### Service messages
 
 `getServiceMessages` answers `[[address, datapoint, value]]`: every datapoint whose description
@@ -609,7 +643,8 @@ lifted again):
 
 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
+`listReplaceableDevices` on rfd lists the other devices of the same `TYPE` that are unreachable
+(`setReachable(iface, address, false)`; a device that still answers is not replaced); `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.

package/lib/faults.d.ts

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

package/lib/faults.js

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

package/lib/sim.js

@@ -45,6 +45,15 @@ const CALLBACK_LOG_SIZE = 10000;
 /** the interfaces that speak the BidCos protocol, and therefore have setTempKey */
 const BIDCOS_INTERFACES = new Set(['rfd', 'wired']);
 
+/** FLAGS bit of a link whose sender rfd counts as broken (bit 2 is the receiver) */
+const LINK_SENDER_BROKEN = 1;
+
+/** The device part of a channel address: `ABC0000001:1` -> `ABC0000001`. */
+function deviceOf(address) {
+    const colon = String(address).indexOf(':');
+    return colon === -1 ? String(address) : String(address).slice(0, colon);
+}
+
 /** 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']);
 
@@ -562,6 +571,28 @@ class HmSim {
         return this.requireDevice(iface, address);
     }
 
+    /**
+     * The RPC `getParamsetDescription`: unlike {@link getParamsetDescription}, which the simulator
+     * calls for itself, an address the interface does not know is a fault (rfd `-2 Unknown instance`,
+     * hmipserver `-2 Invalid device`, measured on 3.89.11), and so is a paramset the channel does not
+     * list in `PARAMSETS` (`-3` on both). A paramset the channel has but the description set lacks
+     * still answers `''`, logged once by {@link resolveParamsetKey} - that is a gap in the fixture,
+     * not something an interface process does.
+     * @param {string} iface
+     * @param {string} address device or channel address
+     * @param {string} paramset MASTER, VALUES, LINK or SERVICE
+     */
+    describeParamset(iface, address, paramset) {
+        const device = this.requireDevice(iface, address);
+        if (typeof paramset !== 'string' || paramset === '') {
+            throw this.fault('invalidArguments', 'paramset type');
+        }
+        if (Array.isArray(device.PARAMSETS) && !device.PARAMSETS.includes(paramset)) {
+            throw this.fault('unknownParamsetDescription', `${address}/${paramset}`);
+        }
+        return this.getParamsetDescription(iface, device, paramset);
+    }
+
     getValue(iface, address, datapoint) {
         const {description, values} = this.storedParamset(iface, address, 'VALUES');
         if (!description[datapoint]) {
@@ -897,14 +928,24 @@ class HmSim {
             links = links.filter((link) => addresses.has(link.SENDER) || addresses.has(link.RECEIVER));
         }
 
-        return links.map((link) => this.linkStruct(iface, link, flags));
+        // rfd (measured, firmware 3.89.11): the list of *all* links carries FLAGS bit 1 (SENDER_BROKEN)
+        // on every device-internal link - a relay's own button on the relay, a dimmer's channel on its
+        // virtual channels - although the link works; asked for one address, the same link comes with
+        // its stored flags, 0. The simulator does the same on rfd, whatever `flags` asks for.
+        const internalBroken = iface === 'rfd' && !address;
+        return links.map((link) => this.linkStruct(iface, link, flags, internalBroken));
+    }
+
+    /** Sender and receiver on one device: `ABC0000001:1` and `ABC0000001:2`, or the same channel. */
+    isInternalLink(link) {
+        return deviceOf(link.SENDER) === deviceOf(link.RECEIVER);
     }
 
-    linkStruct(iface, link, flags) {
+    linkStruct(iface, link, flags, internalBroken = false) {
         const result = {
             SENDER: link.SENDER,
             RECEIVER: link.RECEIVER,
-            FLAGS: link.FLAGS || 0,
+            FLAGS: (link.FLAGS || 0) | (internalBroken && this.isInternalLink(link) ? LINK_SENDER_BROKEN : 0),
             NAME: link.NAME || '',
             DESCRIPTION: link.DESCRIPTION || '',
         };
@@ -930,14 +971,31 @@ class HmSim {
         }
     }
 
+    /**
+     * The peers of a channel: the other end of every link it is on, the own channel once for a link
+     * with itself. For a device address rfd answers `-1 Failure` (measured, 3.89.11); hmipserver
+     * answers the channels' lists one after the other, a peer linked with two of the channels twice
+     * (measured, 3.89.11) - the simulator does the same on every interface but `rfd`.
+     * @param {string} iface
+     * @param {Array} params [address]
+     * @returns {string[]} channel addresses
+     */
     getLinkPeers(iface, params) {
-        const addresses = new Set(this.channelsOf(iface, params[0]));
+        const [address] = params || [];
+        const device = this.requireDevice(iface, address);
+        if (iface === 'rfd' && !device.PARENT) {
+            // rfd's -1 Failure; -1 Generic error under hmipserver's default table
+            throw this.fault('notSupported', `getLinkPeers of a device address: ${address}`);
+        }
+
         const peers = [];
-        for (const link of this.links[iface] || []) {
-            if (addresses.has(link.SENDER)) {
-                peers.push(link.RECEIVER);
-            } else if (addresses.has(link.RECEIVER)) {
-                peers.push(link.SENDER);
+        for (const channel of this.channelsOf(iface, address)) {
+            for (const link of this.links[iface] || []) {
+                if (link.SENDER === channel) {
+                    peers.push(link.RECEIVER);
+                } else if (link.RECEIVER === channel) {
+                    peers.push(link.SENDER);
+                }
             }
         }
         return peers;
@@ -1373,9 +1431,11 @@ class HmSim {
 
     /**
      * `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 `''`.
+     * devices of the same `TYPE` that are unreachable (`setReachable(iface, address, false)`) - a
+     * device that still answers is not replaced (the simulator's model, after what the CCU's WebUI
+     * offers; 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 || [];
@@ -1389,7 +1449,10 @@ class HmSim {
         if (device.PARENT) {
             return [];
         }
-        return this.deviceList(iface).filter((entry) => entry.TYPE === device.TYPE && entry.ADDRESS !== address);
+        const unreachable = this.unreachable[iface] || new Set();
+        return this.deviceList(iface).filter(
+            (entry) => entry.TYPE === device.TYPE && entry.ADDRESS !== address && unreachable.has(entry.ADDRESS),
+        );
     }
 
     /**
@@ -1736,7 +1799,7 @@ class HmSim {
         }
 
         this.deleteDevice(iface, oldAddress);
-        return '';
+        return true;
     }
 
     reportValueUsage(iface, params) {
@@ -2392,7 +2455,7 @@ class HmSim {
             'system.multicall': (iface, params) => this.multicall(iface, params),
             init: (iface, params) => this.init(iface, params),
             listDevices: (iface) => this.devices[iface].devices,
-            getParamsetDescription: (iface, params) => this.getParamsetDescription(iface, params[0], params[1]),
+            getParamsetDescription: (iface, params) => this.describeParamset(iface, params[0], params[1]),
             getDeviceDescription: (iface, params) => this.getDeviceDescription(iface, params[0]),
             ping: (iface, params) => this.ping(iface, params),
             setValue: (iface, params) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hm-simulator",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "description": "Simulates a Homematic CCU (rfd, hmipserver, VirtualDevices, CUxD, ReGa) for automated tests",
   "main": "sim.js",
   "types": "./sim.d.ts",

package/sim.d.ts

@@ -257,6 +257,31 @@ declare namespace HmSim {
     /** `method -> handler(iface, params)`, as the servers dispatch it. */
     type RpcMethodTable = Record<string, (iface: string, params: unknown[]) => unknown>;
 
+    /** A logic layer registered with `init`: what the simulator calls back. */
+    interface Client {
+        /** the interface id the client gave `init` */
+        id: string;
+        /** its callback url, as given */
+        url: string;
+        /** the key in `clients[iface]` (the url, exactly) */
+        key: string;
+        /** the underlying binrpc or xmlrpc client */
+        client: unknown;
+        /** one callback to the client; logged in `getCallbackLog()` */
+        methodCall(
+            method: string,
+            params: unknown[],
+            callback: (error: Error | null | undefined, result?: unknown) => void,
+            options?: {timeout?: number},
+        ): void;
+    }
+
+    /** What the servers hand `dispatch` besides the call. */
+    interface DispatchContext {
+        /** the connection the call came in on, for an injected `closeSocket` */
+        socket?: {destroy(): void};
+    }
+
     /** The ports once `whenReady()` resolved. */
     type Ports = Partial<Record<InterfaceName, number>>;
 
@@ -305,6 +330,8 @@ declare class HmSim {
     /** stored state per interface and address: `{VALUES, MASTER, LINKS, ...}` */
     values: Record<string, Record<string, Record<string, Record<string, unknown>>>>;
     links: Record<string, HmSim.Link[]>;
+    /** the registered logic layers per interface, by callback url: the subscriptions `init(url, '')` removes */
+    readonly clients: Record<string, Record<string, HmSim.Client>>;
     serviceMessages: Record<string, HmSim.ServiceMessage[]>;
     /** every reportValueUsage */
     valueUsage: Array<{iface: string; address: string; valueId: string; refCounter: number; ts: number}>;
@@ -378,6 +405,8 @@ declare class HmSim {
         paramset: string,
     ): HmSim.ParamsetDescription | undefined;
     getDeviceDescription(iface: string, address: string): HmSim.DeviceDescription;
+    /** the RPC `getParamsetDescription`: faults for an unknown address or a paramset the channel lacks */
+    describeParamset(iface: string, address: string, paramset: string): HmSim.ParamsetDescription | undefined;
 
     /* ---------------------------------------------------------------- scenario api: service messages and health */
 
@@ -421,10 +450,21 @@ declare class HmSim {
 
     /** One RPC method as a client call would run it; throws the fault. */
     callMethod(iface: string, method: string, params?: unknown[]): unknown;
+    /**
+     * The servers' entry for every incoming call: injected faults and the lifecycle gates apply, then
+     * `callMethod`, and `callback(fault)` or `callback(null, result)`. A test wraps it to record calls.
+     */
+    dispatch(
+        iface: string,
+        method: string,
+        params: unknown[],
+        callback: (fault: HmSim.RpcFault | null | undefined, result?: unknown) => void,
+        context?: HmSim.DispatchContext,
+    ): void;
     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): '';
+    replaceDevice(iface: string, oldAddress: string, newAddress: string): true;
     getKeyMismatchDevice(iface: string, params?: [reset?: boolean]): string;
     suppressServiceMessages(
         iface: string,