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

package/nodes/utils/matterControllerProfiles/doorLock.js

@@ -0,0 +1,214 @@
+'use strict'
+
+const dptlib = require('knxultimate').dptlib
+
+const DOOR_LOCK_CLUSTER_ID = 0x0101
+const LOCK_STATE = {
+  NOT_FULLY_LOCKED: 0,
+  LOCKED: 1,
+  UNLOCKED: 2,
+  UNLATCHED: 3
+}
+
+const decodeKnxBoolean = (msg, dpt) => {
+  if (msg && msg.knx && Buffer.isBuffer(msg.knx.rawValue)) {
+    return !!dptlib.fromBuffer(msg.knx.rawValue, dptlib.resolve(dpt || '1.001'))
+  }
+  return !!(msg && msg.payload)
+}
+
+const lockStateName = (value) => {
+  switch (Number(value)) {
+    case LOCK_STATE.LOCKED: return 'locked'
+    case LOCK_STATE.UNLOCKED: return 'unlocked'
+    case LOCK_STATE.NOT_FULLY_LOCKED: return 'notFullyLocked'
+    case LOCK_STATE.UNLATCHED: return 'unlatched'
+    default: return 'unknown'
+  }
+}
+
+const lockStateToBoolean = (value) => {
+  if (Number(value) === LOCK_STATE.LOCKED) return true
+  if (Number(value) === LOCK_STATE.UNLOCKED) return false
+  return undefined
+}
+
+const setupDoorLockProfile = (RED, node, config) => {
+  node.name = config.name || node.matterDeviceName || 'Control Matter door lock from KNX'
+  node.topic = node.name
+  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'
+  node.currentLockState = undefined
+  node.knxUltimateAcceptedGAs = [config.GALightSwitch, config.GALightState]
+    .map((ga) => String(ga || '').trim())
+    .filter((ga) => ga !== '')
+
+  const setStatus = (fill, shape, text) => node.status({ fill, shape, text })
+  // knxUltimate-config invokes this synchronously from addClient(). Profiles return
+  // early from the main light constructor, so they must expose the callback before
+  // registering with the shared KNX configuration node.
+  node.setNodeStatus = ({ fill = 'grey', shape = 'ring', text = '' } = {}) => setStatus(fill, shape, text)
+
+  const commandArgs = () => {
+    const pin = String(node.credentials?.doorLockPin || '')
+    return pin === '' ? {} : { pinCode: Buffer.from(pin, 'utf8') }
+  }
+
+  const sendFlow = (source, state, rawState) => {
+    if (config.enableNodePINS !== 'yes') return
+    node.send({
+      topic: node.topic,
+      payload: state,
+      matter: {
+        source,
+        nodeId: node.matterNodeId,
+        endpointId: node.matterEndpointId,
+        clusterId: DOOR_LOCK_CLUSTER_ID,
+        lockState: rawState,
+        lockStateName: rawState === undefined ? (state ? 'locked' : 'unlocked') : lockStateName(rawState)
+      }
+    })
+  }
+
+  const writeKnxState = (state, outputtype = 'write') => {
+    const ga = String(config.GALightState || '').trim()
+    if (ga === '' || !node.serverKNX) return
+    node.serverKNX.sendKNXTelegramToKNXEngine({
+      grpaddr: ga,
+      payload: state,
+      dpt: config.dptLightState || '1.001',
+      outputtype,
+      nodecallerid: node.id
+    })
+  }
+
+  const publishMatterState = (rawState, source = 'matter') => {
+    node.currentLockState = Number(rawState)
+    const state = lockStateToBoolean(rawState)
+    const name = lockStateName(rawState)
+    if (state !== undefined) writeKnxState(state)
+    sendFlow(source, state, rawState)
+    setStatus(state === undefined ? 'yellow' : 'blue', state === undefined ? 'ring' : 'dot', `Matter: ${name}`)
+  }
+
+  const queueCommand = (locked, source = 'knx') => {
+    const manager = node.serverMatter?.matterManager
+    if (!manager) throw new Error('Matter controller not ready')
+    const capabilities = (() => {
+      try { return JSON.parse(config.matterDeviceCapabilities || '{}') } catch (error) { return {} }
+    })()
+    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({
+      nodeId: node.matterNodeId,
+      endpointId: node.matterEndpointId,
+      clusterId: DOOR_LOCK_CLUSTER_ID,
+      kind: 'command',
+      name: locked ? 'lockDoor' : 'unlockDoor',
+      args: commandArgs()
+    })
+    if (queued && typeof queued.catch === 'function') {
+      queued.catch((error) => {
+        RED.log.error(`knxUltimateMatterControllerDevice DoorLock command: ${error.message}`)
+        setStatus('red', 'ring', error.message)
+      })
+    }
+    sendFlow(source, locked)
+    setStatus('green', 'dot', `KNX→Matter: ${locked ? 'lock' : 'unlock'}`)
+  }
+
+  node.handleSend = (msg) => {
+    try {
+      if (!msg?.knx || !node.knxUltimateAcceptedGAs.includes(String(msg.knx.destination || '').trim())) return
+      if (msg.knx.event === 'GroupValue_Read') {
+        if (String(msg.knx.destination) === String(config.GALightState)) {
+          const state = lockStateToBoolean(node.currentLockState)
+          if (state !== undefined) writeKnxState(state, 'response')
+        }
+        return
+      }
+      if (String(msg.knx.destination) !== String(config.GALightSwitch)) return
+      queueCommand(decodeKnxBoolean(msg, config.dptLightSwitch), 'knx')
+    } catch (error) {
+      RED.log.error(`knxUltimateMatterControllerDevice DoorLock KNX: ${error.message}`)
+      setStatus('red', 'ring', error.message)
+    }
+  }
+
+  node.handleSendMatter = (event) => {
+    try {
+      if (String(event?.nodeId) !== String(node.matterNodeId)) return
+      if (Number(event?.endpointId) !== Number(node.matterEndpointId)) return
+      if (Number(event?.clusterId) !== DOOR_LOCK_CLUSTER_ID || event.attributeName !== 'lockState') return
+      publishMatterState(event.value)
+    } catch (error) {
+      RED.log.error(`knxUltimateMatterControllerDevice DoorLock Matter: ${error.message}`)
+    }
+  }
+  node.handleMatterClusterEvent = () => {}
+  node.handleMatterNodeInitialized = () => {
+    try {
+      const value = node.serverMatter?.matterManager?.getCachedAttribute(
+        node.matterNodeId,
+        node.matterEndpointId,
+        DOOR_LOCK_CLUSTER_ID,
+        'lockState'
+      )
+      if (value !== undefined && value !== null) publishMatterState(value, 'initial')
+    } catch (error) {
+      RED.log.error(`knxUltimateMatterControllerDevice DoorLock initial state: ${error.message}`)
+    }
+  }
+  node.setNodeStatusMatter = (status) => {
+    if (status && status.text) setStatus(status.fill || 'grey', status.shape || 'ring', status.text)
+  }
+
+  if (node.serverKNX) {
+    node.serverKNX.removeClient(node)
+    node.serverKNX.addClient(node)
+  } else {
+    setStatus('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 value = typeof msg.payload === 'object' && msg.payload !== null && msg.payload.locked !== undefined
+        ? msg.payload.locked
+        : msg.payload
+      if (typeof value !== 'boolean') throw new Error('Door Lock input requires msg.payload boolean or { locked: boolean }')
+      queueCommand(value, 'flow')
+      if (done) done()
+    } catch (error) {
+      setStatus('red', 'ring', error.message)
+      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 = {
+  DOOR_LOCK_CLUSTER_ID,
+  LOCK_STATE,
+  lockStateName,
+  lockStateToBoolean,
+  setupDoorLockProfile
+}

package/nodes/utils/matterControllerProfiles/index.js

@@ -0,0 +1,21 @@
+'use strict'
+
+const { setupDoorLockProfile } = require('./doorLock')
+const { setupMappedEndpointProfile } = require('./mappedEndpoint')
+
+// Controller-side Matter device profiles live behind this registry.  Keep profile
+// selection capability-driven: the editor records the profile only after inspecting
+// the endpoint's actual device types, clusters, attributes and supported commands.
+const PROFILE_SETUPS = Object.freeze({
+  doorLock: setupDoorLockProfile,
+  mapped: setupMappedEndpointProfile
+})
+
+const setupMatterControllerProfile = (profile, RED, node, config) => {
+  const setup = PROFILE_SETUPS[profile]
+  if (typeof setup !== 'function') return false
+  setup(RED, node, config)
+  return true
+}
+
+module.exports = { PROFILE_SETUPS, setupMatterControllerProfile }

package/nodes/utils/matterControllerProfiles/mappedEndpoint.js

@@ -0,0 +1,150 @@
+'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 })
+  // knxUltimate-config calls setNodeStatus synchronously while adding the client.
+  node.setNodeStatus = ({ fill = 'grey', shape = 'ring', text = '' } = {}) => 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/package.json

@@ -3,7 +3,7 @@
   "engines": {
     "node": ">=20.18.1"
   },
-  "version": "6.0.6",
+  "version": "6.0.8",
   "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",