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

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,13 @@ function startHost(values, log, version) {
         ...(values.callbackIp === undefined ? {} : { callbackIp: values.callbackIp }),
         ...(values.callbackXmlrpcPort === undefined ? {} : { callbackXmlrpcPort: values.callbackXmlrpcPort }),
         ...(values.callbackBinrpcPort === undefined ? {} : { callbackBinrpcPort: values.callbackBinrpcPort }),
+        ...(values.inContainer ? { inContainer: true } : {}),
+        ...(values.callbackXmlrpcDefaultPort === undefined
+            ? {}
+            : { callbackXmlrpcDefaultPort: values.callbackXmlrpcDefaultPort }),
+        ...(values.callbackBinrpcDefaultPort === undefined
+            ? {}
+            : { callbackBinrpcDefaultPort: values.callbackBinrpcDefaultPort }),
         idleUnsubscribeMs: values.idleUnsubscribeMs,
     });
 }

package/dist/options.d.ts

@@ -144,6 +144,21 @@ 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 'in-container': {
+        readonly type: "boolean";
+        readonly describe: "we run in a container (the image sets it): the interface popup says to publish the callback ports unchanged";
+        readonly default: false;
+    };
     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 +236,11 @@ 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;
+    /** Task 38: set by the image's `HMM_IN_CONTAINER`. */
+    readonly inContainer: boolean;
     readonly demo: boolean;
     /** D-31, in milliseconds; `0` disables the idle unsubscribe. */
     readonly idleUnsubscribeMs: number;

package/dist/options.js

@@ -144,6 +144,21 @@ 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',
+    },
+    'in-container': {
+        type: 'boolean',
+        describe: 'we run in a container (the image sets it): the interface popup says to publish the callback ports unchanged',
+        default: false,
+    },
     'idle-unsubscribe': {
         type: 'string',
         describe: 'drop the event subscriptions after this long with no page open (5m, 300s, 0 to disable)',
@@ -292,6 +307,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 +341,9 @@ export function parseOptions(argv, env = process.env) {
         callbackIp: string('callback-ip'),
         callbackXmlrpcPort: number('callback-xmlrpc-port'),
         callbackBinrpcPort: number('callback-binrpc-port'),
+        callbackXmlrpcDefaultPort,
+        callbackBinrpcDefaultPort,
+        inContainer: boolean('in-container') ?? false,
         demo: boolean('demo'),
         idleUnsubscribeMs: parseDuration(string('idle-unsubscribe'), '--idle-unsubscribe'),
         logLevel: isLogLevel(logLevel) ? logLevel : 'info',

package/dist/server.d.ts

@@ -110,14 +110,30 @@ export interface WebHostOptions {
     /** Written to `ConnectionConfig.local` - the addon's "we run on the CCU" mode. */
     readonly local?: boolean | undefined;
     /**
-     * Written to `ConnectionConfig.callback`. A host that cannot see the address the CCU reaches it
+     * Laid over `ConnectionConfig.callback`. A host that cannot see the address the CCU reaches it
      * on has to be told: a container on a bridge network sees `172.17.0.x`, and an `init` that
      * announces that address gets no events at all. With `--network host` none of this is needed.
+     *
+     * Task 38: these three are pinned, not written. They win over `config.json` for as long as the
+     * host runs with them, the settings dialog shows them read-only, and the file keeps what the
+     * user saved. An empty address and a port of `0` pin nothing.
      */
     readonly callbackIp?: string | undefined;
-    /** Fixed callback ports, so a container can publish them. `0` picks a free one. */
+    /** Fixed callback ports, so a container can publish them. `0` pins nothing. */
     readonly callbackXmlrpcPort?: number | undefined;
     readonly callbackBinrpcPort?: number | undefined;
+    /**
+     * Task 38: the host runs in a container (`HMM_IN_CONTAINER`, set by the image). The interface
+     * popup then says beside each callback URL that its port must be published unchanged.
+     */
+    readonly inContainer?: boolean | 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

@@ -24,7 +24,7 @@
 import fs from 'node:fs/promises';
 import http from 'node:http';
 import path from 'node:path';
-import { ApiWebSocketServer, Backend, RegaAuthenticator } from '@homematic-manager/backend';
+import { ApiWebSocketServer, Backend, RegaAuthenticator, } from '@homematic-manager/backend';
 import { applyCookieToken, applySessionToken, clearedSessionCookie, createToken, isLoopbackHost, readCookie, SESSION_COOKIE, sessionCookie, TOKEN_COOKIE, tokenCookie, } from './auth.js';
 import { DeviceImageService, readIconMapFile } from './images.js';
 import { clientAddress, parseLoginForm, pickLanguage, readBody, renderLoginPage, } from './login.js';
@@ -100,6 +100,20 @@ 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`);
+        }
+        const pinnedCallback = callbackPins(options);
+        if (pinnedCallback !== undefined) {
+            const { ip, xmlrpcPort, binrpcPort } = pinnedCallback;
+            const parts = [
+                ...(ip === undefined ? [] : [`ip=${ip}`]),
+                ...(xmlrpcPort === undefined ? [] : [`xmlrpc=${String(xmlrpcPort)}`]),
+                ...(binrpcPort === undefined ? [] : [`binrpc=${String(binrpcPort)}`]),
+            ];
+            log.info(`callback: ${parts.join(' ')} set at start, read-only in the settings dialog`);
+        }
         backend = await Backend.open({
             dataDir,
             version: options.version ?? packageVersion(),
@@ -108,6 +122,9 @@ 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 }),
+            ...(pinnedCallback === undefined ? {} : { pinnedCallback }),
+            ...(options.inContainer === true ? { inContainer: true } : {}),
             ...options.backendOptions,
         });
         backend.on('notice', (notice) => {
@@ -545,17 +562,36 @@ function upstreamOf(connection) {
         ...(connection.auth ? { auth: connection.auth } : {}),
     };
 }
-/** `--ccu`, `--local` and the callback options win over what `config.json` holds. */
+/** 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 };
+}
+/**
+ * Task 38: the callback fields given at start, or nothing. An empty address and a port of `0` are
+ * "not configured" in the connection model and pin nothing.
+ */
+function callbackPins(options) {
+    const pins = {
+        ...(options.callbackIp === undefined || options.callbackIp === '' ? {} : { ip: options.callbackIp }),
+        ...(options.callbackXmlrpcPort === undefined || options.callbackXmlrpcPort === 0
+            ? {}
+            : { xmlrpcPort: options.callbackXmlrpcPort }),
+        ...(options.callbackBinrpcPort === undefined || options.callbackBinrpcPort === 0
+            ? {}
+            : { binrpcPort: options.callbackBinrpcPort }),
+    };
+    return Object.keys(pins).length === 0 ? undefined : pins;
+}
+/**
+ * `--ccu` and `--local` win over what `config.json` holds, and are written to it. The callback
+ * options are not: since task 38 the backend lays them over the profile (`pinnedCallback`).
+ */
 async function applyConnectionOptions(backend, options, log) {
     const wantsHost = options.ccu !== undefined && options.ccu !== '';
     const wantsLocal = options.local !== undefined;
-    const callback = {
-        ...(options.callbackIp === undefined ? {} : { ip: options.callbackIp }),
-        ...(options.callbackXmlrpcPort === undefined ? {} : { xmlrpcPort: options.callbackXmlrpcPort }),
-        ...(options.callbackBinrpcPort === undefined ? {} : { binrpcPort: options.callbackBinrpcPort }),
-    };
-    const wantsCallback = Object.keys(callback).length > 0;
-    if (!wantsHost && !wantsLocal && !wantsCallback) {
+    if (!wantsHost && !wantsLocal) {
         return;
     }
     const config = await backend.request('config.get');
@@ -563,22 +599,11 @@ async function applyConnectionOptions(backend, options, log) {
         ...config.connection,
         ...(wantsHost ? { host: options.ccu } : {}),
         ...(wantsLocal ? { local: options.local } : {}),
-        callback: { ...config.connection.callback, ...callback },
     };
-    if (connection.host === config.connection.host &&
-        connection.local === config.connection.local &&
-        connection.callback.ip === config.connection.callback.ip &&
-        connection.callback.xmlrpcPort === config.connection.callback.xmlrpcPort &&
-        connection.callback.binrpcPort === config.connection.callback.binrpcPort) {
+    if (connection.host === config.connection.host && connection.local === config.connection.local) {
         return;
     }
-    if (wantsHost || wantsLocal) {
-        log.info(`connection: host=${connection.host}${connection.local === true ? ' (local)' : ''}`);
-    }
-    if (wantsCallback) {
-        const { ip, xmlrpcPort, binrpcPort } = connection.callback;
-        log.info(`callback: ${ip === '' ? 'auto' : ip} xmlrpc=${String(xmlrpcPort)} binrpc=${String(binrpcPort)}`);
-    }
+    log.info(`connection: host=${connection.host}${connection.local === true ? ' (local)' : ''}`);
     await backend.request('config.set', connection);
 }
 async function withTimeout(work, ms, onTimeout) {

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

@@ -30,6 +30,21 @@ 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;
+    };
+    /**
+     * Task 38: the host runs in a container (the image sets `HMM_IN_CONTAINER`). Where its callback
+     * servers listen beyond the loopback, `AppConfig.publishCallbackPorts` tells the interface
+     * popup to say that the callback ports must be published unchanged.
+     */
+    readonly inContainer?: boolean;
     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, callbackPinOption, normaliseDescription, repairMisdecodedUtf8, } from '@homematic-manager/core';
 import { CacheStore } from '../cache/store.js';
 import { ConfigStore } from '../config/store.js';
 import { LinkTemplateStore } from '../config/linkTemplates.js';
@@ -23,7 +23,7 @@ import { DataFileServer } from '../data/files.js';
 import { installModeCalls } from '../devices/installMode.js';
 import { discoverCcus } from '../discovery/discover.js';
 import { BackendError, configError, connectionError, errorMessage, internalError, isMethodUnsupported, validationError, } from '../errors.js';
-import { InterfaceManager, firstBidcosInterfaceAddress } from '../interfaces/manager.js';
+import { InterfaceManager, LOOPBACK_IP, callbackBindHost, firstBidcosInterfaceAddress, } from '../interfaces/manager.js';
 import { MetaService } from '../meta/service.js';
 import { RegaService } from '../rega/client.js';
 import { listDevicesAnswer } from '../rpc/server.js';
@@ -37,6 +37,19 @@ 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);
+}
+/** Task 38: how a log line names a callback field. */
+const CALLBACK_FIELD_WORDS = {
+    ip: 'callback address',
+    xmlrpcPort: 'XML-RPC callback port',
+    binrpcPort: 'BIN-RPC callback port',
+};
 /** Implements the whole contract. `open()` loads, `start()` connects, `stop()` disconnects. */
 export class Backend {
     events;
@@ -80,6 +93,8 @@ export class Backend {
      */
     #noServiceMessages = new Set();
     #idleTimer;
+    /** Task 38: the saved callback values a pinned one replaces are logged by the first `start()` only. */
+    #pinsReported = false;
     constructor(options, config, caches) {
         this.#options = options;
         this.#config = config;
@@ -151,6 +166,14 @@ export class Backend {
         if (this.#config.importedFromLegacy) {
             this.#notice('info', 'the configuration of Homematic Manager 2.x was imported');
         }
+        if (!this.#pinsReported) {
+            // Task 38: once per process - the value in config.json stays, it only has no effect
+            this.#pinsReported = true;
+            for (const { field, saved, pinned } of this.#config.ignoredCallback) {
+                this.#notice('info', `callback: the saved ${CALLBACK_FIELD_WORDS[field]} ${String(saved)} is ignored, ` +
+                    `${callbackPinOption(field)} sets ${String(pinned)}`);
+            }
+        }
         const problems = validateConnection(this.#config.connection);
         if (problems.length > 0) {
             this.#notice('info', `not connecting: ${problems.join(', ')}`);
@@ -263,7 +286,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 +496,10 @@ export class Backend {
                 this.#onCall(record);
             },
             ...(this.#options.callbackHost === undefined ? {} : { callbackHost: this.#options.callbackHost }),
+            ...(this.#options.defaultCallbackPorts === undefined
+                ? {}
+                : { defaultCallbackPorts: this.#options.defaultCallbackPorts }),
+            ...(this.#config.callbackPins === undefined ? {} : { callbackPins: this.#config.callbackPins }),
             ...(this.#options.rpcTimeoutMs === undefined ? {} : { rpcTimeoutMs: this.#options.rpcTimeoutMs }),
             ...(this.#options.watchdogIntervalMs === undefined
                 ? {}
@@ -756,13 +783,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 +829,35 @@ export class Backend {
      * configuration
      */
     #configWithDetected() {
-        return this.#config.config;
+        return this.#withHostFacts(this.#config.config);
+    }
+    /**
+     * 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;
+        const pins = this.#config.callbackPins;
+        // Task 38: a container whose callback servers listen on the loopback only has nothing to publish
+        const bindHost = this.#options.callbackHost ?? callbackBindHost(config.connection);
+        const publish = this.#options.inContainer === true && bindHost !== LOOPBACK_IP;
+        return {
+            ...config,
+            ...(ports === undefined ? {} : { callbackDefaultPorts: { xmlrpc: ports.xmlrpc, binrpc: ports.binrpc } }),
+            ...(pins === undefined ? {} : { callbackPinned: { ...pins } }),
+            ...(publish ? { publishCallbackPorts: true } : {}),
+        };
     }
-    async #setConfig(connection) {
+    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 +873,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 +979,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 +1274,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 +1431,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/config/store.d.ts

@@ -17,10 +17,26 @@
  * D-17's one-time import of the 2.x configuration happens exactly when there is no `config.json`
  * yet, which is the only definition of "first start" that survives a reinstall.
  */
-import type { AppConfig, ConnectionConfig, DiscoveredCcu } from '@homematic-manager/core';
+import type { AppConfig, CallbackPins, ConnectionConfig, DiscoveredCcu } from '@homematic-manager/core';
 import { type LegacyEnvironment } from './legacyImport.js';
 /** A host as a directory name: everything unusual becomes `_`. */
 export declare function hostKey(host: string): string;
+/**
+ * Task 38: the callback fields the host was started with (`HMM_CALLBACK_*`, `--callback-*`). An
+ * empty address and a port of `0` are "nothing set" in the connection model, so they pin nothing.
+ */
+export interface PinnedCallback {
+    readonly ip?: string | undefined;
+    readonly xmlrpcPort?: number | undefined;
+    readonly binrpcPort?: number | undefined;
+}
+type CallbackField = keyof CallbackPins;
+/** A saved callback value the host's own one replaced on this start. */
+export interface IgnoredCallbackValue {
+    readonly field: CallbackField;
+    readonly saved: string | number;
+    readonly pinned: string | number;
+}
 export interface ConfigStoreOptions {
     /** The profile directory; created on the first write. */
     readonly dataDir: string;
@@ -32,6 +48,12 @@ export interface ConfigStoreOptions {
     readonly importLegacy?: boolean;
     /** Where the 2.x configuration is looked for; injected by the tests. */
     readonly legacyEnvironment?: LegacyEnvironment;
+    /**
+     * Task 38: callback fields set at start. They win over `config.json` in everything the store
+     * hands out, a `setConnection` cannot change them, and they are never written to the file - the
+     * file keeps what the user saved, so a start without the option goes back to that.
+     */
+    readonly pinnedCallback?: PinnedCallback;
 }
 /** The persisted `AppConfig` plus the derived fields the UI wants with it. */
 export declare class ConfigStore {
@@ -39,6 +61,10 @@ export declare class ConfigStore {
     readonly dataDir: string;
     readonly file: string;
     private constructor();
+    /** Task 38: which callback fields the host pinned; `undefined` when it pinned none. */
+    get callbackPins(): CallbackPins | undefined;
+    /** Task 38: the saved callback values a pinned one replaced when the store was opened. */
+    get ignoredCallback(): readonly IgnoredCallbackValue[];
     /** Loads the configuration, importing the 2.x one when this is the first start (D-17). */
     static open(options: ConfigStoreOptions): Promise<ConfigStore>;
     get importedFromLegacy(): boolean;
@@ -55,4 +81,5 @@ export declare class ConfigStore {
     cacheFile(name: string): string;
     save(): Promise<void>;
 }
+export {};
 //# sourceMappingURL=store.d.ts.map