node-red-contrib-ccu 4.2.0 → 4.4.0

package/.prettierignore

@@ -7,3 +7,6 @@ nodes/locales
 nodes/ccu-switch.js
 test/simulator-data
 docs
+
+# verbatim copy of openccu-lite's conformance corpus (fixtures/store) - do not reformat
+test/fixtures/openccu-lite

package/CHANGELOG.md

@@ -5,6 +5,146 @@ 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.0 (2026-09-06)
+
+### Added
+
+- **openccu-lite support** (roadmap B-17). [openccu-lite](https://github.com/hobbyquaker/openccu-lite)
+  is a Homematic CCU firmware without ReGaHSS: the interface processes
+  are unchanged, but nothing listens on 8181/8183, HM-Script is never
+  interpreted and there are no ReGa ids. The connection node now asks
+  the box `GET /api/meta/v1/version` when it starts and on every
+  reconnect of its name sync; a CCU3/RaspberryMatic/OpenCCU answers 404
+  and everything runs exactly as before, an openccu-lite answers with
+  its API version and device, channel, room and function names come
+  from its metadata API instead — a snapshot at start, then the box's
+  Server-Sent-Events change stream, so a rename in the box's UI reaches
+  running flows within a second without a redeploy. `msg.channelName`,
+  `msg.rooms`, `msg.functions` and the room/function filters keep the
+  shape they have on a CCU (rooms and functions are a tree there and
+  are flattened to the usual arrays of names, most specific first).
+  Nothing has to be configured: the same connection node works on both
+  kinds of box, which is what makes moving a backup between them
+  harmless.
+- connection node: **openccu-lite token** and **openccu-lite port**
+  fields. The token is only needed when Node-RED does _not_ run on the
+  box — on the box the read-only token in
+  `/usr/local/etc/occulite/local-token` is picked up automatically, off
+  the box the administrator creates one on the box's _Users_ page. A
+  rejected or missing token is not fatal: the nodes work with addresses
+  instead of names, the connection logs it once and takes the names as
+  soon as a valid token is there. The port field is only for boxes
+  whose web server is not on 80/443. Both are ignored on a CCU.
+- connection node: the cached `ccu_rega_<host>.json` now also holds the
+  room and function name lists, so the editor's room and function
+  pickers are filled right after a restart instead of only after the
+  first successful sync.
+
+### Changed
+
+- `ccu-sysvar`, `ccu-program`, `ccu-script` and `ccu-poll` stay in the
+  palette and in flows on openccu-lite, and stay accepted in the
+  editor. There is no ReGa DOM on such a box, so instead of failing the
+  connection they log one line when the connection starts and answer
+  every message with a clear error (`… are not available on this box
+(openccu-lite has no ReGaHSS)`). On a CCU nothing about them changes.
+
+## 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

package/HANDOFF.md

@@ -14,9 +14,37 @@ Lab addresses and credentials are intentionally **not** in this file
   (+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).
-- Branch `b-16-homeassistant` (4.2.0) is pushed and **CI green** on all
-  legs including the mocha integration suite.
-- Issue tracker fully triaged; B-6/B-14 archived; roadmap is current.
+- **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)
 
@@ -139,13 +167,21 @@ application/json"`.
   #112, #117 (retest comments posted).
 - Hardware confirmation for B-14 from reporters (#136/#154/#175).
 
-## After 4.1.0 (queue)
+## After 4.3.0 (queue)
 
-1. Editor loader consolidation (Phase 3 §6.4 + §8.1 defect 3, shared
+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.
-2. Remaining Phase 3: split rpc/rega/queue out of ccu-connection.js,
-   async/await as touched, i18n/help consolidation (#58).
-3. 4.3.0 headline (moved from 4.2.0, which is B-16): B-2 dynamic config
-   via msg (7 issues; #133 has the confirmed setValues config-mutation
-   bug as the sharpest target).
+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).

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**
 
+## openccu-lite
+
+[openccu-lite](https://github.com/hobbyquaker/openccu-lite) is a Homematic CCU firmware **without ReGaHSS**. The
+interface processes (`rfd`, `hs485d`, `hmipserver`) are the same, so everything these nodes do over BINRPC/XMLRPC works
+unchanged — but there is no logic layer: nothing listens on 8181/8183, HM-Script is never interpreted, and there are no
+ReGa ids. Device, channel, room and function names come from the box's metadata API instead.
+
+Nothing has to be configured for this. When the connection node starts (and on every reconnect of its name sync) it
+asks the box `GET /api/meta/v1/version`; a CCU3, RaspberryMatic or OpenCCU answers 404 and the ReGaHSS path runs exactly
+as before, an openccu-lite answers with its API version and the node takes names, rooms and functions from there —
+loaded once as a snapshot and then kept current from the box's event stream, so a rename in the box's UI shows up in
+your flows within a second, without a redeploy. `msg.channelName`, `msg.rooms`, `msg.functions` and the room/function
+filters keep exactly the shape they have on a CCU. The same connection node configuration works on both, which is what
+makes moving a backup between the two harmless.
+
+**Credential.** Every metadata endpoint except the version probe needs a token:
+
+- Node-RED **on the box** (RedMatic): nothing to do — the box's own read-only token is read from
+  `/usr/local/etc/occulite/local-token`.
+- Node-RED **elsewhere** (a PC, a container): create a token on the box's _Users_ page and paste it into the
+  **openccu-lite token** field of the connection node. The **openccu-lite port** field next to it is only needed when
+  the box's web server is not on port 80 (443 with TLS).
+
+Without a token the nodes still work, with addresses instead of names: the connection logs the rejected credential once
+and picks the names up on the next retry, as soon as a valid token is there.
+
+**What has no replacement on openccu-lite** (from openccu-lite's own porting guide):
+
+- **System variables** and **programs**: there is no ReGa DOM. The `ccu-sysvar`, `ccu-program` and `ccu-poll` nodes stay
+  in the palette and in your flows — they are accepted, they never break the connection, and every message they get is
+  answered with a clear error instead.
+- **`exec()` of HM-Script** — `dom.GetObject`, `system.GetSessionVarStr` and everything else the `ccu-script` node
+  sends: gone, same handling as above.
+- **ReGa ids** (`dom.GetObject(1234)`): there are none. The metadata API identifies objects by
+  `<interface>.<address>`; these nodes have always keyed on the address, so nothing changes for flows.
+- **Service messages / alarms** (system variables 40 and 41): interface-level state only.
+- **The CCU WebUI's JSON-RPC API** (`/api/homematic.cgi`, `Session.login`, `Device.listAll`): not present.
+
+Rooms and functions are a **tree** on openccu-lite (`room/eg/wohnzimmer`), not a flat list. They are flattened to the
+arrays these nodes have always published, most specific first: a channel in _Wohnzimmer_ below _Erdgeschoss_ gets
+`msg.rooms = ["Wohnzimmer", "Erdgeschoss"]` and `msg.room = "Wohnzimmer"`, so a room filter on either name matches.
+
 ## Home Assistant
 
 The `ccu-homeassistant` node publishes
@@ -41,6 +83,35 @@ device with switch, light, cover, climate, binary_sensor, event, lock and sensor
 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).