homematic-manager 3.0.0-beta.6 → 3.0.0-beta.8

package/dist/testSupport.js

@@ -183,7 +183,14 @@ export async function startForTest(options = {}) {
         }
     }
     const ports = simulator
-        ? { 'BidCos-RF': simulator.ports.rfd, 'HmIP-RF': simulator.ports.hmip }
+        ? {
+            'BidCos-RF': simulator.ports.rfd,
+            'HmIP-RF': simulator.ports.hmip,
+            // only when the simulator was given a `virtualListenPort` (the CCU's group process)
+            ...(typeof simulator.ports.virtual === 'number'
+                ? { VirtualDevices: simulator.ports.virtual }
+                : {}),
+        }
         : {};
     const host = await createWebHost({
         port: 0,
@@ -206,7 +213,7 @@ export async function startForTest(options = {}) {
     if (simulator && host.backend) {
         const connection = {
             host: '127.0.0.1',
-            interfaces: ['BidCos-RF', 'HmIP-RF'],
+            interfaces: ['BidCos-RF', 'HmIP-RF', ...(ports['VirtualDevices'] === undefined ? [] : ['VirtualDevices'])],
             autoDetect: false,
             extraInterfaces: [],
             tls: false,

package/node_modules/@homematic-manager/backend/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homematic-manager/backend",
-  "version": "3.0.0-beta.6",
+  "version": "3.0.0-beta.8",
   "type": "module",
   "description": "Homematic Manager backend: XML-RPC/BIN-RPC clients and callback servers, caches, optional ReGa",
   "license": "AGPL-3.0-or-later",

package/node_modules/@homematic-manager/core/dist/devices/index.d.ts

@@ -72,6 +72,13 @@ export declare const RX_MODES: {
  * by itself and one that does not (task 6).
  */
 export declare function decodeRxMode(rxMode: number | undefined): string[];
+/**
+ * Is roaming on for this device? rfd reports `ROAMING` as `1`/`0` over BIN-RPC and as a boolean
+ * over XML-RPC, so both spellings mean yes.
+ */
+export declare function isRoaming(device: {
+    readonly ROAMING?: boolean | number | undefined;
+}): boolean;
 /** `DIRECTION` of a channel. */
 export declare const DIRECTIONS: readonly ["NONE", "SENDER", "RECEIVER"];
 /** Decodes `DIRECTION`; anything unexpected is `NONE`, as the 2.x grid did. */

package/node_modules/@homematic-manager/core/dist/devices/index.js

@@ -55,6 +55,13 @@ export function decodeRxMode(rxMode) {
     }
     return names;
 }
+/**
+ * Is roaming on for this device? rfd reports `ROAMING` as `1`/`0` over BIN-RPC and as a boolean
+ * over XML-RPC, so both spellings mean yes.
+ */
+export function isRoaming(device) {
+    return device.ROAMING === true || device.ROAMING === 1;
+}
 /** `DIRECTION` of a channel. */
 export const DIRECTIONS = ['NONE', 'SENDER', 'RECEIVER'];
 /** Decodes `DIRECTION`; anything unexpected is `NONE`, as the 2.x grid did. */

package/node_modules/@homematic-manager/core/dist/rssi/index.d.ts

@@ -7,6 +7,7 @@
  * as events and sit in every device's `<device>:0` VALUES paramset - the same thing 2.x does in
  * main.js (:404-432 for the events, :800-822 for the paramset read).
  */
+import type { BidcosInterfaceInfo } from '../api/types.js';
 import type { Paramset, ParamsetValue } from '../rpc/values.js';
 /** What an interface process sends instead of a value it does not have. */
 export declare const RSSI_UNKNOWN = 65536;
@@ -41,6 +42,24 @@ export declare function rssiClass(dbm: number | undefined): RssiClass;
  * `undefined` for a value there is none for - the cell stays empty, as it did.
  */
 export declare function rssiColor(dbm: number | undefined): string | undefined;
+/** The two fields of a `listBidcosInterfaces` entry that name it. */
+export type BidcosInterfaceName = Pick<BidcosInterfaceInfo, 'ADDRESS' | 'DESCRIPTION'>;
+/**
+ * How a BidCos interface is named for a person: the `DESCRIPTION` the CCU carries for it - the
+ * name a LAN gateway was given in the WebUI, `CCU2-Coprocessor` for the built-in module - and the
+ * serial when there is none. The 2.x Funk grid put the serial over the interface's columns with
+ * the description in small print under it; a gateway without a description shows its serial alone.
+ */
+export declare function bidcosInterfaceLabel(gateway: BidcosInterfaceName): string;
+/**
+ * The receiver a BidCos-RF device is routed through, for the device grid (BUGS.md B-2): the
+ * label of the gateway whose serial the description's `INTERFACE` names, the serial itself when
+ * `listBidcosInterfaces` does not know it or has not been read yet, and nothing for a device
+ * without one - HmIP and Wired have no receivers.
+ */
+export declare function receiverLabel(device: {
+    readonly INTERFACE?: string | undefined;
+}, gateways: readonly BidcosInterfaceName[]): string;
 /** The HmIP datapoints the matrix is built from. */
 export declare const RSSI_DATAPOINTS: readonly string[];
 export interface RssiStoreOptions {
@@ -88,4 +107,57 @@ export declare class RssiStore {
         readonly tx?: number;
     } | undefined;
 }
+/**
+ * Why a device is, or is not, proposed for another receiver (#69).
+ *
+ * - `switch`: another interface receives the device better than the configured one by at least
+ *   the margin.
+ * - `marginal`: another interface receives it better, but by less than the margin - one sample
+ *   apart, which `rssiInfo` values are between two reads.
+ * - `unheard`: the configured receiver has no measurement of the device at all while another
+ *   interface has one; that can mean the device never reaches its receiver, or that rfd has not
+ *   heard it since a restart.
+ * - `keep`: the configured receiver hears it best, or at least as well as any other.
+ * - `unmeasured`: no interface has a measurement.
+ * - `roaming`: the device roams, so the CCU picks its receiver itself; nothing to assign.
+ */
+export type ReceiverVerdict = 'switch' | 'marginal' | 'unheard' | 'keep' | 'unmeasured' | 'roaming';
+/** One row of the "assign the best receiver" proposal (#69). */
+export interface ReceiverProposal {
+    readonly address: string;
+    /** The serial of the receiver the device is configured for. */
+    readonly configured: string;
+    /** What the configured receiver receives from the device, in dBm. */
+    readonly configuredTx: number | undefined;
+    /** The interface that receives the device best; `undefined` without a measurement. */
+    readonly best: string | undefined;
+    readonly bestTx: number | undefined;
+    /** `bestTx - configuredTx` where both are known. */
+    readonly gain: number | undefined;
+    readonly verdict: ReceiverVerdict;
+}
+/**
+ * The margin a better interface has to clear before a switch is proposed, in dB. The values of
+ * `rssiInfo` are the last measurement rfd holds, and two reads of the same link differ by a few dB
+ * without anything having moved; 6 dB is roughly a quartering of the received power and clears
+ * that noise.
+ */
+export declare const DEFAULT_RECEIVER_MARGIN_DB = 6;
+/** The fields of a device description the proposal reads. */
+export interface ReceiverCandidate {
+    readonly ADDRESS: string;
+    readonly PARENT?: string | undefined;
+    readonly INTERFACE?: string | undefined;
+    readonly ROAMING?: boolean | number | undefined;
+}
+/**
+ * The dry run behind issue #69: for every BidCos-RF device with a receiver, which interface hears
+ * it best and whether that is worth a `setBidcosInterface`. Nothing is written here - the list
+ * is what the user confirms, device by device, before anything is. Channels and devices without
+ * an `INTERFACE` (HmIP, Wired, groups) are not in the answer at all. Sorted by verdict in the
+ * order of {@link ReceiverVerdict}, then by gain, then by address.
+ */
+export declare function proposeReceivers(devices: readonly ReceiverCandidate[], interfaceAddresses: readonly string[], store: Pick<RssiStore, 'get' | 'bestInterfaceFor'>, options?: {
+    readonly marginDb?: number | undefined;
+}): ReceiverProposal[];
 //# sourceMappingURL=index.d.ts.map

package/node_modules/@homematic-manager/core/dist/rssi/index.js

@@ -59,6 +59,30 @@ export function rssiColor(dbm) {
     const green = channel((256 * (value - RSSI_BAD)) / (RSSI_MEDIUM - RSSI_BAD));
     return `#${hex(red)}${hex(green)}00`;
 }
+/**
+ * How a BidCos interface is named for a person: the `DESCRIPTION` the CCU carries for it - the
+ * name a LAN gateway was given in the WebUI, `CCU2-Coprocessor` for the built-in module - and the
+ * serial when there is none. The 2.x Funk grid put the serial over the interface's columns with
+ * the description in small print under it; a gateway without a description shows its serial alone.
+ */
+export function bidcosInterfaceLabel(gateway) {
+    const description = gateway.DESCRIPTION?.trim() ?? '';
+    return description === '' ? gateway.ADDRESS : description;
+}
+/**
+ * The receiver a BidCos-RF device is routed through, for the device grid (BUGS.md B-2): the
+ * label of the gateway whose serial the description's `INTERFACE` names, the serial itself when
+ * `listBidcosInterfaces` does not know it or has not been read yet, and nothing for a device
+ * without one - HmIP and Wired have no receivers.
+ */
+export function receiverLabel(device, gateways) {
+    const serial = device.INTERFACE ?? '';
+    if (serial === '') {
+        return '';
+    }
+    const gateway = gateways.find((candidate) => candidate.ADDRESS === serial);
+    return gateway ? bidcosInterfaceLabel(gateway) : serial;
+}
 /** The HmIP datapoints the matrix is built from. */
 export const RSSI_DATAPOINTS = ['RSSI_DEVICE', 'RSSI_PEER'];
 /** The RSSI matrix of one interface. */
@@ -172,4 +196,63 @@ function channel(value) {
 function hex(value) {
     return `0${value.toString(16)}`.slice(-2);
 }
+/**
+ * The margin a better interface has to clear before a switch is proposed, in dB. The values of
+ * `rssiInfo` are the last measurement rfd holds, and two reads of the same link differ by a few dB
+ * without anything having moved; 6 dB is roughly a quartering of the received power and clears
+ * that noise.
+ */
+export const DEFAULT_RECEIVER_MARGIN_DB = 6;
+const VERDICT_ORDER = ['switch', 'marginal', 'unheard', 'keep', 'unmeasured', 'roaming'];
+/**
+ * The dry run behind issue #69: for every BidCos-RF device with a receiver, which interface hears
+ * it best and whether that is worth a `setBidcosInterface`. Nothing is written here - the list
+ * is what the user confirms, device by device, before anything is. Channels and devices without
+ * an `INTERFACE` (HmIP, Wired, groups) are not in the answer at all. Sorted by verdict in the
+ * order of {@link ReceiverVerdict}, then by gain, then by address.
+ */
+export function proposeReceivers(devices, interfaceAddresses, store, options = {}) {
+    const margin = Math.max(0, options.marginDb ?? DEFAULT_RECEIVER_MARGIN_DB);
+    const proposals = [];
+    for (const device of devices) {
+        const configured = device.INTERFACE ?? '';
+        if (configured === '' || (device.PARENT ?? '') !== '') {
+            continue;
+        }
+        const configuredTx = store.get(device.ADDRESS, configured)?.tx;
+        const best = store.bestInterfaceFor(device.ADDRESS, interfaceAddresses);
+        const gain = best?.tx !== undefined && configuredTx !== undefined ? best.tx - configuredTx : undefined;
+        let verdict;
+        if (device.ROAMING === true || device.ROAMING === 1) {
+            verdict = 'roaming';
+        }
+        else if (best === undefined) {
+            verdict = 'unmeasured';
+        }
+        else if (best.address === configured) {
+            verdict = 'keep';
+        }
+        else if (gain === undefined) {
+            verdict = 'unheard';
+        }
+        else if (gain <= 0) {
+            verdict = 'keep';
+        }
+        else {
+            verdict = gain >= margin ? 'switch' : 'marginal';
+        }
+        proposals.push({
+            address: device.ADDRESS,
+            configured,
+            configuredTx,
+            best: best?.address,
+            bestTx: best?.tx,
+            gain,
+            verdict,
+        });
+    }
+    return proposals.sort((a, b) => VERDICT_ORDER.indexOf(a.verdict) - VERDICT_ORDER.indexOf(b.verdict) ||
+        (b.gain ?? Number.NEGATIVE_INFINITY) - (a.gain ?? Number.NEGATIVE_INFINITY) ||
+        a.address.localeCompare(b.address));
+}
 //# sourceMappingURL=index.js.map

package/node_modules/@homematic-manager/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homematic-manager/core",
-  "version": "3.0.0-beta.6",
+  "version": "3.0.0-beta.8",
   "type": "module",
   "description": "Pure domain logic of the Homematic Manager: no I/O, no DOM",
   "license": "AGPL-3.0-or-later",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "homematic-manager",
-  "version": "3.0.0-beta.6",
+  "version": "3.0.0-beta.8",
   "type": "module",
   "description": "Configure and administer Homematic and HomematicIP devices - devices and channels, direct links, paramsets, RSSI, service messages, events and an RPC console - from a local HTTP/WebSocket server that also serves the web UI",
   "keywords": [
@@ -67,8 +67,8 @@
     "hm-simulator": "^1.0.0"
   },
   "dependencies": {
-    "@homematic-manager/backend": "3.0.0-beta.6",
-    "@homematic-manager/core": "3.0.0-beta.6",
+    "@homematic-manager/backend": "3.0.0-beta.8",
+    "@homematic-manager/core": "3.0.0-beta.8",
     "binrpc": "^4.2.0",
     "homematic-rega": "^2.0.0",
     "homematic-xmlrpc": "^2.0.0",