node-red-contrib-ccu 3.4.2 → 4.0.0

package/.prettierignore

@@ -0,0 +1,10 @@
+node_modules
+coverage
+package-lock.json
+paramsets.json
+nodes/**/*.html
+nodes/locales
+nodes/ccu-switch.js
+tools/paramsets-join.js
+test/simulator-data
+docs

package/.prettierrc

@@ -0,0 +1,14 @@
+{
+    "tabWidth": 4,
+    "singleQuote": true,
+    "bracketSpacing": false,
+    "printWidth": 120,
+    "overrides": [
+        {
+            "files": ["*.json", "*.yml", "*.yaml", "*.md"],
+            "options": {
+                "tabWidth": 2
+            }
+        }
+    ]
+}

package/AGENTS.md

@@ -0,0 +1,96 @@
+# 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).

package/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+Notable changes to node-red-contrib-ccu. Format follows
+[Keep a Changelog](https://keepachangelog.com/); entries describe the
+user-visible symptom and the cause, not the commit list (the release notes
+append commits automatically).
+
+## 4.0.0 (2026-09-02)
+
+### Breaking
+
+- Requires Node.js >= 20 and Node-RED >= 4.0 (previously Node 10 /
+  Node-RED 1.0). The primary supported target is Node-RED 5 on Node 24.
+  Flows and node configurations are unchanged — existing flows import as
+  before.
+
+### Added
+
+- Importable example flows (`examples/`, shown in the editor's import
+  dialog): switching a datapoint, receiving RPC events, reading and
+  setting a system variable.
+- CCU-Jack can be enabled as an additional interface on the connection
+  node (XMLRPC on port 2121, or 2122 with TLS; port configurable). CCU
+  discovery now probes for CCU-Jack as well. Based on PR #162, closes
+  #164.
+
+### Changed
+
+- `homematic-rega` 1.5 -> 2.0 and `homematic-xmlrpc` 1.0 -> 2.0. This
+  removes the long-deprecated `request` package and the fragile
+  xmlbuilder GitHub-tarball reference from the dependency tree; ReGa
+  timestamps are now converted inside the library, and the "uncertain
+  value" detection (ReGa reporting 1970-01-01) works on the timestamp
+  itself instead of a locale-dependent string compare. Requires Node
+  20.19+/22.12+ (`require(esm)`).
+- Runtime dependencies reduced from 10 to 4: the deprecated
+  `string-similarity` package was replaced by an internal implementation
+  with identical results, `hm-discover`, `nextport` and `buffer-base62`
+  were vendored (the latter two rewritten without their abandoned
+  transitive dependencies), the `promise.prototype.finally` polyfill
+  (a no-op since Node 10) was dropped, and `obj-ease` moved to
+  devDependencies. Fewer install warnings, smaller install. (#176)
+- Tooling modernized: ESLint 9 + Prettier replace xo, c8 replaces
+  nyc/coveralls, mocha 11 and node-red-node-test-helper 0.3.6 run the
+  test suite against Node-RED 4.x, GitHub Actions CI covers Node
+  20/22/24 x Node-RED 4/5, releases publish to npm via OIDC trusted
+  publishing with provenance.
+
+### Fixed
+
+- Node-RED no longer crashes when the CCU connection drops at an
+  unfortunate moment: binrpc 3.3.2 adds the missing socket error
+  listener (a response arriving after a timeout killed the whole
+  process) and stops the methodCall callback from firing twice on
+  failed connections. (#160)
+- The value node no longer writes to the CCU when the incoming message
+  has no `payload` (previously `undefined` was passed to setValue).
+  From PR #173.
+- On Node-RED 4.x, node configuration dialogs had to be opened several
+  times before the interface/device/channel/datapoint selects populated.
+  The editor now triggers the initial load itself instead of relying on
+  a change event Node-RED 4 no longer fires reliably, retries when the
+  config node is not yet available in the runtime, and no longer wedges
+  itself when the request fails or the config node is still unsaved.
+- Removed 46 debug `console.log` statements that the node configuration
+  dialogs wrote to the browser console.

package/README.md

@@ -1,35 +1,32 @@
 # node-red-contrib-ccu
 
-[![NPM version](https://badge.fury.io/js/node-red-contrib-ccu.svg)](http://badge.fury.io/js/node-red-contrib-ccu)
-[![Dependencies Status](https://david-dm.org/rdmtc/node-red-contrib-ccu/status.svg)](https://david-dm.org/rdmtc/node-red-contrib-ccu)
-[![Build Status](https://travis-ci.org/rdmtc/node-red-contrib-ccu.svg?branch=master)](https://travis-ci.org/rdmtc/node-red-contrib-ccu)
-[![Coverage Status](https://coveralls.io/repos/github/rdmtc/node-red-contrib-ccu/badge.svg?branch=master)](https://coveralls.io/github/rdmtc/node-red-contrib-ccu?branch=master)
-[![XO code style](https://img.shields.io/badge/code_style-XO-5ed9c7.svg)](https://github.com/sindresorhus/xo)
+[![NPM version](https://img.shields.io/npm/v/node-red-contrib-ccu.svg)](https://www.npmjs.com/package/node-red-contrib-ccu)
+[![CI](https://github.com/rdmtc/node-red-contrib-ccu/actions/workflows/ci.yml/badge.svg)](https://github.com/rdmtc/node-red-contrib-ccu/actions/workflows/ci.yml)
 [![License][mit-badge]][mit-url]
 
 > Node-RED Nodes for the Homematic CCU
 
-With these Nodes you can connect [Homematic](https://github.com/hobbyquaker/awesome-homematic) and 
-[Node-RED](https://nodered.org/). Homematic is a series of smart home automation hardware from the manufacturer 
+With these Nodes you can connect [Homematic](https://github.com/hobbyquaker/awesome-homematic) and
+[Node-RED](https://nodered.org/). Homematic is a series of smart home automation hardware from the manufacturer
 [eQ-3](http://www.eq-3.de/), popular especially in Germany.
 
-**⚠️ node-red-contrib-ccu >= 3.0 needs Node-RED >= 1.0.** If you're still on Node-RED 0.20 or lower you should use the 
-latest 2.x version of node-red-contrib-ccu.
+**⚠️ node-red-contrib-ccu >= 4.0 needs Node-RED >= 4.0 and Node.js >= 20** (primary target: Node-RED 5 on Node 24).
+On older Node-RED versions use the latest 3.x release of node-red-contrib-ccu.
 
-For the communication with the CCU both RPC and ReGaHSS remote script are used. It's possible to connect to multiple 
+For the communication with the CCU both RPC and ReGaHSS remote script are used. It's possible to connect to multiple
 CCUs from one Node-RED instance. RPC setValue calls can be comfortably complemented with ON_TIME and RAMP_TIME values
-and special nodes ease the control of displays and mp3 actuators. RPC events can be filtered comprehensively (even 
-through regular expressions and also by rooms and functions). It's possible to start rega-programs and set 
+and special nodes ease the control of displays and mp3 actuators. RPC events can be filtered comprehensively (even
+through regular expressions and also by rooms and functions). It's possible to start rega-programs and set
 rega-variables and last but not least there are nodes to execute arbitrary rega-scripts and RPC calls.
 
-These nodes are included in [RedMatic](https://github.com/rdmtc/RedMatic) which ships Node-RED as an addon package 
+These nodes are included in [RedMatic](https://github.com/rdmtc/RedMatic) which ships Node-RED as an addon package
 for installation on a Homematic CCU3 or RaspberryMatic.
 
 Some example flows can be found in the [RedMatic Wiki](https://github.com/rdmtc/RedMatic/wiki) (German language).
 
-__A modern Browser is required, Internet Explorer won't work.__
+**A modern Browser is required, Internet Explorer won't work.**
 
-__Starting with Version 3.x these Nodes need Node-RED >= 1.0 to work correctly__
+**Starting with Version 3.x these Nodes need Node-RED >= 1.0 to work correctly**
 
 ## Configuration Examples
 
@@ -37,13 +34,13 @@ The communication with the Homematic CCU needs independent connections in two di
 
 ### NAT'd network
 
-If Node-RED/node-red-contrib-ccu runs inside a Container or a VM with NAT'd network it's necessary to forward/expose the ports for connections _from_ the CCU _to_ node-red-contrib-ccu's callback listeners (example below for a Docker container: use options `-p 2048:2048 -p 2049:2049`in the docker run command). 
+If Node-RED/node-red-contrib-ccu runs inside a Container or a VM with NAT'd network it's necessary to forward/expose the ports for connections _from_ the CCU _to_ node-red-contrib-ccu's callback listeners (example below for a Docker container: use options `-p 2048:2048 -p 2049:2049`in the docker run command).
 
 ![schema-docker](docs/schema-docker.png)
 
 ![ccu-config-docker](docs/ccu-config-docker.png)
 
-The config option `Init address`will be used to tell the CCU on which Address node-red-contrib-ccu is reachable. As 172.17.0.20 is not reachable for the CCU the Hosts IP Address and port forwarding/exposal has to be used. As `Listen address` setting also `0.0.0.0` (which tells node-red-contrib-ccu to bind it's listeners to all available interfaces) would be possible. 
+The config option `Init address`will be used to tell the CCU on which Address node-red-contrib-ccu is reachable. As 172.17.0.20 is not reachable for the CCU the Hosts IP Address and port forwarding/exposal has to be used. As `Listen address` setting also `0.0.0.0` (which tells node-red-contrib-ccu to bind it's listeners to all available interfaces) would be possible.
 
 ### piVCCU
 
@@ -68,10 +65,9 @@ This will require two individual configuration nodes, in which the respective co
 
 ![schema-multiCCU](docs/schema-multiCCU.png)
 
- - `Listen address` typically is the same for both Configurations as it is determined by the host that is running Node-RED
- - `BINRPC listening port` and `XMLRPC listening port` need to be different across the two configurations. One configuration can use the defaults (2048/tcp and 2049/tcp), the other needs to use two new ports. node-red-contrib-ccu will make a proposal, but this can be modified, e.g. if the proposed ports are already used.
- - The examples for [NAT'd network](#NAT'd-network), [piVCCU](#piVCCU) and [debmatic](#debmatic) will apply likewise for multiple CCUs. This means, for running Node-RED within a docker, all BINRPC and XMLRPC ports must be forwarded, e.g. `-p 2048:2048 -p 2049:2049 -p 2061:2061 -p 2062:2062`
-
+- `Listen address` typically is the same for both Configurations as it is determined by the host that is running Node-RED
+- `BINRPC listening port` and `XMLRPC listening port` need to be different across the two configurations. One configuration can use the defaults (2048/tcp and 2049/tcp), the other needs to use two new ports. node-red-contrib-ccu will make a proposal, but this can be modified, e.g. if the proposed ports are already used.
+- The examples for [NAT'd network](#NAT'd-network), [piVCCU](#piVCCU) and [debmatic](#debmatic) will apply likewise for multiple CCUs. This means, for running Node-RED within a docker, all BINRPC and XMLRPC ports must be forwarded, e.g. `-p 2048:2048 -p 2049:2049 -p 2061:2061 -p 2062:2062`
 
 ## License