hm2mqtt 3.2.1 → 3.3.0

package/README.md

@@ -46,6 +46,40 @@ docker run -d --name hm2mqtt --restart unless-stopped --network host -v hm2mqtt:
 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/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.1",
+  "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",