hm2mqtt 3.2.0 → 3.3.0

package/README.md

@@ -35,17 +35,51 @@ state directory; broker credentials can live in the shared `/etc/mqtt-interfaces
 `--uninstall -n hm` removes the instance. `--config-schema` prints a JSON schema of all options
 (management UIs like [she](https://github.com/hobbyquaker/she) build their config forms from it).
 
-Docker (build from the Dockerfile — no published image yet):
+Docker (multi-arch image for amd64, arm64 and armv7):
 
 ```
-docker build -t hm2mqtt .
-docker run -d --name hm2mqtt --network host -v hm2mqtt:/data \
-  -e HM2MQTT_CCU_ADDRESS=homematic-ccu3 -e HM2MQTT_MQTT_URL=mqtt://broker hm2mqtt
+docker run -d --name hm2mqtt --restart unless-stopped --network host -v hm2mqtt:/data \
+  -e HM2MQTT_CCU_ADDRESS=homematic-ccu3 -e HM2MQTT_MQTT_URL=mqtt://broker \
+  ghcr.io/hobbyquaker/hm2mqtt.js
 ```
 
 Host networking, or publish 2126/2127 and set `HM2MQTT_INIT_ADDRESS` to the docker host's address
 so the CCU can call back. `--restart unless-stopped` brings it back after `maintenance/set/restart`.
 
+## Finding the CCU
+
+```
+hm2mqtt --discover
+```
+
+broadcasts the eQ-3 discovery datagram (UDP 43439) and prints every CCU that answers, with its
+firmware version and the interfaces whose ports are open:
+
+```
+172.16.24.145  eQ3-HmIP-CCU3-App  serial 3014F711A0001F58A992F585  [ReGa BidCos-RF BidCos-Wired HmIP-RF VirtualDevices]  (udp)
+```
+
+`--discover-json` prints the same as JSON. `-a auto` runs the scan at start and uses the CCU it
+found — it refuses to start when none or more than one answers, rather than bridging the wrong
+house:
+
+```
+hm2mqtt -a auto -u mqtt://broker
+```
+
+A broadcast does not cross a router. If the CCU is on another subnet — a separate VLAN for the
+house automation is a common setup — name it (or its subnet's broadcast address):
+
+```
+hm2mqtt --discover --discover-address 172.16.24.145
+hm2mqtt -a auto --discover-address 172.16.24.255 -u mqtt://broker
+```
+
+`--discover-timeout` (default 5 s) is how long the scan listens. The scanning itself lives in
+[mqtt-interfaces-core](https://github.com/hobbyquaker/mqtt-interfaces-core); this adapter only
+declares the probe and the interface ports ([lib/discovery.js](lib/discovery.js)). The probe and
+the reply layout come from [hm-discover](https://github.com/hobbyquaker/hm-discover).
+
 ## Options
 
 `hm2mqtt --help` lists everything; every option is also an environment variable

package/config.js

@@ -1,10 +1,17 @@
 import {parseConfig} from 'mqtt-interfaces-core';
 import pkg from './package.json' with {type: 'json'};
 import {DEFAULT_INTERFACES, INTERFACE_NAMES} from './lib/interfaces.js';
+import {discoveryHint} from './lib/discovery.js';
 import {DEFAULT_ITEM_TEMPLATE, DEFAULT_SYSVAR_ITEM_TEMPLATE, DEFAULT_PROGRAM_ITEM_TEMPLATE} from './lib/topics.js';
 
 export const OPTIONS = {
-    'ccu-address': {alias: 'a', type: 'string', describe: 'hostname or ip of the CCU', demandOption: true},
+    'ccu-address': {
+        alias: 'a',
+        type: 'string',
+        describe: 'hostname or ip of the CCU, or "auto" to find it on the network (see --discover)',
+        demandOption: true,
+        discover: true,
+    },
     'ccu-tls': {type: 'boolean', describe: 'use the TLS ports (4xxxx) and https for ReGa', default: false},
     'ccu-insecure': {type: 'boolean', describe: "accept the CCU's self-signed certificate", default: false},
     'ccu-username': {type: 'string', describe: 'CCU user (authentication enabled on the CCU)'},
@@ -122,7 +129,9 @@ export default parseConfig({
     pkg,
     options: OPTIONS,
     defaults: {name: 'hm'},
+    discovery: discoveryHint(),
     examples: [
+        ['$0 --discover', 'find CCUs on the network and exit'],
         ['$0 -a homematic-ccu3 -u mqtt://broker', 'run in the foreground'],
         ['$0 -a 192.168.1.50 -i BidCos-RF,HmIP-RF --plain-tree state', 'two interfaces plus the plain mirror tree'],
         ['sudo $0 --install -n hm -a homematic-ccu3 -u mqtt://broker', 'install as service hm2mqtt@hm'],

package/index.js

@@ -10,7 +10,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import {fileURLToPath} from 'node:url';
-import {createAdapter} from 'mqtt-interfaces-core';
+import {createAdapter, createLogger, runDiscovery, autoAddress} from 'mqtt-interfaces-core';
 import {Rega} from 'homematic-rega';
 import config from './config.js';
 import pkg from './package.json' with {type: 'json'};
@@ -24,6 +24,30 @@ import {castValue, isWriteable} from './lib/cast.js';
 import {sanitizeName, resolveSet, resolveParamset, plainValue, compileTemplate, ItemIndex} from './lib/topics.js';
 import {compileIgnore} from './lib/roles.js';
 import {discoveryModel} from './lib/hadiscovery.js';
+import {discoveryHint} from './lib/discovery.js';
+
+/*
+ * finding the CCU (core B-2): --discover prints what answers the eQ-3 broadcast probe,
+ * --ccu-address auto uses it when exactly one CCU answers — its dns name if it has one, so a
+ * new dhcp lease does not break the config. This runs before the installer on purpose:
+ * `--install -a auto` then writes what was found, instead of leaving every service start to
+ * scan the network and fail when the CCU is briefly away. The adapter's logger does not exist
+ * yet, so discovery gets its own.
+ */
+if (config.discover || config.ccuAddress === 'auto') {
+    const discoveryLog = createLogger({envPrefix: config.$envPrefix || 'HM2MQTT', level: config.verbosity});
+    const hint = discoveryHint({tls: config.ccuTls});
+    if (config.discover) {
+        await runDiscovery({hint, config, log: discoveryLog}); // prints and exits
+    }
+    try {
+        config.ccuAddress = await autoAddress(hint, {config, log: discoveryLog});
+    } catch (err) {
+        // no CCU or several: a wrong guess would bridge the wrong house
+        discoveryLog.error('--ccu-address auto:', err.message);
+        process.exit(1);
+    }
+}
 
 handleInstall(config);
 

package/lib/compare.js

@@ -39,12 +39,14 @@ function same(a, b) {
 /**
  * @param {Map<string, string>} left item → raw payload (the reference, e.g. the flow)
  * @param {Map<string, string>} right item → raw payload (hm2mqtt)
- * @returns {{leftOnly: string[], rightOnly: string[], differences: Array<{item: string, field: string, left: *, right: *}>, same: number}}
+ * @returns {{leftOnly: string[], rightOnly: string[], differences: Array<{item: string, field: string, left: *, right: *}>,
+ *          additions: Array<{item: string, field: string, right: *}>, same: number}}
  */
 export function compareTrees(left, right) {
     const leftOnly = [];
     const rightOnly = [];
     const differences = [];
+    const additions = [];
     let sameCount = 0;
     for (const item of left.keys()) {
         if (!right.has(item)) {
@@ -73,7 +75,11 @@ export function compareTrees(left, right) {
             if (IGNORED_HM_FIELDS.has(field)) {
                 continue;
             }
-            if (!(field in hl) && ADDED_HM_FIELDS.has(field)) {
+            if (hl[field] === undefined && hr[field] !== undefined) {
+                // a field the reference never had: an addition, not a difference
+                if (!ADDED_HM_FIELDS.has(field)) {
+                    additions.push({item, field: 'hm.' + field, right: hr[field]});
+                }
                 continue;
             }
             if (!same(hl[field], hr[field])) {
@@ -87,17 +93,38 @@ export function compareTrees(left, right) {
     }
     leftOnly.sort();
     rightOnly.sort();
-    return {leftOnly, rightOnly, differences, same: sameCount};
+    return {leftOnly, rightOnly, differences, additions, same: sameCount};
+}
+
+function countBy(list, key) {
+    const counts = new Map();
+    for (const entry of list) {
+        counts.set(entry[key], (counts.get(entry[key]) || 0) + 1);
+    }
+    return [...counts].sort((a, b) => b[1] - a[1]);
 }
 
 export function formatReport(
-    {leftOnly, rightOnly, differences, same},
+    {leftOnly, rightOnly, differences, additions = [], same},
     {leftName = 'left', rightName = 'right', limit = 50} = {},
 ) {
     const lines = [];
+    const differing = new Set(differences.map((d) => d.item)).size;
     lines.push(
-        `${same} items identical, ${differences.length} differences, ${leftOnly.length} only in ${leftName}, ${rightOnly.length} only in ${rightName}`,
+        `${same} items identical, ${differing} items with ${differences.length} differences, ${additions.length} added fields, ${leftOnly.length} only in ${leftName}, ${rightOnly.length} only in ${rightName}`,
     );
+    if (differences.length > 0) {
+        lines.push('', 'differences by field:');
+        for (const [field, n] of countBy(differences, 'field')) {
+            lines.push(`  ${field}: ${n}`);
+        }
+    }
+    if (additions.length > 0) {
+        lines.push('', `fields only in ${rightName} (additions):`);
+        for (const [field, n] of countBy(additions, 'field')) {
+            lines.push(`  ${field}: ${n}`);
+        }
+    }
     const list = (title, items) => {
         if (items.length === 0) {
             return;

package/lib/discovery.js

@@ -0,0 +1,79 @@
+/**
+ * Finding CCUs on the network (core B-2): the eQ-3 UDP broadcast probe plus the interface ports,
+ * declared as a discovery hint the core scans with.
+ *
+ * The probe and the reply layout come from
+ * [hm-discover](https://github.com/hobbyquaker/hm-discover): a datagram to UDP 43439 that every
+ * eQ-3 device (CCU1/2/3, RaspberryMatic, HmIP access points) answers with its type, serial and
+ * firmware version. Which interfaces the CCU actually runs is then read off the ports that
+ * answer — the same table `--interfaces auto` probes.
+ */
+
+import {INTERFACES, INTERFACE_NAMES, interfaceConfig} from './interfaces.js';
+
+/** eQ-3 discovery port and the magic datagram: header + "eQ3-*\0*\0I". */
+export const EQ3_PORT = 43439;
+export const EQ3_HEADER = '028f91c001';
+export const EQ3_PROBE = Buffer.from([
+    0x02, 0x8f, 0x91, 0xc0, 0x01, 0x65, 0x51, 0x33, 0x2d, 0x2a, 0x00, 0x2a, 0x00, 0x49,
+]);
+
+/**
+ * Parse an eQ-3 discovery answer: the 5 byte header, then NUL terminated type and serial, three
+ * flag bytes, then the firmware version.
+ * @param {Buffer} message
+ * @returns {{type: string, serial: string, version?: string} | null} null for a foreign datagram
+ */
+export function parseEq3(message) {
+    if (!Buffer.isBuffer(message) || message.length < 8 || message.subarray(0, 5).toString('hex') !== EQ3_HEADER) {
+        return null;
+    }
+    let offset = 5;
+    const string = () => {
+        const end = message.indexOf(0, offset);
+        if (end < 0) {
+            return null;
+        }
+        const value = message.toString('latin1', offset, end);
+        offset = end + 1;
+        return value;
+    };
+    const type = string();
+    const serial = string();
+    if (type === null || serial === null) {
+        return null;
+    }
+    offset += 3; // three flag bytes between the serial and the version
+    const version = string();
+    return {type, serial, ...(version ? {version} : {})};
+}
+
+/** The ports discovery probes on a candidate: ReGa plus every interface process. */
+export function ports({tls = false} = {}) {
+    const map = {ReGa: tls ? 48181 : 8181};
+    for (const name of INTERFACE_NAMES) {
+        map[name] = interfaceConfig(name, {tls}).port;
+    }
+    return map;
+}
+
+/**
+ * The hint `--discover` and `--ccu-address auto` scan with. A CCU answers the broadcast; the
+ * ports say which interfaces it runs. `requirePort: false` keeps a CCU that answered the probe
+ * but has, say, only HmIP-RF enabled and every other port closed — the broadcast answer is proof
+ * enough, and the open ports are shown as information.
+ */
+export function discoveryHint({tls = false} = {}) {
+    return {
+        udp: {port: EQ3_PORT, payload: EQ3_PROBE, parse: parseEq3},
+        ports: ports({tls}),
+        requirePort: false,
+    };
+}
+
+/** The interfaces of a discovered CCU, in table order, from the probed ports. */
+export function interfacesOf(entry) {
+    return INTERFACE_NAMES.filter((name) => entry && entry.services && entry.services[name]);
+}
+
+export {INTERFACES};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hm2mqtt",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "Interface between Homematic CCU and MQTT",
   "type": "module",
   "main": "index.js",
@@ -69,7 +69,7 @@
     "binrpc": "^3.3.1",
     "homematic-rega": "^2.0.0",
     "homematic-xmlrpc": "^2.0.0",
-    "mqtt-interfaces-core": "^0.7.0"
+    "mqtt-interfaces-core": "^0.9.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.0.0",