node-red-contrib-knx-ultimate 6.0.5 → 6.0.7

package/CHANGELOG.md

@@ -6,8 +6,14 @@
 
 # CHANGELOG
 
-**Version 6.0.5** - July 2026<br/>
-
+**Version 6.0.7** - July 2026<br/>
+
+- **Control Matter from KNX (BETA) — Door Lock support**: commissioned Door Lock endpoints (including locks bridged by a vendor Matter hub) are now detected from their real `0x0101` cluster and expose KNX DPT 1 command/status mappings. `true` invokes `lockDoor`, `false` invokes `unlockDoor`, and subscribed `lockState` feedback updates KNX without command reflection. `NotFullyLocked` and `Unlatched` remain explicit flow states and are never collapsed into an unsafe binary KNX value. The optional remote-operation PIN is stored as a Node-RED credential; endpoints that do not advertise a requested command are rejected instead of receiving an invented operation. This is the first controller-side device profile in the extensible profile architecture requested in [discussion #519](https://github.com/Supergiovane/node-red-contrib-knx-ultimate/discussions/519).<br/>
+- **Control Matter from KNX (BETA) — multi-purpose endpoint profiles**: the controller node now keeps its established light path unchanged while routing non-light endpoints through a separate capability-driven mapped profile. Selecting a plug/On-Off actuator, cover, thermostat, fan, environmental/contact/occupancy sensor, battery, electrical-power or energy endpoint builds only the KNX mappings backed by clusters, attributes and supported commands actually reported by that endpoint. These mappings now live inside a dedicated **Mappings** tab beside **Behaviour**, matching the established light editor layout. Each mapping can be disabled by leaving its GA empty; cached status supports KNX read responses and startup publication, attribute reports never reflect commands back to Matter, and cluster events remain available on the optional flow output. Saved mappings survive an untouched editor save even when the Matter endpoint is temporarily offline.<br/>
+- **Matter nodes — cleaner editors**: long pairing, storage, cache and endpoint-structure explanations were removed from the Matter node forms and consolidated in the localized HTML help, keeping the editors focused on fields, actions and live operational status.<br/>
+- **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) — 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/>

package/README.md

@@ -6,7 +6,7 @@
 
 ## The most popular KNX node for Node-RED
 
-KNX Ultimate is the most advanced KNX integration for Node-RED, providing secure KNX/IP communication, routing, ETS project import, Philips Hue, Matter, MQTT, diagnostics, virtual devices, and powerful automation nodes. Build professional, reliable, and scalable smart home and building automation projects with minimal effort.
+KNX Ultimate is the most advanced KNX integration for Node-RED, providing secure KNX/IP communication, routing, ETS project import, Philips Hue, Matter Controller and Matter Bridge (control matter device via KNX and expose KNX GA via Matter), MQTT, diagnostics, virtual devices, and powerful automation nodes. Build professional, reliable, and scalable smart home and building automation projects with minimal effort.
 
 <br/>
 <br/>

package/nodes/commonFunctions.js

@@ -1043,6 +1043,36 @@ module.exports = (RED) => {
       }
     })
 
+    const exportMatterStorage = async (req, res, idKey) => {
+      try {
+        const configNode = RED.nodes.getNode(req.query[idKey])
+        if (!configNode || typeof configNode.exportMatterStorage !== 'function') throw new Error('PLEASE DEPLOY FIRST: then try again.')
+        const backup = await configNode.exportMatterStorage()
+        const stamp = new Date().toISOString().replace(/[:.]/g, '-')
+        res.setHeader('Content-Type', 'application/json; charset=utf-8')
+        res.setHeader('Content-Disposition', `attachment; filename="knx-ultimate-matter-${backup.kind}-${stamp}.json"`)
+        res.send(JSON.stringify(backup, null, 2))
+      } catch (error) {
+        RED.log.error(`Err Matter storage export: ${error.message}`)
+        if (!res.headersSent) res.status(500).json({ error: error.message })
+      }
+    }
+
+    const importMatterStorage = async (req, res, idKey) => {
+      try {
+        const configNode = RED.nodes.getNode(req.query[idKey])
+        if (!configNode || typeof configNode.importMatterStorage !== 'function') throw new Error('PLEASE DEPLOY FIRST: then try again.')
+        await configNode.importMatterStorage(req.body)
+        res.json({ status: 'ok' })
+      } catch (error) {
+        RED.log.error(`Err Matter storage import: ${error.message}`)
+        res.status(400).json({ error: error.message })
+      }
+    }
+
+    RED.httpAdmin.get('/KNXUltimateMatterStorageExport', normalizeAuthFromAccessTokenQuery, RED.auth.needsPermission('matter-config.read'), (req, res) => exportMatterStorage(req, res, 'serverId'))
+    RED.httpAdmin.post('/KNXUltimateMatterStorageImport', RED.auth.needsPermission('matter-config.write'), (req, res) => importMatterStorage(req, res, 'serverId'))
+
     // 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 {
@@ -1074,6 +1104,9 @@ module.exports = (RED) => {
       }
     })
 
+    RED.httpAdmin.get('/KNXUltimateMatterBridgeStorageExport', normalizeAuthFromAccessTokenQuery, RED.auth.needsPermission('matterbridge-config.read'), (req, res) => exportMatterStorage(req, res, 'configId'))
+    RED.httpAdmin.post('/KNXUltimateMatterBridgeStorageImport', RED.auth.needsPermission('matterbridge-config.write'), (req, res) => importMatterStorage(req, res, 'configId'))
+
     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-bridge-icon.svg

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="40" height="60" viewBox="0 0 40 60" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="Matter Bridge">
+  <text x="20" y="21" fill="#ffffff" text-anchor="middle" font-family="Arial, sans-serif" font-size="20" font-weight="700" textLength="38" lengthAdjust="spacingAndGlyphs">mat</text>
+  <path d="M 37 34 H 12 V 29 L 2 38 L 12 47 V 42 H 25"
+    fill="none" stroke="#ffffff" stroke-width="2.6" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

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

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg width="40" height="60" viewBox="0 0 40 60" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="Matter Controller">
+  <text x="20" y="21" fill="#ffffff" text-anchor="middle" font-family="Arial, sans-serif" font-size="20" font-weight="700" textLength="38" lengthAdjust="spacingAndGlyphs">mat</text>
+  <path d="M 3 34 H 28 V 29 L 38 38 L 28 47 V 42 H 15"
+    fill="none" stroke="#ffffff" stroke-width="2.6" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/nodes/knxUltimate-config.js

@@ -29,6 +29,10 @@ let NODE_VERSION = 'unknown'
 try { NODE_VERSION = require('../package.json').version } catch (e) { /* empty */ }
 let KNX_ENGINE_VERSION = 'unknown'
 try { KNX_ENGINE_VERSION = require('knxultimate/package.json').version } catch (e) { /* empty */ }
+let MATTER_PACKAGE_VERSION = 'unknown'
+let Specification = { REVISION: 'unknown' }
+try { MATTER_PACKAGE_VERSION = require('@matter/main').version } catch (e) { /* empty */ }
+try { Specification = require('@matter/model').Specification } catch (e) { /* empty */ }
 
 // DATAPONT MANIPULATION HELPERS
 // ####################
@@ -193,7 +197,7 @@ const findAutoEthernetInterface = (targetIP) => {
 module.exports = (RED) => {
   // Log node and KNXUltimate engine versions once, at Node-RED startup.
   try {
-    RED.log.info(`KNXUltimate: node-red-contrib-knx-ultimate v${NODE_VERSION} (KNXUltimate engine v${KNX_ENGINE_VERSION})`)
+    RED.log.info(`KNXUltimate: node-red-contrib-knx-ultimate v${NODE_VERSION} (KNXUltimate engine v${KNX_ENGINE_VERSION}, Matter protocol ${Specification.REVISION}, matter.js v${MATTER_PACKAGE_VERSION})`)
   } catch (e) { /* empty */ }
 
   function knxUltimateConfigNode (config) {

package/nodes/knxUltimateMatterBridge.html

@@ -100,7 +100,7 @@
       defaults: gaDefaults,
       inputs: 0,
       outputs: 0,
-      icon: 'node-matter-icon.svg',
+      icon: 'node-matter-bridge-icon.svg',
       label() {
         return this.name || 'Expose KNX to Matter (BETA)';
       },
@@ -337,11 +337,6 @@
     </ul>
 
     <div id="mb-tab-mappings" style="padding-top:12px;">
-      <div class="form-tips" style="display:block; width:100%; max-width:none; box-sizing:border-box; margin-bottom:12px; border-left:4px solid #d9822b;">
-        <i class="fa fa-triangle-exclamation"></i>
-        <span data-i18n="knxUltimateMatterBridge.type_change_warning"></span>
-      </div>
-
       <div id="mb-ga-fields"></div>
 
       <div class="form-row" id="mb-invert-row" style="display:none;">

package/nodes/knxUltimateMatterControllerDevice.html

@@ -18,6 +18,7 @@
         matterEndpointId: { value: 1 },
         matterDeviceName: { value: "" },
         matterDeviceCapabilities: { value: "" },
+        matterMappings: { value: "[]" },
         name: { value: "" },
 
         nameLightSwitch: { value: "" },
@@ -123,9 +124,12 @@
         restoreDayMode: { value: "no" }, // Starting from v 4.1.31
         updateLocalStateFromKNXWrite: { value: true } // Starting from v 4.1.31
       },
+      credentials: {
+        doorLockPin: { type: "password" }
+      },
       inputs: 0,
       outputs: 0,
-      icon: "node-matter-icon.svg",
+      icon: "node-matter-controller-icon.svg",
       label: function () {
         return this.name || this.matterDeviceName || "Control Matter from KNX (BETA)";
       },
@@ -506,11 +510,11 @@
             }
             return val;
           };
-          const matterTypePretty = { 'ma-extendedcolorlight': 'Colour light', 'ma-colortemperaturelight': 'Tunable white', 'ma-dimmablelight': 'Dimmable light', 'ma-onofflight': 'On/off light', 'ma-onoffpluginunit': 'Plug', 'ma-dimmablepluginunit': 'Dimmable plug' };
+          const matterTypePretty = { 'ma-extendedcolorlight': 'Colour light', 'ma-colortemperaturelight': 'Tunable white', 'ma-dimmablelight': 'Dimmable light', 'ma-onofflight': 'On/off light', 'ma-onoffpluginunit': 'Plug', 'ma-dimmablepluginunit': 'Dimmable plug', 'ma-doorlock': 'Door lock', 'ma-windowcovering': 'Cover', 'ma-thermostat': 'Thermostat', 'ma-fan': 'Fan', 'ma-temperaturesensor': 'Temperature sensor', 'ma-humiditysensor': 'Humidity sensor', 'ma-lightsensor': 'Light sensor', 'ma-occupancysensor': 'Occupancy sensor', 'ma-contactsensor': 'Contact sensor' };
           const matterPrettyType = (raw) => {
             const key = String(raw || '').toLowerCase();
             if (matterTypePretty[key]) return matterTypePretty[key];
-            return String(raw || '').replace(/^ma-/i, '').replace(/light$/i, ' light') || 'Light';
+            return String(raw || '').replace(/^ma-/i, '').replace(/light$/i, ' light') || 'Matter endpoint';
           };
           const normalizeMatterToken = (value) => String(value || '').toLowerCase().replace(/[^a-z0-9]/g, '');
           const getMatterCluster = (ep, clusterId) => (ep.clusters || []).find((c) => Number(c.id) === Number(clusterId));
@@ -524,10 +528,64 @@
           };
           const matterCapabilitiesFromEndpoint = (ep) => {
             const deviceTypes = (ep.deviceTypes || []).map(normalizeMatterToken);
+            const primaryDeviceType = (ep.deviceTypes || []).find((value) => !/bridgednode|aggregator|controlbridge/i.test(String(value))) || ep.name;
+            const deviceTypeDisplay = matterPrettyType(primaryDeviceType);
             const typeText = deviceTypes.join(' ');
             const onOffCluster = getMatterCluster(ep, 6);
             const levelCluster = getMatterCluster(ep, 8);
             const colorCluster = getMatterCluster(ep, 768);
+            const doorLockCluster = getMatterCluster(ep, 257);
+            if (doorLockCluster) {
+              return {
+                known: true,
+                profile: 'doorLock',
+                deviceTypeDisplay,
+                onOff: true,
+                level: false,
+                colorTemperature: false,
+                color: false,
+                lockDoor: hasMatterCommand(doorLockCluster, ['lockDoor']),
+                unlockDoor: hasMatterCommand(doorLockCluster, ['unlockDoor']),
+                requirePinForRemoteOperation: (() => {
+                  const attribute = (doorLockCluster.attributes || []).find((item) => normalizeMatterToken(item.name) === 'requirepinforremoteoperation');
+                  return attribute ? attribute.value === true : false;
+                })()
+              };
+            }
+            const isMatterLight = deviceTypes.some((type) => /(?:onoff|dimmable|colortemperature|extendedcolor)light/.test(type));
+            if (!isMatterLight) {
+              const mappedTargets = [];
+              const addCommand = (clusterId, target, label, dpt) => {
+                const cluster = getMatterCluster(ep, clusterId);
+                if (hasMatterCommand(cluster, [target])) mappedTargets.push({ direction: 'command', endpointId: Number(ep.endpointId), clusterId, targetKind: 'command', target, label, dpt });
+              };
+              const addAttribute = (clusterId, target, label, dpt, writable) => {
+                const cluster = getMatterCluster(ep, clusterId);
+                if (hasMatterAttribute(cluster, [target])) mappedTargets.push({ direction: writable ? 'command' : 'status', endpointId: Number(ep.endpointId), clusterId, targetKind: 'attribute', target, label, dpt });
+              };
+              addCommand(6, 'on', 'onoff_command', '1.001');
+              addAttribute(6, 'onOff', 'onoff_state', '1.001', false);
+              addCommand(258, 'upOrOpen', 'cover_updown', '1.008');
+              addCommand(258, 'stopMotion', 'cover_stop', '1.017');
+              addCommand(258, 'goToLiftPercentage', 'cover_position_command', '5.001');
+              addAttribute(258, 'currentPositionLiftPercent100ths', 'cover_position_state', '5.001', false);
+              addAttribute(513, 'occupiedHeatingSetpoint', 'heating_command', '9.001', true);
+              addAttribute(513, 'occupiedHeatingSetpoint', 'heating_state', '9.001', false);
+              addAttribute(513, 'occupiedCoolingSetpoint', 'cooling_command', '9.001', true);
+              addAttribute(513, 'occupiedCoolingSetpoint', 'cooling_state', '9.001', false);
+              addAttribute(513, 'localTemperature', 'local_temperature', '9.001', false);
+              addAttribute(514, 'percentSetting', 'fan_command', '5.001', true);
+              addAttribute(514, 'percentCurrent', 'fan_state', '5.001', false);
+              addAttribute(1026, 'measuredValue', 'temperature', '9.001', false);
+              addAttribute(1029, 'measuredValue', 'humidity', '9.007', false);
+              addAttribute(1024, 'measuredValue', 'illuminance', '9.004', false);
+              addAttribute(1030, 'occupancy', 'occupancy', '1.011', false);
+              addAttribute(69, 'stateValue', 'contact', '1.002', false);
+              addAttribute(47, 'batPercentRemaining', 'battery', '5.001', false);
+              addAttribute(144, 'activePower', 'active_power', '14.056', false);
+              addAttribute(145, 'cumulativeEnergyImported', 'imported_energy', '13.013', false);
+              return { known: true, profile: 'mapped', deviceTypeDisplay, onOff: false, level: false, colorTemperature: false, color: false, mappedTargets };
+            }
             const hasColorTemperatureType = /colortemperature|extendedcolor/.test(typeText);
             const hasColorType = /extendedcolor/.test(typeText);
             const hasLevelType = /dimmable|colortemperature|extendedcolor/.test(typeText);
@@ -542,6 +600,7 @@
             );
             return {
               known: true,
+              deviceTypeDisplay,
               colorDetectionVersion: 2,
               onOff: !!onOffCluster || /onoff|dimmable|colortemperature|extendedcolor/.test(typeText),
               level: !!levelCluster || hasLevelType,
@@ -578,9 +637,8 @@
             });
           };
 
-          // Matter counterpart of the Hue device fetch: every commissioned node is
-          // expanded into its light endpoints (clusters OnOff 6 / Level 8 / Color 768),
-          // so a bridge (e.g. a Hue Bridge paired via Matter) lists each lamp.
+          // Expand every commissioned node into its functional endpoints. Lights keep
+          // the legacy light UI; other endpoints select a capability-driven profile.
           const fetchHueDevices = (term, respond, { forceRefresh = false } = {}) => {
             const matterServer = getHueServerConfig();
             if (!matterServer) {
@@ -609,8 +667,10 @@
                 const items = [];
                 results.forEach((entry) => {
                   const device = entry.device;
-                  const lightEps = entry.endpoints.filter((ep) => Array.isArray(ep.clusters) && ep.clusters.some((c) => [6, 8, 768].indexOf(Number(c.id)) !== -1));
-                  const eps = lightEps.length ? lightEps : entry.endpoints.filter((ep) => Number(ep.endpointId) !== 0);
+                  // Multi-purpose controller: list every functional endpoint. Capability
+                  // detection below decides whether it uses the unchanged light path or
+                  // a dedicated/mapped non-light profile.
+                  const eps = entry.endpoints.filter((ep) => Number(ep.endpointId) !== 0);
                   const many = eps.length > 1;
                   eps.forEach((ep) => {
                     const label = matterEndpointLabel(ep);
@@ -679,7 +739,6 @@
           const $tabs = $("#tabs");
           const $pinSectionRow = $("#node-input-enableNodePINS").closest('.form-row');
           const $pinSelect = $("#node-input-enableNodePINS");
-          const $pinInfoRow = $pinSectionRow.next('.form-tips');
           let currentMatterCapabilities = parseMatterCapabilities($matterCapabilitiesInput.val() || node.matterDeviceCapabilities);
           $tabs.addClass('hue-vertical-tabs');
           $tabs.tabs(); // Tabs gestione KNX
@@ -935,12 +994,29 @@
             const supportsTemperature = hasHueDevice && caps.colorTemperature === true;
             const supportsColor = hasHueDevice && caps.color === true;
             const hasRichBehaviour = supportsDim && (supportsTemperature || supportsColor);
+            const isDoorLock = caps.profile === 'doorLock';
+            const isMapped = caps.profile === 'mapped';
+            const deviceTypeDisplay = String(caps.deviceTypeDisplay || '').trim();
 
             setMatterTabVisible('tabs-1', supportsSwitch);
             setMatterTabVisible('tabs-2', supportsDim);
             setMatterTabVisible('tabs-3', supportsTemperature);
             setMatterTabVisible('tabs-4', supportsColor);
+            setMatterTabVisible('tabs-mapped', isMapped);
             setMatterTabVisible('tabs-6', hasHueDevice);
+            $('#matter-door-lock-options').toggle(isDoorLock);
+            $('#matter-switch-command-label').text(isDoorLock
+              ? (node._('knxUltimateMatterControllerDevice.door_lock_command') || 'Lock / unlock')
+              : (node._('knxUltimateMatterControllerDevice.control') || 'Control'));
+            $('#matter-switch-status-label').text(isDoorLock
+              ? (node._('knxUltimateMatterControllerDevice.door_lock_status') || 'Lock state')
+              : (node._('knxUltimateMatterControllerDevice.status') || 'Status'));
+            $('#matter-door-lock-command-warning').toggle(isDoorLock && (caps.lockDoor === false || caps.unlockDoor === false));
+            $('#matter-door-lock-pin-required').toggle(isDoorLock && caps.requirePinForRemoteOperation === true);
+            $('#matter-mapped-profile').toggle(isMapped);
+            if (isMapped) renderMappedProfile(caps.mappedTargets || []);
+            $('#matter-selected-device-type-value').text(deviceTypeDisplay);
+            $('#matter-selected-device-type').toggle(hasHueDevice && deviceTypeDisplay !== '');
             try { $tabs.tabs('refresh'); } catch (error) { /* empty */ }
             ensureVisibleMatterTabSelected();
 
@@ -961,6 +1037,40 @@
             refreshBehaviourVisibility();
           };
 
+          const parseMatterMappings = () => {
+            try { return JSON.parse($('#node-input-matterMappings').val() || node.matterMappings || '[]'); } catch (error) { return []; }
+          };
+          const renderMappedProfile = (targets) => {
+            const saved = parseMatterMappings();
+            const $body = $('#matter-mapped-profile-body').empty();
+            targets.forEach((target) => {
+              const key = `${target.direction}:${target.endpointId}:${target.clusterId}:${target.targetKind}:${target.target}`;
+              const previous = saved.find((item) => `${item.direction}:${item.endpointId}:${item.clusterId}:${item.targetKind}:${item.target}` === key) || {};
+              const $row = $('<div class="form-row matter-mapped-row" style="display:flex;align-items:center;"></div>').data('mapping', target);
+              const translated = node._(`knxUltimateMatterControllerDevice.mapped.${target.label}`);
+              $('<label style="width:220px; margin-right:10px;"></label>').text(translated || target.target).appendTo($row);
+              $('<label style="width:25px; margin:0 5px 0 0;">GA</label>').appendTo($row);
+              const $ga = $('<input class="matter-mapped-ga" type="text" placeholder="Ex: 1/1/1" style="width:100px; margin-right:18px;">').val(previous.ga || '').appendTo($row);
+              $('<label style="width:35px; margin:0 5px 0 0;">DPT</label>').appendTo($row);
+              const $dpt = $('<input class="matter-mapped-dpt" type="text" placeholder="DPT" style="width:140px;">').val(previous.dpt || target.dpt || '').appendTo($row);
+              $ga.autocomplete({
+                minLength: 0,
+                source(request, response) {
+                  if (!hasKnxServerSelected()) { response([]); return; }
+                  $.getJSON(`knxUltimatecsv?nodeID=${resolveKnxServerValue()}&_=${Date.now()}`, (data) => {
+                    response($.map(data, (value) => {
+                      const searchable = `${value.ga} ${value.devicename} ${value.dpt}`;
+                      if (!htmlUtilsfullCSVSearch(searchable, request.term || '')) return null;
+                      return { label: `${value.ga} # ${value.devicename} # ${value.dpt}`, value: value.ga, dpt: value.dpt };
+                    }));
+                  }).fail(() => response([]));
+                },
+                select(event, ui) { if (ui.item.dpt) $dpt.val(ui.item.dpt); }
+              }).focus(function () { $(this).autocomplete('search', $(this).val()); });
+              $body.append($row);
+            });
+          };
+
           const updateTabsVisibility = () => {
             const knxSelected = hasKnxServerSelected();
             const hueDeviceSelected = getHueDeviceValue() !== '';
@@ -984,9 +1094,6 @@
             if ($pinSectionRow.length) {
               $pinSectionRow.show();
             }
-            if ($pinInfoRow.length) {
-              $pinInfoRow.show();
-            }
           };
           updateTabsVisibility();
 
@@ -1325,6 +1432,20 @@
         this.matterNodeId = ($("#node-input-matterNodeId").val() || '').trim();
         this.matterEndpointId = Number($("#node-input-matterEndpointId").val() || 1);
         this.matterDeviceCapabilities = ($("#node-input-matterDeviceCapabilities").val() || '').trim();
+        const mappedMappings = [];
+        const $mappedRows = $('#matter-mapped-profile-body .matter-mapped-row');
+        $mappedRows.each(function () {
+          const base = $(this).data('mapping') || {};
+          const ga = ($(this).find('.matter-mapped-ga').val() || '').trim();
+          const dpt = ($(this).find('.matter-mapped-dpt').val() || '').trim();
+          if (ga && dpt) mappedMappings.push(Object.assign({}, base, { ga, dpt }));
+        });
+        // Preserve saved mappings when the endpoint is offline and its asynchronous
+        // structure could not be rebuilt during an untouched editor round trip.
+        this.matterMappings = $mappedRows.length > 0
+          ? JSON.stringify(mappedMappings)
+          : ($('#node-input-matterMappings').val() || this.matterMappings || '[]');
+        $('#node-input-matterMappings').val(this.matterMappings);
         this.name = this.matterDeviceName || this.name || '';
         $("#node-input-name").val(this.name);
         const parseSavedMatterCapabilities = (raw) => {
@@ -1550,9 +1671,15 @@
       <span class="hue-devices-loading" style="margin-left:6px; display:none; color:#1b7d33;">
         <i class="fa fa-circle-notch fa-spin"></i>
       </span>
+      <span id="matter-selected-device-type" style="display:none; margin-left:10px; color:#666; white-space:nowrap;">
+        <i class="fa fa-microchip"></i>
+        <span data-i18n="knxUltimateMatterControllerDevice.device_type"></span>:
+        <span id="matter-selected-device-type-value" style="font-weight:600;"></span>
+      </span>
       <input type="hidden" id="node-input-matterNodeId" />
       <input type="hidden" id="node-input-matterEndpointId" />
       <input type="hidden" id="node-input-matterDeviceCapabilities" />
+      <input type="hidden" id="node-input-matterMappings" />
       <input type="hidden" id="node-input-name" />
     </div>
 
@@ -1564,12 +1691,18 @@
         <li><a href="#tabs-2"><i class="fa-solid fa-arrow-up-wide-short"></i> <span data-i18n="knxUltimateMatterControllerDevice.tabs.dim"></span></a></li>
         <li><a href="#tabs-3"><i class="fa-solid fa-temperature-quarter"></i> <span data-i18n="knxUltimateMatterControllerDevice.tabs.tunable_white"></span></a></li>
         <li><a href="#tabs-4"><i class="fa-solid fa-palette"></i> <span data-i18n="knxUltimateMatterControllerDevice.tabs.rgb_hsv"></span></a></li>
+        <li><a href="#tabs-mapped"><i class="fa-solid fa-list-check"></i> <span data-i18n="knxUltimateMatterControllerDevice.tabs.mappings"></span></a></li>
         <li><a href="#tabs-6"><i class="fa-solid fa-code-merge"></i> <span data-i18n="knxUltimateMatterControllerDevice.tabs.behaviour"></span></a></li>
       </ul>
+      <div id="tabs-mapped">
+        <div id="matter-mapped-profile" style="display:none;">
+          <div id="matter-mapped-profile-body"></div>
+        </div>
+      </div>
       <div id="tabs-1">
         <p>
         <div class="form-row">
-          <label for="node-input-nameLightSwitch" style="width:110px;"><i class="fa fa-play-circle-o"></i> <span data-i18n="knxUltimateMatterControllerDevice.control"></span></label>
+          <label for="node-input-nameLightSwitch" style="width:110px;"><i class="fa fa-play-circle-o"></i> <span id="matter-switch-command-label" data-i18n="knxUltimateMatterControllerDevice.control"></span></label>
 
           <label for="node-input-GALightSwitch" style="width:20px;"><span data-i18n="common.ga"></span></label>
           <input type="text" id="node-input-GALightSwitch" placeholder="Ex: 1/1/1"
@@ -1582,7 +1715,7 @@
           <input type="text" id="node-input-nameLightSwitch" style="width:190px;margin-left: 5px; text-align: left;">
         </div>
         <div class="form-row">
-          <label for="node-input-nameLightState" style="width:110px;"><i class="fa fa-question-circle"></i> <span data-i18n="knxUltimateMatterControllerDevice.status"></span></label>
+          <label for="node-input-nameLightState" style="width:110px;"><i class="fa fa-question-circle"></i> <span id="matter-switch-status-label" data-i18n="knxUltimateMatterControllerDevice.status"></span></label>
 
           <label for="node-input-GALightState" style="width:20px;"><span data-i18n="common.ga"></span></label>
           <input type="text" id="node-input-GALightState" placeholder="Ex: 1/1/1"
@@ -1595,6 +1728,14 @@
               data-i18n="knxUltimateMatterControllerDevice.node-input-name"></span></label>
           <input type="text" id="node-input-nameLightState" style="width:190px;margin-left: 5px; text-align: left;">
         </div>
+        <div id="matter-door-lock-options" style="display:none;">
+          <div class="form-row">
+            <label for="node-input-doorLockPin" style="width:260px;"><i class="fa fa-key"></i> <span data-i18n="knxUltimateMatterControllerDevice.door_lock_pin"></span></label>
+            <input type="password" id="node-input-doorLockPin" style="width:210px;" autocomplete="new-password">
+          </div>
+          <div id="matter-door-lock-pin-required" class="form-tips" style="display:none;" data-i18n="knxUltimateMatterControllerDevice.door_lock_pin_required"></div>
+          <div id="matter-door-lock-command-warning" class="form-tips" style="display:none; color:#a94442;" data-i18n="knxUltimateMatterControllerDevice.door_lock_commands_missing"></div>
+        </div>
         </p>
       </div>
       <div id="tabs-2">
@@ -1899,7 +2040,6 @@
           </label>
           <input type="checkbox" id="node-input-updateLocalStateFromKNXWrite" style="display:inline-block; width:auto; vertical-align:top;" />
         </div>
-        <div class="form-tips" style="margin-left:260px;" data-i18n="knxUltimateMatterControllerDevice.update_local_state_from_knx_write_hint"></div><br/>
         <div id ="divBehaviourBrightness">
           <div class="form-row">
             <label for="node-input-specifySwitchOnBrightness" style="width:260px;">
@@ -2116,4 +2256,4 @@ _Non-Hue basic effects_
 The Dimming function works in **KNX mode `start` and`stop` ** . To start dimming, send only one "start" KNX telegram. To stop dimming, send a "stop" KNX telegram. Please**remember that** , when you set your wall swiches properties.
 
 <br/>
-</script>
+</script>

package/nodes/knxUltimateMatterControllerDevice.js

@@ -9,6 +9,7 @@ const dptlib = require('knxultimate').dptlib
 const hueColorConverter = require('./utils/colorManipulators/hueColorConverter')
 const { createLightEngine } = require('./utils/lightEngines')
 const { hueStateToCanonical, matterEventToHuePatch } = require('./utils/lightEngines/matterHueShim')
+const { setupMatterControllerProfile } = require('./utils/matterControllerProfiles')
 
 module.exports = function (RED) {
   function knxUltimateMatterControllerDevice (config) {
@@ -20,6 +21,10 @@ module.exports = function (RED) {
     node.matterEndpointId = config.matterEndpointId !== undefined ? Number(config.matterEndpointId) : 1
     node.matterDeviceName = config.matterDeviceName !== undefined ? String(config.matterDeviceName) : ''
 
+    let matterCapabilities = {}
+    try { matterCapabilities = JSON.parse(config.matterDeviceCapabilities || '{}') } catch (error) { /* empty */ }
+    if (setupMatterControllerProfile(matterCapabilities.profile, RED, node, config)) return
+
     // Matter engine (adapter). The manager is resolved lazily at each write, because
     // matter-config creates its matterManager asynchronously after the deploy.
     node.lightEngine = createLightEngine('matter', {

package/nodes/locales/de/knxUltimateMatterBridge.html

@@ -9,6 +9,8 @@ Jeder Expose KNX to Matter Node stellt **ein KNX-Gerät als Matter-Gerät** bere
 
 Das ist die Gegenrichtung zum *Matter Device*-Node: Dort steuert KNX ein Matter-Gerät, hier steuern Matter-Controller KNX.
 
+Das Ändern des Gerätetyps nach der Kopplung der Bridge verändert die Matter-Endpunktstruktur. Controller können den alten Endpunkt als nicht erreichbar behalten; dann die Bridge zurücksetzen/neu koppeln oder ein neues bereitgestelltes Gerät erstellen.
+
 ## Konfiguration
 
 |Feld|Beschreibung|

package/nodes/locales/de/knxUltimateMatterControllerDevice.html

@@ -15,6 +15,8 @@ Er ersetzt die unveröffentlichten getrennten Matter-Controller-Nodes und behäl
 | Matter controller | Matter-Controller-Konfigurationsknoten, in dem das Gerät gekoppelt wurde. |
 | Matter device | Matter-Endpunkt aus den gekoppelten Geräten. Die UI wird aus den echten Fähigkeiten neu aufgebaut. |
 | Switch / Steckdose / Licht On-Off | On/Off-Befehls- und Status-Gruppenadressen, normalerweise DPT `1.001`. |
+| Türschloss | Eine DPT-`1.xxx`-Befehls-GA ruft bei `true` `lockDoor` und bei `false` `unlockDoor` auf; eine separate Status-GA erhält nur eindeutige Verriegelt/Entriegelt-Zustände. Falls erforderlich, wird die Fernbedienungs-PIN im Credential-Feld gespeichert. Nicht angebotene Befehle werden abgewiesen. |
+| Andere Endpunkte | Steckdosen, Ein/Aus-Aktoren, Jalousien, Thermostate, Lüfter, Umwelt-/Kontakt-/Belegungssensoren sowie Batterie-, Leistungs- und Energieendpunkte verwenden das Mehrzweckprofil. Der Tab **Zuordnungen** enthält nur tatsächlich angebotene Cluster, Attribute und Befehle. |
 | Lichtsteuerung | Für Licht-Endpunkte wird die vollständige Licht-UI verwendet: relatives DIM (DPT `3.007`), Helligkeit %, RGB/HSV, Tunable White, Einschalt-Helligkeit/-Temperatur, Tag/Nacht-Licht, Min/Max-Dimmlevel und Dimmgeschwindigkeit. Nicht unterstützte Bereiche bleiben ausgeblendet. |
 | Sensoren | Sensor-Endpunkte zeigen ihre Mess-/Status-GA nur bei Unterstützung: Temperatur, Feuchte, Helligkeit, Präsenz, Kontakt und Batterie. |
 | Read at startup | Veröffentlicht den gecachten Matter-Wert beim Deploy/Start oder wenn sich das Gerät erneut verbindet. |

package/nodes/locales/de/knxUltimateMatterControllerDevice.json

@@ -17,10 +17,19 @@
       "tunable_white": "Einstellbares Weiß",
       "rgb_hsv": "RGB/HSV",
       "effects": "Effekte",
+      "mappings": "Zuordnungen",
       "behaviour": "Verhalten"
     },
     "control": "Steuerung",
     "status": "Status",
+    "door_lock_command": "Verriegeln / entriegeln",
+    "door_lock_status": "Schlossstatus",
+    "door_lock_pin": "PIN für Fernbedienung",
+    "door_lock_pin_required": "Dieses Schloss meldet, dass für die Fernbedienung eine PIN erforderlich ist.",
+    "door_lock_commands_missing": "Dieser Endpunkt bietet nicht beide Befehle zum Verriegeln und Entriegeln an. Fehlende Befehle werden abgewiesen.",
+    "mapped": {
+      "onoff_command": "Ein/Aus-Befehl", "onoff_state": "Ein/Aus-Status", "cover_updown": "Jalousie auf/ab", "cover_stop": "Jalousie Stopp", "cover_position_command": "Positionsbefehl", "cover_position_state": "Positionsstatus", "heating_command": "Heizsollwert-Befehl", "heating_state": "Heizsollwert-Status", "cooling_command": "Kühlsollwert-Befehl", "cooling_state": "Kühlsollwert-Status", "local_temperature": "Lokale Temperatur", "fan_command": "Lüfterdrehzahl-Befehl", "fan_state": "Lüfterdrehzahl-Status", "temperature": "Temperatur", "humidity": "Luftfeuchte", "illuminance": "Beleuchtungsstärke", "occupancy": "Belegung", "contact": "Binär-/Kontaktstatus", "battery": "Batterie", "active_power": "Wirkleistung", "imported_energy": "Bezogene Energie"
+    },
     "night_lighting": "Nachtbeleuchtung",
     "no_night_lighting": "Keine Nachtbeleuchtung",
     "get_current": "Aktuellen Wert holen",
@@ -82,6 +91,7 @@
     "effect_native_label": "Hue-native Effekte",
     "matter_controller": "Matter-Controller",
     "matter_device": "Matter-Gerät",
+    "device_type": "Gerätetyp",
     "matter_section": "Matter-Gerät"
   },
   "common": {

package/nodes/locales/de/matter-config.html

@@ -15,10 +15,14 @@ Der Controller kommuniziert mit den Geräten über das **IP-Netzwerk** (WLAN, Et
 
 Wenn das Gerät fabrikneu ist und nur Bluetooth-Kommissionierung unterstützt, kopple es zuerst mit der Hersteller-App oder einem anderen Matter-Controller (Alexa, Google Home, Apple Home) und nutze dann dessen Funktion **"mit weiterem Hub teilen"**, um einen neuen Kopplungscode für KNX-Ultimate zu erzeugen. So tritt das Gerät mehreren Fabrics gleichzeitig bei.
 
+Bevorzuge den QR-Payload (`MT:...`): Er enthält den vollständigen Diskriminator. Der manuelle Code enthält nur den kurzen Diskriminator und kann bei mehreren identischen Modellen im Kopplungsmodus das falsche Gerät auswählen. Immer nur ein Gerät gleichzeitig koppeln.
+
 ## Speicherung
 
 Die Fabric-Zugangsdaten und die gekoppelten Geräte werden im Ordner `knxultimatestorage/matter` im Node-RED-Benutzerverzeichnis gespeichert. Das Löschen dieses Ordners entfernt alle Kopplungen.
 
+Mit **Exportieren** wird eine vollständige Sicherung dieser Controller-Instanz heruntergeladen. Sie enthält Fabric, private Zugangsdaten, Sitzungen und Daten gekoppelter Geräte. **Die Datei wie ein Passwort schützen.** Der Import ersetzt den Matter-Speicher dieser Instanz und startet den Controller kurz neu. Eine Controller-Sicherung kann nicht in eine Bridge importiert werden.
+
 ## Ein Gerät entfernen
 
 Nutze den Papierkorb-Button in der Liste der gekoppelten Geräte. Der Controller versucht, das Gerät sauber zu dekommissionieren; ist es nicht erreichbar, wird es trotzdem aus der Fabric entfernt (danach kann ein Werksreset des Geräts nötig sein).

package/nodes/locales/de/matter-config.json

@@ -2,7 +2,6 @@
   "matter-config": {
     "properties": {
       "title": "Matter Controller",
-      "intro": "Dieser Node ist ein Matter-Controller (mit eigener Fabric). Kopple hier deine Matter-Geräte und verwende dann den \"Matter Device\"-Node, um sie auf KNX-Gruppenadressen abzubilden. Zuerst deployen, dann hierher zurückkehren, um Geräte zu koppeln.",
       "node-config-input-name": "Name",
       "fabric_label": "Fabric-Bezeichnung",
       "pairing_title": "Neues Gerät koppeln",
@@ -24,7 +23,13 @@
       "pairing_ok": "Gerät erfolgreich gekoppelt!",
       "rename_button": "Umbenennen",
       "rename_prompt": "Neuer Gerätename",
-      "rename_ok": "Gerät umbenannt."
+      "rename_ok": "Gerät umbenannt.",
+      "storage_title": "Sicherung von Fabric und Inbetriebnahme",
+      "storage_export": "Exportieren",
+      "storage_import": "Importieren",
+      "storage_warning": "Die Sicherung enthält Fabric-Zugangsdaten, private Schlüssel und Daten gekoppelter Geräte. Wie ein Passwort schützen. Der Import ersetzt den Matter-Speicher dieses Controllers und startet ihn kurz neu.",
+      "storage_import_confirm": "Matter-Fabric und gekoppelte Geräte dieses Controllers durch die gewählte Sicherung ersetzen?",
+      "storage_import_ok": "Matter-Sicherung importiert. Der Controller wurde neu gestartet."
     }
   }
 }

package/nodes/locales/de/matterbridge-config.html

@@ -21,12 +21,16 @@ Dieser Konfigurations-Node ist die **Matter-Bridge selbst**: Er betreibt den Mat
 2. Das Kopplungs-Panel zeigt den **QR-Code** und den **manuellen Code**: scannen oder in Alexa / Google Home / Apple Home eingeben ("Matter-Gerät hinzufügen").
 3. Mehrere Controller können mit derselben Bridge gekoppelt werden (Matter Multi-Fabric).
 
+Um nach dem Ausblenden des QR-Codes einen weiteren Controller hinzuzufügen, den Kopplungsmodus über einen bereits gekoppelten Controller öffnen und dann im neuen Controller ein Matter-Gerät hinzufügen. **Kopplung zurücksetzen** nur verwenden, um alle vorhandenen Controller zu entfernen und neu zu beginnen.
+
 Der Button **Kopplung zurücksetzen** entfernt alle gekoppelten Controller und startet die Kopplungs-Ankündigung neu.
 
 ## Identität und Speicherung
 
 Die Bridge-Identität ist an diesen Konfigurations-Node gebunden und wird in `knxultimatestorage/matter` im Node-RED-Benutzerverzeichnis gespeichert: Re-Deploys (auch mit geändertem Port oder Namen) erfordern **KEINE** neue Kopplung. Nur das Löschen dieses Konfigurations-Nodes und das Anlegen eines neuen ändert die Identität — in dem Fall die alte Bridge aus der Matter-App entfernen und neu koppeln.
 
+Mit **Exportieren** wird eine vollständige Sicherung dieser Bridge-Instanz heruntergeladen, einschließlich Fabrics, privater Zugangsdaten, Sitzungen und Kopplungsdaten. **Die Datei wie ein Passwort schützen.** Der Import ersetzt den Speicher dieser Instanz und startet die Bridge kurz neu. Eine Bridge-Sicherung kann nicht in einen Controller importiert werden.
+
 ## Hinweise
 
 - Der Node-RED-Host muss **IPv6 link-local** aktiviert haben (Standard-Matter-Anforderung) und von den Controllern im lokalen Netzwerk erreichbar sein.

package/nodes/locales/de/matterbridge-config.json

@@ -16,7 +16,10 @@
       "deploy_first": "Bitte zuerst diesen Konfigurations-Node deployen und dann auf Aktualisieren klicken.",
       "reset_button": "Kopplung zurücksetzen",
       "reset_confirm": "ALLE gekoppelten Controller entfernen und die Kopplung neu starten? Die Geräte verschwinden aus Alexa/Google/Apple.",
-      "reset_ok": "Kopplung zurückgesetzt. Die Bridge wartet wieder auf Kopplung."
+      "reset_ok": "Kopplung zurückgesetzt. Die Bridge wartet wieder auf Kopplung.",
+      "storage_title": "Sicherung von Fabric und Kopplung", "storage_export": "Exportieren", "storage_import": "Importieren",
+      "storage_warning": "Die Sicherung enthält Fabric-Zugangsdaten, private Schlüssel und Kopplungsdaten. Wie ein Passwort schützen. Der Import ersetzt den Matter-Speicher dieser Bridge und startet sie kurz neu.",
+      "storage_import_confirm": "Matter-Fabrics und gekoppelte Controller dieser Bridge durch die gewählte Sicherung ersetzen?", "storage_import_ok": "Matter-Sicherung importiert. Die Bridge wurde neu gestartet."
     }
   }
 }

package/nodes/locales/en/knxUltimateMatterBridge.html

@@ -9,6 +9,8 @@ Each Expose KNX to Matter node exposes **one KNX device as a Matter device**: th
 
 This is the opposite direction of the *Matter Device* node: there KNX controls a Matter device, here the Matter controllers control KNX.
 
+Changing the device type after the bridge has been paired changes the Matter endpoint structure. Controllers may keep the old endpoint as unreachable; in that case reset/re-pair the bridge or create a new exposed device.
+
 ## Configuration
 
 |Field|Description|