hm2mqtt 2.5.0 → 3.1.0

package/lib/values.js

@@ -0,0 +1,283 @@
+/**
+ * Datapoint values: builds the message of an event exactly like node-red-contrib-ccu's
+ * createMessage() (the `hm` block of the payload), keeps the last message per datapoint
+ * (persisted as values.json) and applies the actuator "wait for WORKING" rule.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const WORKING_WAIT_MS = 300;
+
+/** channel types whose STATE / ARMSTATE / LEVEL* come together with WORKING/DIRECTION */
+export function waitsForWorking(datapoint, channelType) {
+    if (!channelType) {
+        return false;
+    }
+    if (datapoint === 'STATE') {
+        return /SIGNAL|SWITCH|RAINDETECTOR_HEAT|ALARMACTUATOR/.test(channelType);
+    }
+    if (datapoint === 'ARMSTATE') {
+        return channelType === 'ARMING';
+    }
+    if (datapoint.startsWith('LEVEL')) {
+        return /DIMMER|DUAL_WHITE|BLIND|SHUTTER|JALOUSIE|WINMATIC|KEYMATIC/.test(channelType);
+    }
+    return false;
+}
+
+/** the interface processes deliver "°C" as a lone latin1 byte which arrives as U+FFFD */
+export function unit(description) {
+    const u = description && description.UNIT;
+    if (!u || u === '""') {
+        return undefined;
+    }
+    return String(u).replace(/�/g, '°');
+}
+
+/** true for datapoints that are events, not state: PRESS_* and every ACTION */
+export function isEvent(datapoint, description) {
+    return datapoint.startsWith('PRESS_') || Boolean(description && description.TYPE === 'ACTION');
+}
+
+/** The `hm` block of a payload: the message without topic/payload/value. */
+export function hmBlock(message) {
+    const hm = {...message};
+    delete hm.topic;
+    delete hm.payload;
+    delete hm.value;
+    return hm;
+}
+
+export class ValueStore {
+    /**
+     * @param {object} o
+     * @param {string} o.host CCU address (`ccu` field)
+     * @param {object} o.context lookups: device(iface, address), valueDescription(iface, address, datapoint),
+     *        channelName(address), rooms(address), functions(address)
+     * @param {string} [o.stateDir]
+     * @param {object} o.log
+     * @param {object} [o.timers] {setTimeout, clearTimeout, now}
+     */
+    constructor({host, context, stateDir, log, timers}) {
+        this.host = host;
+        this.context = context;
+        this.stateDir = stateDir;
+        this.log = log;
+        this.timers = {setTimeout, clearTimeout, now: Date.now, ...(timers || {})};
+        this.values = new Map();
+        this.workingTimers = new Map();
+    }
+
+    file() {
+        return this.stateDir ? path.join(this.stateDir, 'values.json') : null;
+    }
+
+    load() {
+        const file = this.file();
+        if (!file) {
+            return;
+        }
+        try {
+            const {values} = JSON.parse(fs.readFileSync(file, 'utf8'));
+            for (const [name, message] of Object.entries(values || {})) {
+                this.values.set(name, {...message, cache: true, change: false, uncertain: true});
+            }
+            this.log.info('loaded', this.values.size, 'values from', file);
+        } catch (err) {
+            if (err.code !== 'ENOENT') {
+                this.log.warn('cannot read', file, '-', err.message);
+            }
+        }
+    }
+
+    save() {
+        const file = this.file();
+        if (!file) {
+            return;
+        }
+        try {
+            fs.mkdirSync(this.stateDir, {recursive: true});
+            fs.writeFileSync(file, JSON.stringify({values: Object.fromEntries(this.values)}));
+            this.log.debug('saved', this.values.size, 'values to', file);
+        } catch (err) {
+            this.log.warn('cannot save', file, '-', err.message);
+        }
+    }
+
+    get(iface, channel, datapoint) {
+        return this.values.get(`${iface}.${channel}.${datapoint}`);
+    }
+
+    /**
+     * node-red-contrib-ccu createMessage(): the full message of a datapoint value.
+     * @param {string} iface
+     * @param {string} channel
+     * @param {string} datapoint
+     * @param {*} value
+     * @param {object} [additions] cache, uncertain, working, direction, ts, lc, change overrides
+     */
+    /**
+     * The static (value-independent) fields of a datapoint: device, channel, datapoint and
+     * description facts, rooms and functions — what item templates can use.
+     */
+    fields(iface, channel, datapoint) {
+        const {context} = this;
+        const channelDevice = context.device(iface, channel);
+        const deviceAddress = channelDevice && channelDevice.PARENT;
+        const device = deviceAddress ? context.device(iface, deviceAddress) : undefined;
+        const description = context.valueDescription(iface, channel, datapoint) || {};
+        const rooms = context.rooms(channel) || [];
+        const functions = context.functions(channel) || [];
+        const list = description.VALUE_LIST || description.ENUM;
+        return {
+            ccu: this.host,
+            iface,
+            device: deviceAddress,
+            deviceName: deviceAddress ? context.channelName(deviceAddress) : undefined,
+            deviceType: device && device.TYPE,
+            channel,
+            channelName: context.channelName(channel),
+            channelType: channelDevice && channelDevice.TYPE,
+            channelIndex: channel.includes(':') ? Number.parseInt(channel.split(':')[1], 10) : undefined,
+            datapoint,
+            datapointName: `${iface}.${channel}.${datapoint}`,
+            datapointType: description.TYPE,
+            datapointMin: description.MIN,
+            datapointMax: description.MAX,
+            datapointEnum: list,
+            datapointDefault: description.DEFAULT,
+            datapointControl: description.CONTROL,
+            datapointUnit: unit(description),
+            rooms,
+            room: rooms.length > 0 ? rooms[0] : undefined,
+            functions,
+            function: functions.length > 0 ? functions[0] : undefined,
+        };
+    }
+
+    message(iface, channel, datapoint, value, additions = {}) {
+        const {context} = this;
+        const fields = this.fields(iface, channel, datapoint);
+        const {datapointName} = fields;
+        const previous = this.values.get(datapointName) || {};
+        const description = context.valueDescription(iface, channel, datapoint) || {};
+        const ts = this.timers.now();
+        const valueStable = additions.working ? previous.valueStable : value;
+        const change =
+            description.TYPE === 'ACTION' ||
+            Boolean(previous.cache) ||
+            previous.payload !== value ||
+            previous.valueStable !== valueStable;
+        const list = fields.datapointEnum;
+
+        const message = {
+            topic: '',
+            payload: value,
+            ...fields,
+            value,
+            valuePrevious: previous.value,
+            valueEnum: Array.isArray(list) ? list[Number(value)] : undefined,
+            valueStable,
+            ts,
+            tsPrevious: previous.ts,
+            lc: change ? ts : previous.lc,
+            change,
+            ...additions,
+        };
+        message.stable = !message.working;
+        return message;
+    }
+
+    /**
+     * Applies an event from an interface process. `emit(message)` is called once the value is
+     * final — immediately, or 300 ms later for actuator datapoints whose WORKING/DIRECTION may
+     * follow in a separate call (node-red-contrib-ccu's publishEvent).
+     * @param {{iface: string, channel: string, datapoint: string, value: *, working?: boolean, direction?: number}} event
+     * @param {(message: object) => void} emit
+     */
+    event({iface, channel, datapoint, value, working, direction}, emit) {
+        const message = this.message(iface, channel, datapoint, value, {
+            cache: false,
+            uncertain: false,
+            working,
+            direction,
+        });
+        if (working || !waitsForWorking(datapoint, message.channelType)) {
+            this.values.set(message.datapointName, message);
+            emit(message);
+            return;
+        }
+        const key = message.datapointName;
+        this.timers.clearTimeout(this.workingTimers.get(key));
+        this.workingTimers.set(
+            key,
+            this.timers.setTimeout(() => {
+                this.workingTimers.delete(key);
+                const v = (dp) => this.get(iface, channel, dp);
+                const w = v('WORKING') || v('WORKING_SLATS');
+                if (w) {
+                    message.working = Boolean(
+                        (v('WORKING') && v('WORKING').value) || (v('WORKING_SLATS') && v('WORKING_SLATS').value),
+                    );
+                } else if (v('PROCESS')) {
+                    message.working = Boolean(v('PROCESS').value);
+                }
+                if (v('DIRECTION')) {
+                    message.direction = v('DIRECTION').value;
+                } else if (v('ACTIVITY_STATE')) {
+                    const a = v('ACTIVITY_STATE').value;
+                    message.direction = a === 0 ? 3 : a === 3 ? 0 : a;
+                }
+                message.stable = !message.working;
+                this.values.set(key, message);
+                emit(message);
+            }, WORKING_WAIT_MS),
+        );
+    }
+
+    /**
+     * A value from the ReGa cache (getValues) — not an event: cache/uncertain flags, CCU timestamp.
+     * @param {{name: string, value: *, ts: number}} dp name = <iface>.<channel>.<datapoint>
+     * @returns {object | null} the message, null when the name does not parse
+     */
+    cached({name, value, ts}) {
+        const [iface, channel, datapoint] = String(name).split('.');
+        if (!iface || !channel || !datapoint) {
+            return null;
+        }
+        if ((datapoint === 'RSSI_DEVICE' || datapoint === 'RSSI_PEER') && typeof value === 'number' && value > 127) {
+            value -= 256; // the ReGa reports the unsigned byte
+        }
+        const now = this.timers.now();
+        const message = this.message(iface, channel, datapoint, value, {
+            cache: true,
+            change: false,
+            working: false,
+            uncertain: !ts,
+            ts: ts || now,
+            lc: ts || now,
+        });
+        this.values.set(message.datapointName, message);
+        return message;
+    }
+
+    /** The LEVEL_NOTWORKING / STATE_NOTWORKING companion of a message, or null. */
+    notWorking(message) {
+        if (message.working !== false || !['LEVEL', 'STATE'].includes(message.datapoint)) {
+            return null;
+        }
+        return {
+            ...message,
+            datapoint: message.datapoint + '_NOTWORKING',
+            datapointName: message.datapointName + '_NOTWORKING',
+        };
+    }
+
+    stop() {
+        for (const timer of this.workingTimers.values()) {
+            this.timers.clearTimeout(timer);
+        }
+        this.workingTimers.clear();
+    }
+}

package/names.schema.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "hm2mqtt device and channel names",
+  "description": "Maps device and channel addresses (e.g. OEQ1234567:1) to the names used in topics; overrides the ReGa names.",
+  "type": "object",
+  "additionalProperties": {"type": "string", "minLength": 1},
+  "propertyNames": {"pattern": "^[A-Za-z0-9-]+(:[0-9]+)?$"}
+}

package/package.json

@@ -1,27 +1,50 @@
 {
   "name": "hm2mqtt",
-  "version": "2.5.0",
-  "description": "Interface between Homematic and MQTT",
+  "version": "3.1.0",
+  "description": "Interface between Homematic CCU and MQTT",
+  "type": "module",
   "main": "index.js",
+  "preferGlobal": true,
   "bin": {
-    "hm2mqtt": "./index.js"
+    "hm2mqtt": "index.js"
+  },
+  "files": [
+    "index.js",
+    "config.js",
+    "lib/",
+    "paramsets.json",
+    "example-names.json",
+    "names.schema.json",
+    "scripts/"
+  ],
+  "engines": {
+    "node": "^20.19 || ^22.12 || >=24"
   },
-  "preferGlobal": true,
   "scripts": {
-    "test": "camo-purge ; xo && nyc mocha --exit test.js && nyc report --reporter=text-lcov | coveralls --force",
-    "testonly": "mocha --exit test.js",
-    "lint": "xo",
-    "lintfix": "xo --fix"
+    "start": "node index.js",
+    "lint": "eslint . && prettier --check .",
+    "format": "prettier --write . && eslint --fix .",
+    "test": "node --test",
+    "test:watch": "node --test --watch",
+    "deploy": "bash deploy.sh",
+    "test:e2e": "HM2MQTT_E2E=1 node --test --test-force-exit test/e2e.test.js"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/hobbyquaker/hm2mqtt.js"
+    "url": "git+https://github.com/hobbyquaker/hm2mqtt.js.git"
   },
   "keywords": [
     "mqtt",
     "smarthome",
+    "mqtt-smarthome",
+    "mqtt-interfaces",
+    "home-automation",
+    "home-assistant",
     "homematic",
+    "homematic-ip",
+    "ccu",
     "bidcos",
+    "hmip",
     "eq-3"
   ],
   "author": "Sebastian Raff <hobbyquaker@gmail.com> (https://hobbyquaker.github.io)",
@@ -34,36 +57,31 @@
     "url": "https://github.com/hobbyquaker/hm2mqtt.js/issues"
   },
   "homepage": "https://github.com/hobbyquaker/hm2mqtt.js",
+  "mqttInterfaces": {
+    "spec": "2.0",
+    "envPrefix": "HM2MQTT",
+    "needs": [
+      "network"
+    ],
+    "serviceExtra": []
+  },
   "dependencies": {
-    "async": "^2.6.0",
-    "binrpc": "^3.1.2",
-    "homematic-xmlrpc": "^1.0.2",
-    "mqtt": "^2.16.0",
-    "persist-json": "^1.2.0",
-    "request": "^2.83.0",
-    "yalm": "^4.1.0",
-    "yargs": "^11.0.0"
+    "binrpc": "^3.3.1",
+    "homematic-rega": "^2.0.0",
+    "homematic-xmlrpc": "^2.0.0",
+    "mqtt-interfaces-core": "^0.7.0"
   },
   "devDependencies": {
-    "camo-purge": "latest",
-    "coveralls": "latest",
-    "hm-simulator": "latest",
-    "mocha": "latest",
-    "nyc": "latest",
-    "stream-splitter": "latest",
-    "xo": "latest",
-    "should": "latest"
-  },
-  "engines": {
-    "node": ">=6.0.0"
-  },
-  "yargs": {
-    "boolean-negation": false
+    "@eslint/js": "^9.0.0",
+    "eslint": "^9.0.0",
+    "eslint-config-prettier": "^10.0.0",
+    "globals": "^16.0.0",
+    "hm-simulator": "^0.1.1",
+    "prettier": "^3.0.0"
   },
-  "xo": {
-    "space": 4,
-    "ignore": [
-      "test.js"
-    ]
+  "overrides": {
+    "hm-simulator": {
+      "homematic-xmlrpc": "^2.0.0"
+    }
   }
 }