node-red-contrib-ccu 4.1.0 → 4.3.0

package/roadmap-archive/B-16.md

@@ -0,0 +1,31 @@
+# B-16 — ccu-homeassistant: Home Assistant MQTT auto-discovery node
+
+**✅ done 2026-09-04** (released as 4.2.0) — user request 2026-09-04.
+
+New node `ccu-homeassistant`: publishes device-based Home Assistant MQTT
+discovery configs (HA ≥ 2024.11) for a checkbox-selected set of devices.
+Companion to a ccu-mqtt node whose topic templates and payload format it
+reuses, so state and commands keep flowing through ccu-mqtt and the node
+itself only emits the retained discovery configs (plus the aggregate
+`<channel>/PRESS` item for event entities); unticked devices get an empty
+retained config. Mapping ported from hm2mqtt.js (`lib/haroles.js`,
+`lib/hadiscovery.js`, channel TYPE as primary role key because only about
+half of the shipped VALUES descriptions carry CONTROL hints). Editor: device
+table modeled on RedMatic-HomeKit (filter, check/uncheck all), ccu-mqtt
+select, prefix, generic-entities option; `type=devices` admin endpoint.
+Rode along: ccu-mqtt HA command words (OPEN/CLOSE/STOP/ON/OFF, HM
+`*-MODE`), empty-name topic fix, connection `deregister` fix.
+
+Verified 2026-09-04 on the two lab CCUs against Home Assistant 2026.9.0
+(docker) and she 1.51.1 (the author's dev instance on the test broker plus
+a private instance): DRS8 switches with round trip, DRI16 inputs + events,
+DRAP sensors, PDT light with brightness (plain payloads), WRC2 events,
+removal on untick, editor smoke test by the user. Three payload defects
+found only through the live test (availability-list `val_tpl`, switch
+`stat_on`/`stat_off`, binary-only device classes on sensors) — the first
+two are inherited from hm2mqtt.js / mqtt-interfaces-core and should be
+fixed upstream. Not covered by lab hardware: cover and climate payloads
+(unit tests only), real key presses. Known gaps (as upstream): RGBW lights,
+sirens, garage doors, sysvars/programs as entities.
+
+Original item: | B-16 | **New node `ccu-homeassistant`: Home Assistant MQTT auto-discovery for a checkbox-selected set of devices** (decided 2026-09-04: a dedicated node, not an option on ccu-mqtt). It is a companion to an existing ccu-mqtt node, not a replacement: its config references one ccu-mqtt node of the flow (select populated via `RED.nodes.eachNode`, type `ccu-mqtt`, same ccu-connection) and **reuses that node's configured topics** — `topicOutputEvent` as HA state topics, `topicInputSetValue` as command topics, `topicOutputSysvar` for sysvars later — plus its payload format (`payloadOutput` mqsh-basic/extended/plain → matching `value_template`, e.g. `{{ value_json.val }}`). State and commands keep flowing through ccu-mqtt; the new node only emits the retained discovery configs `{topic, payload, retain: true}` for the same downstream mqtt-out node (no broker connection of its own), republishes them on deploy/reconnect, and publishes empty retained configs for devices that were unchecked (removal from HA). **Device selection like RedMatic-HomeKit's `redmatic-homekit-homematic-devices` node**: the config dialog loads all devices of the connection from the `/ccu` admin endpoint into a table (checkbox · name · address · type, "enable all"/"disable all" buttons, filter box, optionally expandable per-channel rows), stored as a `devices` object keyed by address — but **opt-in**: nothing is checked, hence nothing published, until the user ticks a device. Mapping modeled on hm2mqtt.js [`lib/hadiscovery.js`](https://github.com/hobbyquaker/hm2mqtt.js/blob/master/lib/hadiscovery.js) (README section "Home Assistant"): one HA device per Homematic device, device-based discovery payloads `homeassistant/device/<id>/config` (HA ≥ 2024.11; prefix configurable), entities derived from the paramset descriptions' `CONTROL` hints — switch (SWITCH.STATE, HmIP virtual receivers), light (dimmers), cover (blind position/tilt/direction), climate (HM/HmIP thermostats, modes/presets), binary_sensor (contact/motion/presence/smoke/water), event (key press short/long), lock (KEYMATIC), sensor (energy, weather, maintenance) — port hm2mqtt's mapping table rather than re-deriving it. **Constraint found 2026-09-04 (corrected the same day):** only 290 of the 647 VALUES entries in the shipped `paramsets.json` carry `CONTROL` hints (the older contributed user dumps were stripped of them), and the persisted runtime cache of existing installs inherits that — so a pure CONTROL-based mapping would silently skip roughly half the device types. Key the mapping on the channel `TYPE` from the device metadata (always present) and use CONTROL only as a refinement where the cache has it (live fetches and the B-1 regen bring CONTROL in; the fetch tool stores the full response). B-3 is not a prerequisite (HA commands use the setValue path, which casts in the connection), but its trivial fixes ride along. Builds on Phase 3's extracted `lib/topic.js` so the HA node computes exactly ccu-mqtt's topics. **Runs on branch `b-16-homeassistant`, target 4.2.0** (decided 2026-09-04; 4.1.0 stays the small data release). **Status 2026-09-04: implemented on the branch** — `nodes/lib/haroles.js` + `nodes/lib/hadiscovery.js` (pure, 24 unit tests on paramsets.json fixtures), `nodes/ccu-homeassistant.{js,html}` (device table, ccu-mqtt reference, republish on input, removal configs), `type=devices` admin endpoint, ccu-mqtt command words (OPEN/CLOSE/STOP/ON/OFF, HM `*-MODE`) + empty-name topic fix + connection `deregister` fix, README section, `examples/home-assistant.json`, CHANGELOG "Unreleased (4.2.0)". **Verified end-to-end 2026-09-04** on the lab CCU3 (RedMatic 9.0.0-alpha, aedes broker inside Node-RED) against Home Assistant 2026.9.0 (docker): HmIPW-DRS8 → 8 switches (state from the transmitter channel, secondaries disabled), HmIPW-DRI16 → 16 opening sensors + 16 event entities, HmIPW-DRAP → bus voltage/current sensors; switch round trip HA → `hm/set` → CCU → `hm/status` → HA state on/off; untick + deploy removes the device from HA. Three payload defects found and fixed only because of the live test (HA rejected/ignored silently): an availability-list entry takes `val_tpl`, not `avty_tpl`; a switch needs explicit `stat_on`/`stat_off` because HA compares the templated state with the command payloads by default; a sensor/number must not carry a binary_sensor class (`running` on the ENUM datapoint PROCESS). The first two are inherited from hm2mqtt.js / mqtt-interfaces-core and should be fixed upstream too. Also fixed: the readiness wait treated an empty VALUES paramset as "not cached" (5-minute fallback delay). Second round on the OpenCCU lab box (same HA, second ccu-mqtt with prefix `hm2/` and **plain payloads**, so the non-JSON templates are covered too): HmIP-PDT → light with brightness (HA brightness 128 → `LEVEL` 0.5 → state on/128 from the DIMMER_TRANSMITTER channel, off → 0, plain on → last brightness), HmIP-WRC2 → 2 event entities + battery sensor, no HA warnings. **Second consumer:** [she](https://github.com/hobbyquaker/she) 1.51.1 (the author's dev instance on the test broker, which both lab flows now feed as well) parses the same retained payloads (`GET /she/mqtt/ha-discovery`) into the 5 lab devices with plausible entity groups and no orphaned/duplicate flags — she is the lighter, scriptable check for future B-16 changes; HA stays the reference for schema validation. Not covered by the lab: cover and climate payloads (no blind or thermostat paired anywhere), key presses on real hardware. **Open before merge:** editor smoke test in a browser (device table, ccu-mqtt select), CI run (the local mocha suite cannot bind port 8181 under WSL); cover/climate stay unit-test-only until a device is available. Merge after 4.1.0 ships. Known gaps upstream too: RGBW lights, sirens, garage doors, sysvars/programs as entities. | user request |

package/roadmap-archive/B-2.md

@@ -0,0 +1,69 @@
+# B-2 — Dynamic node configuration via msg
+
+**✅ done 2026-09-04** (`4.3.0`) — issues #172, #71, #103, #80, #56,
+#148, #185, #133.
+
+The request arrived from every direction and was deliberately designed
+once rather than patched per node (which is why PR #173's auto-subscribe
+was closed rather than merged).
+
+## The mechanism
+
+`msg.config` is an object whose properties override the receiving node's
+own configuration **for that message only**. `nodes/lib/dynconfig.js`
+builds the effective configuration; the stored one is never touched.
+
+Why a namespace rather than flat properties everywhere: an event message
+already carries `channel`, `datapoint`, `deviceType`, `rooms` and friends,
+so honouring those on the signal or display node would let any message
+coming from an event node silently retarget it. `msg.ccu` was the obvious
+namespace but is taken — it holds the CCU host name — hence `msg.config`.
+
+Each node passes the list of keys it accepts; anything else in
+`msg.config` is ignored, so a stray property cannot reach node internals.
+The flat mechanism the value/get-value/set-value nodes always had (fill in
+fields left empty in the dialog from `msg.channel`, `msg.rooms`, …) is
+unchanged and keeps working; `msg.config` wins over it.
+
+## Per node
+
+- **set-value** — the whole filter plus `force`. This is also the fix for
+  #133: `setValues()` wrote message properties into `this.config`, so the
+  `if (!config[key])` guard skipped every later message and the node
+  stayed pinned to the first message's targets. The whitelist/blacklist
+  are keyed by the effective filter now, so an unchanged filter keeps the
+  caching benefit and a changed one is re-evaluated. The 200-line inline
+  matching chain moved to `nodes/lib/channelfilter.js` (pure, 14 tests),
+  which also fixed the device-name filter requiring the _channel_ to have
+  a ReGa name while comparing the _device_ name.
+- **value** — `iface`, `channel`, `datapoint`. A message without a
+  payload writes nothing (the 4.0.0 guard) and now retargets the output
+  subscription, which is what #172 asked for. For a node with its own
+  channel/datapoint configured this is a no-op unless `msg.config`
+  overrides them, so no existing flow changes behaviour.
+- **switch** — the source selection (`iface`/`channel`/`datapoint`/
+  `datapointProperty`/`sysvar`/`sysvarProperty`), so one node serves a
+  whole subflow (#103).
+- **sysvar** — `name`, plus a typed input for _where the value comes
+  from_ (msg/flow/global/env) instead of always `msg.payload` (#56).
+- **signal** — every command field including `soundList`/`dimmerList`,
+  which also accept a plain array of values instead of the editor's
+  list-of-objects shape (#148). The existing `<field>Type` typed inputs
+  keep working; `msg.config` wins over them.
+- **display** — channel and the EP-WM55 settings, joining the lines,
+  colours and icons that were already overridable.
+
+## Subflows (#158)
+
+Node-RED substitutes `${PARAMETER}` in a node's string properties before
+the node is constructed, so subflow parameters already worked at runtime —
+but the editor's channel autocomplete cleared any value that was not a
+known channel address, wiping the placeholder every time the dialog was
+opened. Fixed in the value, get-value, switch, signal and alexa editors.
+
+Not done: an explicit `env` type on the filter fields of the event nodes.
+The `${PARAMETER}` route covers the use case and the filters are read once
+at construction, so a typed input would need runtime evaluation for little
+gain. Revisit if someone asks.
+
+Original item: | B-2 | Dynamic node configuration via msg — recurring theme #172, #71, #103, #80, #56, plus #148 (SOUNDFILE_LIST via msg), #158 (subflow env config) and #133 — the latter confirmed still broken in 4.0.0: `setValues()` writes msg values into `config` permanently, so the first message's filters stick. Design properly rather than merging PR #173's auto-subscribe | tracker |

package/roadmap-archive/B-3.md

@@ -0,0 +1,57 @@
+# B-3 — ccu-mqtt node fixes and additions
+
+**✅ done 2026-09-04** (`4.3.0`) — issues #115, #22, #167, plus the three
+findings from ROADMAP §8.2 that the hm2mqtt 3.0 rewrite had confirmed.
+
+## Fixed
+
+- **The writeable check never fired.** Both `putParam` and `putParamset`
+  tested `!(description.OPERATIONS) && 2`, which is `(!OPERATIONS) && 2` —
+  always falsy, since `OPERATIONS` is a non-zero number for every real
+  parameter. Read-only parameters were written regardless. Now
+  `!(OPERATIONS & 2)`, and the write is skipped.
+- **`putParamset` cast against the wrong description.** It passed
+  `paramsetDescription[filter.param]` for every parameter; `filter.param`
+  only exists on the `putParam` topic, so it was `undefined` there and
+  the whole paramset went out uncast (strings where the CCU wanted
+  numbers or booleans). Each value is cast against its own description.
+- **Enum names never worked.** The CCU returns them in `VALUE_LIST`, but
+  `lib/cast.js` and `lib/message.js` read `ENUM`, which no interface
+  process sends: all 9494 ENUM-typed datapoints in the shipped
+  `paramsets.json` carry `VALUE_LIST` and none carries `ENUM`. So
+  `msg.datapointEnum` and `msg.valueEnum` had always been `undefined`,
+  and writing e.g. `AUTO-MODE` to an enum datapoint fell through to the
+  numeric cast and produced `0`. `enumList()` reads `VALUE_LIST` with
+  `ENUM` as a fallback for hand-written data.
+- **The divergent cast copy is gone.** `ccu-mqtt.paramCast` differed from
+  `lib/cast.js` only in clamping to MIN/MAX (and in producing `NaN` for
+  unparseable input, which XML-RPC cannot encode). `castValue` gained a
+  `clamp` option; the mqtt node passes it, the value nodes do not (#74).
+- The empty-name topic bug (`hm/status//STATE` for channels without a
+  ReGa name) was already fixed in 4.2.0.
+
+## Added
+
+- **`get`** (#115): `hm/get/<channel>/<datapoint>` republishes the last
+  known value on its status topic. An empty datapoint republishes every
+  datapoint of the channel. Fresh user interest in April 2026.
+- **`rpc`** (#22): the topic was already in the dispatcher's table, but
+  the class had no `rpc()` method, so `typeof this[command] === 'function'`
+  was false and the message was silently dropped; `topicOutputRpc` was
+  never read at all. That is why both fields sat commented out in the
+  editor since 2018 — exposing them would have created two settings that
+  do nothing. Both are visible now; the result or the error is published
+  on the response topic, and the never-working default topic loses its
+  meaningless `${command}` segment (migrated on dialog open). An empty
+  topic disables a command.
+- **#167**: `getRegaData()` (channel names, rooms, functions, groups) ran
+  once, in the connection constructor; the recurring poll only refreshed
+  variables and programs. A function added in the CCU WebUI was therefore
+  invisible until the flow was redeployed. New connection option
+  _names/rooms refresh_ (minutes, default 15, 0 = off) re-reads channel
+  names, rooms and functions from the ReGa poll's tail.
+
+`resolveChannel()` now holds the channel-name/address resolution the four
+command handlers each had inline.
+
+Original item: | B-3 | Fix the ccu-mqtt node bugs verified in hm2mqtt ROADMAP §1.3 (see §8.2); also #115 get/update method (fresh user interest Apr 2026), #22 missing RPC-topic GUI, #167 stale rooms/functions | hm2mqtt |

package/roadmap-archive/B-4.md

@@ -0,0 +1,44 @@
+# B-4 — Local-CCU detection
+
+**✅ done 2026-09-04** (`4.3.0`).
+
+When Node-RED runs on the CCU itself (RedMatic), the interface processes
+can be reached directly on their 3xxxx ports — BINRPC for BidCos and
+ReGa, and without the hop through the CCU's lighttpd proxy. The
+connection node picked that up from:
+
+```js
+const rfdConf = fs.readFileSync('/etc/lighttpd/conf.d/proxy.conf').toString();
+if (rfdConf.match(/"port"\s+=>\s+32001/)) {
+  this.isLocal = true;
+}
+```
+
+On current firmware that file is a single line:
+
+```
+include "/var/etc/lighttpd_proxy.conf"
+```
+
+which itself only contains `include "/etc/lighttpd/conf.d/proxy_normal.conf"` —
+the `"port" => 32001` markers are two levels down the include chain.
+So the regex has not matched in years and every local install silently
+went through the proxy on 1999/2000/2001/2010/9292.
+
+Measured on a lab CCU3 with firmware 3.89.8: `proxy.conf` is the bare
+include above, while 31999, 32001, 32010 and 39292 are all listening.
+
+## Fix
+
+`nodes/lib/localccu.js` asks the kernel instead of parsing lighttpd's
+configuration: a listener on rfd's direct port (32001, or the ReGa's 31999) is exactly the condition that makes using the direct ports
+correct, and it cannot drift when eQ-3 reorganises the config files
+again. `/proc/net/tcp` and `/proc/net/tcp6` are plain files, so the check
+stays synchronous — the interface table is built in the constructor —
+and on a host without `/proc` (Windows, macOS) it simply reports "not
+local", which is the safe answer.
+
+8 unit tests, including the real `/proc/net/tcp` line format from the
+3.89.8 lab box.
+
+Original item: | B-4 | Fix/remove the dead `isLocal` detection (`/etc/lighttpd/conf.d/proxy.conf` grep, `ccu-connection.js:346` — file is a stub on firmware ≥ 3.87, so local installs silently go through the proxy) | hm2mqtt §15.4 |

package/roadmap-archive/B-5.md

@@ -0,0 +1,57 @@
+# B-5 — Ping checks, sysvar node properties and status
+
+**✅ done 2026-09-04** (`4.3.0`) — issues #44, #54, #52, #124, #166, #96,
+#56, #183.
+
+A collection of small connection- and node-level items that had all been
+open since 2019/2020.
+
+- **#44 — configurable ping checks.** The connection node had a _ping
+  timeout_ field but no way to switch the check off: entering 0 fell
+  through `Number.parseInt(config.rpcPingTimeout, 10) || 60` back to 60
+  seconds. New _RPC ping_ checkbox (default on). Off means no periodic
+  ping and no timeout-triggered re-init for that connection — the honest
+  reading of "deactivate ping checks", with the consequence documented in
+  the dialog.
+- **#54 / #52 — last value and its age under the node.** The connection
+  keeps `value`, `ts` and `lc` for every datapoint and system variable;
+  the nodes simply never showed them, and the sysvar node showed nothing
+  at all unless "emit value on start" was enabled.
+  `nodes/lib/valuestatus.js` renders `<value> (3m)` and re-renders on a timer whose
+  interval follows the resolution shown, so the line does not go stale
+  between events. Used by the sysvar node (which also seeds it from the
+  connection's cache when "emit value on start" is off) and the rpc-event
+  node (which shows the topic that last fired).
+- **#96 — filter uncertain values.** The `uncertain` flag was already in
+  every message; there was no way to filter on it. `uncertain` is a
+  subscription filter property now, exposed as a _discard uncertain
+  values_ checkbox on the value and rpc-event nodes. It is only put into
+  the filter when the option is on, so existing subscriptions are
+  unaffected, and it is evaluated before `callCallback()`'s attribute
+  loop, which may break early for a whitelisted datapoint.
+- **#166 — immediate sysvar echo lost under concurrency.** `setVariable()`
+  triggers a ReGa poll so the new value comes back without waiting for
+  the 30 s interval, but only `if (!this.regaPollPending)`, and
+  `regaPoll()` itself no-ops while one is in flight. Writing several
+  variables at once therefore left all but the first invisible for up to
+  a poll interval — exactly the reported symptom ("works for one
+  variable, not for several"). The request is remembered and exactly one
+  more poll runs when the current one finishes.
+- **#183 — RSSI conversion guarded.** `dp.value -= 256` ran for every
+  RSSI_DEVICE/RSSI_PEER value from the ReGa poll, so a value that was
+  already signed, or the 0 that means "never received", became -318 or
+  -256. Now only for values above 127, matching hm2mqtt's guard. (The
+  XML-RPC event path needs no conversion.)
+- **#124 — re-read variable descriptions on poll** was already fixed in
+  2020 (commit 453f2b2, v3.2.1) and the issue merely never closed; the
+  remaining gap (`info` not selectable as a property) is noted below.
+- **#56** — the sysvar node's configurable source property landed with
+  B-2, which owns the dialog change.
+
+## Not done
+
+- `info` (a variable's description) is still not selectable as a single
+  property in the get-value/sysvar nodes; it is reachable through the
+  whole message. Left for whoever touches those property lists next.
+
+Original item: | B-5 | Configurable ping checks (#44), sysvar node property/status improvements (#54, #56, #52 last-event status, #124 re-read descriptions on poll, #166 immediate sysvar echo, #96 uncertain-filter option) | tracker |

package/roadmap-archive/README.md

@@ -18,6 +18,17 @@ the roadmap's contents index (marked ✅ there, linking here).
 
 **Backlog items**
 
+- [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).
+- [B-4.md](B-4.md) — local-CCU detection via a /proc/net/tcp listener
+  probe instead of the lighttpd config grep that had stopped matching ✅
+  2026-09-04 (4.3.0).
+- [B-3.md](B-3.md) — ccu-mqtt fixes plus the `get` and `rpc` commands and
+  the VALUE_LIST enum names ✅ 2026-09-04 (4.3.0; #115/#22/#167 and the
+  §8.2 findings).
+- [B-2.md](B-2.md) — dynamic node configuration via `msg.config` ✅
+  2026-09-04 (4.3.0; #172/#71/#103/#80/#56/#148/#185/#133/#158).
 - [B-14.md](B-14.md) — COMBINED_PARAMETER mapping for HmIP slat writes ✅
   2026-09-02 (#136/#154/#175, pending hardware confirmation).
 - [B-6.md](B-6.md) — binrpc rewrite without abandoned deps ✅ 2026-09-02