hm-simulator 1.3.1 → 1.3.2

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 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

package/README.md

@@ -496,8 +496,13 @@ information there. Asked for one address, `getLinks("ABC0000001:1", 0)` and `get
 0)` answer the same link with `FLAGS: 0`, and `getLinkPeers` names the own channel once. The simulator
 does the same on `rfd`: `addLink` stores `FLAGS: 0`, the unfiltered list adds bit 1 to internal links
 (seeded flags are kept and or-ed), the filtered one reports what is stored. hmipserver is not
-measured and reports the stored flags. rfd also refuses `getLinkPeers` of a device address (`-1
-Failure`); the simulator answers the peers of all its channels.
+measured and reports the stored flags.
+
+`getLinkPeers` of a **device** address (measured 2026-10-02, 3.89.11): rfd refuses it with `-1
+Failure`; hmipserver answers the channels' peer lists one after the other, so a peer linked with two
+of the channels is named twice. The simulator does the same: on `rfd` the `notSupported` entry of the
+fault table in force (`-1 Generic error` under hmipserver's default table, `-1 Failure` under
+`FAULT_TABLES.bidcos`), on every other interface the channels' lists in channel order.
 
 ### CONFIG_PENDING
 
@@ -535,20 +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
@@ -561,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

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

@@ -571,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]) {
@@ -949,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;
@@ -2416,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.1",
+  "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

@@ -405,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 */