homematic-manager 3.0.0-beta.12 → 3.0.0-beta.13

package/README.md

@@ -65,6 +65,7 @@ hard-coding it.
 | `--local` | - | we run on the CCU itself: talk to the interface processes directly |
 | `--callback-ip` | auto | address the interfaces call back to; needed where this host cannot see it (Docker) |
 | `--callback-xmlrpc-port`, `--callback-binrpc-port` | free ports | fixed callback ports, so a container can publish them |
+| `--callback-xmlrpc-default-port`, `--callback-binrpc-default-port` | - | callback ports while the configured ones are 0, a free port when one is taken (the CCU addon: 2031, 2032; never written to the configuration) |
 | `--demo` | off | serve the UI on its demo fixture and start no backend |
 | `--log-level` | `info` | `error`, `warn`, `info`, `debug` |
 | `--install` / `--uninstall` | - | systemd service; `--purge` also deletes the state |

package/dist/cli.js

@@ -169,6 +169,12 @@ function startHost(values, log, version) {
         ...(values.callbackIp === undefined ? {} : { callbackIp: values.callbackIp }),
         ...(values.callbackXmlrpcPort === undefined ? {} : { callbackXmlrpcPort: values.callbackXmlrpcPort }),
         ...(values.callbackBinrpcPort === undefined ? {} : { callbackBinrpcPort: values.callbackBinrpcPort }),
+        ...(values.callbackXmlrpcDefaultPort === undefined
+            ? {}
+            : { callbackXmlrpcDefaultPort: values.callbackXmlrpcDefaultPort }),
+        ...(values.callbackBinrpcDefaultPort === undefined
+            ? {}
+            : { callbackBinrpcDefaultPort: values.callbackBinrpcDefaultPort }),
         idleUnsubscribeMs: values.idleUnsubscribeMs,
     });
 }

package/dist/options.d.ts

@@ -144,6 +144,16 @@ export declare const OPTIONS: {
         readonly describe: "fixed port for the binrpc callback server; must differ from the xmlrpc one";
         readonly defaultDescription: "0, a free port";
     };
+    readonly 'callback-xmlrpc-default-port': {
+        readonly type: "number";
+        readonly describe: "xmlrpc callback port while the configured one is 0; a free port when it is taken (the CCU addon sets 2031)";
+        readonly defaultDescription: "none, a free port";
+    };
+    readonly 'callback-binrpc-default-port': {
+        readonly type: "number";
+        readonly describe: "binrpc callback port while the configured one is 0; a free port when it is taken (the CCU addon sets 2032)";
+        readonly defaultDescription: "none, a free port";
+    };
     readonly 'idle-unsubscribe': {
         readonly type: "string";
         readonly describe: "drop the event subscriptions after this long with no page open (5m, 300s, 0 to disable)";
@@ -221,6 +231,9 @@ export interface WebOptions {
     readonly callbackIp: string | undefined;
     readonly callbackXmlrpcPort: number | undefined;
     readonly callbackBinrpcPort: number | undefined;
+    /** Task 35 (D-43): the CCU addon's fixed callback ports, taken while the configured ones are `0`. */
+    readonly callbackXmlrpcDefaultPort: number | undefined;
+    readonly callbackBinrpcDefaultPort: number | undefined;
     readonly demo: boolean;
     /** D-31, in milliseconds; `0` disables the idle unsubscribe. */
     readonly idleUnsubscribeMs: number;

package/dist/options.js

@@ -144,6 +144,16 @@ export const OPTIONS = {
         describe: 'fixed port for the binrpc callback server; must differ from the xmlrpc one',
         defaultDescription: '0, a free port',
     },
+    'callback-xmlrpc-default-port': {
+        type: 'number',
+        describe: 'xmlrpc callback port while the configured one is 0; a free port when it is taken (the CCU addon sets 2031)',
+        defaultDescription: 'none, a free port',
+    },
+    'callback-binrpc-default-port': {
+        type: 'number',
+        describe: 'binrpc callback port while the configured one is 0; a free port when it is taken (the CCU addon sets 2032)',
+        defaultDescription: 'none, a free port',
+    },
     'idle-unsubscribe': {
         type: 'string',
         describe: 'drop the event subscriptions after this long with no page open (5m, 300s, 0 to disable)',
@@ -292,6 +302,20 @@ export function parseOptions(argv, env = process.env) {
         const value = raw[name] ?? OPTIONS[name].default;
         return value === undefined ? undefined : Number(value);
     };
+    const port = (name) => {
+        const value = number(name);
+        if (value !== undefined && !(Number.isInteger(value) && value >= 0 && value <= 65535)) {
+            throw new CliError(`--${name}: "${String(value)}" is not a port`);
+        }
+        return value;
+    };
+    const callbackXmlrpcDefaultPort = port('callback-xmlrpc-default-port');
+    const callbackBinrpcDefaultPort = port('callback-binrpc-default-port');
+    if (callbackXmlrpcDefaultPort !== undefined && callbackXmlrpcDefaultPort !== 0) {
+        if (callbackXmlrpcDefaultPort === callbackBinrpcDefaultPort) {
+            throw new CliError('--callback-xmlrpc-default-port and --callback-binrpc-default-port must differ');
+        }
+    }
     const logLevel = string('log-level');
     return {
         port: Number(raw['port'] ?? OPTIONS.port.default),
@@ -312,6 +336,8 @@ export function parseOptions(argv, env = process.env) {
         callbackIp: string('callback-ip'),
         callbackXmlrpcPort: number('callback-xmlrpc-port'),
         callbackBinrpcPort: number('callback-binrpc-port'),
+        callbackXmlrpcDefaultPort,
+        callbackBinrpcDefaultPort,
         demo: boolean('demo'),
         idleUnsubscribeMs: parseDuration(string('idle-unsubscribe'), '--idle-unsubscribe'),
         logLevel: isLogLevel(logLevel) ? logLevel : 'info',

package/dist/server.d.ts

@@ -118,6 +118,13 @@ export interface WebHostOptions {
     /** Fixed callback ports, so a container can publish them. `0` picks a free one. */
     readonly callbackXmlrpcPort?: number | undefined;
     readonly callbackBinrpcPort?: number | undefined;
+    /**
+     * Task 35 (D-43): the callback ports taken while the configuration says `0` - the CCU addon's
+     * fixed pair. Handed to the backend and never written to `config.json`, so a port the user set
+     * in the settings dialog always wins and no update of the addon can overwrite it.
+     */
+    readonly callbackXmlrpcDefaultPort?: number | undefined;
+    readonly callbackBinrpcDefaultPort?: number | undefined;
     /** How long `close()` waits for `backend.stop()`. */
     readonly shutdownTimeoutMs?: number;
     /** How often an idle api socket is pinged; `0` turns the heartbeat off. */

package/dist/server.js

@@ -100,6 +100,10 @@ export async function createWebHost(options = {}) {
     let backend;
     if (!demo) {
         await ensureDataDir(dataDir);
+        const defaultCallbackPorts = callbackDefaults(options);
+        if (defaultCallbackPorts !== undefined) {
+            log.info(`callback: default ports xmlrpc=${String(defaultCallbackPorts.xmlrpc)} binrpc=${String(defaultCallbackPorts.binrpc)} while the configuration says 0`);
+        }
         backend = await Backend.open({
             dataDir,
             version: options.version ?? packageVersion(),
@@ -108,6 +112,7 @@ export async function createWebHost(options = {}) {
             // reports them, and Electron's in-process transport reports none - so an Electron
             // window can never be idled out however the backend is configured.
             ...(options.idleUnsubscribeMs === undefined ? {} : { idleUnsubscribeMs: options.idleUnsubscribeMs }),
+            ...(defaultCallbackPorts === undefined ? {} : { defaultCallbackPorts }),
             ...options.backendOptions,
         });
         backend.on('notice', (notice) => {
@@ -545,6 +550,12 @@ function upstreamOf(connection) {
         ...(connection.auth ? { auth: connection.auth } : {}),
     };
 }
+/** Task 35: the default pair, or nothing when neither port is set to anything but `0`. */
+function callbackDefaults(options) {
+    const xmlrpc = options.callbackXmlrpcDefaultPort ?? 0;
+    const binrpc = options.callbackBinrpcDefaultPort ?? 0;
+    return xmlrpc === 0 && binrpc === 0 ? undefined : { xmlrpc, binrpc };
+}
 /** `--ccu`, `--local` and the callback options win over what `config.json` holds. */
 async function applyConnectionOptions(backend, options, log) {
     const wantsHost = options.ccu !== undefined && options.ccu !== '';

package/node_modules/@homematic-manager/backend/dist/api/backend.d.ts

@@ -30,6 +30,15 @@ export interface BackendOptions extends Omit<ConfigStoreOptions, 'version'> {
     /** Roots `data.file` may read from, keyed by the prefix the UI uses. */
     readonly fileRoots?: Readonly<Record<string, string>>;
     readonly callbackHost?: string;
+    /**
+     * Task 35 (D-43): the callback ports taken while the connection's are `0` - the CCU addon's fixed
+     * pair. A property of the host, not of the profile: it is never written to `config.json`, and
+     * `AppConfig.callbackDefaultPorts` reports it so the settings dialog can say what `0` means.
+     */
+    readonly defaultCallbackPorts?: {
+        readonly xmlrpc: number;
+        readonly binrpc: number;
+    };
     readonly rpcTimeoutMs?: number;
     readonly watchdogIntervalMs?: number;
     readonly serviceMessagePollMs?: number;

package/node_modules/@homematic-manager/backend/dist/api/backend.js

@@ -14,7 +14,7 @@
  * main process with it, issue #127).
  */
 import path from 'node:path';
-import { RPC_METHOD_NAMES, RSSI_UNKNOWN, countsAsServiceMessage, isAcknowledgeable, maintenanceAddress, mergeMethodHelp, methodsFor, normaliseDescription, } from '@homematic-manager/core';
+import { RPC_METHOD_NAMES, RSSI_UNKNOWN, countsAsServiceMessage, isAcknowledgeable, maintenanceAddress, mergeMethodHelp, methodsFor, normaliseDescription, repairMisdecodedUtf8, } from '@homematic-manager/core';
 import { CacheStore } from '../cache/store.js';
 import { ConfigStore } from '../config/store.js';
 import { LinkTemplateStore } from '../config/linkTemplates.js';
@@ -37,6 +37,13 @@ import { WriteQueue } from '../write/queue.js';
 export const SERVICE_MESSAGE_POLL_MS = 300_000;
 /** How long the HmIP `getParamset(:0, VALUES)` sweep waits for the device list to settle. */
 export const HMIP_SWEEP_DELAY_MS = 1000;
+/**
+ * An HmIP interface, by name or by interface type - the same rule the UI's settings dialog uses to
+ * count the messages it asks about (task 34), so the question and the writes agree.
+ */
+function isHmipInterface(name, type) {
+    return /hmip/i.test(name) || /hmip/i.test(type);
+}
 /** Implements the whole contract. `open()` loads, `start()` connects, `stop()` disconnects. */
 export class Backend {
     events;
@@ -263,7 +270,7 @@ export class Backend {
             case 'config.get':
                 return this.#configWithDetected();
             case 'config.set':
-                return this.#setConfig(p[0]);
+                return this.#setConfig(p[0], params[1]);
             case 'config.discover':
                 return this.#discover();
             case 'config.clearCaches':
@@ -473,6 +480,9 @@ export class Backend {
                 this.#onCall(record);
             },
             ...(this.#options.callbackHost === undefined ? {} : { callbackHost: this.#options.callbackHost }),
+            ...(this.#options.defaultCallbackPorts === undefined
+                ? {}
+                : { defaultCallbackPorts: this.#options.defaultCallbackPorts }),
             ...(this.#options.rpcTimeoutMs === undefined ? {} : { rpcTimeoutMs: this.#options.rpcTimeoutMs }),
             ...(this.#options.watchdogIntervalMs === undefined
                 ? {}
@@ -756,13 +766,16 @@ export class Backend {
      * a device that is unreachable is not going to take a write either, which is the normal case
      * here and not worth an error dialog.
      */
-    #noteUnreach(interfaceName, address, datapoint, value) {
+    #noteUnreach(interfaceName, address, datapoint, value, options = {}) {
         if (!this.#caches.unreach.note(interfaceName, address, datapoint, value, this.#now())) {
             return;
         }
         this.#caches.saveUnreach();
         this.events.emit('unreach.changed', this.#caches.unreach.list());
-        if (datapoint === 'STICKY_UNREACH' && value === true && this.#config.connection.autoAckStickyUnreach === true) {
+        if (options.acknowledge !== false &&
+            datapoint === 'STICKY_UNREACH' &&
+            value === true &&
+            this.#config.connection.autoAckStickyUnreach === true) {
             void this.#acknowledge(interfaceName, address, datapoint).catch((error) => {
                 this.#notice('info', `${address}: STICKY_UNREACH could not be acknowledged automatically: ${errorMessage(error)}`, interfaceName);
             });
@@ -799,12 +812,28 @@ export class Backend {
      * configuration
      */
     #configWithDetected() {
-        return this.#config.config;
+        return this.#withHostFacts(this.#config.config);
     }
-    async #setConfig(connection) {
+    /**
+     * What the host adds to the stored configuration before anybody sees it: task 35's callback
+     * ports a `0` stands for. Added to every `AppConfig` that leaves the backend - `config.get`,
+     * `config.set` and both `config.changed` events - so the dialog never loses the hint on a save.
+     */
+    #withHostFacts(config) {
+        const ports = this.#options.defaultCallbackPorts;
+        return ports === undefined
+            ? config
+            : { ...config, callbackDefaultPorts: { xmlrpc: ports.xmlrpc, binrpc: ports.binrpc } };
+    }
+    async #setConfig(connection, options) {
         const previousHost = this.#config.connection.host;
+        // Task 34 (#147, D-42): the messages the settings dialog asked about, taken before the
+        // reconnect, and only on the save that switches the auto-acknowledge from off to on.
+        const existing = options?.acknowledgeExisting === true && this.#config.connection.autoAckStickyUnreach !== true
+            ? this.#stickyUnreachMessages()
+            : [];
         await this.#disconnect();
-        const config = await this.#config.setConnection(connection);
+        const config = this.#withHostFacts(await this.#config.setConnection(connection));
         this.#writeLog.setRpcLogFolder(config.connection.rpcLogFolder);
         if (config.connection.host !== previousHost) {
             await this.#caches.flush();
@@ -820,14 +849,61 @@ export class Backend {
         this.events.emit('config.changed', config);
         if (!this.#stopped && validateConnection(config.connection).length === 0) {
             await this.#connect();
+            // after the reconnect, because a write needs the interface; not awaited, so the
+            // settings dialog closes as quickly as ever and the writes show up in the RPC log
+            if (existing.length > 0 &&
+                config.connection.autoAckStickyUnreach === true &&
+                config.connection.host === previousHost) {
+                void this.#acknowledgeExisting(existing);
+            }
         }
         return config;
     }
+    /**
+     * Task 34: the `STICKY_UNREACH` messages in the list, without HmIP's.
+     *
+     * D-42 says nothing is acknowledged on HmIP: hmipserver has no such flag on real hardware, and
+     * where one appears anyway (a simulator, a future firmware) this is not the switch that should
+     * start writing to those devices.
+     */
+    #stickyUnreachMessages() {
+        const states = this.#manager?.states() ?? [];
+        return this.#caches.listServiceMessages().filter((message) => {
+            if (message.datapoint !== 'STICKY_UNREACH' || message.value === false) {
+                return false;
+            }
+            const type = states.find((state) => state.name === message.interfaceName)?.type ?? '';
+            return !isHmipInterface(message.interfaceName, type);
+        });
+    }
+    /**
+     * Task 34 (#147, D-42): acknowledges the messages that were in the list when the option was
+     * switched on, one after another, each with exactly the write of the acknowledge button
+     * (`#acknowledge`, the paced `setValue`). A message that is gone by now - the device came back
+     * and somebody acknowledged it, or the edge above got there first - is skipped rather than
+     * written twice. A failure is a notice and the write log's red line, as for the edge.
+     */
+    async #acknowledgeExisting(messages) {
+        for (const message of messages) {
+            const listed = this.#caches
+                .listServiceMessages(message.interfaceName)
+                .some((entry) => entry.address === message.address && entry.datapoint === message.datapoint);
+            if (!listed || this.#stopped) {
+                continue;
+            }
+            try {
+                await this.#acknowledge(message.interfaceName, message.address, message.datapoint);
+            }
+            catch (error) {
+                this.#notice('info', `${message.address}: STICKY_UNREACH could not be acknowledged: ${errorMessage(error)}`, message.interfaceName);
+            }
+        }
+    }
     async #discover() {
         const discover = this.#options.discover ?? ((options) => discoverCcus(options));
         const found = await discover({ tls: this.#config.connection.tls });
         this.#config.setDiscovered(found);
-        this.events.emit('config.changed', this.#config.config);
+        this.events.emit('config.changed', this.#withHostFacts(this.#config.config));
         return found;
     }
     async #clearCaches() {
@@ -879,7 +955,14 @@ export class Backend {
         return null;
     }
     async #setInstallMode(interfaceName, on, options) {
-        for (const call of installModeCalls(on, options ?? {})) {
+        const effective = { ...options };
+        if (interfaceName === 'HmIP-RF') {
+            // Task 28, measured in the lab: hmipserver's third `setInstallMode` parameter is a String,
+            // and `setInstallMode(true, 30, 1)` got an empty HTTP reply and no install mode at all.
+            // BidCos's mode integer never reaches HmIP, whoever asks for it.
+            delete effective.mode;
+        }
+        for (const call of installModeCalls(on, effective)) {
             await this.#write(interfaceName, call.method, call.params);
         }
         return null;
@@ -1167,11 +1250,27 @@ export class Backend {
             this.events.emit('serviceMessages.changed', this.#caches.listServiceMessages());
         }
     }
-    /** Files the RSSI and the service messages of a `getParamset(<device>:0, VALUES)` answer. */
+    /**
+     * Files the RSSI, the service messages and the unreach state of a `getParamset(<device>:0,
+     * VALUES)` answer.
+     *
+     * Task 34 (B-9): the unreach state goes through `#noteUnreach` like the BidCos poll's, so the
+     * Funk tab counts the outages of HmIP devices that no event reported. `UNREACH` is what says
+     * whether the device is away now; `STICKY_UNREACH` is only read where there is no `UNREACH`,
+     * because a standing sticky flag next to `UNREACH: false` would count the same outage again on
+     * every sweep. Nothing is acknowledged from here: a sweep is a read, and HmIP has nothing to
+     * acknowledge (D-42).
+     */
     #applyHmipMaintenance(interfaceName, address, values) {
         const device = address.split(':')[0] ?? address;
         this.#caches.rssi(interfaceName).applyHmipParamset(device, values);
-        return this.#caches.serviceMessages.applyParamset(interfaceName, address, values);
+        const changed = this.#caches.serviceMessages.applyParamset(interfaceName, address, values);
+        const datapoint = 'UNREACH' in values ? 'UNREACH' : 'STICKY_UNREACH';
+        const value = values[datapoint];
+        if (value !== undefined) {
+            this.#noteUnreach(interfaceName, address, datapoint, value, { acknowledge: false });
+        }
+        return changed;
     }
     /**
      * Acknowledging a service message writes its datapoint. An `ACTION` is confirmed with `true`,
@@ -1308,17 +1407,30 @@ function asLinks(value) {
     const links = [];
     for (const entry of value) {
         if (isStruct(entry) && typeof entry['SENDER'] === 'string' && typeof entry['RECEIVER'] === 'string') {
-            links.push(entry);
+            links.push(withLinkText(entry));
         }
     }
     return links;
 }
 function asLink(value, sender, receiver) {
     if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
-        return { SENDER: sender, RECEIVER: receiver, ...value };
+        return withLinkText({ SENDER: sender, RECEIVER: receiver, ...value });
     }
     return { SENDER: sender, RECEIVER: receiver };
 }
+/**
+ * B-23 (#156): a link's `NAME` and `DESCRIPTION` are UTF-8 in rfd - the WebUI's default description
+ * "Standardverknüpfung" and our own `setLinkInfo` alike - and the XML-RPC client reads them as
+ * ISO-8859-1. Repaired here, once, for both reads; a BIN-RPC answer (its library decodes UTF-8) and
+ * a real ISO-8859-1 text pass through unchanged.
+ */
+function withLinkText(link) {
+    return {
+        ...link,
+        ...(typeof link.NAME === 'string' ? { NAME: repairMisdecodedUtf8(link.NAME) } : {}),
+        ...(typeof link.DESCRIPTION === 'string' ? { DESCRIPTION: repairMisdecodedUtf8(link.DESCRIPTION) } : {}),
+    };
+}
 function asBidcosInterfaces(value) {
     if (!Array.isArray(value)) {
         return [];

package/node_modules/@homematic-manager/backend/dist/devices/installMode.js

@@ -68,6 +68,15 @@ export function installModeCalls(on, options = {}) {
     }
     const seconds = installSeconds(options.seconds);
     const calls = [];
+    if (options.hmipKeyMode === 'ANY') {
+        // Task 28: any HmIP device, no SGTIN. hmipserver's third parameter is a String - the address
+        // to admit - so BidCos's `mode` integer there is a type fault, which is why "setInstallMode
+        // does not work on HmIP" gets reported. Two arguments arm the interface for whatever asks to
+        // join next, as the CCU WebUI's key-server branch sends it (setinstallmodehmip.tcl); an SGTIN
+        // still in the dialog's field or a BidCos mode must not turn into a third one.
+        calls.push({ method: 'setInstallMode', params: [true, seconds] });
+        return calls;
+    }
     if (options.tempKey !== undefined && options.tempKey !== '') {
         // issue #20: the temporary key has to be set before the install mode opens
         calls.push({ method: 'setTempKey', params: [options.tempKey] });

package/node_modules/@homematic-manager/backend/dist/interfaces/manager.d.ts

@@ -73,8 +73,16 @@ export interface InterfaceManagerOptions {
      * interface that fails once and then works.
      */
     readonly initBackoffMs?: number;
-    /** Address to bind the callback servers to; `0.0.0.0` unless the addon says loopback. */
+    /** Address to bind the callback servers to; left out, {@link callbackBindHost} decides. */
     readonly callbackHost?: string;
+    /**
+     * Task 35 (D-43): the callback ports taken while the connection's are `0`. The CCU addon sets a
+     * fixed pair; the desktop app, npm and Docker leave this out and keep the kernel's free port.
+     */
+    readonly defaultCallbackPorts?: {
+        readonly xmlrpc: number;
+        readonly binrpc: number;
+    };
     /** Injected by the tests. */
     readonly createClient?: (options: RpcClientOptions) => RpcClient;
     readonly createCallbackServers?: (handler: CallbackHandler) => CallbackServerSet;
@@ -95,6 +103,17 @@ export interface InterfaceManagerOptions {
  * takes the whole connection down on a CCU whose HmIP access point is not paired yet.
  */
 export declare function firstBidcosInterfaceAddress(result: unknown): string | undefined;
+/**
+ * Where the callback servers listen when the host names no address of its own (task 35).
+ *
+ * Where the interface processes are told to call back on the loopback - the CCU itself (`local`)
+ * with no address configured (#144), or the loopback configured by hand - nothing has to reach the
+ * servers from anywhere else, and they listen on `127.0.0.1` only. It matters more with the addon's
+ * fixed ports: a listener on every interface would be a known port on the LAN of every CCU whose
+ * firewall is open, and anything on that LAN could send it events. Everywhere else the CCU is
+ * across a network and `undefined` keeps `0.0.0.0`.
+ */
+export declare function callbackBindHost(connection: ConnectionConfig): string | undefined;
 /** Connects, watches and disconnects every configured interface. */
 export declare class InterfaceManager {
     #private;

package/node_modules/@homematic-manager/backend/dist/interfaces/manager.js

@@ -62,6 +62,20 @@ export function firstBidcosInterfaceAddress(result) {
     const address = first['ADDRESS'];
     return typeof address === 'string' && address !== '' ? address : undefined;
 }
+/**
+ * Where the callback servers listen when the host names no address of its own (task 35).
+ *
+ * Where the interface processes are told to call back on the loopback - the CCU itself (`local`)
+ * with no address configured (#144), or the loopback configured by hand - nothing has to reach the
+ * servers from anywhere else, and they listen on `127.0.0.1` only. It matters more with the addon's
+ * fixed ports: a listener on every interface would be a known port on the LAN of every CCU whose
+ * firewall is open, and anything on that LAN could send it events. Everywhere else the CCU is
+ * across a network and `undefined` keeps `0.0.0.0`.
+ */
+export function callbackBindHost(connection) {
+    const { ip } = connection.callback;
+    return ip === LOOPBACK_IP || (ip === '' && connection.local === true) ? LOOPBACK_IP : undefined;
+}
 /** Connects, watches and disconnects every configured interface. */
 export class InterfaceManager {
     #options;
@@ -79,13 +93,22 @@ export class InterfaceManager {
     }
     #defaultServers(handler) {
         const callback = this.#options.connection.callback;
+        const host = this.#options.callbackHost ?? callbackBindHost(this.#options.connection);
         return new CallbackServers({
             handler,
-            ...(this.#options.callbackHost === undefined ? {} : { host: this.#options.callbackHost }),
+            ...(host === undefined ? {} : { host }),
             ports: { xmlrpc: callback.xmlrpcPort, binrpc: callback.binrpcPort },
+            ...(this.#options.defaultCallbackPorts === undefined
+                ? {}
+                : { defaultPorts: this.#options.defaultCallbackPorts }),
             onError: (error) => {
                 this.#options.onNotice('error', `callback server: ${errorMessage(error)}`);
             },
+            // a warning, not an error: the subscription works on the free port, only the fixed URL
+            // that keeps the handler lists short is gone until the next start
+            onFallback: (protocol, port, error) => {
+                this.#options.onNotice('warn', `callback server: the default ${protocol} port ${String(port)} is taken, a free port is used until the next start (${errorMessage(error)})`);
+            },
         });
     }
     /**

package/node_modules/@homematic-manager/backend/dist/rpc/server.d.ts

@@ -88,11 +88,23 @@ export declare class CallbackServers implements CallbackServerSet {
     constructor(options: {
         handler: CallbackHandler;
         host?: string;
+        /** The configured ports; `0` means none is configured. */
         ports: {
             xmlrpc: number;
             binrpc: number;
         };
+        /**
+         * Task 35 (D-43): the port a protocol takes while its configured port is `0` - the CCU
+         * addon's fixed pair, so that a restart registers the very URL it registered before.
+         * Unlike a configured port, a default that is taken is no error: the server falls back to
+         * a free port for this start, and `onFallback` hears about it once.
+         */
+        defaultPorts?: {
+            xmlrpc: number;
+            binrpc: number;
+        };
         onError?: (error: unknown) => void;
+        onFallback?: (protocol: RpcProtocol, port: number, error: unknown) => void;
     });
     /** Starts the server for a protocol if it is not running yet, and returns its port. */
     ensure(protocol: RpcProtocol): Promise<number>;

package/node_modules/@homematic-manager/backend/dist/rpc/server.js

@@ -199,11 +199,18 @@ export class CallbackServer {
         return new Promise((resolve, reject) => {
             const server = xmlrpc.createServer({ host: this.host, port: this.#requestedPort });
             this.#xmlrpcServer = server;
+            let listening = false;
             server.on('error', (error) => {
-                reject(connectionError(`xmlrpc callback server on port ${String(this.#requestedPort)}: ${error.message}`, error));
+                // a bind that fails is the rejection's to report, once; `onError` is for a server
+                // that is running
+                if (!listening) {
+                    reject(connectionError(`xmlrpc callback server on port ${String(this.#requestedPort)}: ${error.message}`, error));
+                    return;
+                }
                 this.#onError(error);
             });
             server.on('listening', () => {
+                listening = true;
                 const address = server.httpServer.address();
                 resolve(typeof address === 'object' && address !== null ? address.port : this.#requestedPort);
             });
@@ -221,11 +228,16 @@ export class CallbackServer {
         return new Promise((resolve, reject) => {
             const server = binrpc.createServer({ host: this.host, port: this.#requestedPort });
             this.#binrpcServer = server;
+            let listening = false;
             server.on('error', (error) => {
-                reject(connectionError(`binrpc callback server on port ${String(this.#requestedPort)}: ${error.message}`, error));
+                if (!listening) {
+                    reject(connectionError(`binrpc callback server on port ${String(this.#requestedPort)}: ${error.message}`, error));
+                    return;
+                }
                 this.#onError(error);
             });
             server.on('listening', () => {
+                listening = true;
                 const address = server.server.address();
                 resolve(typeof address === 'object' && address !== null ? address.port : this.#requestedPort);
             });
@@ -284,12 +296,16 @@ export class CallbackServers {
     #handler;
     #host;
     #ports;
+    #defaultPorts;
     #onError;
+    #onFallback;
     constructor(options) {
         this.#handler = options.handler;
         this.#host = options.host ?? '0.0.0.0';
         this.#ports = options.ports;
+        this.#defaultPorts = options.defaultPorts ?? { xmlrpc: 0, binrpc: 0 };
         this.#onError = options.onError ?? (() => undefined);
+        this.#onFallback = options.onFallback ?? (() => undefined);
     }
     /** Starts the server for a protocol if it is not running yet, and returns its port. */
     async ensure(protocol) {
@@ -297,10 +313,24 @@ export class CallbackServers {
         if (running) {
             return running.port;
         }
+        const configured = protocol === 'binrpc' ? this.#ports.binrpc : this.#ports.xmlrpc;
+        const preferred = protocol === 'binrpc' ? this.#defaultPorts.binrpc : this.#defaultPorts.xmlrpc;
+        if (configured !== 0 || preferred === 0) {
+            return this.#start(protocol, configured);
+        }
+        try {
+            return await this.#start(protocol, preferred);
+        }
+        catch (error) {
+            this.#onFallback(protocol, preferred, error);
+            return this.#start(protocol, 0);
+        }
+    }
+    async #start(protocol, port) {
         const server = new CallbackServer({
             protocol,
             host: this.#host,
-            port: protocol === 'binrpc' ? this.#ports.binrpc : this.#ports.xmlrpc,
+            port,
             handler: this.#handler,
             onError: this.#onError,
         });

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

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