hm-simulator 1.3.0 → 1.3.1

package/CHANGELOG.md

@@ -3,6 +3,21 @@
 All notable changes of hm-simulator. The release workflow takes each version's section from here for the
 GitHub release notes.
 
+## 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,18 @@ 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. rfd also refuses `getLinkPeers` of a device address (`-1
+Failure`); the simulator answers the peers of all its channels.
+
 ### CONFIG_PENDING
 
 What a `putParamset MASTER` does, per interface (`interfaces.<iface>.configPendingMode`):
@@ -609,7 +621,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/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']);
 
@@ -897,14 +906,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 || '',
         };
@@ -1373,9 +1392,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 +1410,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 +1760,7 @@ class HmSim {
         }
 
         this.deleteDevice(iface, oldAddress);
-        return '';
+        return true;
     }
 
     reportValueUsage(iface, params) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hm-simulator",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "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}>;
@@ -421,10 +448,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,