node-red-contrib-knx-ultimate 5.2.1 → 5.2.3

package/CHANGELOG.md

@@ -6,16 +6,26 @@
 
 # CHANGELOG
 
-**Version 5.2.1** - July 2026<br/>
-
-- New **Matter Bridge (BETA)** node: exposes **KNX group addresses as Matter devices**. Alexa, Google Home, Apple Home (or any Matter controller) commission the bridge once — via QR code or 11-digit manual code shown right in the node editor — and see all your KNX devices with the names you typed, ready for app and voice control. It is the opposite direction of the Matter Device node introduced in 5.1.0.<br/>
-  - **17 virtual device types**: on/off light, dimmable light, **RGB color light** (DPT 232.600, converted to/from the Matter color wheel), **tunable white light** (color temperature in Kelvin, DPT 7.600), plug, cover/shutter (up/down, stop, position % with optional inversion), thermostat (current temperature + heating setpoint, both ways), **fan/ventilation** (speed %), sensors (temperature, humidity, illuminance, occupancy, contact), **smoke/CO alarm**, **water leak detector**, **air quality sensor** (CO2 ppm with automatic air-quality classification) and **robot vacuum** (flow-only: integrate your robot with any Node-RED node and expose it to the voice assistants).<br/>
-  - Bidirectional with loop protection: assistant commands write to the KNX *command* group addresses; telegrams on the *status* group addresses update the Matter attributes (and the apps). At startup the node can send a `GroupValue_Read` to every status GA so the Matter attributes are populated before the first app query.<br/>
-  - **Live device reconciliation**: the Matter server stays alive across re-deploys — added/renamed/removed devices appear on the paired controllers within seconds, without restarting Node-RED and without re-pairing.<br/>
-  - Optional **node Input/Output PINs**: the output forwards every controller command to the flow; the input updates the Matter state of a virtual device from flow messages (`msg.payload = { device, function, value }`). Devices without a command GA become flow-only devices.<br/>
-  - The **KNX gateway is optional**: without it the bridge runs in flow-only mode, useful to expose flow-computed or non-KNX devices to Alexa & Co.<br/>
-  - Multi-fabric: several controllers can be paired at the same time; the pairing panel lists them and a **Reset pairing** button decommissions everything. The bridge identity persists across re-deploys (no re-pairing needed).<br/>
-  - Devices editor with ETS group-address autocomplete filtered per function and per-type fields. Localized in EN/IT/DE/FR/ES/zh-CN.<br/>
+**Version 5.2.3** - July 2026<br/>
+
+- **MQTT / Home Assistant bridge — Entity name format**: new selector to reshape the names exposed to Home Assistant. The ETS import builds each name with the group-address path first (e.g. `(Lights->Ground floor) Living room`); now you can choose *As imported from ETS* (default), *Name first* (`Living room (Lights->Ground floor)`), *Name only* (`Living room`) or *Name + group address* (`Living room (0/1/2)`). Changing it only updates the friendly name (the `unique_id`/`object_id` stay stable, so existing entities are not duplicated).<br/>
+  - The group-address list in the editor now previews the chosen format **live**: pick a format and every row is re-labelled instantly, exactly as it will appear in Home Assistant, without reloading the list or losing the expose / read-only ticks.<br/>
+  - Entity names are sanitized before publishing: ASCII control characters are stripped and runs of whitespace collapsed (ETS exports sometimes lose an accented character and leave a double space, e.g. `Velocità vento` → `Velocit  vento`), and a name that would be empty falls back to the group address.<br/>
+- **Documentation**: node help and the online IoT-Bridge page updated for the new option in all six languages (EN/IT/DE/FR/ES/zh-CN).<br/>
+
+**Version 5.2.2** - July 2026<br/>
+
+- New **Matter Bridge (BETA)**: exposes **KNX group addresses as Matter devices**. Alexa, Google Home, Apple Home (or any Matter controller) commission the bridge once — via QR code or 11-digit manual code shown in the editor — and see all your KNX devices with the names you typed, ready for app and voice control. It is the opposite direction of the Matter Device node introduced in 5.1.0.<br/>
+  - Two-node architecture (like the HUE and Matter Controller integrations): a **Matter Bridge** configuration node is the bridge itself (holds the pairing, the QR code and the port), and a **Matter Bridge device** node is added per exposed device and points to it. Spread the device nodes across your flows, each with its own status — no giant list.<br/>
+  - **17 device types**: on/off light, dimmable light, **RGB color light** (DPT 232.600, converted to/from the Matter color wheel), **tunable white light** (color temperature in Kelvin, DPT 7.600), plug, cover/shutter (up/down, stop, position % with optional inversion), thermostat (current temperature + heating setpoint, both ways), **fan/ventilation** (speed %), sensors (temperature, humidity, illuminance, occupancy, contact), **smoke/CO alarm**, **water leak detector**, **air quality sensor** (CO2 ppm with automatic air-quality classification) and **robot vacuum** (flow-only: integrate your robot with any Node-RED node and expose it to the voice assistants).<br/>
+  - Bidirectional with loop protection: assistant commands write to the KNX *command* group addresses; telegrams on the *status* group addresses update the Matter attributes (and the apps). At startup each device node can send a `GroupValue_Read` to its status GAs so the Matter attributes are populated before the first app query.<br/>
+  - **Live device reconciliation**: the Matter server stays alive across re-deploys — added/renamed/removed device nodes appear on the paired controllers within seconds, without restarting Node-RED and without re-pairing.<br/>
+  - Optional **node Input/Output PINs**: the output forwards every controller command to the flow; the input updates the Matter state from flow messages (`msg.payload = { function, value }`). Devices without a command GA become flow-only devices.<br/>
+  - The **KNX gateway is optional** on the device node: without it the device runs in flow-only mode, useful to expose flow-computed or non-KNX devices to Alexa & Co.<br/>
+  - Multi-fabric: several controllers can be paired at the same time; the pairing panel lists them and a **Reset pairing** button decommissions everything. The bridge identity persists across re-deploys (no re-pairing needed). Each configuration node can use a different UDP port, so multiple independent bridges are possible.<br/>
+  - Editor with ETS group-address autocomplete filtered per function: the KNX gateway is resolved automatically (auto-selected when only one exists), so the address list is always available. Localized in EN/IT/DE/FR/ES/zh-CN.<br/>
+  - Note for early 5.2.x BETA testers: the two-node split changes the Matter identity of the bridge - remove the old bridge from your Matter app and pair the new configuration node once.<br/>
+- **Matter Device** node editor: the mappings list grows to fill the edit panel and has a native resize grip (bottom-right corner) to drag it to any height.<br/>
 - Matter integration hardening: try/catch protection on all critical paths (controller startup, client registration, structure queries, commissioning aftermath) so errors never crash Node-RED. Fixed the devices editor losing the configured group addresses on close/reopen (with automatic recovery of configurations saved by the affected versions).<br/>
 - **Documentation**: node help for the three Matter nodes in all six languages, new **Matter section** in the online docs sidebar with the Matter Controller, Matter Device and Matter Bridge pages (EN/IT/DE/FR/ES/zh-CN), the two new nodes on the homepage node list and the Matter logo alongside Home Assistant and MQTT.<br/>
 

package/nodes/commonFunctions.js

@@ -1006,15 +1006,15 @@ module.exports = (RED) => {
       }
     })
 
-    // MATTER BRIDGE: returns the pairing info (QR code, manual code, commissioned fabrics) of a bridge node
-    RED.httpAdmin.get('/KNXUltimateMatterBridgeInfo', RED.auth.needsPermission('knxUltimateMatterBridge.read'), (req, res) => {
+    // MATTER BRIDGE: returns the pairing info (QR code, manual code, commissioned fabrics) of a matterbridge-config node
+    RED.httpAdmin.get('/KNXUltimateMatterBridgeInfo', RED.auth.needsPermission('matterbridge-config.read'), (req, res) => {
       try {
-        const bridgeNode = RED.nodes.getNode(req.query.nodeId)
-        if (bridgeNode === null || bridgeNode === undefined || typeof bridgeNode.getBridgePairingInfo !== 'function') {
+        const bridgeConfig = RED.nodes.getNode(req.query.configId)
+        if (bridgeConfig === null || bridgeConfig === undefined || typeof bridgeConfig.getPairingInfo !== 'function') {
           res.json({ error: 'PLEASE DEPLOY FIRST: then try again.' })
           return
         }
-        res.json(bridgeNode.getBridgePairingInfo())
+        res.json(bridgeConfig.getPairingInfo())
       } catch (error) {
         RED.log.error(`Err KNXUltimateMatterBridgeInfo: ${error.message}`)
         res.json({ error: error.message })
@@ -1022,14 +1022,14 @@ module.exports = (RED) => {
     })
 
     // MATTER BRIDGE: factory reset (removes all paired controllers, restarts pairing advertising)
-    RED.httpAdmin.get('/KNXUltimateMatterBridgeReset', RED.auth.needsPermission('knxUltimateMatterBridge.write'), async (req, res) => {
+    RED.httpAdmin.get('/KNXUltimateMatterBridgeReset', RED.auth.needsPermission('matterbridge-config.write'), async (req, res) => {
       try {
-        const bridgeNode = RED.nodes.getNode(req.query.nodeId)
-        if (bridgeNode === null || bridgeNode === undefined || typeof bridgeNode.factoryResetBridge !== 'function') {
+        const bridgeConfig = RED.nodes.getNode(req.query.configId)
+        if (bridgeConfig === null || bridgeConfig === undefined || typeof bridgeConfig.factoryResetBridge !== 'function') {
           res.json({ error: 'PLEASE DEPLOY FIRST: then try again.' })
           return
         }
-        await bridgeNode.factoryResetBridge()
+        await bridgeConfig.factoryResetBridge()
         res.json({ status: 'ok' })
       } catch (error) {
         RED.log.error(`Err KNXUltimateMatterBridgeReset: ${error.message}`)

package/nodes/knxUltimateIoTBridge.html

@@ -12,7 +12,7 @@
             readOnDeploy: { value: true },
             acceptFlowInput: { value: true },
             mappings: { value: [] },
-            nodeMode: { value: 'iot' },
+            nodeMode: { value: 'homeassistant' },
             haBusMode: { value: 'standalone' },
             inputs: { value: 1 },
             outputs: { value: 2 },
@@ -20,6 +20,7 @@
             mqttBaseTopic: { value: 'knx-ultimate' },
             mqttDiscovery: { value: true },
             mqttDiscoveryPrefix: { value: 'homeassistant' },
+            mqttNameFormat: { value: 'full' },
             mqttCustomEntities: { value: [] },
             mqttExposedGAs: { value: [] },
             mqttReadOnlyGAs: { value: [] },
@@ -327,6 +328,41 @@
                 const readOnlySet = new Set(Array.isArray(node.mqttReadOnlyGAs) ? node.mqttReadOnlyGAs : []);
                 const exposeConfigured = node.mqttExposeConfigured === true;
 
+                // Mirror of formatEntityName() in lib/mqtt-bridge.js so the preview here matches
+                // exactly what gets published to Home Assistant (control chars stripped, whitespace
+                // collapsed, ETS path reshaped per the chosen format).
+                function sanitizeGaName(value) {
+                    return String(value == null ? '' : value)
+                        .replace(/[\u0000-\u001f\u007f]/g, ' ')
+                        .replace(/\s+/g, ' ')
+                        .trim();
+                }
+                function formatGaName(raw, ga, format) {
+                    const full = sanitizeGaName(raw);
+                    if (full === '') return ga;
+                    if (!format || format === 'full') return full;
+                    const m = full.match(/^\(([^)]*)\)\s*(.*)$/);
+                    const path = m ? m[1].trim() : '';
+                    const name = m ? (m[2].trim() || ga) : full;
+                    let result;
+                    switch (format) {
+                        case 'name-first': result = path ? (name + ' (' + path + ')') : name; break;
+                        case 'name-only': result = name; break;
+                        case 'name-ga': result = name + ' (' + ga + ')'; break;
+                        default: result = full;
+                    }
+                    return sanitizeGaName(result) || ga;
+                }
+                // Re-label every GA row from its stored raw name using the currently selected format.
+                function applyGaNameFormat() {
+                    const fmt = $('#node-input-mqttNameFormat').val() || 'full';
+                    $('#mqtt-ga-list .mqtt-ga-name').each(function () {
+                        const span = $(this);
+                        const text = formatGaName(span.data('raw'), span.data('ga'), fmt);
+                        span.text(text).attr('title', text);
+                    });
+                }
+
                 function updateGaCount() {
                     const total = $('#mqtt-ga-list input.mqtt-ga-cb').length;
                     const sel = $('#mqtt-ga-list input.mqtt-ga-cb:checked').length;
@@ -359,7 +395,9 @@
                             const cb = $('<input/>', { type: 'checkbox', class: 'mqtt-ga-cb', value: item.ga, style: 'width:auto; margin:0; flex:0 0 auto;' }).appendTo(row);
                             cb.prop('checked', exposeConfigured ? savedSet.has(item.ga) : true);
                             $('<span/>').css({ flex: '0 0 auto', fontFamily: 'monospace', minWidth: '64px' }).text(item.ga).appendTo(row);
-                            $('<span/>').css({ flex: '1 1 auto', minWidth: '0', overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap', color: '#444' }).attr('title', item.devicename || '').text(item.devicename || '').appendTo(row);
+                            // Keep the raw ETS name + GA on the element so applyGaNameFormat() can
+                            // re-label it live when the "Entity name format" select changes.
+                            $('<span/>').addClass('mqtt-ga-name').css({ flex: '1 1 auto', minWidth: '0', overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap', color: '#444' }).data('raw', item.devicename || '').data('ga', item.ga).appendTo(row);
                             $('<span/>').css({ flex: '0 0 auto', color: '#888', fontSize: '11px' }).text('DPT' + (item.dpt || '')).appendTo(row);
                             // Read-only toggle: expose the GA to HA but never accept commands back to KNX.
                             const roLabel = $('<label/>').css({ flex: '0 0 auto', display: 'flex', alignItems: 'center', gap: '3px', margin: '0', fontSize: '11px', color: '#888', cursor: 'pointer' }).appendTo(row);
@@ -374,6 +412,7 @@
                             });
                         });
                         $('#mqtt-ga-list input.mqtt-ga-cb').on('change', updateGaCount);
+                        applyGaNameFormat();
                         updateGaCount();
                     }).fail(function () {
                         list.empty().append($('<div/>').css('color', '#c0392b').text(node._('knxUltimateIoTBridge.ha.csv_error')));
@@ -395,6 +434,8 @@
 
                 buildGaList();
                 $('#node-input-server').on('change', buildGaList);
+                // Live-preview the entity naming: re-label the list when the format select changes.
+                $('#node-input-mqttNameFormat').on('change', applyGaNameFormat);
             } catch (error) { }
 
             // Home Assistant composite entities (cover / climate): editable list.
@@ -675,6 +716,19 @@
         <label for="node-input-mqttDiscoveryPrefix" data-i18n="knxUltimateIoTBridge.ha.discovery_prefix"></label>
         <input type="text" id="node-input-mqttDiscoveryPrefix" placeholder="homeassistant" />
     </div>
+    <div class="form-row ha-mode-row">
+        <label for="node-input-mqttNameFormat" data-i18n="knxUltimateIoTBridge.ha.name_format"></label>
+        <select id="node-input-mqttNameFormat" style="width:70%;">
+            <option value="full" data-i18n="knxUltimateIoTBridge.ha.name_format_full"></option>
+            <option value="name-first" data-i18n="knxUltimateIoTBridge.ha.name_format_name_first"></option>
+            <option value="name-only" data-i18n="knxUltimateIoTBridge.ha.name_format_name_only"></option>
+            <option value="name-ga" data-i18n="knxUltimateIoTBridge.ha.name_format_name_ga"></option>
+        </select>
+    </div>
+    <div class="form-row ha-mode-row" style="margin-top:-4px;">
+        <label style="width:auto;">&nbsp;</label>
+        <span style="font-size:11px; color:#888;" data-i18n="knxUltimateIoTBridge.ha.name_format_hint"></span>
+    </div>
     <div class="form-row ha-mode-row" id="rowMqttGaSelect">
         <label style="width:auto; font-weight:600;" data-i18n="knxUltimateIoTBridge.ha.exposed_gas"></label>
         <div style="margin:4px 0; display:flex; gap:6px; align-items:center;">
@@ -733,6 +787,9 @@ Native MQTT bridge with Home Assistant discovery. Every group address imported i
 
 Requires an MQTT broker reachable by both Node-RED and Home Assistant, with the MQTT integration enabled in HA. Entities appear under a device named after this node.
 
+### Entity name format
+The ETS import builds each name with the group-address path first, e.g. `(Lights->Ground floor) Living room`. The **Entity name format** selector controls how the Home Assistant entity names are built: *As imported from ETS* (default), *Name first* (`Living room (Lights->Ground floor)`), *Name only* (`Living room`) or *Name + group address* (`Living room (0/1/2)`).
+
 ### KNX bus connection
 Choose how the node exchanges telegrams with KNX:
 

package/nodes/knxUltimateIoTBridge.js

@@ -51,6 +51,9 @@ module.exports = function (RED) {
     node.mqttBaseTopic = typeof config.mqttBaseTopic === 'string' && config.mqttBaseTopic.trim() !== '' ? config.mqttBaseTopic.trim() : 'knx-ultimate'
     node.mqttDiscovery = config.mqttDiscovery !== false && config.mqttDiscovery !== 'false'
     node.mqttDiscoveryPrefix = typeof config.mqttDiscoveryPrefix === 'string' && config.mqttDiscoveryPrefix.trim() !== '' ? config.mqttDiscoveryPrefix.trim() : 'homeassistant'
+    // Entity name format for the exposed GAs: 'full' (ETS path + name, as imported),
+    // 'name-first' (name first, path after), 'name-only' (path removed), 'name-ga' (name + GA).
+    node.mqttNameFormat = typeof config.mqttNameFormat === 'string' && config.mqttNameFormat.trim() !== '' ? config.mqttNameFormat.trim() : 'full'
     node.mqttCustomEntities = Array.isArray(config.mqttCustomEntities) ? config.mqttCustomEntities : []
     // Group addresses to expose as simple entities. Once the user curates the list
     // (mqttExposeConfigured), only the listed GAs are exposed; otherwise all imported GAs are.
@@ -180,6 +183,7 @@ module.exports = function (RED) {
           baseTopic: node.mqttBaseTopic,
           discovery: node.mqttDiscovery,
           discoveryPrefix: node.mqttDiscoveryPrefix,
+          nameFormat: node.mqttNameFormat,
           username: node.credentials ? node.credentials.mqttUsername : undefined,
           password: node.credentials ? node.credentials.mqttPassword : undefined,
           groupAddresses: (node.serverKNX && Array.isArray(node.serverKNX.csv)) ? node.serverKNX.csv : [],