node-red-contrib-knx-ultimate 6.2.1 → 6.2.3-beta.0

package/CHANGELOG.md

@@ -6,6 +6,25 @@
 
 # CHANGELOG
 
+**Version 6.2.3-beta.0** - August 2026<br/>
+
+- **HUE Controller — unified Hue API v2 node**: added one controller node covering the complete set of existing Hue functions: lights and grouped lights, plugs, buttons, Tap dial, motion and camera motion, contacts, light level, temperature, humidity, scenes, battery, Zigbee connectivity and device software update. The compact device-function selector uses one third of the available width and opens the established dedicated editor with its localized labels; KNX mapping fields are hidden whenever no **KNX Gateway** is selected, including `none`, an empty value and **Add new...**. The YouTube tutorial playlist now appears once at the top of the editor, while inline `form-tips` are removed from the unified UI and their useful guidance remains in the multilingual help. A local paste-in migration tool converts a complete exported flow from the dedicated HUE node types to HUE Controller without inspecting or changing the open flow, preserving IDs, configuration references, properties, positions, wires and dynamic pin counts in the copyable JSON output. Because Node-RED excludes credentials from flow exports, same-instance migration now omits the referenced Hue and KNX config-node definitions by default while retaining their IDs, so the imported controllers reuse the existing configurations and their stored credentials; an explicit option keeps config nodes for cross-instance migration with a warning to re-enter credentials. Copying the converted flow now uses the asynchronous browser Clipboard API with a real selected-textarea fallback and selects the visible output for manual copying if the browser blocks both paths. Each profile executes the same mature runtime contract, preserving KNX telegram types, Hue event/status direction, flow pins and loop protection. Runtime implementations, editor definitions, templates and all six translation catalogs are embedded as package-internal HUE Controller profiles; registration order no longer matters, the KNX and Hue gateway fields remain real config-node selectors, and the controller has no runtime or editor dependency on deprecated node types. The original Hue Light node remains unchanged. Existing dedicated Hue nodes remain fully compatible and registered, use Node-RED's special `deprecated` category so they no longer appear in the palette, retain the lighter `#E7E9F6` color and `(deprecated)` canvas suffix without changing saved names, and show a localized HUE Controller migration notice at the top of their editors.<br/>
+- **HUE Controller — complete per-function help**: the established help of every dedicated Hue node is now incorporated under the corresponding HUE Controller function key, with an anchor index and automatic sidebar focus when the function changes. The same 15-section reference is included in the Controller wiki documentation in EN, IT, DE, FR, ES and zh-CN; legacy deprecation notices are deliberately excluded from the embedded copies.<br/>
+- **HUE Controller — legacy-independent maintenance boundary**: private runtime profiles and the private editor/template/translation sources are now the canonical implementation of HUE Controller. Its generator and consistency check read only those private sources and never inspect the frozen legacy nodes, so future Controller fixes remain isolated and the dedicated deprecated nodes can eventually be removed without breaking either runtime or UI. Added detailed architecture and lifecycle comments around runtime constructor capture, RED facades, editor mounting, profile drafts, dynamic pins, translations and the Hue Light bootstrap path.<br/>
+- **HUE Controller — consolidated documentation**: removed all dedicated legacy Hue nodes from the multilingual documentation home cards and HUE navigation, leaving only Hue Bridge configuration and HUE Controller. Reworked the Controller page in EN, IT, DE, FR, ES and zh-CN with a responsive visual overview, the complete 15-function capability map, common Controller behavior, a four-step setup path, optional-KNX guidance, migration details and the full per-function reference inherited from the former dedicated nodes.<br/>
+- **HUE Controller — visible migration action**: highlighted the legacy-flow migration button with a high-contrast orange treatment, darker hover/active states and an accessible keyboard focus ring so it is immediately recognizable in light and dark Node-RED editor themes.<br/>
+- **HUE Controller documentation routing**: added canonical Jekyll front matter and localized permalinks to every HUE Controller wiki page, fixing the GitHub Pages `404` and restoring correct links between EN, IT, DE, FR, ES and zh-CN.<br/>
+- **Matter documentation visual refresh**: redesigned the Matter Controller, Matter Bridge configuration and Expose KNX to Matter wiki introductions in EN, IT, DE, FR, ES and zh-CN. The responsive visual overviews now surface the controller lifecycle, commissioning and backup workflow, persistent multi-fabric bridge identity, live endpoint reconciliation, the complete 17-profile device map and concise setup paths while retaining the established technical reference below.<br/>
+- **HUE Controller — contextual migration action**: the highlighted legacy-flow migration button now appears in HUE Controller only when the Node-RED editor finds at least one registered legacy HUE node in the current flows, and the same orange action is available directly below the deprecation notice in every dedicated legacy HUE editor. All 15 legacy editors share one delegated dialog implementation and the canonical converter; the read-only Controller scan affects visibility only, while conversion remains isolated from editor state and processes exclusively the flow JSON pasted by the user.<br/>
+- **HUE Controller — light capability discovery**: fixed single lights losing their Dim, Tunable White, RGB/HSV and native-effects KNX sections while the embedded Light editor was bootstrapping. Capability discovery now resolves the persisted Hue Bridge configuration instead of Node-RED's temporary `_ADD_` selector sentinel, so Hue API v2 `dimming`, `color_temperature`, `color` and `effects` capabilities enable the corresponding mappings correctly. The legacy Hue Light node remains unchanged.<br/>
+- **HUE Controller — bounded Hue Bridge wait**: restored the Light editor's spinning-hourglass dialog while the selected Hue Bridge is still loading resources. Readiness is polled every 500 ms and the editor is always released after about 10 seconds with a localized error; Save, Cancel, Close and function changes cancel the timer. Removed the Controller wrapper overrides that had forced the wait icon hidden, and replaced the legacy global-`this` timer with strict-mode-safe private state. The legacy Hue Light node remains unchanged.<br/>
+- **HUE Controller — compact KNX rows**: reduced the DPT selector to 90–105 px and the Name field to 70–115 px within Controller mapping rows, keeping GA, DPT and Name on one line instead of wrapping on narrower editor trays. Rows are identified from their strict DPT field IDs after the private profile is mounted, so the scoped layout applies consistently without changing any frozen legacy template or persisted value.<br/>
+
+**Version 6.2.2** - July 2026<br/>
+
+- Bump KNX Engine to 6.0.2<br/>
+- **KNX AI — streamlined configuration and JavaScript chat editors**: removed the raw-hex, custom system-prompt, documentation-toggle, telegram-type and anomaly/pattern controls from the node editor. KNX AI now always listens to GroupValue Read/Response/Write, initializes pattern/anomaly analysis with its established defaults, excludes raw hex from prompts and always includes relevant documentation context. The chat input/output mappings now use the same color-coded JavaScript editors as KNXUltimate (green input and yellow output), including safe save/cancel lifecycle handling; **No adapter** is the default and keeps both editors hidden. All editor `form-tips` were removed, and model refresh now uses only a rotating button icon while loading instead of reporting the number of models found. Missing numeric settings now receive their established defaults instead of invalidating older nodes; this includes 120 minutes for the open threshold, 360 minutes for repeat cooldown and 256 KB for home memory. The KNX gateway is the only editor field that remains mandatory.<br/>
+
 **Version 6.2.1** - July 2026<br/>
 
 - **KNX AI — bounded proactive home intelligence**: added an opt-in **Proactive home & memory** section that derives a multilingual semantic model from ETS hierarchy, names, roles and DPTs and can proactively report reliably recognized covers, windows or doors left open beyond a configurable threshold. Notifications use output 3 with `msg.knxAi.type = "proactive_notification"`, retain the Telegram recipient through `msg.inputMessage`, obey quiet hours, a per-object cooldown and a maximum of three messages per hour, and never emit autonomous KNX commands on output 4. The LLM treats the user-only **AI Education** text as authoritative when deciding whether a candidate notification is useful; if Education cannot be evaluated, the notification is suppressed. A Markdown home reference is loaded at Node-RED startup, updated atomically and periodically, cleans stale temporary files, and is limited to 64–1,024 KB (256 KB by default), 120 significant observations, 80 aggregate habits, 80 notification records and 300 semantic ETS objects; older low-priority entries are pruned before the hard file limit can be exceeded. The direct Telegram example demonstrates the bounded memory and proactive settings.<br/>
@@ -54,13 +73,13 @@
 - **Matter nodes — distinct canvas icons**: Matter Controller and Matter Bridge nodes now use separate compact icons, with `mat` above a large right/left direction arrow, making the two integration directions immediately distinguishable in the palette, workspace and configuration selectors.<br/>
 - **Matter Controller/Bridge — protocol version and portable storage backups**: the Node-RED startup version line now logs the implemented Matter protocol revision (Matter 1.5.1, separately from the matter.js package version). Both Matter configuration editors can export and import a per-instance JSON backup containing the complete persistent Matter storage required to preserve fabrics, private credentials, sessions and commissioned/paired nodes. Import atomically replaces only the selected instance and restarts its engine; backup files contain secrets and must be protected like passwords.<br/>
 - **Homepage — KNX integration engines, MQTT and Matter overview**: the integration-logo heading and Supported technologies section now identify the KNX integration engines and include dedicated MQTT and Matter cards in all six languages (EN/IT/DE/FR/ES/zh-CN), highlighting MQTT/Home Assistant discovery and the bidirectional Matter Controller/Bridge integration for controlling Matter devices and exposing KNX objects to Matter. The feature-request/enterprise-support solicitation, standalone changelog promotion and donation section have been removed.<br/>
-- **Expose KNX to Matter (BETA) — dedup for duplicate Alexa light commands**: same Alexa quirk as the covers below, on lights: a single "turn on" / "set to 50%" voice request could arrive as up to two *identical* cluster commands (two `On`, or `MoveToLevelWithOnOff` + `MoveToLevel` with the same level), making the node emit duplicate raw msgs on `OnOffLightDevice`/`DimmableLightDevice` ([discussion #516](https://github.com/Supergiovane/node-red-contrib-knx-ultimate/discussions/516)). A short leading-edge dedup now forwards the first command immediately (no added latency — lights react instantly) and drops only a command identical to the one just emitted for the same function within the window; any change of value (a real On→Off, or a different brightness) always passes through at once, so genuine commands are never swallowed. The window is exposed in the node's **Advanced** tab as *Alexa duplicate-command window* (default 1.2s, **0 = disabled/raw**), the same approach the Home Assistant Matter Hub adopted for this Alexa behavior. The complementary *ignore brightness after On* option (already present) covers Alexa's other habit of sending a brightness right after On.<br/>
+- **Expose KNX to Matter (BETA) — dedup for duplicate Alexa light commands**: same Alexa quirk as the covers below, on lights: a single "turn on" / "set to 50%" voice request could arrive as up to two _identical_ cluster commands (two `On`, or `MoveToLevelWithOnOff` + `MoveToLevel` with the same level), making the node emit duplicate raw msgs on `OnOffLightDevice`/`DimmableLightDevice` ([discussion #516](https://github.com/Supergiovane/node-red-contrib-knx-ultimate/discussions/516)). A short leading-edge dedup now forwards the first command immediately (no added latency — lights react instantly) and drops only a command identical to the one just emitted for the same function within the window; any change of value (a real On→Off, or a different brightness) always passes through at once, so genuine commands are never swallowed. The window is exposed in the node's **Advanced** tab as _Alexa duplicate-command window_ (default 1.2s, **0 = disabled/raw**), the same approach the Home Assistant Matter Hub adopted for this Alexa behavior. The complementary _ignore brightness after On_ option (already present) covers Alexa's other habit of sending a brightness right after On.<br/>
 - **Expose KNX to Matter (BETA) — Home Assistant Matter Hub-style cover compatibility**: `WindowCovering` now exposes **Swap Open / Close** and **Cover slider debounce** in the Advanced tab. Swap reverses the binary KNX Up/Down command and percentage direction symmetrically for Alexa installations that interpret them backwards. Debounce collapses rapid `GoToLiftPercentage` targets into the last KNX command; `0` uses the adaptive Home Assistant Matter Hub windows (400ms first command / 150ms subsequent commands), while `1`–`5000` selects a fixed per-cover window. `StopMotion` remains immediate and cancels every pending movement. Help HTML and Matter Bridge docs were updated in EN/IT/DE/FR/ES/zh-CN.<br/>
-- **Expose KNX to Matter (BETA) — cover "arrived" safety net**: in *Wait for KNX status* mode, if no KNX status telegram confirms the exact requested position within a generous window (45s), the node now falls back to reflecting the requested position to Matter anyway. Without this, a real actuator that never reports back the *exact* requested percentage (positioning tolerance/drift) could leave the Matter device reporting "still moving" forever, since matter.js only clears `OperationalStatus` on an exact match.<br/>
+- **Expose KNX to Matter (BETA) — cover "arrived" safety net**: in _Wait for KNX status_ mode, if no KNX status telegram confirms the exact requested position within a generous window (45s), the node now falls back to reflecting the requested position to Matter anyway. Without this, a real actuator that never reports back the _exact_ requested percentage (positioning tolerance/drift) could leave the Matter device reporting "still moving" forever, since matter.js only clears `OperationalStatus` on an exact match.<br/>
 - **Expose KNX to Matter (BETA) — raw color commands**: RGB and tunable-white lights now capture color commands at the same "raw" command boundary already used for On/Off, dimming and covers - a repeated color command (e.g. the same color sent twice) is forwarded on the node's optional output PIN every time, not just on the first. Only possible for ColorControl because it is command-based (`MoveToHue`, `MoveToSaturation`, `MoveToHueAndSaturation`, `MoveToColor`, `MoveToColorTemperature`); Thermostat setpoints and Fan speed remain attribute-write only in the Matter spec, so they still report only on actual value changes - there is no lower-level hook matter.js exposes for those.<br/>
 - **Expose KNX to Matter (BETA) — fixed WindowCovering percentage commands**: `GoToLiftPercentage` commands (e.g. "Alexa, set the cover to 50%") were being misread as plain Open/Close commands, discarding the requested percentage. matter.js always resolves the command's `direction` parameter to a concrete Open/Close before calling our handler — it is not a usable signal — while `targetPercent100ths` is always populated. The node now classifies purely on the target position (0/10000 → Up/Down GA, anything else → Position GA), fixing intermediate cover positions from any Matter controller. Thanks to [@till69](https://github.com/till69) for tracing this down in [discussion #516](https://github.com/Supergiovane/node-red-contrib-knx-ultimate/discussions/516).<br/>
 - **Expose KNX to Matter (BETA) — removed the "Expose as dimmable light" Alexa workaround**: now that the actual cause of Alexa's broken cover percentages is fixed (see above), the v6.0.3 workaround that exposed covers as dimmable lights is no longer needed and has been removed, including its editor checkbox. **Breaking for the small number of BETA users who enabled it**: existing flows with the option turned on simply revert to a normal Matter Window Covering device on next deploy - you may need to remove/re-add the accessory in your controller's app.<br/>
-- **Expose KNX to Matter (BETA) — heating/cooling thermostats**: the bridged Thermostat can now expose a **Cooling setpoint** in addition to the existing heating one. Add a *Cooling setpoint command/status GA* on the device to automatically upgrade the Matter endpoint to a dual-mode (Heat/Cool) thermostat; leaving it empty keeps the previous heating-only behavior unchanged. Mode (Heat/Cool) switches from the controller are accepted but not yet mirrored back to KNX.<br/>
+- **Expose KNX to Matter (BETA) — heating/cooling thermostats**: the bridged Thermostat can now expose a **Cooling setpoint** in addition to the existing heating one. Add a _Cooling setpoint command/status GA_ on the device to automatically upgrade the Matter endpoint to a dual-mode (Heat/Cool) thermostat; leaving it empty keeps the previous heating-only behavior unchanged. Mode (Heat/Cool) switches from the controller are accepted but not yet mirrored back to KNX.<br/>
 - **Expose KNX to Matter (BETA) — stable per-device identity**: bridged devices now also set the optional `UniqueID` of `BridgedDeviceBasicInformation` (matching the existing serial number), improving cross-reset device identity for controllers that rely on it (e.g. Apple Home) alongside the endpoint number.<br/>
 - **Matter Bridge/Controller — safer shared storage initialization**: the `storage.path` write on the process-wide matter.js `Environment.default`, followed by the `ServerNode`/`CommissioningController` creation, is now serialized through a small FIFO lock (`matterEnvironmentLock.mjs`) shared by both engines, removing a theoretical race between a concurrently starting Matter Bridge and Matter Controller.<br/>
 
@@ -148,7 +167,7 @@
 **Version 5.0.1** - June 2026<br/>
 
 - **IoT Bridge** node (renamed **MQTT - IoT** in the UI): new **MQTT / Home Assistant (native)** mode selectable via a _Mode_ dropdown. In this mode the node connects directly to an MQTT broker and bridges KNX ↔ MQTT both ways, publishing **Home Assistant MQTT Discovery** so KNX appears automatically in Home Assistant (no `mqtt in`/`mqtt out` wiring needed). The classic IoT bridge mode is unchanged.<br/>
-  - Every group address imported in the KNX gateway (ETS list) can be **exposed automatically** as a Home Assistant entity (switch, sensor, binary_sensor, number, text), typed from its DPT. A checkbox list with filter and _Select all / none_ lets you choose exactly which GAs to publish.<br/>
+  - Every group address imported in the KNX gateway (ETS list) can be **exposed automatically** as a Home Assistant entity (switch, sensor, binary*sensor, number, text), typed from its DPT. A checkbox list with filter and \_Select all / none* lets you choose exactly which GAs to publish.<br/>
   - New **Covers & Thermostats** editor: composite entities that aggregate several GAs (cover with up/down, stop and position including KNX↔HA position inversion; thermostat with current temperature, setpoint and optional on/off). The cover/thermostat GA fields have **ETS group-address autocomplete**, like the KNX device node.<br/>
   - Robust lifecycle: the MQTT broker is closed gracefully on deploy / Node-RED exit (retained `offline`, forced disconnect, hard-capped so a slow or unreachable broker never blocks a deploy); all MQTT event handlers are fully guarded.<br/>
   - Editor help and online docs updated, plus Home Assistant / MQTT logos on the docs pages. Localized in EN/IT/DE/FR/ES/zh-CN.<br/>