hm2mqtt 2.5.0 → 3.1.0

package/lib/cast.js

@@ -0,0 +1,105 @@
+/**
+ * Casting of incoming values to what the interface process expects, driven by the paramset
+ * description of the datapoint (node-red-contrib-ccu's paramCast, with the bugs fixed).
+ */
+
+/** OPERATIONS bit 2 = write */
+export function isWriteable(description) {
+    return !description || typeof description.OPERATIONS !== 'number' || Boolean(description.OPERATIONS & 2);
+}
+
+function enumIndex(value, description) {
+    const list = description.VALUE_LIST || description.ENUM;
+    if (typeof value === 'string' && Array.isArray(list)) {
+        const index = list.indexOf(value);
+        if (index !== -1) {
+            return index;
+        }
+        const lower = list.findIndex((v) => String(v).toLowerCase() === value.toLowerCase());
+        if (lower !== -1) {
+            return lower;
+        }
+    }
+    return value;
+}
+
+/**
+ * Casts a value for setValue/putParamset. FLOATs are wrapped as {explicitDouble} so the XML-RPC
+ * serializer emits <double> even for integral numbers. MIN/MAX are not enforced
+ * (https://github.com/rdmtc/node-red-contrib-ccu/issues/74).
+ * @param {*} value parsed payload (number, boolean, string, object)
+ * @param {object} [description] paramset description of the parameter
+ * @returns {*}
+ */
+export function castValue(value, description) {
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        return value; // already typed, e.g. {explicitDouble: 1}
+    }
+    switch (description && description.TYPE) {
+        case 'ACTION':
+        case 'BOOL':
+            return toBool(value);
+        case 'FLOAT': {
+            const n = typeof value === 'boolean' ? Number(value) : Number.parseFloat(value);
+            return {explicitDouble: Number.isFinite(n) ? n : 0};
+        }
+        case 'ENUM':
+            return toInt(enumIndex(value, description));
+        case 'INTEGER':
+            return toInt(value);
+        case 'STRING':
+            return String(value);
+        default:
+            // unknown description: numbers as strings work for both double and integer datapoints
+            return typeof value === 'number' ? String(value) : value;
+    }
+}
+
+function toBool(value) {
+    if (typeof value === 'string') {
+        const s = value.trim().toLowerCase();
+        if (['false', 'off', 'no', '0', ''].includes(s)) {
+            return false;
+        }
+        if (['true', 'on', 'yes', '1'].includes(s)) {
+            return true;
+        }
+        const n = Number(s);
+        return Number.isNaN(n) ? true : n !== 0;
+    }
+    return Boolean(value);
+}
+
+function toInt(value) {
+    if (typeof value === 'boolean') {
+        return Number(value);
+    }
+    const n = Number.parseInt(value, 10);
+    return Number.isFinite(n) ? n : 0;
+}
+
+/**
+ * Casts a value for a ReGa variable (State()).
+ * @param {*} value
+ * @param {{type: 'boolean' | 'number' | 'string', enum?: string[]}} variable
+ * @returns {boolean | number | string}
+ */
+export function castVariable(value, variable) {
+    switch (variable && variable.type) {
+        case 'boolean':
+            if (typeof value === 'string' && variable.enum && variable.enum.includes(value)) {
+                return variable.enum.indexOf(value) === 1;
+            }
+            return toBool(value);
+        case 'string':
+            return String(value);
+        default:
+            if (typeof value === 'string' && variable && variable.enum && variable.enum.includes(value)) {
+                return variable.enum.indexOf(value);
+            }
+            if (typeof value === 'boolean') {
+                return Number(value);
+            }
+            return Number.parseFloat(value) || 0;
+    }
+}

package/lib/compare.js

@@ -0,0 +1,125 @@
+/**
+ * Comparison of two status trees (the Node-RED flow's `hm/...` and hm2mqtt's `hm3/...` during
+ * the parallel run before the cutover, ROADMAP §9): which items exist on one side only, and
+ * where `val` or the `hm` fields differ.
+ */
+
+/** hm fields that legitimately differ between the two implementations */
+export const IGNORED_HM_FIELDS = new Set([
+    'ts',
+    'tsPrevious',
+    'lc',
+    'lcPrevious',
+    'cache',
+    'uncertain',
+    'change',
+    'valuePrevious',
+    'valueEnumPrevious',
+]);
+
+/** hm fields hm2mqtt adds (missing on the flow side is expected) */
+export const ADDED_HM_FIELDS = new Set(['datapointUnit', 'datapointEnum', 'valueEnum']);
+
+/** items hm2mqtt publishes that the flow never had */
+export const ADDED_ITEMS = /^(interface\/|.*\/(CARRIER_SENSE_LEVEL|CONNECTED)$)/;
+
+function parse(raw) {
+    try {
+        const p = JSON.parse(raw);
+        return p && typeof p === 'object' && 'val' in p ? p : {val: p};
+    } catch {
+        return {val: raw};
+    }
+}
+
+function same(a, b) {
+    return JSON.stringify(a) === JSON.stringify(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}}
+ */
+export function compareTrees(left, right) {
+    const leftOnly = [];
+    const rightOnly = [];
+    const differences = [];
+    let sameCount = 0;
+    for (const item of left.keys()) {
+        if (!right.has(item)) {
+            leftOnly.push(item);
+        }
+    }
+    for (const item of right.keys()) {
+        if (!left.has(item) && !ADDED_ITEMS.test(item)) {
+            rightOnly.push(item);
+        }
+    }
+    for (const [item, rawLeft] of left) {
+        if (!right.has(item)) {
+            continue;
+        }
+        const l = parse(rawLeft);
+        const r = parse(right.get(item));
+        let differs = false;
+        if (!same(l.val, r.val)) {
+            differences.push({item, field: 'val', left: l.val, right: r.val});
+            differs = true;
+        }
+        const hl = l.hm || {};
+        const hr = r.hm || {};
+        for (const field of new Set([...Object.keys(hl), ...Object.keys(hr)])) {
+            if (IGNORED_HM_FIELDS.has(field)) {
+                continue;
+            }
+            if (!(field in hl) && ADDED_HM_FIELDS.has(field)) {
+                continue;
+            }
+            if (!same(hl[field], hr[field])) {
+                differences.push({item, field: 'hm.' + field, left: hl[field], right: hr[field]});
+                differs = true;
+            }
+        }
+        if (!differs) {
+            sameCount += 1;
+        }
+    }
+    leftOnly.sort();
+    rightOnly.sort();
+    return {leftOnly, rightOnly, differences, same: sameCount};
+}
+
+export function formatReport(
+    {leftOnly, rightOnly, differences, same},
+    {leftName = 'left', rightName = 'right', limit = 50} = {},
+) {
+    const lines = [];
+    lines.push(
+        `${same} items identical, ${differences.length} differences, ${leftOnly.length} only in ${leftName}, ${rightOnly.length} only in ${rightName}`,
+    );
+    const list = (title, items) => {
+        if (items.length === 0) {
+            return;
+        }
+        lines.push('', `${title} (${items.length}):`);
+        for (const i of items.slice(0, limit)) {
+            lines.push('  ' + i);
+        }
+        if (items.length > limit) {
+            lines.push(`  … ${items.length - limit} more`);
+        }
+    };
+    list(`only in ${leftName}`, leftOnly);
+    list(`only in ${rightName}`, rightOnly);
+    if (differences.length > 0) {
+        lines.push('', `differences (${differences.length}):`);
+        for (const d of differences.slice(0, limit)) {
+            lines.push(`  ${d.item} ${d.field}: ${JSON.stringify(d.left)} → ${JSON.stringify(d.right)}`);
+        }
+        if (differences.length > limit) {
+            lines.push(`  … ${differences.length - limit} more`);
+        }
+    }
+    return lines.join('\n');
+}

package/lib/install.js

@@ -0,0 +1,17 @@
+/**
+ * --install / --uninstall: systemd template service hm2mqtt@<name> (mqtt-interfaces-core installer).
+ */
+
+import {createInstaller} from 'mqtt-interfaces-core';
+
+export const SERVICE = 'hm2mqtt';
+export const ENV_PREFIX = 'HM2MQTT';
+
+const installer = createInstaller({
+    service: SERVICE,
+    envPrefix: ENV_PREFIX,
+    description: `${SERVICE} %i - Homematic CCU to MQTT bridge`,
+    documentation: 'https://github.com/hobbyquaker/hm2mqtt.js',
+});
+
+export const {unitFile, envFile, installService, uninstallService, handle} = installer;

package/lib/interfaces.js

@@ -0,0 +1,110 @@
+/**
+ * The CCU interface processes: names as the CCU uses them, ports (plain / TLS), protocol,
+ * whether they want an init() subscription and answer pings.
+ */
+
+import net from 'node:net';
+
+export const INTERFACES = {
+    'BidCos-RF': {
+        port: 2001,
+        tlsPort: 42001,
+        protocol: 'xmlrpc',
+        binrpc: true,
+        init: true,
+        ping: true,
+        dutyCycle: true,
+    },
+    'BidCos-Wired': {port: 2000, tlsPort: 42000, protocol: 'xmlrpc', binrpc: true, init: true, ping: true},
+    // https://github.com/eq-3/occu/issues/42 — HmIP-RF answers pings but events are rare, node-red used 600 s
+    'HmIP-RF': {
+        port: 2010,
+        tlsPort: 42010,
+        protocol: 'xmlrpc',
+        init: true,
+        ping: true,
+        pingTimeout: 600,
+        dutyCycle: true,
+    },
+    VirtualDevices: {port: 9292, tlsPort: 49292, path: '/groups', protocol: 'xmlrpc', init: true, ping: false},
+    CUxD: {port: 8701, protocol: 'binrpc', init: true, ping: true},
+};
+
+export const INTERFACE_NAMES = Object.keys(INTERFACES);
+export const DEFAULT_INTERFACES = ['BidCos-RF', 'HmIP-RF', 'VirtualDevices', 'BidCos-Wired'];
+
+/**
+ * Parses the --interfaces option. Returns the list of names, or null for "auto".
+ * @param {string} value
+ * @returns {string[] | null}
+ */
+export function parseInterfaces(value) {
+    const raw = String(value || '').trim();
+    if (raw === '' || raw.toLowerCase() === 'auto') {
+        return null;
+    }
+    const names = raw.split(/[\s,]+/).filter(Boolean);
+    const lower = new Map(INTERFACE_NAMES.map((n) => [n.toLowerCase(), n]));
+    return names.map((n) => {
+        const name = lower.get(n.toLowerCase());
+        if (!name) {
+            throw new Error(`unknown interface "${n}" (known: ${INTERFACE_NAMES.join(', ')})`);
+        }
+        return name;
+    });
+}
+
+/**
+ * Connection parameters of an interface for the given CCU options.
+ * @param {string} name
+ * @param {{tls?: boolean, bidcosBinrpc?: boolean}} [options]
+ * @returns {{name: string, protocol: 'xmlrpc' | 'binrpc', port: number, path?: string, init: boolean,
+ *          ping: boolean, pingTimeout?: number, dutyCycle: boolean}}
+ */
+export function interfaceConfig(name, {tls = false, bidcosBinrpc = false} = {}) {
+    const def = INTERFACES[name];
+    if (!def) {
+        throw new Error('unknown interface ' + name);
+    }
+    const binrpc = def.protocol === 'binrpc' || (def.binrpc && bidcosBinrpc && !tls);
+    return {
+        name,
+        protocol: binrpc ? 'binrpc' : 'xmlrpc',
+        port: tls && def.tlsPort ? def.tlsPort : def.port,
+        path: def.path,
+        init: def.init,
+        ping: def.ping,
+        pingTimeout: def.pingTimeout,
+        dutyCycle: Boolean(def.dutyCycle),
+    };
+}
+
+function portOpen(host, port, timeout) {
+    return new Promise((resolve) => {
+        const socket = net.connect({host, port});
+        const done = (result) => {
+            socket.destroy();
+            resolve(result);
+        };
+        socket.setTimeout(timeout, () => done(false));
+        socket.once('connect', () => done(true));
+        socket.once('error', () => done(false));
+    });
+}
+
+/**
+ * Probes which interface ports answer on the CCU (--interfaces auto).
+ * @param {string} host
+ * @param {{tls?: boolean, timeout?: number, connect?: Function}} [options]
+ * @returns {Promise<string[]>} interface names in table order
+ */
+export async function probeInterfaces(host, {tls = false, timeout = 2000, connect = portOpen} = {}) {
+    const found = [];
+    for (const name of INTERFACE_NAMES) {
+        const {port} = interfaceConfig(name, {tls});
+        if (await connect(host, port, timeout)) {
+            found.push(name);
+        }
+    }
+    return found;
+}