homebridge-smartsystem 7.1.19 → 7.1.20

package/.claude/scheduled_tasks.lock

@@ -0,0 +1 @@
+{"sessionId":"29e28b48-3a89-4159-baf0-58e668c1fe0d","pid":61331,"procStart":"Wed Sep 16 12:58:32 2026","acquiredAt":1789563711220}

package/CLAUDE.md

@@ -0,0 +1,118 @@
+# CLAUDE.md — handover notes for AI coding agents
+
+Project: **homebridge-smartsystem** ("SmartSocket"), a Homebridge plugin + standalone
+server that bridges **Duotecno** home-automation gateways (and a few other power/energy
+sources) to HomeKit, a web UI, and a WebSocket/HTTP API. Author: Johan Coppieters.
+
+## What this thing actually is
+
+- It's a Homebridge **platform plugin** (`homebridge-smartsystem` in [package.json](package.json)),
+  registered from [index.ts](index.ts) via `api.registerPlatform(...)`.
+- It also runs stand-alone as an Express-like web/proxy server (no Homebridge) — see
+  `server/webapp.ts`, `server/smartapp.ts`, `server/socapp.ts`.
+- Talks to one or more **Duotecno masters** (physical IP-connected controllers) over raw
+  TCP using a custom binary protocol, and exposes their nodes/units (switches, dimmers,
+  moods, up/downs, temperature sensors, locks, garage doors, window coverings...) as:
+  - HomeKit accessories (via Homebridge)
+  - a web UI (EJS views in `server/views/`, static assets in `www/`)
+  - a WebSocket device-control API (see [WEBSOCKET-API.md](WEBSOCKET-API.md))
+  - proxied raw TCP-over-WebSocket (`server/proxy.ts`)
+- Also integrates power/energy sources: Smappee (MQTT), a P1 smart meter, Shelly, and
+  can drive Somfy screens over GPIO on a Raspberry Pi.
+
+## Source layout
+
+- [index.ts](index.ts) — Homebridge plugin entry point.
+- `duotecno/` — protocol layer, independent of Homebridge/HTTP:
+  - [protocol.ts](duotecno/protocol.ts) — binary frame encode/decode, `Unit` types.
+  - [master.ts](duotecno/master.ts) (885 lines) — one TCP connection to a Duotecno master; heartbeat, reconnect logic.
+  - [system.ts](duotecno/system.ts) — collection of masters/nodes/units, the in-memory model.
+  - [smartsocket.ts](duotecno/smartsocket.ts), [Q.ts](duotecno/Q.ts) — low-level socket/queue helpers.
+  - [config.ts](duotecno/config.ts), [types.ts](duotecno/types.ts), [logger.ts](duotecno/logger.ts), [colors.ts](duotecno/colors.ts).
+- `server/` — everything HTTP/WebSocket/Homebridge-facing:
+  - [platform.ts](server/platform.ts) — Homebridge `Platform` class; wires `System` + `SmartApp` + `SocApp` to Homebridge accessories.
+  - [smartapp.ts](server/smartapp.ts) (1691 lines, **the biggest file**) — web app: routes, device WebSocket API, power/energy bindings, links, switches. See [MIXINS-GUIDE.md](MIXINS-GUIDE.md) for a *proposed but not-yet-applied* refactor plan to split this file.
+  - [webapp.ts](server/webapp.ts) — generic HTTP server base (Express-like) that `smartapp`/`socapp` extend.
+  - [socapp.ts](server/socapp.ts) — raw-socket flavored app variant.
+  - [proxy.ts](server/proxy.ts) — WebSocket⇄TCP proxy.
+  - [base.ts](server/base.ts) — tiny shared base class.
+  - [smappee.ts](server/smappee.ts), [p1.ts](server/p1.ts), [shelly.ts](server/shelly.ts) — power measurement sources.
+  - [somfy.ts](server/somfy.ts) — GPIO control for Somfy screens (Raspberry Pi only).
+  - [HA-API.ts](server/HA-API.ts) — Home Assistant / openHAB style API stubs.
+  - [HB.ts](server/HB.ts) — Homebridge-specific glue.
+  - [mDNS.ts](server/mDNS.ts) — Bonjour service advertisement (`*.local` names).
+  - [support.ts](server/support.ts) — misc helpers.
+  - `views/` — EJS templates for the built-in web UI.
+- `accessories/` — one file per HomeKit accessory type (bulb, dimmer, switch, lock, door,
+  garagedoor, mood, temperature, windowcovering) — each maps a Duotecno unit type/name
+  convention to a HomeKit service. The naming-convention rules (`$`, `*`, `!` markers in
+  Duotecno unit names) are documented at the bottom of [README.md](README.md) (v5.4.0 entry) — this is important domain logic, not incidental.
+- `www/` — built/bundled front-end assets (webpack output, not source you'd hand-edit).
+- `data/` — sample/backup JSON dumps of real systems (groups/scenes/system), used for
+  local testing, not app config.
+- Root `test*.ts` (`testHB.ts`, `testWS.ts`, `testProxy.ts`) — standalone manual test
+  scripts/harnesses, not a unit test suite. See [TESTING-GUIDE.md](TESTING-GUIDE.md).
+- `config*.json` at repo root — real/sample runtime configs for different installs
+  (`config.gm.json`, `config.peter.json`, ...). `config.json` is the active one used when
+  running locally via the `start` npm script.
+
+## Build & run
+
+- **Language**: TypeScript, compiled to plain `.js` sitting next to each `.ts` file
+  (`"outDir"` = same folder, per [tsconfig.json](tsconfig.json)). Every `.ts` file has a
+  matching committed `.js` + `.js.map` — **the compiled JS is checked into git** and is
+  what Homebridge actually loads (`main: index.js`). Always rebuild after editing `.ts`.
+- Build once: `npm run build` (`tsc --build`).
+- Watch mode: `npm run watch` (also runs automatically on folder open, task `npm: 1`).
+- Run under Homebridge locally: `npm start` (`homebridge -D -P <this dir>`), reads
+  `config.json` for platform config.
+- No automated test framework/CI configured — testing is manual via `testHB.ts` /
+  `testWS.ts` / `testProxy.ts` and the guides in [TESTING-GUIDE.md](TESTING-GUIDE.md).
+- Releases: `npm run release:patch|minor|major` — bumps version, commits, tags, publishes
+  to npm, and **pushes to origin**. Never run these without the user's explicit go-ahead.
+
+## Conventions / gotchas worth knowing before editing
+
+- Compiled `.js` files are committed — after any `.ts` change, rebuild (or rely on the
+  watch task) before assuming the runtime behavior changed, and commit the regenerated
+  `.js`/`.js.map` alongside the `.ts` change.
+- Duotecno unit *display names* encode behavior via trailing marker characters
+  (`$`, `*`, `!`, `#`), e.g. an "updown" unit named with `$` becomes a HomeKit
+  `GarageDoor`, with `*` becomes a `Door`, otherwise a `WindowCovering` — same pattern for
+  moods (`mood`/`unlocker`) and switches (`lock`/`switch`/`lightbulb`). This logic lives
+  across `accessories/*.ts` and `duotecno/types.ts` — check [README.md](README.md)'s
+  v5.4.0 section for the authoritative rule table before changing accessory-type mapping.
+- `server/smartapp.ts` is large and mixes several concerns (device WS API, links, HTTP
+  switches, power bindings, proxy config). [MIXINS-GUIDE.md](MIXINS-GUIDE.md) captures a
+  discussed refactor (module/delegate pattern) that was **never carried out** — don't
+  assume that structure exists; it's a plan, not current code.
+- Multiple root `config*.json` files exist for different physical installs/customers
+  (gm, peter, homebridge). Don't assume `config.json` is representative of all of them;
+  check which one is relevant when debugging a specific report.
+- Hex formatting convention for Duotecno addresses: always display Node/Unit addresses
+  as hex with `0x` prefix (e.g. `0x04`, `0xFC`) in any UI/log output you add.
+- `raspberry-pi-setup.sh`, `update.sh`, `updserv.sh` are deployment scripts for the actual
+  Raspberry Pi gateway hardware in the field — treat changes to these as
+  infrastructure-affecting, confirm with the user before running them.
+- Somfy/GPIO code (`server/somfy.ts`) only makes sense on real Raspberry Pi hardware.
+
+## Where to look for more detail
+
+- [README.md](README.md) — full version history/changelog; the most reliable source of
+  "why does this weird naming rule exist" answers.
+- [WEBSOCKET-API.md](WEBSOCKET-API.md) — device WebSocket protocol (client/server message
+  formats, device ID = `node*256 + unit`).
+- [MIXINS-GUIDE.md](MIXINS-GUIDE.md) — proposed (unapplied) refactor of `smartapp.ts`.
+- [TESTING-GUIDE.md](TESTING-GUIDE.md) — manual testing steps using `testHB.ts`/`testWS.ts`.
+- [SETTINGS-UPDATE.md](SETTINGS-UPDATE.md) — notes on the web UI Settings page state
+  (some features intentionally disabled/commented out pending real implementation).
+
+## Working style expected on this repo
+
+- Prefer lean, minimal diffs; avoid speculative refactors or defensive code not clearly
+  needed (see the large-file/mixins situation above — it's known and intentionally
+  deferred, don't "fix" it unprompted).
+- Commit locally often once a coherent, verified chunk of work is done (this user has
+  lost uncommitted work before). Never push or run `release:*` scripts without explicit
+  confirmation.
+- Split unrelated changes into separate commits with descriptive messages.

package/accessories/temperature.js

@@ -23,7 +23,8 @@ class Temperature extends accessory_1.Accessory {
     getTemperature(next) {
         if (this.unit) {
             (0, logger_1.log)("accessory", "getTemperature was called for " + this.unit.node.getName() + " - " + this.unit.getName() + " -> " + this.unit.value);
-            next(null, this.unit.value / 10.0);
+            const limited = Math.max(-100, Math.min(100, this.unit.value / 10.0));
+            next(null, limited);
         }
         else {
             next(new Error("accessory -> getTemperature needs a unit."));

package/duotecno/logger.js

@@ -20,6 +20,7 @@ exports.logSettings = {
     "webapp": LogLevel.log,
     "p1": LogLevel.log,
     "shelly": LogLevel.log,
+    "overkiz": LogLevel.log,
     "power": LogLevel.log,
     "smartapp": LogLevel.log
 };

package/duotecno/protocol.js

@@ -754,13 +754,13 @@ exports.Protocol = {
         let kind = "-";
         if (next.cmd === Rec.Sensor) {
             // sensor -> value
-            unit.value = this.makeWord(next.message, 9); // 10x current temperature
+            unit.value = this.makeSignedWord(next.message, 9); // 10x current temperature
             unit.status = next.message[7]; // 0=idle, 1=heating, 2=cooling
             unit.preset = (next.message[6]) ? next.message[8] : -1; // 0=sun, 1=half sun, 2=moon, 3=half moon, -1 = off
-            unit.sun = this.makeWord(next.message, 11); // 10x temperature
-            unit.hsun = this.makeWord(next.message, 13); // 10x temperature
-            unit.moon = this.makeWord(next.message, 15); // 10x temperature
-            unit.hmoon = this.makeWord(next.message, 17); // 10x temperature
+            unit.sun = this.makeSignedWord(next.message, 11); // 10x temperature
+            unit.hsun = this.makeSignedWord(next.message, 13); // 10x temperature
+            unit.moon = this.makeSignedWord(next.message, 15); // 10x temperature
+            unit.hmoon = this.makeSignedWord(next.message, 17); // 10x temperature
             (0, logger_1.debug)("protocol", "received status - " + unit.getDisplayName() + ", temperature = " + unit.value / 10.0 + ", sun = " + unit.sun);
             kind = "S";
             // Dimmers, switches and moods have 
@@ -815,7 +815,7 @@ exports.Protocol = {
             // only change dim value when state = 1 (ON, PIR ON, DIM STOP) for Dimmers and IRTX + for any setpoint event
             if ((((next.message[4] === 1) || (next.message[4] === 6) || (next.message[4] === 7)) && (next.message[5] === 1)) ||
                 (next.message[4] === 11)) {
-                unit.value = this.makeWord(next.message, 6);
+                unit.value = this.makeSignedWord(next.message, 6);
             }
             else if (next.message[4] === 32) {
                 // unit_type_duoswitch -> Event = 32 

package/duotecno/types.js

@@ -214,6 +214,7 @@ exports.Sanitizers = {
         config.smappee = config.smappee || false;
         config.p1 = config.p1 || false;
         config.shelly = config.shelly || false;
+        config.overkiz = config.overkiz || false;
         config.smartapp = config.smartapp || null;
         config.system = exports.Sanitizers.system(config.system);
         config.proxy = exports.Sanitizers.proxy(config.proxy, config.system);
@@ -308,6 +309,17 @@ exports.Sanitizers = {
         cfg.addresses = (config === null || config === void 0 ? void 0 : config.addresses) || "";
         return cfg;
     },
+    overkiz: function (config) {
+        if (!config)
+            config = {};
+        config.debug = config.debug || false;
+        config.service = config.service || "local";
+        config.user = config.user || "";
+        config.password = config.password || "";
+        config.pollingPeriod = config.pollingPeriod || 10;
+        config.refreshPeriod = config.refreshPeriod || 60;
+        return config;
+    },
     linkConfig: function (aLink) {
         const link = exports.Sanitizers.unitDef(aLink);
         link.accId = aLink.accId || "";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "homebridge-smartsystem",
   "displayname": "Duotecno Bridge",
-  "version": "7.1.19",
+  "version": "7.1.20",
   "description": "SmartServer (Proxy TCP sockets to the cloud, Smappee MQTT, Duotecno IP Nodes, Homekit interface)",
   "main": "index.js",
   "author": "Johan Coppieters",
@@ -44,6 +44,7 @@
     "mqtt": "^4.3.7",
     "multicast-dns": "^7.2.5",
     "node-fetch": "^3.2.4",
+    "overkiz-client": "^1.0.23",
     "rpi-gpio": "^2.1.7",
     "ws": "^7.4.6"
   },

package/server/overkiz.js

@@ -0,0 +1,143 @@
+"use strict";
+// Direct Somfy/TaHoma (Overkiz) integration.
+//
+// Talks straight to the Overkiz gateway (local TaHoma Developer Mode API, or
+// cloud API as a fallback) using the same client library ("overkiz-client")
+// that dubocr/homebridge-tahoma itself depends on. This replaces the old
+// detour of running homebridge-tahoma as a second Homebridge platform and
+// then polling its HomeKit accessories back into Duotecno via server/HB.ts
+// and the Link mechanism in smartapp.ts.
+//
+// Phase 1 (this file): connect, discover devices, send open/close/stop
+// commands, and emit translated Duotecno-style states when Overkiz reports
+// a change. Wiring this into the Link UI (so a Duotecno unit can be coupled
+// to a specific Somfy screen) is a follow-up step once connectivity against
+// real hardware is confirmed.
+//
+// Johan Coppieters, 2026.
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Overkiz = void 0;
+const events_1 = require("events");
+const overkiz_client_1 = require("overkiz-client");
+const types_1 = require("../duotecno/types");
+const logger_1 = require("../duotecno/logger");
+const base_1 = require("./base");
+// core:ClosureState / core:ClosureOrRollerShutterPositionState: 0 = fully
+// open, 100 = fully closed (opposite of HomeKit's TargetPosition scale).
+const kOpenThreshold = 5;
+const kClosedThreshold = 95;
+function closureToUnitState(closure, previousClosure) {
+    if (closure <= kOpenThreshold)
+        return types_1.UnitState.kOpen;
+    if (closure >= kClosedThreshold)
+        return types_1.UnitState.kClosed;
+    if (typeof previousClosure === "number") {
+        if (closure < previousClosure)
+            return types_1.UnitState.kOpening;
+        if (closure > previousClosure)
+            return types_1.UnitState.kClosing;
+    }
+    return types_1.UnitState.kStopped;
+}
+class Overkiz extends base_1.Base {
+    constructor(system) {
+        super("overkiz");
+        this.emitter = new events_1.EventEmitter();
+        this.devices = new Map();
+        this.closures = new Map();
+        this.system = system;
+        if (this.config.user && this.config.password) {
+            this.connect().catch(e => (0, logger_1.err)("overkiz", "connect failed: " + (e.message || e)));
+        }
+        else {
+            (0, logger_1.log)("overkiz", "Overkiz not configured (missing user/password) -> not starting.");
+        }
+    }
+    connect() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const bridge = {
+                warn: (...args) => (0, logger_1.log)("overkiz", args.join(" ")),
+                error: (...args) => (0, logger_1.err)("overkiz", args.join(" ")),
+                debug: (...args) => (0, logger_1.debug)("overkiz", args.join(" ")),
+                info: (...args) => (0, logger_1.log)("overkiz", args.join(" ")),
+                log: (...args) => (0, logger_1.log)("overkiz", args.join(" ")),
+            };
+            this.client = new overkiz_client_1.Client(bridge, {
+                service: this.config.service || "local",
+                user: this.config.user,
+                password: this.config.password,
+                pollingPeriod: this.config.pollingPeriod || 10,
+                refreshPeriod: this.config.refreshPeriod || 60,
+            });
+            const setup = yield this.client.getSetup();
+            setup.devices.forEach(device => this.attachDevice(device));
+            (0, logger_1.log)("overkiz", `connected -> ${setup.devices.length} device(s) found`);
+        });
+    }
+    attachDevice(device) {
+        this.devices.set(device.deviceURL, device);
+        const closure = device.getNumber("core:ClosureState");
+        if (device.hasState("core:ClosureState"))
+            this.closures.set(device.deviceURL, closure);
+        device.on("states", (states) => this.onStates(device, states));
+    }
+    onStates(device, states) {
+        (0, logger_1.debug)("overkiz", `states for ${device.label} -> ${JSON.stringify(states)}`);
+        const closureState = states.find(s => s.name === "core:ClosureState");
+        if (closureState) {
+            const closure = Number(closureState.value);
+            const previous = this.closures.get(device.deviceURL);
+            const unitState = closureToUnitState(closure, previous);
+            this.closures.set(device.deviceURL, closure);
+            (0, logger_1.log)("overkiz", `${device.label} -> closure ${closure} -> UnitState ${types_1.UnitState[unitState]}`);
+            this.emitter.emit("state", device.deviceURL, unitState, closure);
+        }
+    }
+    listDevices() {
+        return Array.from(this.devices.values()).map(d => ({
+            deviceURL: d.deviceURL, label: d.label, widget: d.definition.widgetName,
+        }));
+    }
+    execute(deviceURL, commandName, parameters = []) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.client)
+                throw new Error("Overkiz not connected");
+            (0, logger_1.log)("overkiz", `execute ${commandName}${parameters.length ? "(" + parameters.join(",") + ")" : ""} on ${deviceURL}`);
+            yield this.client.execute("apply", {
+                label: "smartsocket",
+                actions: [{ deviceURL, commands: [{ name: commandName, parameters }] }],
+            });
+        });
+    }
+    up(deviceURL) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.execute(deviceURL, "open");
+        });
+    }
+    down(deviceURL) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.execute(deviceURL, "close");
+        });
+    }
+    stop(deviceURL) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.execute(deviceURL, "stop");
+        });
+    }
+    setClosure(deviceURL, percentClosed) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.execute(deviceURL, "setClosure", [percentClosed]);
+        });
+    }
+}
+exports.Overkiz = Overkiz;
+//# sourceMappingURL=overkiz.js.map

package/server/platform.js

@@ -28,6 +28,7 @@ const door_1 = require("../accessories/door");
 const lock_1 = require("../accessories/lock");
 const p1_1 = require("./p1");
 const shelly_1 = require("./shelly");
+const overkiz_1 = require("./overkiz");
 const config_1 = require("../duotecno/config");
 const fs_1 = require("fs");
 const proxy_1 = require("./proxy");
@@ -85,6 +86,7 @@ class Platform extends base_1.Base {
         this.startPower("smappee", smappee_1.Smappee);
         this.startPower("p1", p1_1.P1);
         this.startPower("shelly", shelly_1.Shelly);
+        this.startPower("overkiz", overkiz_1.Overkiz);
         // startup a smartApp if configured
         if (this.config.smartapp) {
             try {