node-red-contrib-ccu 4.3.0 → 4.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-red-contrib-ccu",
-  "version": "4.3.0",
+  "version": "4.4.1",
   "license": "MIT",
   "main": "none",
   "keywords": [

package/roadmap-archive/B-17.md

@@ -0,0 +1,106 @@
+# B-17 — openccu-lite (a CCU without ReGaHSS)
+
+**✅ done 2026-09-06** (`4.4.0`).
+
+[openccu-lite](https://github.com/hobbyquaker/openccu-lite) is a Homematic
+CCU firmware that drops ReGaHSS. The interface processes are the ones we
+already talk to (`rfd` BidCos-RF/BIN-RPC, `hs485d`, `hmipserver`
+XML-RPC) — but nothing listens on 8181/8183, `rega.exe`/`tclrega.exe` do
+not exist, HM-Script is never interpreted, and there are no ReGa ids.
+Everything this package took from the ReGa apart from names, rooms and
+functions has no replacement there.
+
+What it offers instead is `occulited`'s **metadata API**, a small JSON
+store served under `/api/meta/v1/` behind the box's lighttpd, with a
+Server-Sent-Events change stream. Its porting kit (`docs/porting-from-rega.md`,
+`docs/PORTING-PROMPT.md`, `docs/meta-api.md` and the `fixtures/`
+conformance corpus in the openccu-lite repository) is what this item
+was implemented against.
+
+## The rule the port follows
+
+Keep the ReGa code path, add a provider, detect at runtime. On a CCU3,
+RaspberryMatic or OpenCCU nothing changes: the same configuration, the
+same messages, the same cache files.
+
+## What was built
+
+- **`nodes/lib/metaprovider.js`** — the counterpart of the `getRega*()`
+  methods. `detect()` is the feature test (`GET /api/meta/v1/version`,
+  no credential, 404 on a CCU). `MetaProvider` loads `GET /snapshot`,
+  then follows `GET /events/sse?since=<revision>`: `object.updated` and
+  `object.deleted` are applied to the in-memory document, everything
+  that can rewrite member paths (`node.*`, `enum.*`, `import`, an
+  explicit `resync`, a gap in the revisions) re-reads the snapshot.
+  `buildNames()` is pure and derives exactly what the rest of the code
+  already reads — `channelNames`, `channelRooms`, `channelFunctions`
+  keyed by the bare address (the API's ref is `<interface>.<address>`),
+  plus the `rooms` / `functions` name lists the editor asks for.
+- **Rooms and functions are a tree** there (`room/eg/wohnzimmer`), not a
+  flat list. They are flattened to the arrays the nodes have always
+  published, ancestors included and most specific first, so a channel in
+  _Wohnzimmer_ below _Erdgeschoss_ matches a room filter on either name
+  and `msg.room` is still the room the user means.
+- **Detection in the startup path** of `ccu-connection.js`: when the
+  ReGaHSS interface is ticked, the node probes once before deciding
+  between `startMeta()` and `getRegaData()`. The provider probes again
+  on every reconnect; three failed probes in a row hand control back to
+  the detection (a restored backup or a firmware swap under a running
+  Node-RED), and on the ReGa side a failing `getRegaData()` /
+  `refreshRegaData()` re-probes at most every five minutes. So a box
+  that changes kind is picked up in both directions without a redeploy.
+- **Credential**: on the box the read-only local token
+  (`/usr/local/etc/occulite/local-token`) is read automatically, off the
+  box an _openccu-lite token_ field takes one created on the box's Users
+  page. `401`/`403` degrades to addresses-only, is logged once, and is
+  retried — never fatal. An _openccu-lite port_ field covers boxes whose
+  web server is not on 80/443 (it is also what the integration test
+  uses).
+- **The ReGa-only nodes stay**: `ccu-sysvar`, `ccu-program`,
+  `ccu-script` and `ccu-poll` remain in the palette and in flows, the
+  connection logs one line about them when it starts, and every message
+  they get is rejected with `… are not available on this box
+(openccu-lite has no ReGaHSS)` instead of breaking the connection.
+- **No new dependency.** `node:http`/`node:https` rather than `fetch`,
+  because the connection node already offers "ignore invalid TLS
+  certificates", which `fetch` cannot express per request without
+  pulling in undici — and a Node stream is the natural shape for SSE.
+
+## Tests
+
+16 unit tests in `test/unit/metaprovider.test.js` (`npm run test:pure`):
+`buildNames()` over the openccu-lite conformance corpus, copied verbatim
+into `test/fixtures/openccu-lite/` (`valid-house`, `valid-empty`,
+`valid-depth-8`), plus a fake `/api/meta/v1` server built from
+`node:http` for detection (openccu-lite / a CCU's 404 / a 200 that is
+not the metadata API / nothing listening), the 401 path, an event →
+"names changed" round trip, the re-snapshot triggers, reconnects and the
+"not an openccu-lite any more" hand-back. The existing ReGa specs are
+untouched.
+
+Verified against a real `occulited` (built from the openccu-lite
+repository, `--listen 127.0.0.1:2132`, the `valid-house` fixture
+imported) with `node-red-node-test-helper` driving a real
+`ccu-connection` node: names, rooms and functions match the box; a
+`PATCH /objects/{ref}` rename, a room rename and a `node.moved` all
+reach `ccu.channelNames` / `ccu.channelRooms` in under 150 ms; the four
+ReGa-only nodes error per message; `createMessage()` produces the same
+`channelName` / `rooms` / `room` / `functions` / `function` fields as on
+a CCU.
+
+## Findings handed back to openccu-lite
+
+1. `occulited`'s SSE endpoint does not flush the response header until
+   it has an event or a heartbeat to write, so an HTTP client cannot
+   tell "connected" from "still connecting" for up to 30 s. A client
+   that applies its ordinary request timeout to the open stream tears it
+   down on every cycle; this implementation arms a separate idle timeout
+   after the socket connects and reports "connected" once the snapshot
+   is in, not when the stream opens.
+2. The porting prompt's example is `fetch`, which cannot do per-request
+   TLS verification settings in Node — worth a sentence in the kit,
+   since every integration that offers "ignore invalid certificates"
+   hits it.
+
+Original item: openccu-lite port — names, rooms and functions from the
+metadata API instead of ReGaHSS, ReGa path unchanged, runtime detection.

package/roadmap-archive/README.md

@@ -18,6 +18,9 @@ the roadmap's contents index (marked ✅ there, linking here).
 
 **Backlog items**
 
+- [B-17.md](B-17.md) — the openccu-lite port: names, rooms and
+  functions from the box's metadata API when it has no ReGaHSS ✅
+  2026-09-06 (4.4.0).
 - [B-5.md](B-5.md) — ping toggle, value/age status lines, uncertain
   filter, trailing sysvar re-poll, RSSI guard ✅ 2026-09-04 (4.3.0;
   #44/#54/#52/#96/#166/#183/#124).