node-red-contrib-knx-ultimate 6.0.8 → 6.0.10

package/CHANGELOG.md

@@ -6,8 +6,10 @@
 
 # CHANGELOG
 
-**Version 6.0.8** - July 2026<br/>
+**Version 6.0.10** - July 2026<br/>
 
+- **Matter nodes — crash containment**: asynchronous bridge state updates, controller client callbacks, engine errors, startup/watchdog timers and the controller command queue are now guarded so rejected promises and EventEmitter errors are reported instead of becoming uncaught exceptions or unhandled rejections capable of stopping Node-RED.<br/>
+- **Matter Controller — post-commission naming**: assigning a name immediately after pairing now waits for matter.js to finish exposing the root `BasicInformation` cluster. Root endpoint 0 is resolved explicitly, preventing the misleading `BasicInformation cluster not found` warning seen when re-adding devices such as Shelly Plug.<br/>
 - **Control Matter from KNX — profile deploy crash**: Door Lock and multi-purpose profiles now expose the KNX status callback before registering with `knxUltimate-config`, preventing `_Node.setNodeStatus is not a function` during deploy.<br/>
 - **Control Matter from KNX — flow PIN persistence**: the **Node Input/Output PINs** selection is no longer overwritten from the KNX gateway presence when reopening the editor. The saved choice remains authoritative and `inputs`/`outputs` are updated coherently on save.<br/>
 - **Matter terminology cleanup**: removed leftover Philips Hue wording from Matter controller labels, notifications, runtime status, localized strings and help. Backward-compatible saved configuration keys remain unchanged.<br/>

package/nodes/knxUltimateMatterBridge.js

@@ -157,6 +157,8 @@ module.exports = function (RED) {
     }
 
     const safeSendToKNX = (telegram, context = 'write') => {
+      // Matter command handlers are asynchronous and shared by many endpoints. Guard
+      // each KNX dispatch so one unavailable gateway cannot break other device routes.
       try {
         if (!node.serverKNX || typeof node.serverKNX.sendKNXTelegramToKNXEngine !== 'function') {
           node.setNodeStatus({ fill: 'red', shape: 'dot', text: `KNX server missing (${context})` })
@@ -168,6 +170,24 @@ module.exports = function (RED) {
       }
     }
 
+    const reportMatterError = (context, error) => {
+      const message = error?.message || String(error)
+      node.setNodeStatus({ fill: 'red', shape: 'dot', text: `${context} ${message}`, payload: '' })
+      try { RED.log.error(`knxUltimateMatterBridge: ${context}: ${message}`) } catch (logError) { /* empty */ }
+    }
+
+    const safeSetDeviceState = async (fn, value, context) => {
+      try {
+        if (!node.serverMatterBridge || typeof node.serverMatterBridge.setDeviceState !== 'function') {
+          throw new Error('Matter bridge unavailable')
+        }
+        return await node.serverMatterBridge.setDeviceState(node.matterDeviceId, fn, value)
+      } catch (error) {
+        reportMatterError(context, error)
+        return false
+      }
+    }
+
     const clearCoverStatusTimer = () => {
       if (coverStatusTimer !== null) {
         clearTimeout(coverStatusTimer)
@@ -225,7 +245,7 @@ module.exports = function (RED) {
       clearCoverArrivalTimer()
 
       if (node.coverUpdateMode === 'optimistic') {
-        node.serverMatterBridge.setDeviceState(node.matterDeviceId, 'position', requestedPosition)
+        safeSetDeviceState('position', requestedPosition, 'Matter position update error')
         return
       }
 
@@ -239,7 +259,7 @@ module.exports = function (RED) {
       }
       coverArrivalTimer = setTimeout(() => {
         coverArrivalTimer = null
-        node.serverMatterBridge.setDeviceState(node.matterDeviceId, 'position', requestedPosition)
+        safeSetDeviceState('position', requestedPosition, 'Matter position fallback error')
         node.setNodeStatus({ fill: 'yellow', shape: 'ring', text: 'No exact KNX confirmation in time, assuming arrived at', payload: requestedPosition })
       }, COVER_ARRIVAL_FALLBACK_MS)
     }
@@ -339,7 +359,7 @@ module.exports = function (RED) {
           try {
             const value = dptlib.fromBuffer(msg.knx.rawValue, dptlib.resolve(route.dpt))
             if (value === undefined || value === null) return
-            node.serverMatterBridge.setDeviceState(node.matterDeviceId, route.fn, value)
+            safeSetDeviceState(route.fn, value, 'KNX->Matter error')
             if (node.deviceType === 'windowcovering' && route.fn === 'position') { clearCoverStatusTimer(); clearCoverArrivalTimer() }
             node.setNodeStatus({ fill: 'blue', shape: 'dot', text: `KNX->Matter ${route.fn}`, payload: value })
           } catch (error) {
@@ -389,7 +409,7 @@ module.exports = function (RED) {
 
     // Flow input pin: updates the Matter state of this device without going through the KNX bus.
     // msg.payload = { function: 'onoff'|'level'|'position'|'temperature'|..., value: ... }
-    node.on('input', (msg, send, done) => {
+    node.on('input', async (msg, send, done) => {
       if (!node.enableNodePINS) {
         if (done) done()
         return
@@ -399,7 +419,8 @@ module.exports = function (RED) {
         const fn = (payload.function || payload.fn || '').toString().trim()
         if (fn === '' || payload.value === undefined) throw new Error('msg.payload must be { function, value }')
         if (node.serverMatterBridge === undefined) throw new Error('No Matter bridge selected')
-        node.serverMatterBridge.setDeviceState(node.matterDeviceId, fn, payload.value)
+        const updated = await safeSetDeviceState(fn, payload.value, 'Flow->Matter error')
+        if (!updated) throw new Error('Matter state update failed')
         node.setNodeStatus({ fill: 'green', shape: 'dot', text: `Flow->Matter ${fn}`, payload: payload.value })
         if (done) done()
       } catch (error) {

package/nodes/knxUltimateMatterControllerDevice.js

@@ -23,6 +23,10 @@ module.exports = function (RED) {
 
     let matterCapabilities = {}
     try { matterCapabilities = JSON.parse(config.matterDeviceCapabilities || '{}') } catch (error) { /* empty */ }
+    // Non-light endpoints are handled by isolated profiles. A successful profile setup
+    // owns the complete node lifecycle and deliberately bypasses the legacy light path.
+    // Keeping this boundary here prevents new device types from changing established
+    // light behaviour or its saved configuration contract.
     if (setupMatterControllerProfile(matterCapabilities.profile, RED, node, config)) return
 
     // Matter engine (adapter). The manager is resolved lazily at each write, because

package/nodes/matter-config.js

@@ -31,7 +31,8 @@ module.exports = (RED) => {
     node.matterInstanceId = `knxultimate-matter-${node.id.replace(/[^a-zA-Z0-9]/g, '')}`
     node.matterStoragePath = path.join(RED.settings.userDir || '.', 'knxultimatestorage', 'matter')
 
-    // Helper like the hue-config one
+    // Expose controller connectivity without copying engine state into the config node.
+    // Consumers read the latest value lazily, including during asynchronous startup.
     Object.defineProperty(node, 'linkStatus', {
       get: function () {
         return node.matterManager?.matterConnectionStatus ?? 'disconnected'
@@ -39,9 +40,14 @@ module.exports = (RED) => {
     })
 
     const safeClientCall = (client, fn, label) => {
+      // One faulty device node must never interrupt event delivery to the remaining
+      // Matter clients registered on this shared controller connection.
       try {
         if (!client || typeof fn !== 'function') return
-        fn()
+        const result = fn()
+        if (result && typeof result.catch === 'function') {
+          result.catch((error) => node.sysLogger?.warn(`Matter client ${label} async error: ${error.message}`))
+        }
       } catch (error) {
         node.sysLogger?.warn(`Matter client ${label} error: ${error.message}`)
       }
@@ -129,6 +135,11 @@ module.exports = (RED) => {
         })
       })
 
+      // EventEmitter treats an unhandled "error" event as a process exception.
+      node.matterManager.on('error', (error) => {
+        node.sysLogger?.error(`Matter controller engine error: ${error?.message || error}`)
+      })
+
       try {
         await node.matterManager.Connect()
       } catch (error) {
@@ -147,8 +158,12 @@ module.exports = (RED) => {
               node.sysLogger?.error(`Errore matter-config: node.startWatchdogTimer: ${error.message}`)
             }
           }
-          await node.startWatchdogTimer()
-        })()
+          try {
+            await node.startWatchdogTimer()
+          } catch (error) {
+            node.sysLogger?.error(`matter-config: watchdog reschedule error: ${error.message}`)
+          }
+        })().catch((error) => node.sysLogger?.error(`matter-config: watchdog callback error: ${error.message}`))
       }, 60000)
     }
 
@@ -162,11 +177,11 @@ module.exports = (RED) => {
           node.sysLogger?.error(`matter-config: startup error: ${error.message}`)
         }
         try {
-          node.startWatchdogTimer()
+          await node.startWatchdogTimer()
         } catch (error) {
           node.sysLogger?.error(`matter-config: watchdog start error: ${error.message}`)
         }
-      })()
+      })().catch((error) => node.sysLogger?.error(`matter-config: startup callback error: ${error.message}`))
     }, 5000)
 
     // Functions called from the nodes and the admin endpoints ----------------------------------------

package/nodes/matterbridge-config.js

@@ -53,7 +53,10 @@ module.exports = (RED) => {
     const safeClientCall = (client, fn, label) => {
       try {
         if (!client || typeof fn !== 'function') return
-        fn()
+        const result = fn()
+        if (result && typeof result.catch === 'function') {
+          result.catch((error) => node.sysLogger?.warn(`Matter bridge client ${label} async error: ${error.message}`))
+        }
       } catch (error) {
         node.sysLogger?.warn(`Matter bridge client ${label} error: ${error.message}`)
       }
@@ -80,6 +83,10 @@ module.exports = (RED) => {
 
     const bindEngineEvents = (engine) => {
       engine.removeAllListeners()
+      // An EventEmitter "error" without a listener terminates Node-RED.
+      engine.on('error', (error) => {
+        node.sysLogger?.error(`Matter bridge engine error: ${error?.message || error}`)
+      })
       // Matter -> KNX: a controller (Alexa...) sent a command to a bridged device.
       // Route it to the device node that owns that Matter device.
       engine.on('command', (command) => {
@@ -109,7 +116,7 @@ module.exports = (RED) => {
           } catch (error) {
             node.sysLogger?.warn(`matterbridge-config: reconcile error: ${error.message}`)
           }
-        })()
+        })().catch((error) => node.sysLogger?.warn(`matterbridge-config: reconcile callback error: ${error.message}`))
       }, 1500)
     }
 
@@ -160,7 +167,7 @@ module.exports = (RED) => {
       (async () => {
         if (closing) return
         await ensureEngineStarted()
-      })()
+      })().catch((error) => node.sysLogger?.error(`matterbridge-config: startup callback error: ${error.message}`))
     }, 5000)
 
     // Functions called from the device nodes -----------------------------------------

package/nodes/utils/matterControllerProfiles/doorLock.js

@@ -28,12 +28,16 @@ const lockStateName = (value) => {
 }
 
 const lockStateToBoolean = (value) => {
+  // KNX DPT 1 can represent only two states. Do not collapse transitional or
+  // ambiguous Matter lock states into a potentially unsafe locked/unlocked value.
   if (Number(value) === LOCK_STATE.LOCKED) return true
   if (Number(value) === LOCK_STATE.UNLOCKED) return false
   return undefined
 }
 
 const setupDoorLockProfile = (RED, node, config) => {
+  // Profiles initialize the same flags consumed by knxUltimate-config as ordinary
+  // KNX nodes. In particular, listenallga must remain enabled for handleSend calls.
   node.name = config.name || node.matterDeviceName || 'Control Matter door lock from KNX'
   node.topic = node.name
   node.notifyreadrequest = true
@@ -59,6 +63,8 @@ const setupDoorLockProfile = (RED, node, config) => {
   node.setNodeStatus = ({ fill = 'grey', shape = 'ring', text = '' } = {}) => setStatus(fill, shape, text)
 
   const commandArgs = () => {
+    // Matter represents the remote credential as bytes. Keep the PIN in Node-RED's
+    // credential store and materialize the Buffer only for the outgoing command.
     const pin = String(node.credentials?.doorLockPin || '')
     return pin === '' ? {} : { pinCode: Buffer.from(pin, 'utf8') }
   }
@@ -95,6 +101,8 @@ const setupDoorLockProfile = (RED, node, config) => {
     node.currentLockState = Number(rawState)
     const state = lockStateToBoolean(rawState)
     const name = lockStateName(rawState)
+    // Attribute reports update KNX state only; they never enqueue a Matter command.
+    // This one-way path is the primary feedback-loop guard for Door Lock endpoints.
     if (state !== undefined) writeKnxState(state)
     sendFlow(source, state, rawState)
     setStatus(state === undefined ? 'yellow' : 'blue', state === undefined ? 'ring' : 'dot', `Matter: ${name}`)
@@ -106,6 +114,8 @@ const setupDoorLockProfile = (RED, node, config) => {
     const capabilities = (() => {
       try { return JSON.parse(config.matterDeviceCapabilities || '{}') } catch (error) { return {} }
     })()
+    // Never invent optional operations: the editor persists the commands actually
+    // advertised by this endpoint and runtime validation enforces that snapshot.
     if (locked && capabilities.lockDoor === false) throw new Error('The Matter endpoint does not expose lockDoor')
     if (!locked && capabilities.unlockDoor === false) throw new Error('The Matter endpoint does not expose unlockDoor')
     const queued = manager.writeMatterQueueAdd({
@@ -157,6 +167,8 @@ const setupDoorLockProfile = (RED, node, config) => {
   node.handleMatterClusterEvent = () => {}
   node.handleMatterNodeInitialized = () => {
     try {
+      // The controller engine already caches the initial attribute read. Reusing that
+      // value avoids an extra request and publishes startup state through the same path.
       const value = node.serverMatter?.matterManager?.getCachedAttribute(
         node.matterNodeId,
         node.matterEndpointId,

package/nodes/utils/matterControllerProfiles/index.js

@@ -13,7 +13,10 @@ const PROFILE_SETUPS = Object.freeze({
 
 const setupMatterControllerProfile = (profile, RED, node, config) => {
   const setup = PROFILE_SETUPS[profile]
+  // Returning false is significant: the caller must continue through the unchanged
+  // Matter-light implementation when no specialized profile claims the endpoint.
   if (typeof setup !== 'function') return false
+  // A profile that returns successfully owns input, close, KNX and Matter handlers.
   setup(RED, node, config)
   return true
 }

package/nodes/utils/matterControllerProfiles/mappedEndpoint.js

@@ -13,6 +13,8 @@ const isValidGroupAddress = (value) => {
 const parseMappings = (value) => {
   try {
     const parsed = Array.isArray(value) ? value : JSON.parse(value || '[]')
+    // Ignore incomplete or stale editor rows. Only mappings with a valid KNX address,
+    // resolvable DPT and explicit Matter target are allowed into runtime routing.
     return parsed.filter((mapping) => {
       if (!mapping || !isValidGroupAddress(mapping.ga) || !mapping.target || !mapping.dpt) return false
       try { dptlib.resolve(mapping.dpt); return true } catch (error) { return false }
@@ -59,12 +61,16 @@ const setupMappedEndpointProfile = (RED, node, config) => {
   const sendCached = (mapping, outputtype) => {
     const currentManager = manager()
     if (!currentManager) return false
+    // Cached reports are authoritative for KNX read responses and startup publication;
+    // reading them must not generate a new Matter write or command.
     const value = currentManager.getCachedAttribute(node.matterNodeId, mapping.endpointId, mapping.clusterId, mapping.target)
     return sendKnx(mapping, matterToKnx(mapping.clusterId, mapping.target, value), outputtype)
   }
   const enqueue = (mapping, value) => {
     const currentManager = manager()
     if (!currentManager) throw new Error('Matter controller not ready')
+    // Conversion happens before queueing so the Matter manager receives a canonical,
+    // cluster-specific command or attribute write rather than a raw KNX payload.
     const action = knxToMatter(mapping, value)
     if (!action) return
     const queued = currentManager.writeMatterQueueAdd({
@@ -98,6 +104,8 @@ const setupMappedEndpointProfile = (RED, node, config) => {
   }
   node.handleSendMatter = (event) => {
     try {
+      // Attribute reports travel only toward KNX/flow. Keeping feedback separate from
+      // enqueue() prevents programmatic state synchronization from echoing to Matter.
       if (String(event?.nodeId) !== String(node.matterNodeId) || Number(event?.endpointId) !== Number(node.matterEndpointId)) return
       node.mappings.filter((mapping) => mapping.direction === 'status' && Number(mapping.clusterId) === Number(event.clusterId) && mapping.target === event.attributeName).forEach((mapping) => {
         sendKnx(mapping, matterToKnx(event.clusterId, event.attributeName, event.value))
@@ -110,11 +118,15 @@ const setupMappedEndpointProfile = (RED, node, config) => {
     }
   }
   node.handleMatterClusterEvent = (event) => {
+    // Cluster events have no implicit KNX mapping. They are exposed as raw flow output
+    // only when the user explicitly enables the node pins.
     if (enablePins && String(event?.nodeId) === String(node.matterNodeId) && Number(event?.endpointId) === Number(node.matterEndpointId)) {
       node.send({ topic: `${event.clusterId}.${event.eventName}`, payload: event.events, matter: event })
     }
   }
   node.handleMatterNodeInitialized = () => {
+    // nodeInitialized can be emitted more than once while sessions recover. Bound the
+    // startup publication to avoid duplicate KNX telegram bursts during reconnects.
     if (config.readStatusAtStartup === 'no' || Date.now() - lastInitialReadTs < 5000) return
     let sent = 0
     node.mappings.filter((mapping) => mapping.direction === 'status').forEach((mapping) => { if (sendCached(mapping, 'write')) sent += 1 })

package/nodes/utils/matterEngine.mjs

@@ -37,7 +37,11 @@ class classMatter extends EventEmitter {
     this.exitAllQueues = false
     this._api = null // Lazy loaded matter.js exports
     this._logThrottle = new Map()
-    if (startQueue) this.handleQueue()
+    if (startQueue) {
+      // The queue is intentionally fire-and-forget, but its Promise must always be
+      // observed so an unexpected loop failure cannot become an unhandled rejection.
+      this.handleQueue().catch((error) => this._log('error', `classMatter: queue loop: ${error.message}`))
+    }
   }
 
   _log = (level, message) => {
@@ -443,6 +447,15 @@ class classMatter extends EventEmitter {
   }
 
   _findEndpoint = (node, _endpointId) => {
+    // getDevices() can expose only functional/bridged endpoints while the root endpoint
+    // lives behind getRootEndpoint(). Resolve endpoint 0 explicitly for node clusters
+    // such as BasicInformation and GeneralCommissioning.
+    if (Number(_endpointId) === 0 && typeof node?.getRootEndpoint === 'function') {
+      try {
+        const root = node.getRootEndpoint()
+        if (root !== undefined) return root
+      } catch (error) { /* The legacy endpoint structure may still be initializing. */ }
+    }
     return this._getAllEndpoints(node).find((ep) => Number(ep.number) === Number(_endpointId))
   }
 
@@ -564,12 +577,21 @@ class classMatter extends EventEmitter {
     if (label.length > 64) throw new Error('Matter device name is too long')
     const node = this.pairedNodes.get(_nodeIdString)
     if (node === undefined) throw new Error(`Matter node ${_nodeIdString} unknown or not yet connected`)
+    // commission() attaches the PairedNode before its first wildcard read/subscription
+    // has necessarily built the legacy endpoint structure. A user-supplied name is
+    // applied immediately after commissioning, so wait briefly for BasicInformation
+    // instead of reporting a misleading permanent-cluster warning.
+    const deadline = Date.now() + 10000
     let clusterClient
-    try {
-      if (typeof node.getRootClusterClient === 'function') clusterClient = node.getRootClusterClient(this._api.BasicInformation)
-    } catch (error) { /* empty */ }
-    if (clusterClient === undefined) clusterClient = this._findClusterClient(node, 0, 40) // BasicInformation on the root endpoint
-    if (clusterClient === undefined) throw new Error(`BasicInformation cluster not found on node ${_nodeIdString}`)
+    do {
+      try {
+        if (typeof node.getRootClusterClient === 'function') clusterClient = node.getRootClusterClient(this._api.BasicInformation)
+      } catch (error) { /* Endpoint structure is still initializing. */ }
+      if (clusterClient === undefined) clusterClient = this._findClusterClient(node, 0, 40) // BasicInformation on the root endpoint
+      if (clusterClient !== undefined) break
+      await pleaseWait(100)
+    } while (Date.now() < deadline)
+    if (clusterClient === undefined) throw new Error(`BasicInformation cluster was not available on node ${_nodeIdString} after initialization`)
     const attribute = clusterClient.attributes.nodeLabel
     if (attribute === undefined) throw new Error(`nodeLabel attribute not found on node ${_nodeIdString}`)
     await attribute.set(label)

package/package.json

@@ -3,7 +3,7 @@
   "engines": {
     "node": ">=20.18.1"
   },
-  "version": "6.0.8",
+  "version": "6.0.10",
   "description": "Control your KNX and KNX Secure intallation via Node-Red! A bunch of KNX nodes, with integrated Philips HUE control, ETS group address importer, KNX AI for diagnosticsand KNX routing between interfaces. Easy to use and highly configurable.",
   "files": [
     "nodes/",
@@ -145,4 +145,4 @@
     "vite": "^7.1.3",
     "vue": "^3.5.21"
   }
-}
+}