node-red-contrib-knx-ultimate 6.0.11 → 6.1.0

package/nodes/utils/matterControllerSemanticInput.js

@@ -0,0 +1,212 @@
+'use strict'
+
+const { CLUSTER } = require('./matterKnxConverter')
+
+const normalizeToken = (value) => String(value || '').trim().toLowerCase().replace(/[^a-z0-9]/g, '')
+
+const requireNumber = (value, functionName, min, max) => {
+  const numeric = Number(value)
+  if (!Number.isFinite(numeric)) throw new Error(`Matter function "${functionName}" requires a numeric value`)
+  if (min !== undefined && numeric < min) throw new Error(`Matter function "${functionName}" requires a value >= ${min}`)
+  if (max !== undefined && numeric > max) throw new Error(`Matter function "${functionName}" requires a value <= ${max}`)
+  return numeric
+}
+
+const requireBoolean = (value, functionName) => {
+  if (value === true || value === 1 || value === '1' || normalizeToken(value) === 'true' || normalizeToken(value) === 'on') return true
+  if (value === false || value === 0 || value === '0' || normalizeToken(value) === 'false' || normalizeToken(value) === 'off') return false
+  throw new Error(`Matter function "${functionName}" requires true/false`)
+}
+
+const command = (clusterId, names, value) => ({
+  clusterId,
+  targetKind: 'command',
+  names: Array.isArray(names) ? names : [names],
+  value
+})
+
+const attribute = (clusterId, names, value, writableOnly = false) => ({
+  clusterId,
+  targetKind: 'attribute',
+  names: Array.isArray(names) ? names : [names],
+  value,
+  writableOnly
+})
+
+// Friendly functions deliberately use the same names as the Matter Bridge where
+// the concepts overlap. Values use human units (percent, °C, lux, W and kWh).
+const SEMANTIC_FUNCTIONS = {
+  onoff: {
+    read: attribute(CLUSTER.ON_OFF, 'onOff'),
+    write: (value) => {
+      if (normalizeToken(value) === 'toggle') return command(CLUSTER.ON_OFF, 'toggle', false)
+      const on = requireBoolean(value, 'onoff')
+      return command(CLUSTER.ON_OFF, on ? 'on' : 'off', on)
+    }
+  },
+  level: {
+    read: attribute(CLUSTER.LEVEL_CONTROL, 'currentLevel'),
+    write: (value) => command(CLUSTER.LEVEL_CONTROL, ['moveToLevelWithOnOff', 'moveToLevel'], requireNumber(value, 'level', 0, 100))
+  },
+  position: {
+    read: attribute(CLUSTER.WINDOW_COVERING, ['currentPositionLiftPercent100ths', 'currentPositionLiftPercentage']),
+    write: (value) => command(CLUSTER.WINDOW_COVERING, 'goToLiftPercentage', requireNumber(value, 'position', 0, 100))
+  },
+  tiltposition: {
+    read: attribute(CLUSTER.WINDOW_COVERING, ['currentPositionTiltPercent100ths', 'currentPositionTiltPercentage']),
+    write: (value) => command(CLUSTER.WINDOW_COVERING, 'goToTiltPercentage', requireNumber(value, 'tiltposition', 0, 100))
+  },
+  open: {
+    write: () => command(CLUSTER.WINDOW_COVERING, 'upOrOpen', false)
+  },
+  close: {
+    write: () => command(CLUSTER.WINDOW_COVERING, 'downOrClose', true)
+  },
+  stop: {
+    write: () => command(CLUSTER.WINDOW_COVERING, 'stopMotion', undefined)
+  },
+  setpoint: {
+    read: attribute(CLUSTER.THERMOSTAT, 'occupiedHeatingSetpoint'),
+    write: (value) => attribute(CLUSTER.THERMOSTAT, 'occupiedHeatingSetpoint', requireNumber(value, 'setpoint'), true)
+  },
+  coolingsetpoint: {
+    read: attribute(CLUSTER.THERMOSTAT, 'occupiedCoolingSetpoint'),
+    write: (value) => attribute(CLUSTER.THERMOSTAT, 'occupiedCoolingSetpoint', requireNumber(value, 'coolingsetpoint'), true)
+  },
+  currenttemp: {
+    read: attribute(CLUSTER.THERMOSTAT, 'localTemperature')
+  },
+  fanspeed: {
+    read: attribute(CLUSTER.FAN_CONTROL, ['percentCurrent', 'percentSetting']),
+    write: (value) => attribute(CLUSTER.FAN_CONTROL, 'percentSetting', requireNumber(value, 'fanspeed', 0, 100), true)
+  },
+  temperature: {
+    read: attribute(CLUSTER.TEMPERATURE, 'measuredValue')
+  },
+  humidity: {
+    read: attribute(CLUSTER.HUMIDITY, 'measuredValue')
+  },
+  illuminance: {
+    read: attribute(CLUSTER.ILLUMINANCE, 'measuredValue')
+  },
+  occupancy: {
+    read: attribute(CLUSTER.OCCUPANCY, 'occupancy')
+  },
+  contact: {
+    read: attribute(CLUSTER.BOOLEAN_STATE, 'stateValue')
+  },
+  battery: {
+    read: attribute(CLUSTER.POWER_SOURCE, 'batPercentRemaining')
+  },
+  activepower: {
+    read: attribute(CLUSTER.ELECTRICAL_POWER, 'activePower')
+  },
+  importedenergy: {
+    read: attribute(CLUSTER.ELECTRICAL_ENERGY, 'cumulativeEnergyImported')
+  },
+  identify: {
+    write: () => command(CLUSTER.IDENTIFY, 'identify', undefined)
+  }
+}
+
+const getInputStructure = (capabilities) => {
+  if (!capabilities || typeof capabilities !== 'object') return undefined
+  const structure = capabilities.inputStructure
+  return structure && Array.isArray(structure.clusters) ? structure : undefined
+}
+
+const targetSupported = (capabilities, candidate) => {
+  const structure = getInputStructure(capabilities)
+  if (!structure) return true
+  const cluster = structure.clusters.find((item) => Number(item.id) === Number(candidate.clusterId))
+  if (!cluster) return false
+  const collection = candidate.targetKind === 'command' ? cluster.commands : cluster.attributes
+  if (!Array.isArray(collection)) return false
+  return candidate.names.some((name) => collection.some((item) =>
+    normalizeToken(item.name) === normalizeToken(name) &&
+    (!candidate.writableOnly || item.writable === true)
+  ))
+}
+
+const materializeTarget = (capabilities, candidate) => {
+  if (!candidate) return undefined
+  const structure = getInputStructure(capabilities)
+  if (!structure) return { ...candidate, target: candidate.names[0] }
+  const cluster = structure.clusters.find((item) => Number(item.id) === Number(candidate.clusterId))
+  const collection = candidate.targetKind === 'command' ? cluster?.commands : cluster?.attributes
+  if (!Array.isArray(collection)) return undefined
+  for (const name of candidate.names) {
+    const found = collection.find((item) =>
+      normalizeToken(item.name) === normalizeToken(name) &&
+      (!candidate.writableOnly || item.writable === true)
+    )
+    if (found) return { ...candidate, target: found.name }
+  }
+  return undefined
+}
+
+const semanticPayload = (msg) => {
+  const payload = msg?.payload
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload) || Buffer.isBuffer(payload)) return undefined
+  const rawFunction = payload.function ?? payload.fn
+  if (rawFunction === undefined || rawFunction === null || String(rawFunction).trim() === '') return undefined
+  return {
+    functionName: normalizeToken(rawFunction),
+    value: payload.value,
+    requestFromRemote: payload.requestFromRemote === true || payload.remote === true
+  }
+}
+
+const supportedSemanticFunctions = (capabilities) => Object.entries(SEMANTIC_FUNCTIONS)
+  .filter(([, definition]) => {
+    const readSupported = definition.read && targetSupported(capabilities, definition.read)
+    const writeSupported = definition.write && [undefined, 0, true, false, 'toggle'].some((value) => {
+      try {
+        return targetSupported(capabilities, definition.write(value))
+      } catch (error) {
+        return false
+      }
+    })
+    return readSupported || writeSupported
+  })
+  .map(([name]) => name)
+
+const resolveSemanticInput = (msg, capabilities) => {
+  const input = semanticPayload(msg)
+  if (!input) return undefined
+  const definition = SEMANTIC_FUNCTIONS[input.functionName]
+  if (!definition) {
+    const supported = supportedSemanticFunctions(capabilities)
+    throw new Error(`Unsupported Matter function "${input.functionName}"${supported.length ? `. Supported: ${supported.join(', ')}` : ''}`)
+  }
+  const wantsWrite = input.value !== undefined || !definition.read
+  let candidate
+  if (wantsWrite) {
+    if (!definition.write) throw new Error(`Matter function "${input.functionName}" is read-only`)
+    candidate = definition.write(input.value)
+  } else {
+    candidate = definition.read
+  }
+  const resolved = materializeTarget(capabilities, candidate)
+  if (!resolved) throw new Error(`Matter endpoint does not support function "${input.functionName}"`)
+  return {
+    functionName: input.functionName,
+    requestFromRemote: input.requestFromRemote,
+    operation: wantsWrite ? 'write' : 'read',
+    value: resolved.value,
+    mapping: {
+      endpointId: msg.endpointId,
+      clusterId: resolved.clusterId,
+      targetKind: resolved.targetKind,
+      target: resolved.target
+    }
+  }
+}
+
+module.exports = {
+  SEMANTIC_FUNCTIONS,
+  normalizeToken,
+  resolveSemanticInput,
+  semanticPayload,
+  supportedSemanticFunctions
+}

package/nodes/utils/matterEngine.mjs

@@ -23,7 +23,12 @@ const normalizeHostForCompare = (value) => {
 // emitting 'connected', 'disconnected', 'event' (attribute changes), 'matterEvent' (cluster events),
 // 'nodeState' and 'structureChanged'.
 class classMatter extends EventEmitter {
-  constructor (_storagePath, _instanceId, _fabricLabel, _sysLogger, { startQueue = true } = {}) {
+  constructor (_storagePath, _instanceId, _fabricLabel, _sysLogger, {
+    startQueue = true,
+    commandTimeoutMs = 15000,
+    queuePollMs = 150,
+    queueMaxConcurrent = 32
+  } = {}) {
     super()
     this.matterConnectionStatus = 'disconnected'
     this.storagePath = _storagePath
@@ -33,7 +38,14 @@ class classMatter extends EventEmitter {
     this.controller = null
     this.pairedNodes = new Map() // nodeId (string) -> PairedNode
     this.commandQueue = []
+    // Commands remain strictly ordered per Matter node, but different nodes use
+    // independent lanes. An unreachable device must never head-of-line block every
+    // other endpoint sharing this controller/fabric.
+    this.commandQueueInFlight = new Map()
     this.queueMaxLength = 2000
+    this.queueMaxConcurrent = Math.max(1, Number(queueMaxConcurrent) || 32)
+    this.commandTimeoutMs = Math.max(10, Number(commandTimeoutMs) || 15000)
+    this.queuePollMs = Math.max(10, Number(queuePollMs) || 150)
     this.exitAllQueues = false
     this._api = null // Lazy loaded matter.js exports
     this._logThrottle = new Map()
@@ -75,7 +87,8 @@ class classMatter extends EventEmitter {
     if (this._api !== null) return this._api
     const { Environment, StorageService, Logger, LogLevel } = await import('@matter/main')
     const { Seconds } = await import('@matter/general')
-    const { CommissioningController, NodeStates } = await import('@project-chip/matter.js')
+    const { CommissioningController } = await import('@project-chip/matter.js')
+    const { NodeStates } = await import('@project-chip/matter.js/device')
     const { ManualPairingCodeCodec, QrPairingCodeCodec, NodeId } = await import('@matter/main/types')
     const { BasicInformation, GeneralCommissioning } = await import('@matter/main/clusters')
     this._api = {
@@ -505,12 +518,18 @@ class classMatter extends EventEmitter {
               if (typeof cc.isAttributeSupportedByName === 'function' && !cc.isAttributeSupportedByName(attrName)) return
               // Skip the global meta attributes (FeatureMap, AttributeList, ClusterRevision...):
               // they are useless for KNX mappings and only confuse the user.
-              if (Number(cc.attributes[attrName].id) >= 65528) return
+              const exposeFeatureMap = [47, 768].includes(Number(cc.id)) && attrName === 'featureMap'
+              if (Number(cc.attributes[attrName].id) >= 65528 && !exposeFeatureMap) return
               let value
               try {
                 value = cc.attributes[attrName].getLocal()
               } catch (error) { value = undefined }
-              attributes.push({ name: attrName, id: Number(cc.attributes[attrName].id), value: this._jsonSafe(value) })
+              attributes.push({
+                name: attrName,
+                id: Number(cc.attributes[attrName].id),
+                value: this._jsonSafe(value),
+                writable: cc.attributes[attrName]?.attribute?.schema?.writable === true
+              })
             } catch (error) { /* empty */ }
           })
           const commands = []
@@ -617,56 +636,140 @@ class classMatter extends EventEmitter {
     return true
   }
 
+  _isNodeCommissioned = (nodeId) => {
+    const key = String(nodeId)
+    try {
+      if (this.controller && typeof this.controller.getCommissionedNodes === 'function') {
+        return this.controller.getCommissionedNodes().some((commissionedNodeId) => commissionedNodeId.toString() === key)
+      }
+    } catch (error) { /* Fall back to the attached-node map while the controller changes state. */ }
+    return this.pairedNodes.has(key)
+  }
+
   // Add a command or attribute write to the queue.
   // _item: { nodeId, endpointId, clusterId, kind: 'command'|'attributeWrite', name, args }
   writeMatterQueueAdd = async (_item) => {
-    return this._enqueueCommand(_item)
+    const nodeId = _item?.nodeId === undefined || _item?.nodeId === null ? '' : String(_item.nodeId)
+    const item = { ..._item, nodeId }
+    if (nodeId === '' || !this._isNodeCommissioned(nodeId)) {
+      const error = new Error(`Matter node ${nodeId || '(empty)'} is no longer commissioned`)
+      error.code = 'MATTER_NODE_NOT_COMMISSIONED'
+      // Defer the notification so a legacy fire-and-forget caller cannot overwrite
+      // the red orphan-device status with its immediate optimistic "command sent" state.
+      queueMicrotask(() => this.emit('commandError', { item, error: error.message, code: error.code }))
+      throw error
+    }
+    return this._enqueueCommand(item)
   }
 
   deleteMatterQueue = async (_nodeIdString) => {
-    this.commandQueue = this.commandQueue.filter((el) => el.nodeId !== _nodeIdString)
+    const nodeId = String(_nodeIdString)
+    this.commandQueue = this.commandQueue.filter((el) => String(el.nodeId) !== nodeId)
   }
 
-  processQueueItem = async () => {
-    let item = null
+  _withCommandTimeout = async (operation) => {
+    let timer
+    try {
+      return await Promise.race([
+        Promise.resolve().then(operation),
+        new Promise((resolve, reject) => {
+          timer = setTimeout(() => {
+            const error = new Error(`Matter command timed out after ${this.commandTimeoutMs} ms`)
+            error.code = 'MATTER_COMMAND_TIMEOUT'
+            reject(error)
+          }, this.commandTimeoutMs)
+          timer.unref?.()
+        })
+      ])
+    } finally {
+      if (timer !== undefined) clearTimeout(timer)
+    }
+  }
+
+  processQueueItem = async (_item = undefined) => {
+    let item = _item ?? null
     try {
       if (this.matterConnectionStatus !== 'connected') return
-      item = this.commandQueue.pop()
+      if (item === null) item = this.commandQueue.pop()
       if (!item) return
       const node = this.pairedNodes.get(item.nodeId)
-      if (node === undefined) throw new Error(`Matter node ${item.nodeId} unknown or not yet connected`)
+      if (node === undefined || !this._isNodeCommissioned(item.nodeId)) {
+        const error = new Error(`Matter node ${item.nodeId} is no longer commissioned`)
+        error.code = 'MATTER_NODE_NOT_COMMISSIONED'
+        throw error
+      }
       const clusterClient = this._findClusterClient(node, item.endpointId, item.clusterId)
       if (clusterClient === undefined) throw new Error(`Cluster ${item.clusterId} not found on endpoint ${item.endpointId} of node ${item.nodeId}`)
       if (item.kind === 'attributeWrite') {
         const attribute = clusterClient.attributes[item.name]
         if (attribute === undefined) throw new Error(`Attribute ${item.name} not found in cluster ${clusterClient.name}`)
-        await attribute.set(item.args)
+        await this._withCommandTimeout(() => attribute.set(item.args))
       } else {
         const command = clusterClient.commands[item.name]
         if (typeof command !== 'function') throw new Error(`Command ${item.name} not found in cluster ${clusterClient.name}`)
-        await command(item.args)
+        await this._withCommandTimeout(() => command(item.args))
       }
     } catch (error) {
       const target = item ? `${item.nodeId}/${item.endpointId}/${item.clusterId}/${item.name}` : 'unknown'
+      if (!error.code && item) {
+        let connectionState = 'unknown'
+        try {
+          const targetNode = this.pairedNodes.get(item.nodeId)
+          if (targetNode?.connectionState !== undefined) connectionState = this.nodeStateToString(targetNode.connectionState)
+        } catch (stateError) { /* empty */ }
+        if (connectionState !== 'unknown' && connectionState !== 'connected') {
+          error.code = 'MATTER_NODE_UNAVAILABLE'
+        } else if (/disconnected|reconnecting|unreachable|no session|peer communication|network.*(?:failed|error)|timed? ?out/i.test(error.message || '')) {
+          error.code = 'MATTER_NODE_UNAVAILABLE'
+        }
+      }
       this._logThrottled('error', `matter:queue:error:${target}`, `classMatter: processQueueItem (${target}): ${error.message}`, 30000)
-      this.emit('commandError', { item, error: error.message })
+      this.emit('commandError', { item, error: error.message, code: error.code })
+    }
+  }
+
+  _takeNextQueueItem = () => {
+    if (!Array.isArray(this.commandQueue) || this.commandQueue.length === 0) return undefined
+    // New items are unshifted, therefore the oldest FIFO item is at the end.
+    // Walk backwards until a device lane that is not already busy is found.
+    for (let index = this.commandQueue.length - 1; index >= 0; index--) {
+      const item = this.commandQueue[index]
+      const nodeId = String(item?.nodeId ?? '')
+      if (this.commandQueueInFlight.has(nodeId)) continue
+      return this.commandQueue.splice(index, 1)[0]
+    }
+    return undefined
+  }
+
+  _dispatchQueueItems = () => {
+    if (this.matterConnectionStatus !== 'connected') return
+    while (this.commandQueueInFlight.size < this.queueMaxConcurrent) {
+      const item = this._takeNextQueueItem()
+      if (!item) return
+      const nodeId = String(item.nodeId)
+      const laneToken = {}
+      this.commandQueueInFlight.set(nodeId, laneToken)
+      Promise.resolve(this.processQueueItem(item))
+        .catch((error) => this._logThrottled('error', `matter:queue:lane:${nodeId}`, `classMatter: queue lane ${nodeId}: ${error.message}`, 30000))
+        .finally(() => {
+          if (this.commandQueueInFlight.get(nodeId) === laneToken) this.commandQueueInFlight.delete(nodeId)
+        })
     }
   }
 
   handleQueue = async () => {
     do {
       if (this.matterConnectionStatus === 'connected' && this.commandQueue && this.commandQueue.length > 0) {
-        try {
-          await this.processQueueItem()
-        } catch (error) { /* empty */ }
+        this._dispatchQueueItems()
       }
-      await pleaseWait(150)
+      await pleaseWait(this.queuePollMs)
     } while (!this.exitAllQueues)
   }
 
   close = async () => {
     this.exitAllQueues = true
     this.commandQueue = []
+    this.commandQueueInFlight.clear()
     this._logThrottle.clear()
     this.matterConnectionStatus = 'disconnected'
     try {

package/package.json

@@ -3,7 +3,7 @@
   "engines": {
     "node": ">=20.18.1"
   },
-  "version": "6.0.11",
+  "version": "6.1.0",
   "description": "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 with AI, virtual devices, and powerful automation nodes. Build professional, reliable, and scalable smart home and building automation projects with minimal effort.",
   "files": [
     "nodes/",

package/resources/matterQrScanner.js

@@ -0,0 +1,98 @@
+(function (root, factory) {
+  const api = factory()
+  if (typeof module === 'object' && module.exports) module.exports = api
+  if (root) root.KNXUltimateMatterQrScanner = api
+}(typeof globalThis !== 'undefined' ? globalThis : this, function () {
+  'use strict'
+
+  function normalizeMatterQrPayload (rawValue) {
+    const value = typeof rawValue === 'string' ? rawValue.trim() : ''
+    if (!/^MT:[0-9A-Z.-]+$/.test(value)) return null
+    return value
+  }
+
+  function getResultText (result) {
+    if (result && typeof result.getText === 'function') return result.getText()
+    if (result && typeof result.text === 'string') return result.text
+    return ''
+  }
+
+  function getCameraStatus (browserWindow, browserNavigator) {
+    if (!browserWindow || browserWindow.isSecureContext !== true) {
+      return { available: false, reason: 'insecure' }
+    }
+    if (!browserNavigator || !browserNavigator.mediaDevices || typeof browserNavigator.mediaDevices.getUserMedia !== 'function') {
+      return { available: false, reason: 'unsupported' }
+    }
+    return { available: true, reason: null }
+  }
+
+  function stopVideo (videoElement) {
+    if (!videoElement) return
+    const stream = videoElement.srcObject
+    if (stream && typeof stream.getTracks === 'function') {
+      stream.getTracks().forEach(function (track) {
+        try {
+          track.stop()
+        } catch (error) { /* empty */ }
+      })
+    }
+    try {
+      videoElement.pause()
+    } catch (error) { /* empty */ }
+    try {
+      videoElement.srcObject = null
+    } catch (error) { /* empty */ }
+  }
+
+  function isCameraPermissionError (error) {
+    return Boolean(error && (error.name === 'NotAllowedError' || error.name === 'SecurityError'))
+  }
+
+  function invertCanvasPixels (canvas) {
+    if (!canvas || typeof canvas.getContext !== 'function') throw new Error('Canvas is not available')
+    let context
+    try {
+      context = canvas.getContext('2d', { willReadFrequently: true })
+    } catch (error) {
+      context = canvas.getContext('2d')
+    }
+    if (!context) throw new Error('Canvas 2D context is not available')
+    const imageData = context.getImageData(0, 0, canvas.width, canvas.height)
+    for (let index = 0; index < imageData.data.length; index += 4) {
+      imageData.data[index] = 255 - imageData.data[index]
+      imageData.data[index + 1] = 255 - imageData.data[index + 1]
+      imageData.data[index + 2] = 255 - imageData.data[index + 2]
+    }
+    context.putImageData(imageData, 0, 0)
+    return canvas
+  }
+
+  function enableInvertedQrFallback (reader) {
+    if (!reader || typeof reader.decodeFromCanvas !== 'function') throw new Error('QR reader is not available')
+    const decodeFromCanvas = reader.decodeFromCanvas.bind(reader)
+    reader.decodeFromCanvas = function (canvas) {
+      try {
+        return decodeFromCanvas(canvas)
+      } catch (normalError) {
+        try {
+          invertCanvasPixels(canvas)
+          return decodeFromCanvas(canvas)
+        } catch (invertedError) {
+          throw normalError
+        }
+      }
+    }
+    return reader
+  }
+
+  return {
+    enableInvertedQrFallback,
+    getCameraStatus,
+    getResultText,
+    invertCanvasPixels,
+    isCameraPermissionError,
+    normalizeMatterQrPayload,
+    stopVideo
+  }
+}))