node-red-contrib-knx-ultimate 5.0.4 → 5.2.2

package/CHANGELOG.md

@@ -6,6 +6,30 @@
 
 # CHANGELOG
 
+**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/>
+
+**Version 5.1.0** - July 2026<br/>
+
+- New **Matter integration (BETA)**: control any commissioned **Matter device** from the KNX bus and track its states on KNX group addresses.<br/>
+  - New **Matter Controller** configuration node: a full Matter controller with its own fabric (based on [matter.js](https://github.com/project-chip/matter.js)). Pair devices directly from the editor using the 11-digit manual pairing code or the QR code content (`MT:...`); commissioning works over the IP network (WiFi/Ethernet or Thread via border router). The commissioned devices list shows name, product, node ID and connection state, with one-click unpair. Fabric credentials are stored under `knxultimatestorage/matter` in the Node-RED user directory.<br/>
+  - New **Matter Device (BETA)** node: pick a paired Matter device and map KNX group addresses to its functions with a dynamic mapping list. The function list is **human friendly**: it shows only the functions the device really exposes, with plain-language localized names (e.g. *"On/Off switch"*, *"Instantaneous power (W)"*, *"Room temperature (°C)"*) and the current value in brackets, instead of raw Matter cluster/attribute names. Friendly endpoint names for 34 common device types (smart plug, dimmable light, cover, thermostat, sensors...).<br/>
+  - Mappings are bidirectional: **KNX → Matter** (commands/attribute writes, e.g. GA 1/1/1 DPT 1.001 → OnOff) and **Matter → KNX** (attribute changes written to the GA; `GroupValue_Read` requests answered from the cache). Automatic value conversion for the common clusters: OnOff, LevelControl (0-254 ↔ %), WindowCovering (percent100ths ↔ %, up/down), ColorControl (mireds ↔ Kelvin), Thermostat and temperature/humidity sensors (centi-units ↔ units), illuminance (log scale ↔ Lux), battery (half-percent ↔ %), power/energy metering (mW ↔ W, mWh ↔ kWh), door lock, occupancy and contact sensors.<br/>
+  - Selecting a function pre-fills the **suggested KNX DPT** and the GA name; the group address field has the usual **ETS autocomplete**. Optional node input/output pins for raw Matter access from the flow. Editor and help localized in EN/IT/DE/FR/ES/zh-CN.<br/>
+
 **Version 5.0.4** - July 2026<br/>
 
 - **IoT Bridge** node, **Covers & Thermostats** editor: fixed the group-address autocomplete, which suggested only DPT **1.x** addresses in every field. Each field now filters by the datapoint it expects: cover **Set/Status position** GAs list DPT **5.x** (5.001), and the thermostat **Current temperature** and **Setpoint set/status** GAs list DPT **9.x** (9.001). Up/Down, Stop and On/Off keep their 1.x filter.<br/>

package/nodes/commonFunctions.js

@@ -944,6 +944,99 @@ module.exports = (RED) => {
       }
     })
 
+    // MATTER: returns the list of commissioned Matter devices of a matter-config node
+    RED.httpAdmin.get('/KNXUltimateMatterGetNodes', RED.auth.needsPermission('matter-config.read'), (req, res) => {
+      try {
+        const matterServer = RED.nodes.getNode(req.query.serverId)
+        if (matterServer === null || matterServer === undefined) {
+          res.json({ error: 'PLEASE DEPLOY FIRST: then try again.' })
+          return
+        }
+        res.json({ devices: matterServer.getCommissionedNodesDetails() })
+      } catch (error) {
+        RED.log.error(`Err KNXUltimateMatterGetNodes: ${error.message}`)
+        res.json({ error: error.message })
+      }
+    })
+
+    // MATTER: returns endpoints/clusters/attributes/commands of a commissioned Matter device
+    RED.httpAdmin.get('/KNXUltimateMatterGetStructure', RED.auth.needsPermission('matter-config.read'), (req, res) => {
+      try {
+        const matterServer = RED.nodes.getNode(req.query.serverId)
+        if (matterServer === null || matterServer === undefined) {
+          res.json({ error: 'PLEASE DEPLOY FIRST: then try again.' })
+          return
+        }
+        res.json(matterServer.getNodeStructure(req.query.nodeId))
+      } catch (error) {
+        RED.log.error(`Err KNXUltimateMatterGetStructure: ${error.message}`)
+        res.json({ error: error.message })
+      }
+    })
+
+    // MATTER: commissions (pairs) a new Matter device using a pairing code or QR code string
+    RED.httpAdmin.get('/KNXUltimateMatterPair', RED.auth.needsPermission('matter-config.write'), async (req, res) => {
+      try {
+        const matterServer = RED.nodes.getNode(req.query.serverId)
+        if (matterServer === null || matterServer === undefined) {
+          res.json({ error: 'PLEASE DEPLOY FIRST: then try again.' })
+          return
+        }
+        const nodeId = await matterServer.commission(req.query.code)
+        res.json({ nodeId })
+      } catch (error) {
+        RED.log.error(`Err KNXUltimateMatterPair: ${error.message}`)
+        res.json({ error: error.message })
+      }
+    })
+
+    // MATTER: decommissions (unpairs) a Matter device
+    RED.httpAdmin.get('/KNXUltimateMatterUnpair', RED.auth.needsPermission('matter-config.write'), async (req, res) => {
+      try {
+        const matterServer = RED.nodes.getNode(req.query.serverId)
+        if (matterServer === null || matterServer === undefined) {
+          res.json({ error: 'PLEASE DEPLOY FIRST: then try again.' })
+          return
+        }
+        await matterServer.removeCommissionedNode(req.query.nodeId)
+        res.json({ status: 'ok' })
+      } catch (error) {
+        RED.log.error(`Err KNXUltimateMatterUnpair: ${error.message}`)
+        res.json({ error: error.message })
+      }
+    })
+
+    // 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 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(bridgeConfig.getPairingInfo())
+      } catch (error) {
+        RED.log.error(`Err KNXUltimateMatterBridgeInfo: ${error.message}`)
+        res.json({ error: error.message })
+      }
+    })
+
+    // MATTER BRIDGE: factory reset (removes all paired controllers, restarts pairing advertising)
+    RED.httpAdmin.get('/KNXUltimateMatterBridgeReset', RED.auth.needsPermission('matterbridge-config.write'), async (req, res) => {
+      try {
+        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 bridgeConfig.factoryResetBridge()
+        res.json({ status: 'ok' })
+      } catch (error) {
+        RED.log.error(`Err KNXUltimateMatterBridgeReset: ${error.message}`)
+        res.json({ error: error.message })
+      }
+    })
+
     RED.httpAdmin.get('/knxUltimateDpts', (req, res) => {
       try {
         const dpts = Object.entries(dptlib.dpts).filter(onlyDptKeys).map(extractBaseNo).sort(sortBy('base'))

package/nodes/icons/node-matter-icon.svg

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="40" height="60" viewBox="0 0 40 60" xmlns="http://www.w3.org/2000/svg">
+    <g fill="#ffffff" stroke="none">
+        <circle cx="20" cy="30" r="4.5"/>
+        <g id="matterArrow">
+            <rect x="18.4" y="9" width="3.2" height="11"/>
+            <path d="M 14.5 18.5 L 25.5 18.5 L 20 25.5 Z"/>
+        </g>
+        <use href="#matterArrow" transform="rotate(120 20 30)"/>
+        <use href="#matterArrow" transform="rotate(240 20 30)"/>
+    </g>
+</svg>

package/nodes/knxUltimateMatterBridge.html

@@ -0,0 +1,342 @@
+<script type="text/javascript" src="resources/node-red-contrib-knx-ultimate/11f26b4500.js"></script>
+<script type="text/javascript" src="resources/node-red-contrib-knx-ultimate/htmlUtils.js"></script>
+
+<script type="text/javascript">
+    (function () {
+        // GA fields of each virtual device type.
+        // dir 'command' = Matter -> KNX (GA written on assistant commands), 'status' = KNX -> Matter.
+        const TYPE_FIELDS = {
+            onofflight: [
+                { key: 'OnOff', labelKey: 'fn_onoff_cmd', dptPrefix: '1.', fallbackDpt: '1.001' },
+                { key: 'OnOffStatus', labelKey: 'fn_onoff_status', dptPrefix: '1.', fallbackDpt: '1.001' }
+            ],
+            onoffplug: [
+                { key: 'OnOff', labelKey: 'fn_onoff_cmd', dptPrefix: '1.', fallbackDpt: '1.001' },
+                { key: 'OnOffStatus', labelKey: 'fn_onoff_status', dptPrefix: '1.', fallbackDpt: '1.001' }
+            ],
+            dimmablelight: [
+                { key: 'OnOff', labelKey: 'fn_onoff_cmd', dptPrefix: '1.', fallbackDpt: '1.001' },
+                { key: 'OnOffStatus', labelKey: 'fn_onoff_status', dptPrefix: '1.', fallbackDpt: '1.001' },
+                { key: 'Level', labelKey: 'fn_level_cmd', dptPrefix: '5.', fallbackDpt: '5.001' },
+                { key: 'LevelStatus', labelKey: 'fn_level_status', dptPrefix: '5.', fallbackDpt: '5.001' }
+            ],
+            rgblight: [
+                { key: 'OnOff', labelKey: 'fn_onoff_cmd', dptPrefix: '1.', fallbackDpt: '1.001' },
+                { key: 'OnOffStatus', labelKey: 'fn_onoff_status', dptPrefix: '1.', fallbackDpt: '1.001' },
+                { key: 'Level', labelKey: 'fn_level_cmd', dptPrefix: '5.', fallbackDpt: '5.001' },
+                { key: 'LevelStatus', labelKey: 'fn_level_status', dptPrefix: '5.', fallbackDpt: '5.001' },
+                { key: 'RGB', labelKey: 'fn_rgb_cmd', dptPrefix: '232.', fallbackDpt: '232.600' },
+                { key: 'RGBStatus', labelKey: 'fn_rgb_status', dptPrefix: '232.', fallbackDpt: '232.600' }
+            ],
+            colortemperaturelight: [
+                { key: 'OnOff', labelKey: 'fn_onoff_cmd', dptPrefix: '1.', fallbackDpt: '1.001' },
+                { key: 'OnOffStatus', labelKey: 'fn_onoff_status', dptPrefix: '1.', fallbackDpt: '1.001' },
+                { key: 'Level', labelKey: 'fn_level_cmd', dptPrefix: '5.', fallbackDpt: '5.001' },
+                { key: 'LevelStatus', labelKey: 'fn_level_status', dptPrefix: '5.', fallbackDpt: '5.001' },
+                { key: 'CT', labelKey: 'fn_ct_cmd', dptPrefix: '7.', fallbackDpt: '7.600' },
+                { key: 'CTStatus', labelKey: 'fn_ct_status', dptPrefix: '7.', fallbackDpt: '7.600' }
+            ],
+            temperaturesensor: [{ key: 'Status', labelKey: 'fn_sensor_ga', dptPrefix: '9.', fallbackDpt: '9.001' }],
+            humiditysensor: [{ key: 'Status', labelKey: 'fn_sensor_ga', dptPrefix: '9.', fallbackDpt: '9.007' }],
+            lightsensor: [{ key: 'Status', labelKey: 'fn_sensor_ga', dptPrefix: '9.', fallbackDpt: '9.004' }],
+            occupancysensor: [{ key: 'Status', labelKey: 'fn_sensor_ga', dptPrefix: '1.', fallbackDpt: '1.011' }],
+            contactsensor: [{ key: 'Status', labelKey: 'fn_sensor_ga', dptPrefix: '1.', fallbackDpt: '1.002' }],
+            windowcovering: [
+                { key: 'UpDown', labelKey: 'fn_updown', dptPrefix: '1.', fallbackDpt: '1.008' },
+                { key: 'Stop', labelKey: 'fn_stop', dptPrefix: '1.', fallbackDpt: '1.017' },
+                { key: 'Position', labelKey: 'fn_position_cmd', dptPrefix: '5.', fallbackDpt: '5.001' },
+                { key: 'PositionStatus', labelKey: 'fn_position_status', dptPrefix: '5.', fallbackDpt: '5.001' }
+            ],
+            thermostat: [
+                { key: 'CurrentTemp', labelKey: 'fn_currenttemp', dptPrefix: '9.', fallbackDpt: '9.001' },
+                { key: 'Setpoint', labelKey: 'fn_setpoint_cmd', dptPrefix: '9.', fallbackDpt: '9.001' },
+                { key: 'SetpointStatus', labelKey: 'fn_setpoint_status', dptPrefix: '9.', fallbackDpt: '9.001' }
+            ],
+            smokecoalarm: [
+                { key: 'Smoke', labelKey: 'fn_smoke_ga', dptPrefix: '1.', fallbackDpt: '1.005' },
+                { key: 'CO', labelKey: 'fn_co_ga', dptPrefix: '1.', fallbackDpt: '1.005' }
+            ],
+            waterleakdetector: [{ key: 'Status', labelKey: 'fn_leak_ga', dptPrefix: '1.', fallbackDpt: '1.005' }],
+            airqualitysensor: [{ key: 'Status', labelKey: 'fn_co2_ga', dptPrefix: '9.', fallbackDpt: '9.008' }],
+            fan: [
+                { key: 'FanSpeed', labelKey: 'fn_fanspeed_cmd', dptPrefix: '5.', fallbackDpt: '5.001' },
+                { key: 'FanSpeedStatus', labelKey: 'fn_fanspeed_status', dptPrefix: '5.', fallbackDpt: '5.001' }
+            ],
+            robotvacuum: [] // Flow-only: no GA fields, controlled via the node PINs
+        };
+        const TYPE_ORDER = ['onofflight', 'dimmablelight', 'rgblight', 'colortemperaturelight', 'onoffplug', 'windowcovering', 'thermostat', 'fan', 'temperaturesensor', 'humiditysensor', 'lightsensor', 'occupancysensor', 'contactsensor', 'smokecoalarm', 'waterleakdetector', 'airqualitysensor', 'robotvacuum'];
+
+        // Every GA/DPT key across all types, used to declare the node defaults.
+        const ALL_KEYS = [];
+        Object.keys(TYPE_FIELDS).forEach((t) => TYPE_FIELDS[t].forEach((f) => { if (ALL_KEYS.indexOf(f.key) === -1) ALL_KEYS.push(f.key); }));
+        const gaDefaults = {
+            server: { type: 'knxUltimate-config', required: false },
+            serverMatterBridge: { type: 'matterbridge-config', required: true },
+            name: { value: '' },
+            deviceType: { value: 'onofflight' },
+            invertPosition: { value: false },
+            readStatusAtStartup: { value: 'yes' },
+            enableNodePINS: { value: 'no' },
+            outputs: { value: 0 },
+            inputs: { value: 0 }
+        };
+        ALL_KEYS.forEach((key) => {
+            gaDefaults['ga' + key] = { value: '' };
+            gaDefaults['dpt' + key] = { value: '' };
+        });
+
+        RED.nodes.registerType('knxUltimateMatterBridge', {
+            category: 'KNX Ultimate Matter',
+            color: '#D7C7E9',
+            defaults: gaDefaults,
+            inputs: 0,
+            outputs: 0,
+            icon: 'node-matter-icon.svg',
+            label() {
+                return this.name || 'Matter Bridge device (BETA)';
+            },
+            paletteLabel: 'Matter Bridge device (BETA)',
+            oneditprepare() {
+                try { RED.sidebar.show('help'); } catch (error) { /* empty */ }
+                const node = this;
+
+                // Resolves the KNX gateway at query time: the selected one, or - as a
+                // fallback - the first knxUltimate-config available, so the GA list works
+                // even before the user picks the gateway on this device node.
+                const findKnxGateway = () => {
+                    let srv = null;
+                    try {
+                        const val = $('#node-input-server').val();
+                        if (val && val !== '_ADD_') srv = RED.nodes.node(val);
+                    } catch (error) { /* empty */ }
+                    if (!srv) {
+                        try {
+                            RED.nodes.eachConfig((c) => { if (!srv && c.type === 'knxUltimate-config') srv = c; });
+                        } catch (error) { /* empty */ }
+                    }
+                    return srv;
+                };
+
+                // Auto-select the KNX gateway when there is only one, sparing the user a click per device node
+                try {
+                    const cur = $('#node-input-server').val();
+                    if (!cur || cur === '_ADD_') {
+                        const gws = [];
+                        RED.nodes.eachConfig((c) => { if (c.type === 'knxUltimate-config') gws.push(c); });
+                        if (gws.length === 1) $('#node-input-server').val(gws[0].id).trigger('change');
+                    }
+                } catch (error) { /* empty */ }
+
+                // Device type dropdown
+                const $type = $('#node-input-deviceType');
+                TYPE_ORDER.forEach((t) => {
+                    $type.append($('<option></option>').attr('value', t).text(node._('knxUltimateMatterBridge.types.' + t)));
+                });
+                $type.val(node.deviceType || 'onofflight');
+
+                // Compact "list" layout: a small gray caption above each input, fields wrapping
+                // on one or more rows (same pattern used across the rest of the KNX-Ultimate nodes).
+                const $fields = $('#mb-ga-fields').css({ display: 'flex', flexWrap: 'wrap', alignItems: 'flex-end', gap: '10px' });
+                const $invertRow = $('#mb-invert-row');
+                const gaInputs = {};
+
+                function createLabeledField(row, element, options = {}) {
+                    const wrapper = $('<div/>', {
+                        style: 'display:flex; flex-direction:column; margin-bottom:8px;'
+                    }).appendTo(row);
+                    if (options.width) wrapper.css('width', options.width);
+                    const $labelSpan = $('<span/>', {
+                        style: 'font-size:11px; color:#666; margin-bottom:2px; white-space:nowrap;'
+                    }).appendTo(wrapper);
+                    element.css('width', '100%');
+                    element.appendTo(wrapper);
+                    return { wrapper, $labelSpan };
+                }
+
+                function attachGaAutocomplete($ga, $dpt, fieldDef) {
+                    $ga.autocomplete({
+                        minLength: 0,
+                        source(request, response) {
+                            const gw = findKnxGateway();
+                            if (!gw) { response([]); return; }
+                            $.getJSON(`knxUltimatecsv?nodeID=${gw.id}`, (data) => {
+                                response($.map(data, (value) => {
+                                    const search = `${value.ga} (${value.devicename}) DPT${value.dpt}`;
+                                    if (htmlUtilsfullCSVSearch(search, `${request.term} ${fieldDef.dptPrefix}`)) {
+                                        return { label: `${value.ga} # ${value.devicename} # ${value.dpt}`, value: value.ga, dpt: value.dpt };
+                                    }
+                                    return null;
+                                }));
+                            });
+                        },
+                        select(event, ui) { $dpt.val(ui.item.dpt || fieldDef.fallbackDpt); }
+                    });
+                    $ga.on('focus.knxUltimateMatterBridge click.knxUltimateMatterBridge', function () {
+                        try { $(this).autocomplete('search', ''); } catch (error) { /* empty */ }
+                    });
+                    try {
+                        const gw = findKnxGateway();
+                        if (gw && gw.id) KNX_enableSecureFormatting($ga, gw.id);
+                    } catch (error) { /* empty */ }
+                }
+
+                // Build one field per possible GA key; show only the ones of the selected type.
+                ALL_KEYS.forEach((key) => {
+                    const fieldDef = {};
+                    Object.keys(TYPE_FIELDS).forEach((t) => { const f = TYPE_FIELDS[t].find((x) => x.key === key); if (f) Object.assign(fieldDef, f); });
+                    const $ga = $('<input/>', { type: 'text', placeholder: '1/1/1' }).val(node['ga' + key] || '');
+                    const $dpt = $('<input/>', { type: 'hidden' }).val(node['dpt' + key] || '');
+                    const { wrapper, $labelSpan } = createLabeledField($fields, $ga, { width: '150px' });
+                    wrapper.append($dpt); // Kept alongside the GA input; never rendered.
+                    attachGaAutocomplete($ga, $dpt, fieldDef);
+                    // Keyed by field key (not DOM position), so save is robust regardless of layout.
+                    gaInputs[key] = { wrapper, $ga, $dpt, $labelSpan };
+                });
+
+                function updateTypePresentation() {
+                    const selected = $type.val();
+                    const active = TYPE_FIELDS[selected] || [];
+                    ALL_KEYS.forEach((key) => {
+                        const entry = gaInputs[key];
+                        const fieldForType = active.find((f) => f.key === key);
+                        if (fieldForType) {
+                            entry.wrapper.show();
+                            entry.$labelSpan.text(node._('knxUltimateMatterBridge.functions.' + fieldForType.labelKey));
+                        } else {
+                            entry.wrapper.hide();
+                        }
+                    });
+                    $invertRow.toggle(selected === 'windowcovering');
+                }
+                $type.on('change', updateTypePresentation);
+                updateTypePresentation();
+
+                // oneditsave reads the GA values straight from these references: no DOM
+                // position matching, so it cannot break if the layout changes again.
+                node._matterGaInputs = gaInputs;
+
+                $('#node-input-invertPosition').prop('checked', node.invertPosition === true);
+                $('#node-input-readStatusAtStartup').val(node.readStatusAtStartup || 'yes');
+                $('#node-input-enableNodePINS').val(node.enableNodePINS || 'no');
+            },
+            oneditsave() {
+                try { RED.sidebar.show('info'); } catch (error) { /* empty */ }
+                const node = this;
+                const selected = $('#node-input-deviceType').val();
+                node.deviceType = selected;
+                node.invertPosition = $('#node-input-invertPosition').is(':checked');
+                const active = TYPE_FIELDS[selected] || [];
+                const gaInputs = node._matterGaInputs || {};
+                // Clear every GA/DPT, then write only the ones of the selected type, reading
+                // straight from the field references built in oneditprepare (not DOM position).
+                ALL_KEYS.forEach((key) => {
+                    node['ga' + key] = '';
+                    node['dpt' + key] = '';
+                    const entry = gaInputs[key];
+                    if (!entry) return;
+                    const isActive = active.some((f) => f.key === key);
+                    const ga = (entry.$ga.val() || '').trim();
+                    if (isActive && ga !== '') {
+                        node['ga' + key] = ga;
+                        node['dpt' + key] = (entry.$dpt.val() || '').trim();
+                    }
+                });
+                delete node._matterGaInputs;
+                this.enableNodePINS = $('#node-input-enableNodePINS').val() || 'no';
+                this.outputs = this.enableNodePINS === 'yes' ? 1 : 0;
+                this.inputs = this.enableNodePINS === 'yes' ? 1 : 0;
+            },
+            oneditcancel() {
+                try { RED.sidebar.show('info'); } catch (error) { /* empty */ }
+                delete this._matterGaInputs;
+            }
+        });
+    }());
+</script>
+
+<script type="text/html" data-template-name="knxUltimateMatterBridge">
+  <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>
+
+  <div class="form-row">
+    <label for="node-input-server">
+      <img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAKnRFWHRDcmVhdGlvbiBUaW1lAEZyIDYgQXVnIDIwMTAgMjE6NTI6MTkgKzAxMDD84aS8AAAAB3RJTUUH3gYYCicNV+4WIQAAAAlwSFlzAAALEgAACxIB0t1+/AAAAARnQU1BAACxjwv8YQUAAACUSURBVHjaY2CgFZg5c+Z/ZEyWAZ8+f/6/ZsWs/xoamqMGkGrA6Wla/1+fVARjEBuGsSoGmY4eZSCNL59d/g8DIDbIAHR14OgFGQByKjIGKX5+6/T///8gGMQGiV1+/B0Fg70GIkD+RMYgxf/O5/7//2MSmAZhkBi6OrgB6Bg5DGB4ajr3f2xqsYYLSDE2THJUDg0AAAqyDVd4tp4YAAAAAElFTkSuQmCC" />
+      <span data-i18n="common.knx_gw"></span>
+    </label>
+    <input type="text" id="node-input-server">
+  </div>
+
+  <div class="form-row">
+    <label for="node-input-serverMatterBridge">
+      <i class="fa fa-share-alt"></i> <span data-i18n="knxUltimateMatterBridge.bridge"></span>
+    </label>
+    <input type="text" id="node-input-serverMatterBridge">
+  </div>
+
+  <div class="form-row">
+    <label for="node-input-name">
+      <i class="fa fa-tag"></i> <span data-i18n="knxUltimateMatterBridge.device_name"></span>
+    </label>
+    <input type="text" id="node-input-name" data-i18n="[placeholder]knxUltimateMatterBridge.fields.name_placeholder">
+  </div>
+
+  <div class="form-row">
+    <label for="node-input-deviceType">
+      <i class="fa fa-microchip"></i> <span data-i18n="knxUltimateMatterBridge.fields.type"></span>
+    </label>
+    <select id="node-input-deviceType" style="width:260px;"></select>
+  </div>
+
+  <div class="form-tips" style="margin-bottom:8px;">
+    <i class="fa fa-circle-info"></i>
+    <span data-i18n="knxUltimateMatterBridge.device_help"></span>
+  </div>
+
+  <div id="mb-ga-fields"></div>
+
+  <div class="form-row" id="mb-invert-row" style="display:none;">
+    <label for="node-input-invertPosition" style="width:auto;">
+      <input type="checkbox" id="node-input-invertPosition" style="width:auto; display:inline-block; vertical-align:middle;">
+      <span data-i18n="knxUltimateMatterBridge.fields.invert"></span>
+    </label>
+  </div>
+
+  <hr/>
+
+  <div class="form-row">
+    <label for="node-input-readStatusAtStartup" style="width:260px;">
+      <i class="fa fa-question-circle"></i> <span data-i18n="knxUltimateMatterBridge.read_status_startup"></span>
+    </label>
+    <select id="node-input-readStatusAtStartup" style="width:120px;">
+      <option value="yes" data-i18n="knxUltimateMatterBridge.opt_yes"></option>
+      <option value="no" data-i18n="knxUltimateMatterBridge.opt_no"></option>
+    </select>
+  </div>
+
+  <div class="form-row">
+    <label for="node-input-enableNodePINS" style="width:260px;">
+      <i class="fa fa-code"></i> <span data-i18n="knxUltimateMatterBridge.node_pins"></span>
+    </label>
+    <select id="node-input-enableNodePINS" style="width:220px;">
+      <option value="no" data-i18n="knxUltimateMatterBridge.node_pins_hide"></option>
+      <option value="yes" data-i18n="knxUltimateMatterBridge.node_pins_show"></option>
+    </select>
+  </div>
+</script>
+
+<script type="text/markdown" data-help-name="knxUltimateMatterBridge">
+Exposes **one KNX device as a Matter device**. This node is in **BETA**.
+
+Point it to a **Matter Bridge** configuration node (the actual bridge, paired once by Alexa/Google Home/Apple Home), pick the device type, give it the name the assistant will use, and fill the group addresses.
+
+- **Matter → KNX**: commands from the voice assistant write to the *command* group addresses.
+- **KNX → Matter**: telegrams on the *status* group addresses update the Matter attribute (and the app UI).
+
+The **KNX gateway is optional**: without it, enable the node PINs and drive the device from the flow.
+
+If you enable the **node PINs**:
+
+- input: `msg.payload = { function: "onoff", value: true }` updates the Matter state without the KNX bus
+- output: every command from a Matter controller is forwarded as `msg` (topic = device name, payload = value, `msg.matter` = raw command)
+</script>