node-red-contrib-ccu 4.4.0 → 4.4.2

package/AGENTS.md

@@ -1,96 +1,3 @@
-# Agent Instructions
+# Agent instructions
 
-Instructions for AI coding agents (Claude Code, etc.) working in this repository.
-
-## Project overview
-
-`node-red-contrib-ccu` provides Node-RED nodes to connect to a Homematic CCU
-(BidCos/HmIP/CUxD home automation hardware from eQ-3). It talks to the CCU
-via BINRPC/XMLRPC (`nodes/ccu-connection.js` holds the bulk of the connection
-and RPC logic) and via ReGaHSS remote scripts.
-
-Layout:
-
-- `nodes/` — one `.js` (server-side logic) + `.html` (editor UI/registration)
-  pair per node type. `nodes/lib/` has shared helpers, `nodes/icons/` and
-  `nodes/locales/` are editor assets/i18n.
-- `test/` — mocha specs (`*_spec.js`), plus `test/simulator-data` and
-  `test/simulator-behaviors` used with `hm-simulator` to fake a CCU for tests.
-- `tools/` — one-off scripts, not part of the published package.
-- `paramsets.json` — large generated/vendored data file describing CCU device
-  paramsets (datapoints). Treat as data, not something to hand-edit.
-- `docs/` — images referenced from README.md.
-
-## Roadmap
-
-Planned work lives in ROADMAP.md (stable IDs: `D-n` decisions, `B-n`
-backlog, `OQ-n` open questions — never reuse an ID). When an item is
-completed, move its content to `roadmap-archive/<ID>.md` (one file per
-item), list it in `roadmap-archive/README.md`, and mark its line in the
-ROADMAP.md contents with ✅ linking to the archive file. Read ROADMAP.md
-before starting work that might overlap with a decision recorded there.
-
-## Reference documentation
-
-For anything involving HomematicIP (HmIP) devices, channels, or datapoints
-(paramset names, value ranges, units, ENUM meanings, which channel a
-datapoint belongs to, etc.), consult the official eQ-3 documentation:
-
-https://www.eq-3.de/Downloads/eq3/download%20bereich/hm_web_ui_doku/HmIP_Device_Documentation.pdf
-
-This PDF is the authoritative source for HmIP device/channel/datapoint
-definitions — prefer it over guessing when adding or fixing paramset
-handling, value casting, or device-specific logic.
-
-For CUxD-specific devices/channels/datapoints, consult the docs in the
-cuxd project itself:
-
-https://github.com/jens-maus/cuxd/tree/master/docs
-
-## Related fork worth checking
-
-https://github.com/ptweety/node-red-contrib-ccu is an active fork of this
-repo (currently at v3.6.2 vs. our v3.4.2). Not all of its direction is
-necessarily wanted here, but it has diverged with changes that may be worth
-cherry-picking individually — evaluate case by case rather than bulk-merging.
-Known differences as of 2026-07:
-
-- Added CCU-Jack as a supported interface.
-- Dropped dependencies: `mqtt-wildcard`, `nextport`, `hm-discover`, and a
-  `promise.prototype.finally` polyfill.
-- Split build into separate JS/HTML build steps; moved node help texts into
-  a restructured `locales/` layout.
-- Tooling churn: `nyc` → `c8` for coverage, bumped `xo`/`eslint`/`mocha`/
-  `husky`/`node-red` devDependency versions, added `auto-changelog`.
-- Added `MIGRATION.md`/contribution guidelines docs.
-
-When a task here touches an area also changed upstream in that fork (e.g.
-interface handling, build/lint tooling, locale structure), check what they
-did before implementing from scratch — but confirm it still fits this
-repo's compatibility floors (Node >= 20, Node-RED >= 4.0) before porting.
-
-## Conventions
-
-- Code style: ESLint 9 (flat config, `eslint.config.js`) + Prettier
-  (`.prettierrc`, 4-space, 120 cols). `npm run lint` checks both,
-  `npm run format` auto-fixes. Let a failing lint stop you.
-- Tests: `npm run test:unit` runs mocha over `test/**/*_spec.js` against
-  `hm-simulator`; `npm test` = lint + tests; `npm run test:cov` adds c8
-  coverage.
-- Each node's `.js` and `.html` files must stay in sync — the `.html`
-  defines the editor palette entry, config form, and help text; the `.js`
-  registers the runtime node type with the same name.
-- `nodes/ccu-switch.js`/`.html` and `tools/paramsets-join.js` are excluded
-  from linting (see `eslint.config.js` ignores and `.prettierignore`) —
-  legacy exclusions to burn down.
-
-## Working here
-
-- Do not hand-edit `paramsets.json`; if it needs updating, look at how
-  `tools/paramsets-join.js` produces it.
-- This addon is also shipped inside RedMatic (a Node-RED distribution for
-  CCU3/RaspberryMatic) — avoid breaking changes to node config schemas
-  without considering migration for existing flows.
-- Supported floors as of 4.0: Node.js >= 20, Node-RED >= 4.0; the primary
-  target is Node-RED 5 on Node 24 (see ROADMAP.md D-1). Stay CommonJS
-  (D-2).
+Agent working documents for this repository (roadmap, handoff, bugs) are kept outside it, in the maintainer's private agents repository, checked out next to this one as `../openccu-lite-agents/node-red-contrib-ccu/`. Read them first. Nothing in this repository links to them.

package/CHANGELOG.md

@@ -5,6 +5,55 @@ Notable changes to node-red-contrib-ccu. Format follows
 user-visible symptom and the cause, not the commit list (the release notes
 append commits automatically).
 
+## 4.4.2 (2026-09-09)
+
+### Fixed
+
+- **`getRegaVariables Error: socket hang up` every few minutes on a CCU**
+  (B-18, [RedMatic #601](https://github.com/rdmtc/RedMatic/issues/601)
+  follow-up). Since 4.3.0 a local install talks to ReGaHSS itself on port 8183. ReGaHSS answers HTTP/1.1 without `Connection: close` — and then
+  closes the connection 0.4–7 ms after every response (measured on a
+  CCU3 3.89.8, median 0.55 ms). `homematic-rega` 2.0 (since 4.0.0) sent
+  its requests through Node's `http.globalAgent`, which pools connections
+  (`keepAlive: true` since Node 19), so the next request on such a socket —
+  `regaPoll` right after a `setVariable`, or `getRegaPrograms` right after
+  `getRegaVariables` — could land in that window and die with
+  `ECONNRESET` / `socket hang up`; the sysvar nodes then showed
+  "disconnected" until the next poll. lighttpd on 8181 (the remote path,
+  and the local path before 4.3.0) keeps connections alive properly, which
+  is why nobody saw it before. In the lab (CCU3 3.89.8, Node 24.18.1, ReGaHSS kept busy by a script loop) a poll every 10 s preceded by a write, timed as the addon does it, lost 20 of 810 requests in 45 minutes with the pooled socket (27 per hour; the reporter's log shows about 6), 7 of 807 with a few milliseconds of client-side jitter, and 0 of 807 without keep-alive. Fixed in
+  `homematic-rega` 2.0.1, which uses an agent without keep-alive (the 1.x
+  behaviour) and takes an `agent` option; this release requires it. No
+  change to the addon's own code paths.
+
+## 4.4.1 (2026-09-07)
+
+### Fixed
+
+- **Node-RED could be killed by a failed ReGaHSS write, seconds after
+  start** ([RedMatic #601](https://github.com/rdmtc/RedMatic/issues/601)).
+  A write to a system variable that arrives before the variable list is
+  known is deferred into a queue and flushed once the first
+  `getRegaVariables` completes. That flush dropped the resulting promise,
+  so a rejected write — ReGaHSS closing the connection, `Error: socket
+hang up` — became an **unhandled rejection**, which Node >= 15 turns
+  into an uncaught exception: the whole Node-RED process exited with
+  status 1 and its supervisor restarted it into the same crash. The
+  rejection is now caught and logged.
+
+  This became reachable in 4.3.0: the rewritten local-CCU detection made
+  `isLocal` true again on RedMatic boxes (it had silently stopped
+  matching on current firmware), which moves ReGa traffic from lighttpd
+  on 8181 to ReGaHSS directly on 8183. lighttpd absorbed a busy ReGaHSS;
+  the direct port simply closes the connection.
+
+- The same floating-promise pattern in `ccu-mqtt`: `setVariable`,
+  `programActive` and `programExecute` triggered over MQTT dropped their
+  promises too, and now report through the node's error output instead of
+  taking the process down.
+- `regaPoll`'s `finally` chain is caught as well, so a throw in the
+  follow-up scheduling cannot escape as an unhandled rejection.
+
 ## 4.4.0 (2026-09-06)
 
 ### Added

package/nodes/ccu-connection.js

@@ -1593,7 +1593,10 @@ module.exports = function (RED) {
                             this.regaPollAgain = false;
                             this.refreshRegaDataIfDue();
                         }
-                    });
+                    })
+                    // a throw inside the finally above would otherwise be an
+                    // unhandled rejection, see #601
+                    .catch((error) => this.logger.error('regaPoll', error));
             }
         }
 
@@ -1784,10 +1787,17 @@ module.exports = function (RED) {
                             Object.keys(this.setVariableQueueTimeout).forEach((name) =>
                                 clearTimeout(this.setVariableQueueTimeout[name]),
                             );
-                            Object.keys(this.setVariableQueue).reduce(
-                                (p, name) => p.then((_) => this.setVariable(name, this.setVariableQueue[name])),
-                                Promise.resolve(),
-                            );
+                            // #601: a rejected write here used to be an
+                            // unhandled rejection, which Node >= 15 turns into
+                            // an uncaught exception - it killed the whole
+                            // process seconds after start whenever ReGaHSS
+                            // dropped the connection (RedMatic #601).
+                            Object.keys(this.setVariableQueue)
+                                .reduce(
+                                    (p, name) => p.then((_) => this.setVariable(name, this.setVariableQueue[name])),
+                                    Promise.resolve(),
+                                )
+                                .catch((error) => this.logger.error('deferred setVariable', error));
                         }
 
                         resolve();

package/nodes/ccu-mqtt.js

@@ -405,13 +405,22 @@ module.exports = function (RED) {
                 return;
             }
 
+            // #601: these promises used to float - a rejection (e.g. ReGaHSS
+            // closing the connection) became an unhandled rejection and took
+            // the whole Node-RED process down.
             if (this.ccu.sysvar[filter.name]) {
-                this.ccu.setVariable(filter.name, payload);
+                this.ccu
+                    .setVariable(filter.name, payload)
+                    .catch((error) => this.error('setVariable ' + filter.name + ': ' + error.message));
             } else if (this.ccu.program[filter.name]) {
                 if (typeof payload === 'boolean') {
-                    this.ccu.programActive(filter.name, payload);
+                    this.ccu
+                        .programActive(filter.name, payload)
+                        .catch((error) => this.error('programActive ' + filter.name + ': ' + error.message));
                 } else {
-                    this.ccu.programExecute(filter.name);
+                    this.ccu
+                        .programExecute(filter.name)
+                        .catch((error) => this.error('programExecute ' + filter.name + ': ' + error.message));
                 }
             } else {
                 this.error('no sysvar or program with name ' + filter.name + ' found');

package/nodes/ccu-poll.js

@@ -23,7 +23,8 @@ module.exports = function (RED) {
                     return;
                 }
 
-                this.ccu.regaPoll(); // TODO catch errors
+                // regaPoll() returns nothing and handles its own errors (#601)
+                this.ccu.regaPoll();
                 done();
             });
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-red-contrib-ccu",
-  "version": "4.4.0",
+  "version": "4.4.2",
   "license": "MIT",
   "main": "none",
   "keywords": [
@@ -51,7 +51,7 @@
   ],
   "dependencies": {
     "binrpc": "^4.2.0",
-    "homematic-rega": "^2.0.0",
+    "homematic-rega": "^2.0.1",
     "homematic-xmlrpc": "^2.0.0",
     "mqtt-wildcard": "^3.0.9"
   },

package/HANDOFF.md

@@ -1,187 +0,0 @@
-# Session handoff — 2026-09-04
-
-Context for continuing on another machine. Delete this file once its
-content is consumed (state that outlives the day belongs in ROADMAP.md).
-Lab addresses and credentials are intentionally **not** in this file
-(nor in the wiki or issues).
-
-## State
-
-- **4.0.0 released 2026-09-02, 4.1.0 released 2026-09-04** (npm latest
-  = 4.1.0, OIDC provenance, GitHub releases). 4.1.0 = binrpc 4.2.0, B-14
-  (LEVEL_2 → COMBINED_PARAMETER, unverified on hardware by decision),
-  paramsets fetch/join tooling and the regenerated `paramsets.json`
-  (+605 keys from the production CCU and two lab CCUs). Phase 3:
-  cast/topic/message/castSysvar extracted, 43 unit tests
-  (`npm run test:pure`, 71 on the B-16 branch).
-- **4.2.0 released 2026-09-04** (tag v4.2.0, npm latest = 4.2.0): the
-  ccu-homeassistant node (B-16, archived). Branch `b-16-homeassistant`
-  merged with `--no-ff` and deleted. The lab CCUs run the equivalent
-  `4.2.0-dev.1` build with the "B-16 Home Assistant" flow tabs; reporters
-  of #136/#154/#175 were asked (2026-09-04) to confirm the LEVEL_2 fix
-  on their hardware.
-- **4.3.0 released 2026-09-04** (tag v4.3.0, npm latest = 4.3.0):
-  B-2 (dynamic configuration via `msg.config`), B-3 (ccu-mqtt fixes plus
-  the `get` and `rpc` commands and the VALUE_LIST enum names), B-4
-  (local-CCU detection via a /proc/net/tcp listener probe) and B-5
-  (ping toggle, value+age status lines, uncertain filter, trailing sysvar
-  re-poll, RSSI guard). All four archived. Branch `b-2-b-5` merged with
-  `--no-ff`; 145 pure tests, 23 integration specs green on all four CI
-  legs.
-- Issue tracker: 36 → **19 open**. The 17 issues 4.3.0 fixes were
-  commented and closed after the release (#172 #71 #103 #80 #56 #148
-  #133 #115 #22 #167 #44 #54 #52 #96 #166 #183 #51, plus comments on the
-  already-closed #185 and #158). B-6/B-7/B-14/B-16 archived; roadmap is
-  current.
-- **Not done for 4.3.0: the editor smoke test in a browser.** The inline
-  editor scripts are syntax-checked by a new unit test and the runtime
-  was verified on a lab CCU, but the dialogs themselves have not been
-  clicked through — and 4.3.0 adds fields to ccu-connection (RPC ping,
-  names/rooms refresh), ccu-sysvar (Value from), ccu-mqtt (get + the two
-  RPC topics) and ccu-value/ccu-rpc-event (discard uncertain values).
-- Lab CCU `ccu-charly` runs 4.3.0-dev.1 (identical to the release) with a
-  flow tab **"B-2..B-5 test"**: three inject nodes driving one
-  ccu-set-value through different `msg.config` filters, an rpc-event
-  debug, and an mqtt rig on the `hm2test/` prefix (mqtt in → ccu-mqtt →
-  mqtt out) used to verify the new `get` and `rpc` commands. The relays
-  were left switched off.
-
-## Decisions (2026-09-04)
-
-- **The production CCU3 stays on firmware 3.87.6.** No update for the
-  sake of the paramsets regeneration. The regen runs against it as-is;
-  what matters is the set of _paired_ device types, and 3.87.6 already
-  reports the current descriptions for those (verified for the heating
-  group / eTRV in docs/paramsets.md §4).
-- **Two lab systems exist** (set up for the RedMatic 9.0.0 work, see
-  `../RedMatic/HANDOFF.md`): x86_64 OpenCCU 3.89.8 and an armv7l CCU3
-  on original firmware 3.89.8, both running a RedMatic dev install with
-  node-red-contrib-ccu 4.0.0. Use them for anything risky or
-  destructive (firmware-3.89 behavior, install/update paths, B-14
-  style hardware pokes if a suitable device gets paired there). They
-  have few/no devices paired, so they **cannot replace the production
-  dump** — at most they add the group-type (VirtualDevices) keys on
-  3.89.8 and serve as a diff reference.
-
-## Plan (blocks 4.1.0)
-
-1. ~~Full paramsets regeneration~~ **done 2026-09-04** (4.1.0-dev.7):
-   lab CCUs (3.89.8) joined first (+58 keys), then the production CCU
-   (3.87.6, fetched read-only from WSL with `--delay 600`, ~25 min for
-   962 keys: +547 new, 32 refreshed — BidCos-RF, BidCos-Wired, HmIP and
-   the HmIP-HEATING 2.0.0 group). Rules for the production box, given by
-   the user: read-only, slow request rate (it overloads easily), and its
-   RPC callbacks only reach the Node-RED test box (firewall) — a live
-   node-red-contrib-ccu connection against it must run there, never from
-   WSL or a lab CCU. Procedure: docs/paramsets.md §3.
-2. ~~B-14 hardware check~~ **skipped by user decision 2026-09-04** — no
-   test on the production blind for now; the CHANGELOG says so and the
-   reporters of #136/#154/#175 are asked for confirmation. The recipe
-   (ccu-value node writing LEVEL_2 to the HmIP-FBL's `:4` channel on
-   the Node-RED test box, log shows the COMBINED_PARAMETER remap) stays
-   valid if it is ever wanted.
-3. ~~Release 4.1.0~~ **done 2026-09-04** (tag v4.1.0, release.yml green,
-   npm latest 4.1.0). Follow-up worth doing: comment on #136/#154/#175
-   that 4.1.0 contains the LEVEL_2 fix and ask for confirmation on real
-   hardware (needs the user's go — outward-facing).
-4. **Release 4.2.0 = B-16** — editor smoke test done by the user
-   2026-09-04 (ok), released the same day: branch merged into master
-   with `--no-ff` (never rebase with `-X theirs` — it silently keeps the
-   branch side of conflicting doc hunks, which bit twice today), CHANGELOG
-   dated, version 4.2.0, tag v4.2.0. B-16 archived. B-2 is 4.3.0.
-
-## B-16 branch `b-16-homeassistant` (2026-09-04, target 4.2.0)
-
-- Implemented and committed on the branch (not pushed): ccu-homeassistant
-  node + `lib/haroles.js` + `lib/hadiscovery.js` (ported from hm2mqtt.js;
-  channel TYPE is the primary role key because only ~45 % of the shipped
-  VALUES descriptions carry CONTROL hints), 24 unit tests, ccu-mqtt HA
-  command words + empty-name
-  topic fix, ccu-connection `deregister` fix and `type=devices` admin
-  endpoint, README section, `examples/home-assistant.json`, CHANGELOG
-  "Unreleased (4.2.0)". Details in ROADMAP B-16.
-- Local `npm test`: lint + 71 pure tests green. The mocha integration
-  suite cannot run on this WSL machine (hm-simulator's port 8181 →
-  EADDRINUSE, identical on master) — push the branch and let CI run it.
-- **Lab test done 2026-09-04** on the CCU3 lab box (branch build
-  installed into RedMatic, `node-red-contrib-aedes` as broker inside
-  Node-RED, flow tab "B-16 Home Assistant" left deployed there) against
-  Home Assistant 2026.9.0 in docker on WSL: 3 wired devices discovered
-  (232 entities, 47 enabled), switch round trip on/off, DRI16 event
-  entities, removal on untick — all good after fixing three payload
-  defects HA had rejected (see ROADMAP B-16). Scripts for the whole setup
-  (install, deploy, HA onboarding, status via comms websocket) are in
-  this session's scratchpad; the lab hand-over note lists the HA
-  container and login.
-- Second round on the OpenCCU lab box (branch build installed there too,
-  flow tab "B-16 Home Assistant" with topic prefix `hm2/` and plain
-  payloads, publishing to the CCU3 box's broker): HmIP-PDT light round
-  trip with brightness verified, HmIP-WRC2 events discovered, no HA
-  warnings.
-- she (Smart Home Engine) as consumer: the user moved their she dev
-  instance to the test broker, and both lab flows now publish there as
-  well (second mqtt-broker config in each flow), so that instance's
-  HA-discovery view lists the 5 lab devices (no orphaned/duplicate
-  flags) — the quick check for future B-16 changes; a private she on the
-  lab broker exists too. Details and addresses in the lab hand-over note.
-- Still open: editor smoke test in a browser on a lab box (device table,
-  ccu-mqtt select), a real key press (event entity), CI. Cover/climate
-  payloads have no lab hardware — unit tests only.
-- Merge after 4.1.0 is released (rebase onto master; the CHANGELOG has
-  separate Unreleased sections, so this is trivial).
-
-## Infrastructure (this does not travel via git; addresses live outside the repo)
-
-- **Node-RED test box** (Debian bookworm, Node 24, Node-RED 5.0.6, ssh as
-  root with key auth): `systemctl {restart,status} node-red`,
-  `journalctl -u node-red`, user dir `/root/.node-red`, nginx TLS in
-  front with internal CA certs. Deploy: `npm pack` → scp tarball →
-  `cd /root/.node-red && npm install /tmp/<tarball> && systemctl restart
-node-red`. Verify: `curl -s http://localhost:1880/nodes -H "Accept:
-application/json"`.
-- **Production CCU3** (fw 3.87.6, stays there, other VLAN): read-only ssh
-  as root works; XML-RPC 2001/2010/9292 answer client calls from WSL.
-  Contrary to the earlier note it is _not_ HmIP-only: the 2026-09-04
-  dump lists ~35 BidCos-RF, 3 BidCos-Wired and ~30 HmIP device types
-  plus heating groups. Gotcha that cost hours: the CCU firewall must
-  allow the CCU → Node-RED callback port, otherwise inits hang for
-  minutes and metadata never arrives — only the Node-RED test box is
-  allowed through.
-- **Lab CCUs**: see Decisions above and `../RedMatic/HANDOFF.md`
-  ("Building and testing locally") for the scripted-check recipes
-  (Node-RED token via `POST /addons/red/auth/token`, CCU session via the
-  JSON-API).
-- **Firmware image** `ccu3-3.89.8.tgz` lives in a temp dir on the old
-  Mac only — if needed again, re-download from the official CCU3
-  firmware page. Its analysis is preserved in docs/paramsets.md.
-- **gh CLI**: needs auth on the new machine (`gh auth login`,
-  account hobbyquaker). Issue/PR comments are signed
-  "Claude (Fable 5) … on behalf of @hobbyquaker" (German or English
-  matching the issue).
-
-## Waiting on externals (do not gate 4.1.0)
-
-- Reporter dumps: #177 (BSL-V2), #144 (WRCD), #159 (CuxD) — for B-15 +
-  paramsets; requested in the issues 2026-09-02.
-- Retest answers: #111, #145, #146, #151 (close ~2026-12 if silent);
-  #112, #117 (retest comments posted).
-- Hardware confirmation for B-14 from reporters (#136/#154/#175).
-
-## After 4.3.0 (queue)
-
-1. Browser smoke test of the config dialogs changed in 4.3.0 (see above).
-2. Editor loader consolidation (Phase 3 §6.4 + §8.1 defect 3, shared
-   `resources/` script for the 9 dialogs) — needs a user smoke test on
-   the Node-RED test box afterwards.
-3. Remaining Phase 3: split rpc/rega/queue out of ccu-connection.js,
-   async/await as touched, i18n/help consolidation (#58). `lib/` grew
-   `dynconfig`, `channelfilter`, `valuestatus` and `localccu` in 4.3.0;
-   `ccu-connection.js` is still ~3100 lines.
-4. Remaining Phase 4: B-11 (re-init robustness — the `rpcCheckInit`
-   early return for device-less interfaces is still there, deliberately
-   left alone in 4.3.0 to keep its scope), B-12 (auth/TLS, #27), B-13
-   (party mode, #161/#156), B-15 (new HmIP channel types, #177/#144),
-   B-8/B-9/B-10.
-5. Still open from §8.3: the stale device-table cache (#181 — 4.3.0's
-   refresh covers names/rooms/functions only) and the internal system
-   variables (#184, needs a `homematic-rega` release).