node-red-contrib-knx-ultimate 6.2.2 → 6.2.3-beta.1

package/CHANGELOG.md

@@ -6,6 +6,20 @@
 
 # CHANGELOG
 
+**Version 6.2.3-beta.1** - 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 routine inline `form-tips` are removed from the unified UI and a compact migration privacy disclaimer remains directly below the conversion button. The migration action runs entirely inside the browser and changes only the legacy HUE nodes requiring conversion, preserving every existing property, config reference, group, position and link; no flow or node data leaves the editor and the workspace remains undeployed for user review. After a successful conversion, an editable email draft addressed to the author opens without navigating the top-level Node-RED page and contains only the converted-node count and space for optional notes, while the PayPal donation page opens in a new browser window without flow data in its URL; the user decides whether to send the email and nothing is sent automatically. 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 confirmation dialog with the original pale-yellow backup warning before the fully local conversion and a separate safety notice requiring users to inspect every modified HUE node—function, configuration references, pins and wiring—before Deploy. Locked or changed flows and local conversion errors leave the workspace untouched; successful conversion creates one undoable editor change, opens an editable usage email draft without navigating away from Node-RED plus the PayPal donation page in a new browser window, and never deploys or sends email automatically. When these steps finish, a fixed modal Node-RED success message remains visible until the user clicks **OK**.<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/>

package/nodes/knxUltimateAI.js

@@ -214,7 +214,12 @@ const buildKnxAiPackageNodeCatalog = () => {
         const inputsRaw = knxAiMatchAfter(objText, /\binputs\s*:\s*(\d+)/)
         const outputsRaw = knxAiMatchAfter(objText, /\boutputs\s*:\s*(\d+)/)
         let fields = {}
-        const defIdx = objText.search(/\bdefaults\s*:\s*\{/)
+        let defIdx = objText.search(/\bdefaults\s*:\s*\{/)
+        // Profile-driven editors may compose their full Node-RED defaults from
+        // already registered node definitions. They can expose a compact static
+        // catalogDefaults block so the backend Flow Builder still discovers
+        // configuration references and essential persisted fields.
+        if (defIdx < 0) defIdx = objText.search(/\bcatalogDefaults\s*:\s*\{/)
         if (defIdx >= 0) {
           const braceIdx = objText.indexOf('{', defIdx)
           const defaultsBlock = knxAiSliceBalanced(objText, braceIdx)
@@ -10074,6 +10079,7 @@ module.exports = function (RED) {
 }
 
 module.exports.__test = {
+  buildKnxAiPackageNodeCatalog,
   buildKnxAiConfirmationRequest,
   buildKnxAiUniversalMessage,
   classifyKnxAiConfirmation,

package/nodes/knxUltimateHueAreaMotion.html

@@ -375,8 +375,8 @@
     };
 
     RED.nodes.registerType('knxUltimateHueAreaMotion', {
-      category: 'KNX Ultimate HUE',
-      color: '#C0C7E9',
+      category: 'deprecated',
+      color: '#E7E9F6',
       defaults: {
         server: { type: 'knxUltimate-config', required: false },
         serverHue: { type: 'hue-config', required: true },
@@ -395,9 +395,9 @@
       outputs: 1,
       icon: 'node-hue-icon.svg',
       label() {
-        return this.name || RED._('node-red-contrib-knx-ultimate/knxUltimateHueAreaMotion:knxUltimateHueAreaMotion.paletteLabel');
+        return `${this.name || RED._('node-red-contrib-knx-ultimate/knxUltimateHueAreaMotion:knxUltimateHueAreaMotion.paletteLabel')} (deprecated)`;
       },
-      paletteLabel: 'Hue Motion Area',
+      paletteLabel: 'Hue Motion Area (deprecated)',
       oneditprepare() {
         try { RED.sidebar.show('help'); } catch (error) { /* empty */ }
         const node = this;
@@ -519,6 +519,16 @@
 </script>
 
 <script type="text/html" data-template-name="knxUltimateHueAreaMotion">
+  <div class="form-row hue-legacy-controller-notice" role="note" style="box-sizing:border-box; padding:10px 12px; margin-bottom:14px; border-left:4px solid #d79b00; background:#fff8df; color:#4d3a00;">
+    <i class="fa fa-exclamation-triangle" aria-hidden="true" style="color:#a15c00; margin-right:6px;"></i>
+    <span data-i18n="node-red-contrib-knx-ultimate/knxUltimateHueController:knxUltimateHueController.legacy_node_notice"></span>
+  </div>
+  <div class="form-row hue-legacy-migration-action" style="margin-top:-6px; margin-bottom:14px;">
+    <button type="button" class="red-ui-button hue-legacy-migrate-flow" style="background:#d97706; border-color:#b45309; color:#fff; font-weight:700;" data-i18n="[title]node-red-contrib-knx-ultimate/knxUltimateHueController:knxUltimateHueController.migration_button_title">
+      <i class="fa fa-exchange"></i> <span data-i18n="node-red-contrib-knx-ultimate/knxUltimateHueController:knxUltimateHueController.migration_button"></span>
+    </button>
+    <div class="form-tips hue-controller-migration-disclaimer" style="margin-top:8px;" data-i18n="node-red-contrib-knx-ultimate/knxUltimateHueController:knxUltimateHueController.migration_disclaimer"></div>
+  </div>
   <div class="form-row" style="margin-bottom:10px;">
     <span style="color:#ff0000"><i class="fa fa-youtube"></i></span>&nbsp;<a target="_blank" href="https://www.youtube.com/playlist?list=PL9Yh1bjbLAYrU8PsVhW4xzEug2WtVFv3E"><b>KNX-Ultimate video tutorials (YouTube playlist)</b></a>
   </div>
@@ -604,6 +614,8 @@
 
 
 <script type="text/markdown" data-help-name="knxUltimateHueAreaMotion">
+> **Deprecated:** This dedicated HUE node remains available for existing flows. Use **HUE Controller** for new work. The legacy node is marked `(deprecated)` in the palette and on the canvas, uses a lighter color than HUE Controller, and its editor opens with a migration notice.
+
 <p>The Hue Motion Area node listens to MotionAware area motion events (Hue Bridge Pro) and mirrors the aggregated detected/not-detected state to KNX or your Node-RED flow.</p>
 
 Start typing in the GA field (name or Group Address) to link the KNX GA; devices appear while you type.

package/nodes/knxUltimateHueBattery.html

@@ -359,8 +359,8 @@
     };
 
     RED.nodes.registerType('knxUltimateHueBattery', {
-      category: 'KNX Ultimate HUE',
-      color: '#C0C7E9',
+      category: 'deprecated',
+      color: '#E7E9F6',
       defaults: {
         server: { type: 'knxUltimate-config', required: false },
         serverHue: { type: 'hue-config', required: true },
@@ -377,9 +377,9 @@
       outputs: 1,
       icon: 'node-hue-icon.svg',
       label() {
-        return this.name || RED._('node-red-contrib-knx-ultimate/knxUltimateHueBattery:knxUltimateHueBattery.paletteLabel');
+        return `${this.name || RED._('node-red-contrib-knx-ultimate/knxUltimateHueBattery:knxUltimateHueBattery.paletteLabel')} (deprecated)`;
       },
-      paletteLabel: 'Hue Battery Sensor',
+      paletteLabel: 'Hue Battery Sensor (deprecated)',
       oneditprepare() {
         try { RED.sidebar.show('help'); } catch (error) { /* empty */ }
         const node = this;
@@ -498,6 +498,16 @@
 </script>
 
 <script type="text/html" data-template-name="knxUltimateHueBattery">
+  <div class="form-row hue-legacy-controller-notice" role="note" style="box-sizing:border-box; padding:10px 12px; margin-bottom:14px; border-left:4px solid #d79b00; background:#fff8df; color:#4d3a00;">
+    <i class="fa fa-exclamation-triangle" aria-hidden="true" style="color:#a15c00; margin-right:6px;"></i>
+    <span data-i18n="node-red-contrib-knx-ultimate/knxUltimateHueController:knxUltimateHueController.legacy_node_notice"></span>
+  </div>
+  <div class="form-row hue-legacy-migration-action" style="margin-top:-6px; margin-bottom:14px;">
+    <button type="button" class="red-ui-button hue-legacy-migrate-flow" style="background:#d97706; border-color:#b45309; color:#fff; font-weight:700;" data-i18n="[title]node-red-contrib-knx-ultimate/knxUltimateHueController:knxUltimateHueController.migration_button_title">
+      <i class="fa fa-exchange"></i> <span data-i18n="node-red-contrib-knx-ultimate/knxUltimateHueController:knxUltimateHueController.migration_button"></span>
+    </button>
+    <div class="form-tips hue-controller-migration-disclaimer" style="margin-top:8px;" data-i18n="node-red-contrib-knx-ultimate/knxUltimateHueController:knxUltimateHueController.migration_disclaimer"></div>
+  </div>
   <div class="form-row" style="margin-bottom:10px;">
     <span style="color:#ff0000"><i class="fa fa-youtube"></i></span>&nbsp;<a target="_blank" href="https://www.youtube.com/playlist?list=PL9Yh1bjbLAYrU8PsVhW4xzEug2WtVFv3E"><b>KNX-Ultimate video tutorials (YouTube playlist)</b></a>
   </div>
@@ -587,6 +597,8 @@
 
 
 <script type="text/markdown" data-help-name="knxUltimateHueBattery">
+> **Deprecated:** This dedicated HUE node remains available for existing flows. Use **HUE Controller** for new work. The legacy node is marked `(deprecated)` in the palette and on the canvas, uses a lighter color than HUE Controller, and its editor opens with a migration notice.
+
 <p>This node exposes the battery level of a Hue device to KNX and raises an event whenever the value changes.</p>
 
 Start typing the KNX device name or Group Address in the GA field; matching entries appear while you type. Use the refresh icon next to <q>Hue sensor</q> to reload the list from the Hue bridge after adding new devices.

package/nodes/knxUltimateHueButton.html

@@ -405,8 +405,8 @@
     };
 
     RED.nodes.registerType('knxUltimateHueButton', {
-      category: 'KNX Ultimate HUE',
-      color: '#C0C7E9',
+      category: 'deprecated',
+      color: '#E7E9F6',
       defaults: {
         server: { type: 'knxUltimate-config', required: false },
         serverHue: { type: 'hue-config', required: true },
@@ -429,9 +429,9 @@
       outputs: 1,
       icon: 'node-hue-icon.svg',
       label() {
-        return this.name || 'Hue Button';
+        return `${this.name || 'Hue Button'} (deprecated)`;
       },
-      paletteLabel: 'Hue Button',
+      paletteLabel: 'Hue Button (deprecated)',
       oneditprepare() {
         try { RED.sidebar.show('help'); } catch (error) { /* empty */ }
         const node = this;
@@ -616,6 +616,16 @@
 </script>
 
 <script type="text/html" data-template-name="knxUltimateHueButton">
+  <div class="form-row hue-legacy-controller-notice" role="note" style="box-sizing:border-box; padding:10px 12px; margin-bottom:14px; border-left:4px solid #d79b00; background:#fff8df; color:#4d3a00;">
+    <i class="fa fa-exclamation-triangle" aria-hidden="true" style="color:#a15c00; margin-right:6px;"></i>
+    <span data-i18n="node-red-contrib-knx-ultimate/knxUltimateHueController:knxUltimateHueController.legacy_node_notice"></span>
+  </div>
+  <div class="form-row hue-legacy-migration-action" style="margin-top:-6px; margin-bottom:14px;">
+    <button type="button" class="red-ui-button hue-legacy-migrate-flow" style="background:#d97706; border-color:#b45309; color:#fff; font-weight:700;" data-i18n="[title]node-red-contrib-knx-ultimate/knxUltimateHueController:knxUltimateHueController.migration_button_title">
+      <i class="fa fa-exchange"></i> <span data-i18n="node-red-contrib-knx-ultimate/knxUltimateHueController:knxUltimateHueController.migration_button"></span>
+    </button>
+    <div class="form-tips hue-controller-migration-disclaimer" style="margin-top:8px;" data-i18n="node-red-contrib-knx-ultimate/knxUltimateHueController:knxUltimateHueController.migration_disclaimer"></div>
+  </div>
   <div class="form-row" style="margin-bottom:10px;">
     <span style="color:#ff0000"><i class="fa fa-youtube"></i></span>&nbsp;<a target="_blank" href="https://www.youtube.com/playlist?list=PL9Yh1bjbLAYrU8PsVhW4xzEug2WtVFv3E"><b>KNX-Ultimate video tutorials (YouTube playlist)</b></a>
   </div>
@@ -730,6 +740,8 @@
 
 
 <script type="text/markdown" data-help-name="knxUltimateHueButton">
+> **Deprecated:** This dedicated HUE node remains available for existing flows. Use **HUE Controller** for new work. The legacy node is marked `(deprecated)` in the palette and on the canvas, uses a lighter color than HUE Controller, and its editor opens with a migration notice.
+
 <p>The Hue Button node maps Hue button events to KNX group addresses and exposes the same events on its flow output via <code>button.button_report.event</code>.</p>
 
 Start typing in the GA field (name or Group Address) to link the KNX GA; devices appear while you type.

package/nodes/knxUltimateHueCameraMotion.html

@@ -376,8 +376,8 @@
     };
 
     RED.nodes.registerType('knxUltimateHueCameraMotion', {
-      category: 'KNX Ultimate HUE',
-      color: '#C0C7E9',
+      category: 'deprecated',
+      color: '#E7E9F6',
       defaults: {
         server: { type: 'knxUltimate-config', required: false },
         serverHue: { type: 'hue-config', required: true },
@@ -396,9 +396,9 @@
       outputs: 1,
       icon: 'node-hue-icon.svg',
       label() {
-        return this.name || 'Hue Camera Motion';
+        return `${this.name || 'Hue Camera Motion'} (deprecated)`;
       },
-      paletteLabel: 'Hue Camera Motion',
+      paletteLabel: 'Hue Camera Motion (deprecated)',
       oneditprepare() {
         try { RED.sidebar.show('help'); } catch (error) { /* empty */ }
         const node = this;
@@ -529,6 +529,16 @@
 </script>
 
 <script type="text/html" data-template-name="knxUltimateHueCameraMotion">
+  <div class="form-row hue-legacy-controller-notice" role="note" style="box-sizing:border-box; padding:10px 12px; margin-bottom:14px; border-left:4px solid #d79b00; background:#fff8df; color:#4d3a00;">
+    <i class="fa fa-exclamation-triangle" aria-hidden="true" style="color:#a15c00; margin-right:6px;"></i>
+    <span data-i18n="node-red-contrib-knx-ultimate/knxUltimateHueController:knxUltimateHueController.legacy_node_notice"></span>
+  </div>
+  <div class="form-row hue-legacy-migration-action" style="margin-top:-6px; margin-bottom:14px;">
+    <button type="button" class="red-ui-button hue-legacy-migrate-flow" style="background:#d97706; border-color:#b45309; color:#fff; font-weight:700;" data-i18n="[title]node-red-contrib-knx-ultimate/knxUltimateHueController:knxUltimateHueController.migration_button_title">
+      <i class="fa fa-exchange"></i> <span data-i18n="node-red-contrib-knx-ultimate/knxUltimateHueController:knxUltimateHueController.migration_button"></span>
+    </button>
+    <div class="form-tips hue-controller-migration-disclaimer" style="margin-top:8px;" data-i18n="node-red-contrib-knx-ultimate/knxUltimateHueController:knxUltimateHueController.migration_disclaimer"></div>
+  </div>
   <div class="form-row" style="margin-bottom:10px;">
     <span style="color:#ff0000"><i class="fa fa-youtube"></i></span>&nbsp;<a target="_blank" href="https://www.youtube.com/playlist?list=PL9Yh1bjbLAYrU8PsVhW4xzEug2WtVFv3E"><b>KNX-Ultimate video tutorials (YouTube playlist)</b></a>
   </div>
@@ -613,6 +623,8 @@
 </script>
 
 <script type="text/markdown" data-help-name="knxUltimateHueCameraMotion">
+> **Deprecated:** This dedicated HUE node remains available for existing flows. Use **HUE Controller** for new work. The legacy node is marked `(deprecated)` in the palette and on the canvas, uses a lighter color than HUE Controller, and its editor opens with a migration notice.
+
 <p>This node listens to motion events reported by a Philips Hue camera and mirrors them to KNX.</p>
 
 Start typing in the GA field (name or Group Address) to link the KNX GA; devices appear while you type.

package/nodes/knxUltimateHueContactSensor.html

@@ -357,8 +357,8 @@
     };
 
     RED.nodes.registerType('knxUltimateHueContactSensor', {
-      category: 'KNX Ultimate HUE',
-      color: '#C0C7E9',
+      category: 'deprecated',
+      color: '#E7E9F6',
       defaults: {
         server: { type: 'knxUltimate-config', required: false },
         serverHue: { type: 'hue-config', required: true },
@@ -372,9 +372,9 @@
       outputs: 1,
       icon: 'node-hue-icon.svg',
       label() {
-        return this.name || 'Hue Contact Sensor';
+        return `${this.name || 'Hue Contact Sensor'} (deprecated)`;
       },
-      paletteLabel: 'Hue Contact Sensor',
+      paletteLabel: 'Hue Contact Sensor (deprecated)',
       oneditprepare() {
         try { RED.sidebar.show('help'); } catch (error) { /* empty */ }
         const node = this;
@@ -489,6 +489,16 @@
 </script>
 
 <script type="text/html" data-template-name="knxUltimateHueContactSensor">
+  <div class="form-row hue-legacy-controller-notice" role="note" style="box-sizing:border-box; padding:10px 12px; margin-bottom:14px; border-left:4px solid #d79b00; background:#fff8df; color:#4d3a00;">
+    <i class="fa fa-exclamation-triangle" aria-hidden="true" style="color:#a15c00; margin-right:6px;"></i>
+    <span data-i18n="node-red-contrib-knx-ultimate/knxUltimateHueController:knxUltimateHueController.legacy_node_notice"></span>
+  </div>
+  <div class="form-row hue-legacy-migration-action" style="margin-top:-6px; margin-bottom:14px;">
+    <button type="button" class="red-ui-button hue-legacy-migrate-flow" style="background:#d97706; border-color:#b45309; color:#fff; font-weight:700;" data-i18n="[title]node-red-contrib-knx-ultimate/knxUltimateHueController:knxUltimateHueController.migration_button_title">
+      <i class="fa fa-exchange"></i> <span data-i18n="node-red-contrib-knx-ultimate/knxUltimateHueController:knxUltimateHueController.migration_button"></span>
+    </button>
+    <div class="form-tips hue-controller-migration-disclaimer" style="margin-top:8px;" data-i18n="node-red-contrib-knx-ultimate/knxUltimateHueController:knxUltimateHueController.migration_disclaimer"></div>
+  </div>
   <div class="form-row" style="margin-bottom:10px;">
     <span style="color:#ff0000"><i class="fa fa-youtube"></i></span>&nbsp;<a target="_blank" href="https://www.youtube.com/playlist?list=PL9Yh1bjbLAYrU8PsVhW4xzEug2WtVFv3E"><b>KNX-Ultimate video tutorials (YouTube playlist)</b></a>
   </div>
@@ -552,6 +562,8 @@
 
 
 <script type="text/markdown" data-help-name="knxUltimateHueContactSensor">
+> **Deprecated:** This dedicated HUE node remains available for existing flows. Use **HUE Controller** for new work. The legacy node is marked `(deprecated)` in the palette and on the canvas, uses a lighter color than HUE Controller, and its editor opens with a migration notice.
+
 <p>This node forwards events from a Hue contact sensor and maps them to KNX group addresses.</p>
 
 Start typing in the GA field, the name or group address of your KNX device, the avaiable devices start showing up while you're typing.