hm-simulator 1.0.0 → 1.1.0

package/README.md

@@ -37,11 +37,12 @@ messages. rfd and hmipserver start by default, the others when their port is con
 | devices     | `listDevices`, `getDeviceDescription`, `deleteDevice`, `replaceDevice`, `setInstallMode`, `getInstallMode`                     |
 | paramsets   | `getParamsetDescription`, `getParamset`, `putParamset`, `getValue`, `setValue`, `determineParameter`, `reportValueUsage`       |
 | links       | `getLinks`, `getLinkPeers`, `getLinkInfo`, `setLinkInfo`, `addLink`, `removeLink`, `activateLinkParamset`                      |
-| interface   | `rssiInfo`, `listBidcosInterfaces`, `setBidcosInterface`, `getServiceMessages`                                                 |
+| interface   | `rssiInfo`, `listBidcosInterfaces`, `setBidcosInterface`, `getServiceMessages`, `setTempKey` (BidCos only)                     |
+| teams       | `listTeams`, `setTeam` (BidCos only): the smoke detector teams as rfd keeps them, pseudo devices `*<serial>`                   |
 | maintenance | `clearConfigCache`, `restoreConfigToDevice`, `updateFirmware`, `installFirmware` (the last two are stubs that record the call) |
 
 **Outgoing RPC calls** to every registered logic layer: `listDevices`, `newDevices`,
-`deleteDevices`, `event`, `system.multicall`.
+`deleteDevices`, `updateDevice` (after `setTeam`), `event`, `system.multicall`.
 
 **ReGa** (`rega.exe` on port 8181): the scripts of the
 [homematic-rega](https://github.com/hobbyquaker/homematic-rega) client - `getChannels`,
@@ -300,6 +301,20 @@ hm-simulator [options]
 
 ## Changelog
 
+### 1.1.0
+
+- `setTempKey` on the BidCos interfaces: the passphrase a device is taught in with, applied to
+  the pairings that follow; `sim.getTempKey(iface)` reads back what was set, an empty string
+  clears it. No cryptography. hmipserver has no such method, so it faults with unknown-method
+  there (Homematic Manager issue #20).
+- Smoke detector teams on the BidCos interfaces: `listTeams` and `setTeam`. A channel with a
+  `TEAM_TAG` is in the team its `TEAM` names, a pseudo device `*<serial>` whose team channel lists
+  the members in `TEAM_CHANNELS`; `setTeam(channel, team)` moves it and deletes a team nobody is
+  left in, `setTeam(channel, '')` puts it back into a team of its own, created like the one it
+  left (`newDevices`, `deleteDevices`, `updateDevice` to the logic layers). The shape is rfd's
+  as Homematic Manager task 58 read it from a CCU3; when rfd deletes and creates the team devices
+  is the simulator's model, not a measurement.
+
 ### 1.0.0
 
 - Node >= 20.19, `binrpc` ^4.2, `homematic-xmlrpc` ^2.0; `express`, `body-parser`, `request`,

package/lib/method-help.js

@@ -36,6 +36,10 @@ module.exports = {
     getServiceMessages: 'array getServiceMessages() - the pending service messages',
     setInstallMode: 'void setInstallMode(boolean on, int time, int mode) - switch the install mode',
     getInstallMode: 'int getInstallMode() - remaining seconds of the install mode',
+    setTempKey: 'void setTempKey(string passphrase) - the temporary key the next BidCos pairings use; BidCos only',
+    listTeams: 'array listTeams() - the team pseudo devices (smoke detector teams) with their channels; BidCos only',
+    setTeam:
+        'void setTeam(string channelAddress, string teamAddress) - put a channel into a team, an empty team into its own; BidCos only',
     deleteDevice: 'void deleteDevice(string address, int flags) - remove a device',
     replaceDevice:
         'void replaceDevice(string oldDeviceAddress, string newDeviceAddress) - take over the configuration of a device',

package/lib/sim.js

@@ -37,6 +37,9 @@ const PARAMSET_PREFIX = {
     cuxd: 'CUxD',
 };
 
+/** the interfaces that speak the BidCos protocol, and therefore have setTempKey */
+const BIDCOS_INTERFACES = new Set(['rfd', 'wired']);
+
 /** paramset keys that are not the address of a linked peer channel */
 const STANDARD_PARAMSETS = new Set(['MASTER', 'VALUES', 'SERVICE']);
 
@@ -181,6 +184,8 @@ class HmSim {
         this.serviceMessages = {};
         /** end of the install mode per interface, as an epoch timestamp */
         this.installMode = {};
+        /** the temporary AES key of the BidCos interfaces, see setTempKey */
+        this.tempKey = {};
         /** devices that appear when the install mode is switched on, see scriptNewDevices() */
         this.newDevicesScript = {};
         /** every reportValueUsage the simulator was told about */
@@ -978,6 +983,172 @@ class HmSim {
         return '';
     }
 
+    /**
+     * `setTempKey(passphrase)` - the temporary key a BidCos device is taught in with.
+     *
+     * A HomeMatic device can be paired with a passphrase instead of the interface's own key, and a
+     * device that was taught in that way can only be paired again when the same passphrase is
+     * offered. rfd takes it as one string argument and answers with the empty string; it applies to
+     * the pairings that follow, so an application sends it *before* `setInstallMode` or
+     * `addDevice`. An empty string clears it back to the interface's key.
+     *
+     * Only the BidCos processes have the method - hmipserver answers an unknown-method fault, which
+     * is what an application has to handle when a user types it into the wrong interface.
+     *
+     * The simulator does no cryptography: it remembers the key so a test can assert that the call
+     * happened, in which order, and with what. `sim.getTempKey(iface)` reads it back.
+     *
+     * @param {string} iface
+     * @param {Array} params [passphrase]
+     */
+    setTempKey(iface, params) {
+        if (!BIDCOS_INTERFACES.has(iface)) {
+            throw this.fault('unknownMethod', `${iface}/setTempKey`);
+        }
+        const [key] = params || [];
+        if (key !== undefined && typeof key !== 'string') {
+            throw this.fault('invalidArguments', 'setTempKey wants a string');
+        }
+        this.tempKey[iface] = key === undefined ? '' : key;
+        this.log.info(iface, this.tempKey[iface] === '' ? 'temporary key cleared' : 'temporary key set');
+        return '';
+    }
+
+    /* ------------------------------------------------------------------ teams */
+
+    /**
+     * `listTeams()` - the team pseudo devices of a BidCos interface, with their channels.
+     *
+     * rfd keeps smoke detectors (and the other devices with a `TEAM_TAG`) in *teams*. A team is a
+     * pseudo device whose address is `*` plus the serial of the device it was made from
+     * (`*NEQ0448334`, type `HM-Sec-SD-2-Team`); its team channel carries the members in
+     * `TEAM_CHANNELS`, and every member channel names the team channel in `TEAM`. The team devices
+     * come with `listDevices` as well; `listTeams` is only them. hmipserver has no teams.
+     *
+     * @param {string} iface
+     */
+    listTeams(iface) {
+        if (!BIDCOS_INTERFACES.has(iface)) {
+            throw this.fault('unknownMethod', `${iface}/listTeams`);
+        }
+        return this.devices[iface].devices.filter((device) => device.ADDRESS.startsWith('*'));
+    }
+
+    /**
+     * `setTeam(channelAddress, teamAddress)` - puts a channel into a team.
+     *
+     * The shape is rfd's, as Homematic Manager task 58 read it from a CCU3: every detector starts in
+     * a team of its own (`*<its serial>`); joining another team takes it out of the old one. That a
+     * team nobody is left in is deleted (`deleteDevices`) is the simulator's model, not a measurement. An empty
+     * `teamAddress` puts the channel back into a team of its own, which is created again
+     * (`newDevices`) with the type of the team it leaves. Channel and team must carry the same
+     * `TEAM_TAG`; there is no call that creates a team. The changed channels are announced with
+     * `updateDevice`. BidCos only.
+     *
+     * @param {string} iface
+     * @param {Array} params [channelAddress, teamAddress]
+     */
+    setTeam(iface, params) {
+        if (!BIDCOS_INTERFACES.has(iface)) {
+            throw this.fault('unknownMethod', `${iface}/setTeam`);
+        }
+        const [channelAddress, teamAddress = ''] = params || [];
+        if (typeof channelAddress !== 'string' || typeof teamAddress !== 'string') {
+            throw this.fault('invalidArguments', 'setTeam wants two strings');
+        }
+        const channel = this.requireDevice(iface, channelAddress);
+        if (!channel.PARENT || !channel.TEAM_TAG || Array.isArray(channel.TEAM_CHANNELS)) {
+            throw this.fault('invalidArguments', `${channelAddress} cannot be in a team`);
+        }
+        const oldTeam = channel.TEAM ? this.index[iface].get(channel.TEAM) : undefined;
+        const ownDevice = `*${channel.PARENT}`;
+        const ownTeam = `${ownDevice}:1`;
+        const target = teamAddress === '' ? ownTeam : teamAddress;
+        if (channel.TEAM === target) {
+            return '';
+        }
+
+        let team = this.index[iface].get(target);
+        if (team === undefined && target === ownTeam) {
+            team = this.createTeam(iface, channel, oldTeam);
+        }
+        if (team === undefined) {
+            throw this.fault('unknownInstance', `${iface}/${target}`);
+        }
+        if (!Array.isArray(team.TEAM_CHANNELS) || team.TEAM_TAG !== channel.TEAM_TAG) {
+            throw this.fault('invalidArguments', `${target} is no team for ${channelAddress}`);
+        }
+
+        const changed = [channelAddress, target];
+        if (oldTeam) {
+            oldTeam.TEAM_CHANNELS = (oldTeam.TEAM_CHANNELS || []).filter((member) => member !== channelAddress);
+            changed.push(oldTeam.ADDRESS);
+        }
+        team.TEAM_CHANNELS = [...team.TEAM_CHANNELS.filter((member) => member !== channelAddress), channelAddress];
+        channel.TEAM = target;
+        this.log.info(iface, 'team', channelAddress, '->', target);
+
+        for (const address of changed) {
+            if (this.index[iface].has(address) && !(oldTeam && address === oldTeam.ADDRESS)) {
+                this.tellClientsParams(iface, 'updateDevice', [address, 0]);
+            }
+        }
+        // a team nobody is in any more is gone
+        if (oldTeam && oldTeam.TEAM_CHANNELS.length === 0 && oldTeam.PARENT) {
+            this.deleteDevice(iface, oldTeam.PARENT);
+        } else if (oldTeam) {
+            this.tellClientsParams(iface, 'updateDevice', [oldTeam.ADDRESS, 0]);
+        }
+        return '';
+    }
+
+    /**
+     * A team of a channel's own, `*<serial>`, shaped like the team it leaves (or, without one, as
+     * `<PARENT_TYPE>-Team` with a `<TYPE>_TEAM` channel), and announced with `newDevices`.
+     */
+    createTeam(iface, channel, like) {
+        const parent = this.index[iface].get(channel.PARENT) || {};
+        const likeDevice = like && like.PARENT ? this.index[iface].get(like.PARENT) : undefined;
+        const address = `*${channel.PARENT}`;
+        const type = likeDevice ? likeDevice.TYPE : `${channel.PARENT_TYPE}-Team`;
+        const device = {
+            ADDRESS: address,
+            TYPE: type,
+            VERSION: likeDevice ? likeDevice.VERSION : parent.VERSION || 1,
+            FIRMWARE: likeDevice ? likeDevice.FIRMWARE : parent.FIRMWARE || '1.0',
+            CHILDREN: [`${address}:0`, `${address}:1`],
+            PARAMSETS: ['MASTER'],
+            FLAGS: 9,
+        };
+        const maintenance = {
+            ADDRESS: `${address}:0`,
+            TYPE: 'MAINTENANCE',
+            VERSION: device.VERSION,
+            PARENT: address,
+            PARENT_TYPE: type,
+            PARAMSETS: ['MASTER', 'VALUES'],
+            INDEX: 0,
+        };
+        const teamChannel = {
+            ADDRESS: `${address}:1`,
+            TYPE: like ? like.TYPE : `${channel.TYPE}_TEAM`,
+            VERSION: device.VERSION,
+            PARENT: address,
+            PARENT_TYPE: type,
+            PARAMSETS: ['MASTER', 'VALUES'],
+            INDEX: 1,
+            TEAM_TAG: channel.TEAM_TAG,
+            TEAM_CHANNELS: [],
+        };
+        this.addDevices(iface, [device, maintenance, teamChannel]);
+        return this.index[iface].get(teamChannel.ADDRESS);
+    }
+
+    /** The temporary key an interface was last given, `''` when there is none. */
+    getTempKey(iface) {
+        return this.tempKey[iface] || '';
+    }
+
     /** Remaining seconds of the install mode, 0 when it is off. */
     getInstallMode(iface) {
         const until = this.installMode[iface] || 0;
@@ -1261,9 +1432,14 @@ class HmSim {
 
     /** Calls one method on every connected logic layer. */
     tellClients(iface, method, payload) {
+        this.tellClientsParams(iface, method, [payload]);
+    }
+
+    /** The same with several parameters after the interface id (`updateDevice(id, address, hint)`). */
+    tellClientsParams(iface, method, params) {
         for (const key of Object.keys(this.clients[iface] || {})) {
             const client = this.clients[iface][key];
-            client.methodCall(method, [client.id, payload]);
+            client.methodCall(method, [client.id, ...params]);
         }
     }
 
@@ -1320,6 +1496,9 @@ class HmSim {
             getServiceMessages: (iface) => this.getServiceMessages(iface),
             setInstallMode: (iface, params) => this.setInstallMode(iface, params),
             getInstallMode: (iface) => this.getInstallMode(iface),
+            setTempKey: (iface, params) => this.setTempKey(iface, params),
+            listTeams: (iface) => this.listTeams(iface),
+            setTeam: (iface, params) => this.setTeam(iface, params),
             deleteDevice: (iface, params) => this.deleteDevice(iface, params[0], params[1]),
             replaceDevice: (iface, params) => this.replaceDevice(iface, params[0], params[1]),
             reportValueUsage: (iface, params) => this.reportValueUsage(iface, params),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hm-simulator",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Simulates a Homematic CCU (rfd, hmipserver, VirtualDevices, CUxD, ReGa) for automated tests",
   "main": "sim.js",
   "preferGlobal": true,