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

package/CHANGELOG.md

@@ -6,8 +6,9 @@
 
 # CHANGELOG
 
-**Version 6.0.8** - July 2026<br/>
+**Version 6.0.9** - July 2026<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})` })

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,6 +40,8 @@ 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()

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

@@ -443,6 +443,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 +573,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.9",
   "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"
   }
-}
+}