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

package/nodes/utils/matterControllerProfiles/mappedEndpoint.js

@@ -0,0 +1,148 @@
+'use strict'
+
+const dptlib = require('knxultimate').dptlib
+const { knxToMatter, matterToKnx } = require('../matterKnxConverter')
+
+const isValidGroupAddress = (value) => {
+  const parts = String(value || '').trim().split('/')
+  if (parts.length !== 3 || parts.some((part) => !/^\d+$/.test(part))) return false
+  const [main, middle, sub] = parts.map(Number)
+  return main >= 0 && main <= 31 && middle >= 0 && middle <= 7 && sub >= 0 && sub <= 255
+}
+
+const parseMappings = (value) => {
+  try {
+    const parsed = Array.isArray(value) ? value : JSON.parse(value || '[]')
+    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 }
+    })
+  } catch (error) {
+    return []
+  }
+}
+
+const setupMappedEndpointProfile = (RED, node, config) => {
+  node.name = config.name || node.matterDeviceName || 'Control Matter from KNX'
+  node.topic = node.name
+  node.mappings = parseMappings(config.matterMappings)
+  node.knxUltimateAcceptedGAs = [...new Set(node.mappings.map((mapping) => String(mapping.ga).trim()))]
+  node.notifyreadrequest = true
+  node.notifyreadrequestalsorespondtobus = 'false'
+  node.notifyreadrequestalsorespondtobusdefaultvalueifnotinitialized = ''
+  node.notifyresponse = false
+  node.notifywrite = true
+  node.initialread = true
+  node.listenallga = true
+  node.outputtype = 'write'
+  node.outputRBE = 'false'
+  node.inputRBE = 'false'
+  node.passthrough = 'no'
+  const enablePins = config.enableNodePINS === 'yes'
+  let lastInitialReadTs = 0
+
+  const status = (fill, shape, text) => node.status({ fill, shape, text })
+  const manager = () => node.serverMatter?.matterManager
+  const sendKnx = (mapping, payload, outputtype = 'write') => {
+    if (payload === undefined || !node.serverKNX) return false
+    node.serverKNX.sendKNXTelegramToKNXEngine({
+      grpaddr: mapping.ga,
+      payload,
+      dpt: mapping.dpt,
+      outputtype,
+      nodecallerid: node.id
+    })
+    return true
+  }
+  const sendCached = (mapping, outputtype) => {
+    const currentManager = manager()
+    if (!currentManager) return false
+    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')
+    const action = knxToMatter(mapping, value)
+    if (!action) return
+    const queued = currentManager.writeMatterQueueAdd({
+      nodeId: node.matterNodeId,
+      endpointId: mapping.endpointId,
+      clusterId: mapping.clusterId,
+      kind: action.kind,
+      name: action.name,
+      args: action.args
+    })
+    if (queued && typeof queued.catch === 'function') queued.catch((error) => status('red', 'ring', error.message))
+  }
+
+  node.handleSend = (msg) => {
+    try {
+      if (!msg?.knx || !node.knxUltimateAcceptedGAs.includes(String(msg.knx.destination || '').trim())) return
+      const matches = node.mappings.filter((mapping) => mapping.ga === msg.knx.destination)
+      if (msg.knx.event === 'GroupValue_Read') {
+        matches.filter((mapping) => mapping.direction === 'status').forEach((mapping) => sendCached(mapping, 'response'))
+        return
+      }
+      matches.filter((mapping) => mapping.direction === 'command').forEach((mapping) => {
+        const value = dptlib.fromBuffer(msg.knx.rawValue, dptlib.resolve(mapping.dpt))
+        enqueue(mapping, value)
+      })
+      status('green', 'dot', 'KNX→Matter')
+    } catch (error) {
+      RED.log.error(`knxUltimateMatterControllerDevice mapped KNX: ${error.message}`)
+      status('red', 'ring', error.message)
+    }
+  }
+  node.handleSendMatter = (event) => {
+    try {
+      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))
+      })
+      if (enablePins) node.send({ topic: `${event.clusterId}.${event.attributeName}`, payload: event.value, matter: event })
+      status('blue', 'dot', `Matter→KNX: ${event.attributeName}`)
+    } catch (error) {
+      RED.log.error(`knxUltimateMatterControllerDevice mapped Matter: ${error.message}`)
+      status('red', 'ring', error.message)
+    }
+  }
+  node.handleMatterClusterEvent = (event) => {
+    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 = () => {
+    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 })
+    if (sent > 0) lastInitialReadTs = Date.now()
+  }
+  node.setNodeStatusMatter = (value) => { if (value?.text) status(value.fill || 'grey', value.shape || 'ring', value.text) }
+
+  if (node.serverKNX) { node.serverKNX.removeClient(node); node.serverKNX.addClient(node) } else status('yellow', 'ring', 'No KNX gateway selected')
+  if (node.serverMatter) { node.serverMatter.removeClient(node); node.serverMatter.addClient(node) }
+  node.on('input', (msg, send, done) => {
+    try {
+      const payload = msg.payload || {}
+      const mapping = {
+        endpointId: payload.endpointId ?? node.matterEndpointId,
+        clusterId: payload.clusterId,
+        targetKind: payload.command !== undefined ? 'command' : 'attribute',
+        target: payload.command ?? payload.attribute
+      }
+      if (!mapping.target || mapping.clusterId === undefined) throw new Error('Matter input requires clusterId and command or attribute')
+      enqueue(mapping, payload.args ?? payload.value)
+      if (done) done()
+    } catch (error) {
+      if (done) done(error); else node.error(error, msg)
+    }
+  })
+  node.on('close', (done) => {
+    try { if (node.serverKNX) node.serverKNX.removeClient(node) } catch (error) { /* empty */ }
+    try { if (node.serverMatter) node.serverMatter.removeClient(node) } catch (error) { /* empty */ }
+    done()
+  })
+}
+
+module.exports = { isValidGroupAddress, parseMappings, setupMappedEndpointProfile }

package/nodes/utils/matterStorageBackup.js

@@ -0,0 +1,100 @@
+const fs = require('fs/promises')
+const path = require('path')
+
+const BACKUP_FORMAT = 'knx-ultimate-matter-storage'
+const BACKUP_VERSION = 1
+const MAX_BACKUP_BYTES = 64 * 1024 * 1024
+
+const instancePath = (storagePath, instanceId) => path.join(storagePath, instanceId)
+
+const listFiles = async (root, current = root) => {
+  const entries = await fs.readdir(current, { withFileTypes: true })
+  const files = []
+  for (const entry of entries) {
+    if (entry.isSymbolicLink()) throw new Error('Matter storage contains an unsupported symbolic link')
+    const absolute = path.join(current, entry.name)
+    if (entry.isDirectory()) files.push(...await listFiles(root, absolute))
+    else if (entry.isFile()) files.push(path.relative(root, absolute).split(path.sep).join('/'))
+  }
+  return files.sort()
+}
+
+const exportMatterStorage = async ({ storagePath, instanceId, kind, protocolVersion, packageVersion }) => {
+  const root = instancePath(storagePath, instanceId)
+  let names
+  try {
+    names = await listFiles(root)
+  } catch (error) {
+    if (error.code === 'ENOENT') names = []
+    else throw error
+  }
+  const files = []
+  let totalBytes = 0
+  for (const name of names) {
+    const content = await fs.readFile(path.join(root, ...name.split('/')))
+    totalBytes += content.length
+    if (totalBytes > MAX_BACKUP_BYTES) throw new Error('Matter backup exceeds the 64 MB safety limit')
+    files.push({ path: name, content: content.toString('base64') })
+  }
+  return {
+    format: BACKUP_FORMAT,
+    version: BACKUP_VERSION,
+    kind,
+    createdAt: new Date().toISOString(),
+    sourceInstanceId: instanceId,
+    matterProtocolVersion: protocolVersion,
+    matterPackageVersion: packageVersion,
+    files
+  }
+}
+
+const validateRelativePath = (name) => {
+  if (typeof name !== 'string' || name === '' || name.includes('\\')) return false
+  const normalized = path.posix.normalize(name)
+  return normalized === name && !path.posix.isAbsolute(name) && name !== '..' && !name.startsWith('../')
+}
+
+const importMatterStorage = async ({ storagePath, instanceId, kind, backup }) => {
+  if (!backup || backup.format !== BACKUP_FORMAT || backup.version !== BACKUP_VERSION) throw new Error('Unsupported Matter backup file')
+  if (backup.kind !== kind) throw new Error(`This is a Matter ${backup.kind || 'unknown'} backup, not a ${kind} backup`)
+  if (!Array.isArray(backup.files)) throw new Error('Invalid Matter backup: files are missing')
+
+  const decoded = []
+  const seen = new Set()
+  let totalBytes = 0
+  for (const file of backup.files) {
+    if (!file || !validateRelativePath(file.path) || seen.has(file.path) || typeof file.content !== 'string') throw new Error('Invalid Matter backup file entry')
+    const content = Buffer.from(file.content, 'base64')
+    totalBytes += content.length
+    if (totalBytes > MAX_BACKUP_BYTES) throw new Error('Matter backup exceeds the 64 MB safety limit')
+    seen.add(file.path)
+    decoded.push({ path: file.path, content })
+  }
+
+  await fs.mkdir(storagePath, { recursive: true })
+  const target = instancePath(storagePath, instanceId)
+  const temporary = `${target}.import-${process.pid}-${Date.now()}`
+  const previous = `${target}.previous-${process.pid}-${Date.now()}`
+  await fs.mkdir(temporary, { recursive: true })
+  try {
+    for (const file of decoded) {
+      const destination = path.join(temporary, ...file.path.split('/'))
+      await fs.mkdir(path.dirname(destination), { recursive: true })
+      await fs.writeFile(destination, file.content, { mode: 0o600 })
+    }
+    let hadTarget = true
+    try { await fs.rename(target, previous) } catch (error) { if (error.code === 'ENOENT') hadTarget = false; else throw error }
+    try {
+      await fs.rename(temporary, target)
+    } catch (error) {
+      if (hadTarget) await fs.rename(previous, target)
+      throw error
+    }
+    if (hadTarget) await fs.rm(previous, { recursive: true, force: true })
+  } catch (error) {
+    await fs.rm(temporary, { recursive: true, force: true })
+    throw error
+  }
+}
+
+module.exports = { exportMatterStorage, importMatterStorage, BACKUP_FORMAT, BACKUP_VERSION, MAX_BACKUP_BYTES }

package/package.json

@@ -3,7 +3,7 @@
   "engines": {
     "node": ">=20.18.1"
   },
-  "version": "6.0.5",
+  "version": "6.0.7",
   "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/",
@@ -99,7 +99,11 @@
     "smarthome",
     "routing"
   ],
-  "author": "Massimo Saccani (Supergiovane)",
+  "author": {
+    "name": "Massimo Saccani",
+    "email": "maxsupergiovane@icloud.com",
+    "url": "https://youtube.com/@maxsupervibe"
+  },
   "license": "MIT",
   "scripts": {
     "build": "npm run knx-ai:build && npm run knx-viewer:build",

package/resources/htmlUtils.js

@@ -1,6 +1,17 @@
 /* global window, document, MutationObserver, $, jQuery */
 /* eslint-disable camelcase */
 
+// Keep informational tips aligned with the full width of our Node-RED editor forms.
+// Node-RED applies a max-width to .form-tips by default, which otherwise leaves
+// inconsistent empty space in wider edit dialogs.
+;(function ensureKnxUltimateEditorStyles () {
+  if (document.getElementById('knx-ultimate-editor-styles')) return
+  const style = document.createElement('style')
+  style.id = 'knx-ultimate-editor-styles'
+  style.textContent = '.form-tips { width: 100% !important; max-width: none !important; box-sizing: border-box !important; background-color: #e8f5e9 !important; }'
+  document.head.appendChild(style)
+})()
+
 // 31/03/2020 Search Helper
 function htmlUtilsfullCSVSearch (sourceText, searchString) {
   let aSearchWords = []