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

package/nodes/knxUltimateMatterDevice.js

@@ -0,0 +1,308 @@
+const dptlib = require('knxultimate').dptlib
+const matterKnxConverter = require('./utils/matterKnxConverter')
+
+module.exports = function (RED) {
+  function knxUltimateMatterDevice (config) {
+    RED.nodes.createNode(this, config)
+    const node = this
+    node.serverKNX = RED.nodes.getNode(config.server) || undefined
+    node.serverMatter = RED.nodes.getNode(config.serverMatter) || undefined
+
+    node.topic = node.name
+    node.name = config.name === undefined || config.name === '' ? 'Matter Device (BETA)' : config.name
+    node.dpt = ''
+    node.notifyreadrequest = false
+    node.notifyreadrequestalsorespondtobus = 'false'
+    node.notifyreadrequestalsorespondtobusdefaultvalueifnotinitialized = ''
+    node.notifyresponse = false
+    node.notifywrite = true
+    node.initialread = true
+    node.listenallga = true // Don't remove
+    node.outputtype = 'write'
+    node.outputRBE = 'false'
+    node.inputRBE = 'false'
+    node.currentPayload = ''
+    node.passthrough = 'no'
+    node.formatmultiplyvalue = 1
+    node.formatnegativevalue = 'leave'
+    node.formatdecimalsvalue = 2
+
+    node.matterNodeId = config.matterNodeId || ''
+    node.mappings = []
+    try {
+      node.mappings = Array.isArray(config.mappings) ? config.mappings : JSON.parse(config.mappings || '[]')
+    } catch (error) {
+      node.mappings = []
+    }
+
+    node.initializingAtStart = config.readStatusAtStartup === undefined || config.readStatusAtStartup === 'yes'
+    node.enableNodePINS = config.enableNodePINS === 'yes'
+    node.inputs = node.enableNodePINS ? 1 : 0
+    node.outputs = node.enableNodePINS ? 1 : 0
+
+    let lastInitialReadTs = 0
+
+    const pushStatus = (status) => {
+      if (!status) return
+      const provider = node.serverKNX
+      if (provider && typeof provider.applyStatusUpdate === 'function') {
+        provider.applyStatusUpdate(node, status)
+      } else {
+        node.status(status)
+      }
+    }
+
+    const formatTs = (date) => {
+      const d = date instanceof Date ? date : new Date(date)
+      const provider = node.serverKNX
+      if (provider && typeof provider.formatStatusTimestamp === 'function') return provider.formatStatusTimestamp(d)
+      return `${d.getDate()}, ${d.toLocaleTimeString()}`
+    }
+
+    node.setNodeStatus = ({ fill, shape, text, payload }) => {
+      try {
+        if (payload === undefined) payload = ''
+        const dDate = new Date()
+        payload = typeof payload === 'object' ? JSON.stringify(payload) : payload.toString()
+        node.sKNXNodeStatusText = `|KNX: ${text} ${payload} (${formatTs(dDate)})`
+        pushStatus({ fill, shape, text: (node.sMatterNodeStatusText || '') + ' ' + (node.sKNXNodeStatusText || '') })
+      } catch (error) { /* empty */ }
+    }
+
+    node.setNodeStatusMatter = ({ fill, shape, text, payload }) => {
+      try {
+        if (payload === undefined) payload = ''
+        const dDate = new Date()
+        payload = typeof payload === 'object' ? JSON.stringify(payload) : payload.toString()
+        node.sMatterNodeStatusText = `|Matter: ${text} ${payload} (${formatTs(dDate)})`
+        pushStatus({ fill, shape, text: node.sMatterNodeStatusText + ' ' + (node.sKNXNodeStatusText || '') })
+      } catch (error) { /* empty */ }
+    }
+
+    const safeSendToKNX = (telegram, context = 'write') => {
+      try {
+        if (!node.serverKNX || typeof node.serverKNX.sendKNXTelegramToKNXEngine !== 'function') {
+          pushStatus({ fill: 'red', shape: 'dot', text: `KNX server missing (${context}) (${formatTs(new Date())})` })
+          return
+        }
+        node.serverKNX.sendKNXTelegramToKNXEngine({ ...telegram, nodecallerid: node.id })
+      } catch (error) {
+        pushStatus({ fill: 'red', shape: 'dot', text: `KNX send error ${error.message}` })
+      }
+    }
+
+    const sendMappingToKNX = (mapping, payload, outputtype = 'write') => {
+      if (payload === undefined || mapping.ga === undefined || mapping.ga === '') return
+      safeSendToKNX({
+        grpaddr: mapping.ga,
+        payload,
+        dpt: mapping.dpt,
+        outputtype
+      }, outputtype)
+    }
+
+    const getMatterManager = () => {
+      if (!node.serverMatter || node.serverMatter.matterManager === null || node.serverMatter.matterManager === undefined) return undefined
+      return node.serverMatter.matterManager
+    }
+
+    // Send the cached Matter value of a status mapping to KNX
+    const sendCachedStatusToKNX = (mapping, outputtype = 'write') => {
+      try {
+        const manager = getMatterManager()
+        if (manager === undefined) return false
+        const rawValue = manager.getCachedAttribute(node.matterNodeId, mapping.endpointId, mapping.clusterId, mapping.target)
+        if (rawValue === undefined) return false
+        const payload = matterKnxConverter.matterToKnx(mapping.clusterId, mapping.target, rawValue)
+        if (payload === undefined) return false
+        sendMappingToKNX(mapping, payload, outputtype)
+        return true
+      } catch (error) {
+        node.setNodeStatusMatter({ fill: 'red', shape: 'dot', text: `Cached status error ${error.message}`, payload: '' })
+        return false
+      }
+    }
+
+    // KNX -> Matter
+    node.handleSend = (msg) => {
+      if (!msg || !msg.knx) return
+      if (node.matterNodeId === '') {
+        node.setNodeStatusMatter({ fill: 'red', shape: 'ring', text: 'Missing Matter device selection', payload: '' })
+        return
+      }
+      try {
+        if (!Array.isArray(node.mappings)) return
+        if (msg.knx.event === 'GroupValue_Read') {
+          // Respond to read requests with the cached Matter values
+          node.mappings.filter((m) => m.direction === 'status' && m.ga === msg.knx.destination).forEach((mapping) => {
+            if (sendCachedStatusToKNX(mapping, 'response')) {
+              node.setNodeStatus({ fill: 'grey', shape: 'ring', text: 'Response', payload: mapping.ga })
+            }
+          })
+          return
+        }
+        const manager = getMatterManager()
+        node.mappings.filter((m) => m.direction === 'command' && m.ga === msg.knx.destination).forEach((mapping) => {
+          const value = dptlib.fromBuffer(msg.knx.rawValue, dptlib.resolve(mapping.dpt))
+          const matterAction = matterKnxConverter.knxToMatter(mapping, value)
+          if (matterAction === null) return
+          if (manager === undefined || node.serverMatter.linkStatus !== 'connected') {
+            node.setNodeStatusMatter({ fill: 'red', shape: 'ring', text: 'Matter controller unavailable', payload: '' })
+            return
+          }
+          manager.writeMatterQueueAdd({
+            nodeId: node.matterNodeId,
+            endpointId: mapping.endpointId,
+            clusterId: mapping.clusterId,
+            kind: matterAction.kind,
+            name: matterAction.name,
+            args: matterAction.args
+          })
+          node.setNodeStatusMatter({
+            fill: 'green',
+            shape: 'dot',
+            text: `KNX->Matter ${mapping.clusterName || mapping.clusterId}.${matterAction.name}`,
+            payload: value
+          })
+        })
+      } catch (error) {
+        node.setNodeStatusMatter({ fill: 'red', shape: 'dot', text: `KNX->Matter error ${error.message}`, payload: '' })
+      }
+    }
+
+    // Matter -> KNX (attribute change reported by the subscription)
+    node.handleSendMatter = (_event) => {
+      try {
+        if (_event === undefined) return
+        if (_event.nodeId !== node.matterNodeId) return
+        const matchingMappings = node.mappings.filter((m) => m.direction === 'status' &&
+          Number(m.endpointId) === Number(_event.endpointId) &&
+          Number(m.clusterId) === Number(_event.clusterId) &&
+          m.targetKind === 'attribute' &&
+          m.target === _event.attributeName)
+        matchingMappings.forEach((mapping) => {
+          const payload = matterKnxConverter.matterToKnx(_event.clusterId, _event.attributeName, _event.value)
+          if (payload === undefined) return
+          sendMappingToKNX(mapping, payload, 'write')
+          node.setNodeStatusMatter({
+            fill: 'blue',
+            shape: 'dot',
+            text: `Matter->KNX ${_event.attributeName}`,
+            payload
+          })
+        })
+        if (node.enableNodePINS) {
+          node.send({
+            topic: `${_event.clusterId}.${_event.attributeName}`,
+            payload: _event.value,
+            matter: _event
+          })
+        }
+      } catch (error) {
+        node.setNodeStatusMatter({ fill: 'red', shape: 'dot', text: `Matter->KNX error ${error.message}`, payload: '' })
+      }
+    }
+
+    // Cluster events (e.g. switch presses). Forwarded to the flow only.
+    node.handleMatterClusterEvent = (_event) => {
+      try {
+        if (_event === undefined || _event.nodeId !== node.matterNodeId) return
+        if (node.enableNodePINS) {
+          node.send({
+            topic: `${_event.clusterId}.${_event.eventName}`,
+            payload: _event.events,
+            matter: _event
+          })
+        }
+      } catch (error) { /* empty */ }
+    }
+
+    // Called by matter-config when the paired node completed its initial sync (or reconnected)
+    node.handleMatterNodeInitialized = () => {
+      try {
+        if (!node.initializingAtStart) return
+        if (node.matterNodeId === '') return
+        const now = Date.now()
+        if ((now - lastInitialReadTs) < 5000) return // Avoid duplicate bursts on reconnections
+        let sentCount = 0
+        node.mappings.filter((m) => m.direction === 'status' && m.targetKind === 'attribute').forEach((mapping) => {
+          if (sendCachedStatusToKNX(mapping, 'write')) sentCount += 1
+        })
+        if (sentCount > 0) {
+          lastInitialReadTs = now
+          node.setNodeStatusMatter({ fill: 'green', shape: 'dot', text: `Initial read: ${sentCount} value(s) sent`, payload: '' })
+        }
+      } catch (error) {
+        node.setNodeStatusMatter({ fill: 'red', shape: 'dot', text: `Initial read error ${error.message}`, payload: '' })
+      }
+    }
+
+    if (node.serverKNX) {
+      try {
+        node.serverKNX.removeClient(node)
+        node.serverKNX.addClient(node)
+      } catch (error) {
+        RED.log.error(`knxUltimateMatterDevice: register KNX client error ${error.message}`)
+      }
+    }
+    if (node.serverMatter) {
+      try {
+        node.serverMatter.removeClient(node)
+        node.serverMatter.addClient(node)
+      } catch (error) {
+        RED.log.error(`knxUltimateMatterDevice: register client error ${error.message}`)
+      }
+    }
+
+    // Flow input pin: send raw Matter commands/attribute writes.
+    // msg.payload = { endpointId, clusterId, command: 'on', args: {...} } or { endpointId, clusterId, attribute: 'onOff', value: true }
+    node.on('input', (msg, send, done) => {
+      if (!node.enableNodePINS) {
+        if (done) done()
+        return
+      }
+      try {
+        const manager = getMatterManager()
+        if (manager === undefined) throw new Error('Matter controller unavailable')
+        const payload = msg.payload || {}
+        if (payload.command !== undefined) {
+          manager.writeMatterQueueAdd({
+            nodeId: node.matterNodeId,
+            endpointId: payload.endpointId,
+            clusterId: payload.clusterId,
+            kind: 'command',
+            name: payload.command,
+            args: payload.args
+          })
+        } else if (payload.attribute !== undefined) {
+          manager.writeMatterQueueAdd({
+            nodeId: node.matterNodeId,
+            endpointId: payload.endpointId,
+            clusterId: payload.clusterId,
+            kind: 'attributeWrite',
+            name: payload.attribute,
+            args: payload.value
+          })
+        } else {
+          throw new Error('msg.payload must contain "command" or "attribute"')
+        }
+        node.setNodeStatusMatter({ fill: 'green', shape: 'dot', text: 'Flow->Matter', payload })
+        if (done) done()
+      } catch (error) {
+        node.setNodeStatusMatter({ fill: 'red', shape: 'dot', text: `Flow error ${error.message}`, payload: '' })
+        if (done) done(error)
+      }
+    })
+
+    node.on('close', () => {
+      try {
+        if (node.serverKNX) node.serverKNX.removeClient(node)
+      } catch (error) { /* empty */ }
+      try {
+        if (node.serverMatter) node.serverMatter.removeClient(node)
+      } catch (error) { /* empty */ }
+    })
+  }
+
+  RED.nodes.registerType('knxUltimateMatterDevice', knxUltimateMatterDevice)
+}

package/nodes/locales/de/knxUltimateMatterBridge.html

@@ -0,0 +1,64 @@
+<script type="text/markdown" data-help-name="knxUltimateMatterBridge">
+# Matter Bridge (BETA)
+
+> Dieser Node ist in **BETA**: Er funktioniert, aber Details können sich zwischen Releases noch ändern.
+
+## Übersicht
+
+Der Matter Bridge Node stellt **KNX-Gruppenadressen als Matter-Geräte** bereit: Alexa, Google Home, Apple Home (oder jeder Matter-Controller) koppeln diese Bridge **einmal** und sehen alle konfigurierten KNX-Geräte mit den von dir vergebenen Namen — bereit für App- und Sprachsteuerung.
+
+Das ist die Gegenrichtung zum *Matter Device*-Node: Dort steuert KNX ein Matter-Gerät, hier steuern Matter-Controller KNX.
+
+## Konfiguration
+
+|Feld|Beschreibung|
+|--|--|
+| KNX GW | KNX-Gateway für die Telegramme. **Optional**: Ohne Gateway arbeitet die Bridge im Nur-Flow-Modus — aktiviere die Node-PINs und steuere jedes Gerät über Flow-Nachrichten |
+| Name der Matter-Bridge | Wie die Bridge selbst in den Matter-Apps heißt |
+| Port | UDP-Port des Matter-Servers (Standard 5540). Nur ein Bridge-Node pro Node-RED-Instanz. |
+| Geräte | Die auf Matter bereitgestellten virtuellen KNX-Geräte (siehe unten) |
+| Status-GAs beim Start lesen | Sendet beim Start ein `GroupValue_Read` an jede Status-GA, damit die Matter-Attribute gefüllt sind |
+
+## Geräte
+
+Jede Zeile ist ein Gerät, das Alexa & Co. anzeigen. Wähle den **Typ**, gib den **Namen** ein, den der Assistent verwendet, und fülle die Gruppenadressen aus (mit ETS-Autovervollständigung):
+
+|Typ|Gruppenadressen|
+|--|--|
+| Ein/Aus-Licht, Steckdose | Ein/Aus Befehls-GA, Ein/Aus Status-GA (DPT 1.001) |
+| Dimmbares Licht | + Dimmen % Befehls-/Status-GA (DPT 5.001) |
+| RGB-Farblicht | + RGB-Farbe Befehls-/Status-GA (DPT 232.600). Die Matter-Farbe (Hue/Saturation oder XY, vom Farbrad der App) wird von/zur KNX-RGB-Triplette konvertiert |
+| Tunable-White-Licht | + Farbtemperatur Befehls-/Status-GA in Kelvin (DPT 7.600) |
+| Rollladen / Jalousie | Auf/Ab (DPT 1.008), Stopp (DPT 1.017), Position % Befehl/Status (DPT 5.001), optionale Positionsumkehr |
+| Thermostat (Heizung) | GA aktuelle Temperatur, Sollwert Befehls-/Status-GA (DPT 9.001) |
+| Ventilator / Lüftung | Geschwindigkeit % Befehls-/Status-GA (DPT 5.001) |
+| Sensoren (Temperatur, Feuchte, Licht, Präsenz, Kontakt) | Je eine Status-GA |
+| Rauch-/CO-Melder | Rauchalarm Status-GA + optionale CO-Alarm Status-GA (DPT 1.005): kritische Benachrichtigungen auf dem Telefon |
+| Wasserleckmelder | Leckage Status-GA (DPT 1.005) |
+| Luftqualitätssensor (CO2) | CO2 Status-GA in ppm (DPT 9.008); die Luftqualitätsklasse (gut/mäßig/schlecht...) wird automatisch abgeleitet |
+| Saugroboter | **Nur Flow**: keine Gruppenadressen. Aktiviere die Node-PINs: Befehle des Assistenten ("Reinigung starten", Pause/Fortsetzen/zur Basis) kommen am Output als `rvcmode`/`rvccommand` an; melde den Zustand zurück mit `msg.payload = { device, function: "rvcstate", value: "running"|"docked"|"charging"|"paused"|"error" }` und den Modus mit `function: "rvcmode", value: "cleaning"|"idle"`. Integriere deinen Roomba/Roborock mit beliebigen Node-RED-Nodes und stelle ihn Alexa/Apple bereit |
+
+- **Befehls-GA**: wird auf den KNX-Bus geschrieben, wenn der Assistent einen Befehl sendet.
+- **Status-GA**: wird vom Bus gelesen, um die Matter-Attribute (und die Apps) aktuell zu halten.
+
+## Kopplung
+
+1. **Deployen**, ein paar Sekunden warten, dann den Node erneut öffnen.
+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).
+
+Der Button **Kopplung zurücksetzen** entfernt alle gekoppelten Controller und startet die Kopplungs-Ankündigung neu.
+
+## Node-PINs
+
+Wenn du die Input/Output-PINs des Nodes aktivierst:
+
+- **Input**: aktualisiere den Matter-Zustand eines virtuellen Geräts aus dem Flow, ohne über den KNX-Bus zu gehen: `msg.payload = { device: "Küchenlicht", function: "onoff", value: true }` (`device` akzeptiert den Namen oder die interne ID; `function` ist eine von `onoff`, `level`, `position`, `temperature`, `humidity`, `illuminance`, `occupancy`, `contact`, `currenttemp`, `setpoint`). Nützlich, um im Flow berechnete Werte (z.B. einen virtuellen Sensor) für Alexa & Co. bereitzustellen.
+- **Output**: Jeder von einem Matter-Controller empfangene Befehl wird an den Flow weitergeleitet: `msg.topic` = Gerätename, `msg.payload` = Wert, `msg.matter` = der rohe Befehl. Geräte ohne Befehls-GA werden zu **Nur-Flow-Geräten**: Der Befehl erreicht deinen Flow und du entscheidest, was damit geschieht.
+
+## Hinweise
+
+- Der Node-RED-Host muss **IPv6 link-local** aktiviert haben (Standard-Matter-Anforderung) und vom Controller im lokalen Netzwerk erreichbar sein.
+- Die Bridge-Identität wird in `knxultimatestorage/matter` im Node-RED-Benutzerverzeichnis gespeichert: Re-Deploys erfordern KEINE neue Kopplung.
+- Umbenennungen und neue Geräte werden von den Controllern automatisch übernommen; entfernte Geräte verschwinden aus den Apps.
+</script>

package/nodes/locales/de/knxUltimateMatterBridge.json

@@ -0,0 +1,80 @@
+{
+  "knxUltimateMatterBridge": {
+    "title": "Matter Bridge (BETA)",
+    "bridge_name": "Name der Matter-Bridge",
+    "port": "Port",
+    "devices_help": "Füge die KNX-Geräte hinzu, die über Matter bereitgestellt werden sollen. Der \"Name\" ist der, den Alexa/Google/Apple anzeigen und für Sprachbefehle verwenden. Befehls-GA = wird geschrieben, wenn der Assistent einen Befehl sendet; Status-GA = wird vom Bus gelesen, um die App aktuell zu halten.",
+    "read_status_startup": "Status-Gruppenadressen beim Start lesen",
+    "opt_yes": "Ja",
+    "opt_no": "Nein",
+    "node_pins": "Node Input/Output PINs",
+    "node_pins_hide": "Ausblenden",
+    "node_pins_show": "Input/Output-PINs anzeigen",
+    "fields": {
+      "type": "Gerätetyp",
+      "name": "Name (von Alexa & Co. angezeigt)",
+      "name_placeholder": "z.B. Küchenlicht",
+      "invert": "Position % invertieren"
+    },
+    "functions": {
+      "fn_onoff_cmd": "Ein/Aus Befehls-GA",
+      "fn_onoff_status": "Ein/Aus Status-GA",
+      "fn_level_cmd": "Dimmen % Befehls-GA",
+      "fn_level_status": "Dimmen % Status-GA",
+      "fn_sensor_ga": "Sensor Status-GA",
+      "fn_updown": "Auf/Ab Befehls-GA",
+      "fn_stop": "Stopp Befehls-GA",
+      "fn_position_cmd": "Position % Befehls-GA",
+      "fn_position_status": "Position % Status-GA",
+      "fn_currenttemp": "GA aktuelle Temperatur",
+      "fn_setpoint_cmd": "Sollwert Befehls-GA",
+      "fn_setpoint_status": "Sollwert Status-GA",
+      "fn_rgb_cmd": "RGB-Farbe Befehls-GA (DPT 232.600)",
+      "fn_rgb_status": "RGB-Farbe Status-GA (DPT 232.600)",
+      "fn_ct_cmd": "Farbtemperatur Befehls-GA (Kelvin)",
+      "fn_ct_status": "Farbtemperatur Status-GA (Kelvin)",
+      "fn_smoke_ga": "Rauchalarm Status-GA",
+      "fn_co_ga": "CO-Alarm Status-GA (optional)",
+      "fn_leak_ga": "Leckage Status-GA",
+      "fn_co2_ga": "CO2 Status-GA (ppm, DPT 9.008)",
+      "fn_fanspeed_cmd": "Lüftergeschwindigkeit % Befehls-GA",
+      "fn_fanspeed_status": "Lüftergeschwindigkeit % Status-GA"
+    },
+    "types": {
+      "onofflight": "Ein/Aus-Licht",
+      "dimmablelight": "Dimmbares Licht",
+      "rgblight": "RGB-Farblicht",
+      "colortemperaturelight": "Tunable-White-Licht (Farbtemperatur)",
+      "onoffplug": "Steckdose (Ein/Aus)",
+      "temperaturesensor": "Temperatursensor",
+      "humiditysensor": "Feuchtesensor",
+      "lightsensor": "Lichtsensor (Lux)",
+      "occupancysensor": "Präsenzsensor",
+      "contactsensor": "Kontaktsensor",
+      "windowcovering": "Rollladen / Jalousie",
+      "thermostat": "Thermostat (Heizung)",
+      "fan": "Ventilator / Lüftung",
+      "smokecoalarm": "Rauch-/CO-Melder",
+      "waterleakdetector": "Wasserleckmelder",
+      "airqualitysensor": "Luftqualitätssensor (CO2)",
+      "robotvacuum": "Saugroboter (nur Flow, über Node-PINs)"
+    },
+    "pairing": {
+      "title": "Kopplung (Alexa, Google Home, Apple Home...)",
+      "not_running": "Die Matter-Bridge läuft noch nicht. Deployen, ein paar Sekunden warten und dann auf Aktualisieren klicken.",
+      "commissioned": "Bridge mit diesen Controllern gekoppelt:",
+      "awaiting": "Warte auf Kopplung. Scanne den QR-Code oder gib den manuellen Code in deiner Matter-App ein:",
+      "qr_link": "QR-Code im Browser öffnen",
+      "deploy_first": "Bitte zuerst diesen 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."
+    }
+  },
+  "common": {
+    "ga": "GA",
+    "dpt": "DPT",
+    "name": "Name",
+    "knx_gw": "KNX GW"
+  }
+}

package/nodes/locales/de/knxUltimateMatterDevice.html

@@ -0,0 +1,56 @@
+<script type="text/markdown" data-help-name="knxUltimateMatterDevice">
+# Matter-Gerät (BETA)
+
+> Dieser Node ist in **BETA**: Er funktioniert, aber Details können sich zwischen Releases noch ändern.
+
+## Übersicht
+
+Der Matter Device Node verbindet ein **Matter-Gerät** mit **KNX-Gruppenadressen**. Der Node arbeitet über den Konfigurations-Node *Matter Controller*, der die Geräte in seine eigene Matter-Fabric kommissioniert.
+
+- **Steuere** jedes gekoppelte Matter-Gerät vom KNX-Bus aus (Ein/Aus, Dimmen, Rollläden, Thermostate, Schlösser, ...).
+- **Verfolge** jedes Attribut des Geräts auf KNX-Gruppenadressen (Statusmeldungen, Sensoren, Leistungsmessung, Batterie...).
+- Vollständig generisch: Die Zuordnungsliste wird aus den **realen Endpoints/Clustern** des Geräts aufgebaut.
+
+## Konfiguration
+
+|Feld|Beschreibung|
+|--|--|
+| KNX GW | KNX-Gateway für die Telegramme |
+| Matter Ctrl | Der Matter-Controller-Konfigurations-Node (dort werden die Geräte gekoppelt) |
+| Gerät | Wähle das gekoppelte Matter-Gerät aus der Autovervollständigung |
+| Zuordnungen | Eine Zeile pro Zuordnung Gruppenadresse ↔ Matter-Cluster |
+| Status beim Start lesen | Wenn aktiviert, sendet der Node die aktuellen zwischengespeicherten Werte beim Deploy/Verbinden |
+| Node Input/Output PINs | Aktiviert die Node-RED-Pins für den rohen Matter-Zugriff |
+
+## Zuordnungen
+
+Die Ziel-Liste zeigt die unterstützten Funktionen mit verständlichen Namen wie *"Ein/Aus-Schalter"* oder *"Momentanleistung (W)"*, gefiltert nach dem, was das Gerät wirklich bereitstellt, mit dem aktuellen Wert in eckigen Klammern.
+
+Jede Zuordnungszeile hat eine **Richtung**:
+
+- **KNX → Matter (Befehl)**: Ein Telegramm auf der Gruppenadresse ruft einen Matter-Cluster-Befehl auf oder schreibt ein Attribut. Beispiel: GA `1/1/1` DPT 1.001 → `OnOff.on/off` (der boolesche Wert wählt automatisch Ein oder Aus).
+- **Matter → KNX (Status)**: Wenn sich das abonnierte Matter-Attribut ändert, wird sein Wert konvertiert und auf die Gruppenadresse geschrieben. `GroupValue_Read`-Anfragen werden mit dem zwischengespeicherten Wert beantwortet.
+
+Die gängigen Cluster werden automatisch in KNX-freundliche Werte konvertiert:
+
+|Cluster|Konvertierung|
+|--|--|
+| OnOff | boolesch (DPT 1.001) |
+| LevelControl | 0-254 ↔ Prozent (DPT 5.001) |
+| WindowCovering | percent100ths ↔ Prozent (DPT 5.001), Auf/Ab (DPT 1.008) |
+| ColorControl | Mired ↔ Kelvin (DPT 7.600) |
+| Thermostat | Zenti-°C ↔ °C (DPT 9.001) |
+| Temperatur/Feuchte | Zenti-Einheiten ↔ Einheiten (DPT 9.001/9.007) |
+| Beleuchtungsstärke | Log-Skala ↔ Lux (DPT 9.004) |
+| PowerSource | Halb-Prozent ↔ Batterie-Prozent (DPT 5.001) |
+| Elektrische Leistung/Energie | mW ↔ W (DPT 14.056), mWh ↔ kWh (DPT 13.013) |
+
+Andere Cluster/Attribute werden unverändert durchgereicht; der gewählte DPT übernimmt die finale KNX-Kodierung.
+
+## Node-PINs
+
+Wenn du die Node-PINs aktivierst:
+
+- **Input**: sende rohe Befehle: `msg.payload = { endpointId: 1, clusterId: 6, command: "toggle" }` oder Attribut-Schreibzugriffe: `msg.payload = { endpointId: 1, clusterId: 8, attribute: "onLevel", value: 128 }`
+- **Output**: empfängt jede Attributänderung (`msg.matter` enthält das komplette Ereignis) und jedes Cluster-Ereignis (Tastendrücke usw.).
+</script>

package/nodes/locales/de/knxUltimateMatterDevice.json

@@ -0,0 +1,109 @@
+{
+  "knxUltimateMatterDevice": {
+    "title": "Matter-Gerät (BETA)",
+    "paletteLabel": "Matter Device (BETA)",
+    "matter_controller": "Matter Ctrl",
+    "matter_device": "Gerät",
+    "device_placeholder": "Klicken, um ein gekoppeltes Matter-Gerät auszuwählen",
+    "mapping_help": "Füge pro Zuordnung eine Zeile hinzu. \"KNX → Matter\" ruft einen Cluster-Befehl auf (oder schreibt ein Attribut), wenn ein Telegramm auf der Gruppenadresse eintrifft. \"Matter → KNX\" schreibt den Attributwert bei jeder Änderung auf die Gruppenadresse (Leseanfragen werden mit dem zwischengespeicherten Wert beantwortet).",
+    "select_target": "-- Matter-Ziel auswählen --",
+    "stored_target": "Gespeichert",
+    "read_status_startup": "Status beim Start lesen",
+    "opt_yes_emit": "Ja, und KNX-Telegramme senden.",
+    "opt_no": "Nein",
+    "node_pins": "Node Input/Output PINs",
+    "node_pins_hide": "Ausblenden",
+    "node_pins_show": "Input/Output-PINs anzeigen",
+    "direction": {
+      "command": "KNX → Matter (Befehl)",
+      "status": "Matter → KNX (Status)"
+    },
+    "fields": {
+      "direction": "Richtung",
+      "target": "Matter Endpoint / Cluster / Ziel",
+      "ga": "Gruppenadresse",
+      "dpt": "DPT",
+      "ganame": "Name"
+    },
+    "no_simple_targets": "Keine unterstützten Funktionen auf diesem Gerät gefunden (oder das Gerät ist noch nicht verbunden).",
+    "endpoint": "Endpoint",
+    "friendly": {
+      "onoff_switch": "Ein/Aus-Schalter (ein-/ausschalten)",
+      "onoff_toggle": "Umschalten (Toggle)",
+      "onoff_state": "Ein/Aus-Status",
+      "level_set": "Helligkeit / Stufe setzen (%)",
+      "level_state": "Aktuelle Helligkeit / Stufe (%)",
+      "colortemp_set": "Farbtemperatur setzen (Kelvin)",
+      "colortemp_state": "Aktuelle Farbtemperatur (Kelvin)",
+      "cover_updown": "Rollladen Auf/Ab",
+      "cover_stop": "Rollladen Stopp",
+      "cover_position_set": "Rollladen auf Position fahren (%)",
+      "cover_position_state": "Aktuelle Rollladenposition (%)",
+      "cover_tilt_set": "Lamellen neigen (%)",
+      "cover_tilt_state": "Aktuelle Lamellenneigung (%)",
+      "thermo_localtemp": "Raumtemperatur (°C)",
+      "thermo_heatsp_set": "Heiz-Sollwert setzen (°C)",
+      "thermo_coolsp_set": "Kühl-Sollwert setzen (°C)",
+      "thermo_heatsp_state": "Heiz-Sollwert (°C)",
+      "thermo_coolsp_state": "Kühl-Sollwert (°C)",
+      "fan_speed_set": "Lüftergeschwindigkeit setzen (%)",
+      "fan_speed_state": "Aktuelle Lüftergeschwindigkeit (%)",
+      "lock_cmd": "Tür ver-/entriegeln",
+      "lock_state": "Schlossstatus (verriegelt)",
+      "temp_measured": "Gemessene Temperatur (°C)",
+      "humidity_measured": "Relative Luftfeuchte (%)",
+      "illuminance_measured": "Beleuchtungsstärke (Lux)",
+      "occupancy_state": "Anwesenheit erkannt",
+      "contact_state": "Kontaktstatus (geschlossen/offen)",
+      "battery_percent": "Batteriestand (%)",
+      "power_active": "Momentanleistung (W)",
+      "power_voltage": "Spannung (V)",
+      "power_current": "Strom (A)",
+      "energy_imported": "Energieverbrauch (kWh)",
+      "identify_cmd": "Gerät identifizieren (blinken)",
+      "switch_position": "Tastenposition"
+    },
+    "devtype": {
+      "onofflight": "Ein/Aus-Licht",
+      "dimmablelight": "Dimmbares Licht",
+      "colortemperaturelight": "Licht mit Farbtemperatur",
+      "extendedcolorlight": "Farblicht",
+      "onoffpluginunit": "Steckdose (Ein/Aus)",
+      "dimmablepluginunit": "Steckdose (dimmbar)",
+      "smartplug": "Smarte Steckdose",
+      "contactsensor": "Kontaktsensor",
+      "lightsensor": "Lichtsensor",
+      "occupancysensor": "Präsenzsensor",
+      "temperaturesensor": "Temperatursensor",
+      "humiditysensor": "Feuchtesensor",
+      "pressuresensor": "Drucksensor",
+      "flowsensor": "Durchflusssensor",
+      "doorlock": "Türschloss",
+      "windowcovering": "Rollladen/Jalousie",
+      "thermostat": "Thermostat",
+      "fan": "Ventilator",
+      "genericswitch": "Taster/Schalter",
+      "airqualitysensor": "Luftqualitätssensor",
+      "smokecoalarm": "Rauch-/CO-Melder",
+      "waterleakdetector": "Wasserleckmelder",
+      "roomairconditioner": "Klimagerät",
+      "airpurifier": "Luftreiniger",
+      "speaker": "Lautsprecher",
+      "pumpcontroller": "Pumpe",
+      "onofflightswitch": "Lichtschalter",
+      "dimmerswitch": "Dimmerschalter",
+      "colordimmerswitch": "Farbdimmerschalter",
+      "powersource": "Stromversorgung",
+      "electricalsensor": "Elektrischer Sensor",
+      "bridgednode": "Bridged-Gerät",
+      "aggregator": "Bridge/Aggregator",
+      "rootnode": "Root-Node"
+    }
+  },
+  "common": {
+    "ga": "GA",
+    "dpt": "DPT",
+    "name": "Name",
+    "knx_gw": "KNX GW"
+  }
+}

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

@@ -0,0 +1,25 @@
+<script type="text/markdown" data-help-name="matter-config">
+# Matter Controller
+
+## Übersicht
+
+Dieser Konfigurations-Node ist ein vollwertiger **Matter-Controller**: Er erstellt seine eigene Matter-*Fabric* und koppelt (kommissioniert) deine Matter-Geräte. Die gekoppelten Geräte stehen anschließend den **Matter Device**-Nodes zur Verfügung, die sie auf KNX-Gruppenadressen abbilden.
+
+Der Controller kommuniziert mit den Geräten über das **IP-Netzwerk** (WLAN, Ethernet oder Thread über einen Border Router). Bluetooth-Kommissionierung wird nicht unterstützt: Das Gerät muss bereits im Netzwerk erreichbar sein.
+
+## Ein Gerät koppeln
+
+1. Zuerst diesen Konfigurations-Node **deployen** (der Controller muss laufen).
+2. Den Node erneut öffnen und den **Kopplungscode** eingeben: entweder den 11-stelligen manuellen Code (z.B. `3497-011-2332`) oder den QR-Code-Inhalt (`MT:....`).
+3. Auf **KOPPELN** klicken. Die Kommissionierung kann bis zu einer Minute dauern.
+
+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.
+
+## 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.
+
+## 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).
+</script>