node-red-contrib-ccu 4.1.0 → 4.3.0

package/CHANGELOG.md

@@ -5,6 +5,131 @@ 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.3.0 (2026-09-04)
+
+### Added
+
+- **Dynamic node configuration through `msg.config`** (roadmap B-2). Put
+  an object in `msg.config` and its properties override that node's own
+  configuration for that one message; the stored configuration is never
+  modified, so the next message starts from the dialog settings again.
+  Supported by the value, set-value, switch, sysvar, signal and display
+  nodes; each node's help panel lists the keys it accepts, and anything
+  else is ignored. `msg.ccu` could not be used for this because it
+  already carries the CCU host name. (#172, #71, #103, #80, #56, #148,
+  #185)
+- signal node: every command field is reachable that way, including
+  `soundList` and `dimmerList`, which now also accept a plain array of
+  values (`msg.config.soundList = [1, 2]`) instead of the editor's
+  list-of-objects shape. (#148, #80)
+- sysvar node: a typed input selects where the value to write comes from
+  (msg/flow/global/env). Computing a value and storing it in a variable
+  no longer needs a change node to move it into `msg.payload` first.
+  (#56)
+- sysvar and rpc-event nodes show the last value and how long ago it
+  arrived under the node — the sysvar node also when "emit value on
+  start" is off, since the connection knows the value either way. (#54,
+  #52)
+- value and rpc-event nodes: new option **discard uncertain values**,
+  which drops values the ReGa could not timestamp (`msg.uncertain`).
+  Off by default, so existing flows are unaffected. (#96)
+- ccu-mqtt: new **get** topic (`hm/get/<channel>/<datapoint>` by
+  default) republishes the last known value on its status topic, so a
+  refresh can be triggered over MQTT. An empty datapoint republishes the
+  whole channel. (#115)
+- ccu-mqtt: the **RPC** topics are implemented and visible in the editor.
+  The dispatcher recognised the RPC topic before but the node had no
+  handler for it, so such messages were silently dropped and the
+  response topic was never used — which is why both fields were
+  commented out. The result (or the error) is published on the response
+  topic. (#22)
+- switch node: rule values accept the **bool** type, as core Node-RED's
+  switch node does. Without it `true` had to be entered as a string, and
+  `true == "true"` is false in JavaScript, so boolean datapoints could
+  only be compared by writing 0/1. (#51)
+- connection node: **RPC ping** can be switched off, which disables the
+  periodic ping and the timeout-triggered re-init for that connection.
+  Setting the ping timeout to 0 never did this — it fell back to 60
+  seconds. (#44)
+- connection node: **names/rooms refresh** interval (default 15 minutes,
+  0 = off). Channel names, rooms and functions used to be read once when
+  the connection started, so anything added in the CCU WebUI stayed
+  invisible until the flow was redeployed. (#167)
+
+### Fixed
+
+- set-value node: only the _first_ message ever configured the node.
+  Message properties were written into the node's own configuration, so
+  every later message hit the "already configured" guard and was
+  ignored, and the node kept acting on the first message's rooms,
+  functions or channel. Each message is now evaluated on its own. (#133)
+- set-value node: the device-name filter tested whether the _channel_
+  had a ReGa name while comparing the _device_ name, so channels without
+  a name of their own were dropped even when their device matched.
+- Enum names never worked: the CCU sends them in `VALUE_LIST`, but the
+  code read `ENUM`, which no interface process sends. `msg.datapointEnum`
+  and `msg.valueEnum` were always `undefined`, and writing an enum
+  datapoint by name (`AUTO-MODE` rather than `0`) fell back to `0`.
+- ccu-mqtt: the "is this parameter writeable" check was
+  `!(desc.OPERATIONS) && 2`, which is always false — it never fired, and
+  read-only parameters were written anyway.
+- ccu-mqtt: `putParamset` cast every value against the description of a
+  parameter that does not exist in that call, so the whole paramset went
+  out uncast. Its private copy of the cast logic is gone; the shared one
+  gained the MIN/MAX clamping that copy did. Unparseable numbers become
+  0 instead of NaN, which XML-RPC cannot encode.
+- Running on the CCU itself was not detected any more, so local installs
+  (RedMatic) silently talked to the interface processes through the
+  CCU's lighttpd proxy instead of their direct ports. The check grepped
+  `/etc/lighttpd/conf.d/proxy.conf` for a port number; on current
+  firmware that file is a one-line include and the port markers live two
+  levels down. It now looks for a listener on the direct port instead.
+  (Roadmap B-4)
+- Writing several system variables at once left all but the first
+  invisible until the next scheduled ReGa poll (30 s by default): the
+  immediate re-poll each write triggers was dropped while another poll
+  was still running. It is remembered and run once afterwards. (#166)
+- RSSI values from the ReGa poll were converted from the unsigned byte
+  unconditionally, so a value that was already negative, or the 0 that
+  means "never received", became -318 or -256. (#183)
+- Editor: the Channel and Datapoint fields were cleared whenever their
+  content was not a known channel address, which also wiped
+  `${PARAMETER}` placeholders every time the dialog was opened — so a
+  node inside a subflow lost its subflow parameter. Placeholders are
+  left alone now. (#158)
+- The German help texts of the rpc-event node never loaded:
+  `locales/de/ccu-rpc-event.json` had a trailing comma and was not valid
+  JSON.
+
+## 4.2.0 (2026-09-04)
+
+### Added
+
+- New node **ccu-homeassistant**: publishes Home Assistant MQTT
+  auto-discovery configurations (device-based, HA >= 2024.11) for a
+  checkbox-selected set of devices. It is a companion to the ccu-mqtt
+  node and reuses its topic templates and payload format, so the
+  discovery configs point at the topics ccu-mqtt already publishes and
+  consumes; wire its output to the same mqtt-out node. Entities: switch,
+  light (dimmers), cover (blinds/shutters incl. tilt), climate (HM and
+  HmIP thermostats), binary_sensor (contact, rotary handle, motion,
+  presence, smoke, water), event (keys), lock (KeyMatic), sensor (energy,
+  weather, maintenance) plus, optionally, disabled-by-default entities for
+  every other datapoint. Unchecking a device removes it from Home
+  Assistant on the next deploy. (Roadmap B-16)
+- ccu-mqtt: the setValue topic accepts Home Assistant's command words —
+  `OPEN`, `CLOSE`, `STOP`, `ON`, `OFF` on LEVEL and `AUTO-MODE`,
+  `MANU-MODE`, `BOOST-MODE`, `COMFORT-MODE`, `LOWERING-MODE` on the
+  read-only CONTROL_MODE of HM thermostats (translated to the `*_MODE`
+  actions).
+
+### Fixed
+
+- ccu-mqtt: channels without a ReGa name produced topics with an empty
+  segment (`hm/status//STATE`); the channel address is used instead.
+- Closing a ccu-mqtt or ccu-rpc-event node threw inside the connection's
+  deregister, so the node was never reported as closed on deploy.
+
 ## 4.1.0 (2026-09-04)
 
 ### Fixed

package/HANDOFF.md

@@ -7,14 +7,24 @@ Lab addresses and credentials are intentionally **not** in this file
 
 ## State
 
-- **4.0.0 released 2026-09-02** (npm latest, OIDC provenance, GitHub
-  release). Master is at `4.1.0-dev.5`+, **CI fully green** (lint + Node
-  22/24 × Node-RED 4/5).
-- In the Unreleased (4.1.0) changelog: binrpc 4.2.0, B-14
-  (LEVEL_2 → COMBINED_PARAMETER, unverified on hardware), paramsets
-  fetch/join tooling. Phase 3: cast/topic/message/castSysvar extracted,
-  43 unit tests (`npm run test:pure`).
-- Issue tracker fully triaged; B-6/B-14 archived; roadmap is current.
+- **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.
+- Issue tracker fully triaged (second pass 2026-09-04, B-7 done): 36
+  issues open, all annotated with their roadmap item; 5 closed that day;
+  8 newly diagnosed defects recorded in ROADMAP §8.3 — the two cheapest
+  are the unguarded RSSI conversion (#183) and the dropped sysvar
+  re-poll (#166). B-6/B-14/B-16 archived; roadmap is current.
 
 ## Decisions (2026-09-04)
 
@@ -50,14 +60,55 @@ Lab addresses and credentials are intentionally **not** in this file
    (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** — in progress 2026-09-04: CHANGELOG heading dated,
-   `npm pkg set version=4.1.0`, commit, push, CI green, `git tag v4.1.0
-&& git push origin v4.1.0` — release.yml publishes via OIDC and
-   creates the GitHub release from the CHANGELOG.
-4. **Release 4.2.0 = B-16** right after: user does the editor smoke test
-   on a lab CCU (the branch build is installed on both), then rebase the
-   branch onto master, push for CI, merge, date the CHANGELOG section,
-   version 4.2.0, tag. B-2 moves to 4.3.0.
+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)
 

package/README.md

@@ -28,6 +28,48 @@ Some example flows can be found in the [RedMatic Wiki](https://github.com/rdmtc/
 
 **Starting with Version 3.x these Nodes need Node-RED >= 1.0 to work correctly**
 
+## Home Assistant
+
+The `ccu-homeassistant` node publishes
+[MQTT discovery](https://www.home-assistant.io/integrations/mqtt/#mqtt-discovery) configurations (device-based,
+Home Assistant >= 2024.11) for the devices you tick in its config dialog. It is a companion to the `ccu-mqtt` node:
+it reuses that node's topic templates and payload format, so state and commands keep flowing through `ccu-mqtt` and
+the discovery configs simply point Home Assistant at those topics. Wire both nodes to the same `mqtt out` node and
+feed the `hm/set/#` topics from an `mqtt in` node into `ccu-mqtt` — see
+[examples/home-assistant.json](examples/home-assistant.json). One Home Assistant device is created per Homematic
+device with switch, light, cover, climate, binary_sensor, event, lock and sensor entities; every other datapoint can
+optionally be included as a disabled-by-default entity. Unticking a device removes it from Home Assistant on the
+next deploy.
+
+## Dynamic configuration
+
+Most nodes can be reconfigured per message: put an object in `msg.config` and its
+properties override that node's own configuration **for that one message**. The stored
+configuration is never modified, so the next message starts from the dialog settings
+again — sending a different room, channel or brightness each time works as you would
+expect.
+
+```javascript
+// one signal node, a different colour and duration per message
+msg.config = {dimmerColor: 4, durationValue: 10};
+
+// one set-value node, a different room per message
+msg.config = {rooms: 'Kitchen'};
+return msg;
+```
+
+Which keys a node accepts is listed in its help panel in the editor. Anything not on
+that list is ignored, so an unrelated property in `msg.config` cannot reach node
+internals. `msg.ccu` is not used for this because it already carries the CCU host name.
+
+The `value`, `get value` and `set value` nodes additionally read plain top-level
+properties (`msg.channel`, `msg.datapoint`, `msg.rooms`, …) to fill in fields left empty
+in the dialog. That is the older mechanism and is unchanged; `msg.config` wins over it.
+
+Inside a **subflow**, Node-RED substitutes `${PARAMETER}` placeholders in a node's text
+fields before the node is created, so a subflow parameter can be typed straight into the
+Channel or Datapoint field and each instance reads its own device.
+
 ## Configuration Examples
 
 The communication with the Homematic CCU needs independent connections in two directions. Node-red-contrib-ccu connects to the CCU's interface listeners (e.g. 2001/TCP for BidCos-RF) while the CCU connects to node-red-contrib-ccu's BINRPC/XMLRPC listeners (2048/tcp and 2049/tcp in examples below).