node-red-contrib-knx-ultimate 4.1.19 → 4.1.21

package/CHANGELOG.md

@@ -6,6 +6,16 @@
 
 # CHANGELOG
 
+**Version 4.1.21** - January 2026<br/>
+
+- NEW: **KNX Multi Routing**: added KNX routing counter (hop count) handling to prevent telegram loops: optional **Respect routing counter (drop if 0)** and **Decrement routing counter when routing**.<br/>
+- FIX: **KNX Multi Routing**: improved behaviour with rewritten telegrams by relying on coherent cEMI; `knx.routingCounter` is exposed based on `knx.cemi.hex`.<br/>
+- CHANGE: **KNX Router Filter**: cEMI consistency is now always enforced when rewriting `knx.source`/`knx.destination` (updates `knx.cemi.hex` accordingly; removed the related toggle option).<br/>
+- CHANGE: **KNX Router Filter**: added `cemiSynced` metadata on passed messages (`msg.payload.knxRouterFilter.cemiSynced`).<br/>
+- NEW: **KNX Router Filter**: runtime configuration via `msg.setConfig` (all node parameters), retained until next `msg.setConfig` or redeploy/restart; config messages are not forwarded.<br/>
+- IMPROVE: **KNX Multi Routing Server KNX/IP**: better status/diagnostics and docs note about **Advertise host** for clients that show “connected” but the server receives no telegrams (multi-homed/Docker/VM).<br/>
+- Docs/help/wiki: updated **KNX Multi Routing** and **KNX Router Filter** pages in all supported languages to document routing counter, rewrite+cEMI sync behaviour, and `msg.setConfig` usage (with examples).<br/>
+
 **Version 4.1.19** - February 2026<br/>
 
 - NEW: **KNX Multi Routing**: added **Server KNX/IP** mode (standalone KNXnet/IP tunneling server) that outputs/accepts RAW telegrams on the node ports (no gateway required).<br/>

package/nodes/knxUltimateMultiRouting.html

@@ -10,6 +10,8 @@
             name: { value: "KNX Multi Routing", required: false },
             outputtopic: { value: "", required: false },
             dropIfSameGateway: { value: true },
+            respectRoutingCounter: { value: true },
+            decrementRoutingCounter: { value: false },
 
             // KNX/IP tunneling server options (mode=server)
             tunnelListenHost: { value: "0.0.0.0", required: false },
@@ -83,6 +85,16 @@
         <label style="width:auto" for="node-input-dropIfSameGateway">&nbsp;&nbsp;<span data-i18n="knxUltimateMultiRouting.properties.dropIfSameGateway"></span></label>
     </div>
 
+    <div class="form-row">
+        <input type="checkbox" id="node-input-respectRoutingCounter" style="display:inline-block; width:auto; vertical-align:top;">
+        <label style="width:auto" for="node-input-respectRoutingCounter">&nbsp;&nbsp;<span data-i18n="knxUltimateMultiRouting.properties.respectRoutingCounter"></span></label>
+    </div>
+
+    <div class="form-row">
+        <input type="checkbox" id="node-input-decrementRoutingCounter" style="display:inline-block; width:auto; vertical-align:top;">
+        <label style="width:auto" for="node-input-decrementRoutingCounter">&nbsp;&nbsp;<span data-i18n="knxUltimateMultiRouting.properties.decrementRoutingCounter"></span></label>
+    </div>
+
     <div class="form-row knxmr-row-tunnel">
         <hr/>
         <b><span data-i18n="knxUltimateMultiRouting.properties.tunnelTitle"></span></b>

package/nodes/knxUltimateMultiRouting.js

@@ -1,5 +1,16 @@
 // KNX Multi Routing - interconnect multiple KNX Ultimate gateways via Node-RED flows
 const loggerClass = require('./utils/sysLogger')
+const os = require('os')
+
+const toBoolean = (value, fallback) => {
+  if (value === undefined || value === null) return fallback
+  if (typeof value === 'boolean') return value
+  if (typeof value === 'number') return value !== 0
+  const s = String(value).trim().toLowerCase()
+  if (s === 'true' || s === '1' || s === 'yes' || s === 'on') return true
+  if (s === 'false' || s === '0' || s === 'no' || s === 'off') return false
+  return fallback
+}
 
 const safeNumber = (value, fallback) => {
   const n = Number(value)
@@ -28,6 +39,34 @@ const bufferFromMaybe = (value) => {
   return null
 }
 
+const CEMI_L_DATA_REQ = 0x11
+const CEMI_L_DATA_IND = 0x29
+
+const isWildcardHost = (host) => {
+  const h = host === undefined || host === null ? '' : String(host).trim()
+  return h === '' || h === '0.0.0.0' || h === '::' || h === '::0'
+}
+
+const guessAdvertiseHost = (listenHost) => {
+  if (listenHost && !isWildcardHost(listenHost)) return String(listenHost)
+  try {
+    const ifaces = os.networkInterfaces()
+    for (const entries of Object.values(ifaces)) {
+      for (const entry of entries || []) {
+        if (entry.family === 'IPv4' && !entry.internal) return entry.address
+      }
+    }
+  } catch (e) { /* ignore */ }
+  return '127.0.0.1'
+}
+
+let _knxultimateCache = null
+const getKnxultimate = () => {
+  if (_knxultimateCache) return _knxultimateCache
+  _knxultimateCache = require('knxultimate')
+  return _knxultimateCache
+}
+
 module.exports = function (RED) {
   function knxUltimateMultiRouting (config) {
     RED.nodes.createNode(this, config)
@@ -61,12 +100,18 @@ module.exports = function (RED) {
     // Forwarding controls (input -> KNX bus)
     // Basic loop protection: drop messages already tagged as originating from this same gateway.
     node.dropIfSameGateway = config.dropIfSameGateway !== undefined ? (config.dropIfSameGateway === true || config.dropIfSameGateway === 'true') : true
+    node.respectRoutingCounter = toBoolean(config.respectRoutingCounter, true)
+    node.decrementRoutingCounter = toBoolean(config.decrementRoutingCounter, false)
 
     // KNX/IP tunneling server (optional)
     node.tunnelServer = null
     node.tunnelSessions = new Set()
     node.tunnelGatewayId = ''
     node.tunnelAssignedIndividualAddress = ''
+    node.tunnelAdvertiseHostTimer = null
+    node.tunnelStatusRefreshTimer = null
+    node.tunnelRxCount = 0
+    node.tunnelLastRxAt = 0
 
     const pushStatus = (status) => {
       if (!status) return
@@ -118,12 +163,80 @@ module.exports = function (RED) {
     // Called by knxUltimate-config.js to deliver bus telegrams (raw APDU + addresses)
     node.handleSend = (msg) => {
       try {
-        node.send(msg)
+        const processed = applyRoutingCounterOnOutboundMsg(msg)
+        if (!processed) return
+        node.send(processed)
       } catch (error) {
         node.sysLogger?.error(`knxUltimateMultiRouting: output error: ${error.message}`)
       }
     }
 
+    const tryParseCemiHex = (cemiHex) => {
+      const clean = normalizeHex(cemiHex)
+      if (!clean || clean.length % 2 !== 0) return null
+      let KNXTunnelingRequest
+      try { ({ KNXTunnelingRequest } = getKnxultimate()) } catch (e) { return null }
+      try { return KNXTunnelingRequest.parseCEMIMessage(Buffer.from(clean, 'hex'), 0) } catch (e) { return null }
+    }
+
+    const getHopCountFromCemiHex = (cemiHex) => {
+      const cemi = tryParseCemiHex(cemiHex)
+      const hop = cemi && cemi.control ? Number(cemi.control.hopCount) : NaN
+      return Number.isFinite(hop) ? hop : null
+    }
+
+    const decrementHopCountInCemiHex = (cemiHex) => {
+      const cemi = tryParseCemiHex(cemiHex)
+      if (!cemi || !cemi.control) return null
+      const hop = Number(cemi.control.hopCount)
+      if (!Number.isFinite(hop)) return null
+      if (hop <= 0) return { oldHopCount: hop, newHopCount: hop, cemiHex: cemi.toBuffer().toString('hex') }
+      const newHop = hop - 1
+      cemi.control.hopCount = newHop
+      return { oldHopCount: hop, newHopCount: newHop, cemiHex: cemi.toBuffer().toString('hex') }
+    }
+
+    const applyRoutingCounterOnOutboundMsg = (msg) => {
+      if (!msg) return msg
+      const p = msg.payload !== undefined ? msg.payload : msg
+      const k = (p && p.knx) ? p.knx : (msg && msg.knx ? msg.knx : null)
+      if (!k || typeof k !== 'object') return msg
+      const cemiHex = (k.cemi && (k.cemi.hex || k.cemi)) ? (k.cemi.hex || k.cemi) : ''
+      if (!cemiHex) return msg
+
+      const hopCount = getHopCountFromCemiHex(cemiHex)
+      if (hopCount !== null) {
+        try { k.routingCounter = hopCount } catch (e) { /* ignore */ }
+        try {
+          if (k.cemi && typeof k.cemi === 'object') k.cemi.hopCount = hopCount
+        } catch (e) { /* ignore */ }
+      }
+
+      if (node.respectRoutingCounter && hopCount === 0) {
+        node.setNodeStatus({ fill: 'grey', shape: 'ring', text: 'Dropped (routing counter 0)', payload: k.event || '', GA: k.destination || '', dpt: '', devicename: k.source || '' })
+        return null
+      }
+
+      if (!node.decrementRoutingCounter) return msg
+      if (hopCount === null) return msg
+
+      const dec = decrementHopCountInCemiHex(cemiHex)
+      if (!dec) return msg
+
+      if (node.respectRoutingCounter && dec.newHopCount === 0) {
+        node.setNodeStatus({ fill: 'grey', shape: 'ring', text: 'Dropped (routing counter 0)', payload: k.event || '', GA: k.destination || '', dpt: '', devicename: k.source || '' })
+        return null
+      }
+
+      try {
+        if (k.cemi && typeof k.cemi === 'object' && 'hex' in k.cemi) k.cemi.hex = dec.cemiHex
+        else k.cemi = dec.cemiHex
+      } catch (e) { /* ignore */ }
+      try { k.routingCounter = dec.newHopCount } catch (e) { /* ignore */ }
+      try { if (k.cemi && typeof k.cemi === 'object') k.cemi.hopCount = dec.newHopCount } catch (e) { /* ignore */ }
+      return msg
+    }
+
     const parseIncoming = (msg) => {
       const p = (msg && msg.payload !== undefined) ? msg.payload : msg
       const k = (p && p.knx) ? p.knx : (msg && msg.knx ? msg.knx : p)
@@ -136,10 +249,11 @@ module.exports = function (RED) {
       const apduData = bufferFromMaybe(apdu.data !== undefined ? apdu.data : (k.rawValue !== undefined ? k.rawValue : k.apduData))
       const bitlength = Number(apdu.bitlength !== undefined ? apdu.bitlength : (k.bitlength !== undefined ? k.bitlength : (apduData ? apduData.length * 8 : 0)))
       const cemiHex = (k.cemi && (k.cemi.hex || k.cemi)) ? (k.cemi.hex || k.cemi) : ''
+      const hopCount = cemiHex ? getHopCountFromCemiHex(cemiHex) : null
 
       const routing = (p && p.knxMultiRouting) ? p.knxMultiRouting : (msg && msg.knxMultiRouting ? msg.knxMultiRouting : null)
       const originGatewayId = routing && routing.gateway && routing.gateway.id ? String(routing.gateway.id) : ''
-      return { event, destination, source, apduData, bitlength, originGatewayId, cemiHex }
+      return { event, destination, source, apduData, bitlength, originGatewayId, cemiHex, hopCount }
     }
 
     const canForwardToGateway = (parsed) => {
@@ -147,11 +261,55 @@ module.exports = function (RED) {
       if (!parsed.destination || typeof parsed.destination !== 'string') return false
       if (!node.serverKNX || node.serverKNX.linkStatus !== 'connected' || !node.serverKNX.knxConnection) return false
       if (node.dropIfSameGateway && parsed.originGatewayId && localGatewayIds().has(String(parsed.originGatewayId))) return false
+      if (node.respectRoutingCounter && parsed.hopCount === 0) return false
       return true
     }
 
     const forwardToBus = (parsed) => {
       const client = node.serverKNX.knxConnection
+      if (parsed.cemiHex) {
+        const cemi = tryParseCemiHex(parsed.cemiHex)
+        if (cemi && cemi.control) {
+          // Apply routing-counter checks while forwarding to the BUS.
+          const hop = Number(cemi.control.hopCount)
+          if (Number.isFinite(hop)) {
+            if (node.respectRoutingCounter && hop === 0) return
+          }
+
+          const isSerial = typeof client.isSerialTransport === 'function' ? client.isSerialTransport() : false
+          const hostProtocol = client && client._options && client._options.hostProtocol ? String(client._options.hostProtocol) : ''
+          let KNXProtocol
+          try { ({ KNXProtocol } = getKnxultimate()) } catch (e) { KNXProtocol = null }
+          if (!KNXProtocol || typeof client.send !== 'function') {
+            // fall back to legacy methods below
+          } else if (hostProtocol === 'Multicast' || isSerial) {
+            cemi.msgCode = hostProtocol === 'Multicast' ? CEMI_L_DATA_IND : CEMI_L_DATA_REQ
+            const knxPacketRequest = KNXProtocol.newKNXRoutingIndication(cemi)
+            const expected = (typeof client.getSeqNumber === 'function') ? client.getSeqNumber() : 0
+            client.send(knxPacketRequest, undefined, false, expected)
+            return
+          } else {
+            // Tunneling
+            cemi.msgCode = CEMI_L_DATA_REQ
+            try {
+              if (hostProtocol === 'TunnelTCP') cemi.control.ack = 0
+              else cemi.control.ack = (client._options && client._options.suppress_ack_ldatareq) ? 0 : 1
+            } catch (e) { /* ignore */ }
+
+            const seqNum = (hostProtocol === 'TunnelTCP' && typeof client.secureIncTunnelSeq === 'function')
+              ? client.secureIncTunnelSeq()
+              : (typeof client.incSeqNumber === 'function' ? client.incSeqNumber() : 0)
+
+            const ch = (client.channelID !== undefined && client.channelID !== null) ? client.channelID : (client._channelID || 0)
+            const knxPacketRequest = KNXProtocol.newKNXTunnelingRequest(ch, seqNum, cemi)
+            const wantsAck = !(client._options && client._options.suppress_ack_ldatareq)
+            client.send(knxPacketRequest, wantsAck ? knxPacketRequest : undefined, false, seqNum)
+            return
+          }
+        }
+      }
+
+      // Legacy: re-create telegram from event+APDU (routing counter will be reset by the library).
       const ga = parsed.destination
       if (parsed.event === 'GroupValue_Write') {
         if (!parsed.apduData) return
@@ -177,6 +335,7 @@ module.exports = function (RED) {
       if (!node.tunnelServer) return false
       if (!parsed.cemiHex) return false
       if (node.dropIfSameGateway && parsed.originGatewayId && localGatewayIds().has(String(parsed.originGatewayId))) return false
+      if (node.respectRoutingCounter && parsed.hopCount === 0) return false
       return true
     }
 
@@ -184,7 +343,7 @@ module.exports = function (RED) {
       const clean = normalizeHex(parsed.cemiHex)
       if (!clean || clean.length % 2 !== 0) return
       let KNXTunnelingRequest
-      try { ({ KNXTunnelingRequest } = require('knxultimate')) } catch (e) { throw new Error('knxultimate KNXTunnelingRequest not available') }
+      try { ({ KNXTunnelingRequest } = getKnxultimate()) } catch (e) { throw new Error('knxultimate KNXTunnelingRequest not available') }
       const cemi = KNXTunnelingRequest.parseCEMIMessage(Buffer.from(clean, 'hex'), 0)
       node.tunnelServer.injectCemi(cemi)
     }
@@ -194,9 +353,16 @@ module.exports = function (RED) {
       const addr = node.tunnelServer && typeof node.tunnelServer.address === 'object' ? node.tunnelServer.address : null
       const host = addr ? addr.host : (config.tunnelListenHost || '0.0.0.0')
       const port = addr ? addr.port : safeNumber(config.tunnelListenPort, 3671)
-      const sessions = node.tunnelSessions ? node.tunnelSessions.size : 0
+      const sessionsFromServer = node.tunnelServer && node.tunnelServer.sessions && typeof node.tunnelServer.sessions.size === 'number'
+        ? node.tunnelServer.sessions.size
+        : null
+      const sessionsFromEvents = node.tunnelSessions ? node.tunnelSessions.size : 0
+      const sessions = sessionsFromServer !== null ? sessionsFromServer : sessionsFromEvents
+      const adv = (node.tunnelServer && node.tunnelServer.options && node.tunnelServer.options.advertiseHost) ? node.tunnelServer.options.advertiseHost : ''
       const tail = extraText ? ` ${extraText}` : ''
-      updateStatus({ fill: 'green', shape: 'dot', text: `Tunnel ${host}:${port} sessions:${sessions}${tail}` })
+      const advText = adv ? ` adv:${adv}` : ''
+      const rxText = node.tunnelRxCount ? ` rx:${node.tunnelRxCount}` : ''
+      updateStatus({ fill: 'green', shape: 'dot', text: `Tunnel ${host}:${port}${advText} sessions:${sessions}${rxText}${tail}` })
     }
 
     const startTunnelServerIfNeeded = () => {
@@ -213,7 +379,8 @@ module.exports = function (RED) {
 
       const listenHost = (config.tunnelListenHost && String(config.tunnelListenHost).trim()) || '0.0.0.0'
       const listenPort = safeNumber(config.tunnelListenPort, 3671)
-      const advertiseHost = (config.tunnelAdvertiseHost && String(config.tunnelAdvertiseHost).trim()) || undefined
+      const advertiseHostConfigured = (config.tunnelAdvertiseHost && String(config.tunnelAdvertiseHost).trim()) || ''
+      const advertiseHost = advertiseHostConfigured || guessAdvertiseHost(listenHost)
       const maxSessions = Math.max(1, safeNumber(config.tunnelMaxSessions, 1))
 
       const loglevel = (node.serverKNX && node.serverKNX.loglevel) ? node.serverKNX.loglevel : 'error'
@@ -227,6 +394,26 @@ module.exports = function (RED) {
         loglevel
       })
 
+      // If the OS network was not ready at boot, periodically refresh auto-advertise host.
+      // This affects only new client connections (CONNECT_RESPONSE payload).
+      if (!advertiseHostConfigured) {
+        const refreshAdvertiseHost = () => {
+          try {
+            if (!node.tunnelServer || !node.tunnelServer.options) return
+            const next = guessAdvertiseHost(listenHost)
+            const cur = node.tunnelServer.options.advertiseHost
+            if (next && cur !== next) {
+              node.tunnelServer.options.advertiseHost = next
+              updateTunnelStatus('(adv host updated)')
+            }
+          } catch (e) { /* ignore */ }
+        }
+        try {
+          node.tunnelAdvertiseHostTimer = setInterval(refreshAdvertiseHost, 10000)
+          if (node.tunnelAdvertiseHostTimer && typeof node.tunnelAdvertiseHostTimer.unref === 'function') node.tunnelAdvertiseHostTimer.unref()
+        } catch (e) { /* ignore */ }
+      }
+
       node.tunnelServer.on('error', (err) => {
         updateStatus({ fill: 'red', shape: 'dot', text: `Tunnel error: ${err.message}` })
         node.error(err)
@@ -248,6 +435,8 @@ module.exports = function (RED) {
 
       node.tunnelServer.on('rawTelegram', (knx, info) => {
         try {
+          node.tunnelRxCount = (node.tunnelRxCount || 0) + 1
+          node.tunnelLastRxAt = Date.now()
           const msg = {
             topic: node.outputtopic || knx.destination,
             payload: {
@@ -259,12 +448,20 @@ module.exports = function (RED) {
               }
             }
           }
-          node.send(msg)
+          const processed = applyRoutingCounterOnOutboundMsg(msg)
+          if (!processed) return
+          node.send(processed)
         } catch (error) {
           node.sysLogger?.error(`knxUltimateMultiRouting: tunnel rawTelegram output error: ${error.message}`)
         }
       })
 
+      // Periodic refresh to surface session count even if Node-RED doesn't show transient updates.
+      try {
+        node.tunnelStatusRefreshTimer = setInterval(() => updateTunnelStatus(''), 5000)
+        if (node.tunnelStatusRefreshTimer && typeof node.tunnelStatusRefreshTimer.unref === 'function') node.tunnelStatusRefreshTimer.unref()
+      } catch (e) { /* ignore */ }
+
       updateStatus({ fill: 'grey', shape: 'dot', text: 'Starting KNX/IP Server...' })
       Promise.resolve()
         .then(() => node.tunnelServer.start())
@@ -278,6 +475,23 @@ module.exports = function (RED) {
     node.on('input', function (msg) {
       try {
         const parsed = parseIncoming(msg)
+        if (node.respectRoutingCounter && parsed && parsed.hopCount === 0) {
+          node.setNodeStatus({ fill: 'grey', shape: 'ring', text: 'Dropped (routing counter 0)', payload: parsed.event || '', GA: parsed.destination, dpt: '', devicename: parsed.source || '' })
+          return
+        }
+
+        if (node.decrementRoutingCounter && parsed && parsed.cemiHex && parsed.hopCount !== null && parsed.hopCount > 0) {
+          const dec = decrementHopCountInCemiHex(parsed.cemiHex)
+          if (dec) {
+            if (node.respectRoutingCounter && dec.newHopCount === 0) {
+              node.setNodeStatus({ fill: 'grey', shape: 'ring', text: 'Dropped (routing counter 0)', payload: parsed.event || '', GA: parsed.destination, dpt: '', devicename: parsed.source || '' })
+              return
+            }
+            parsed.cemiHex = dec.cemiHex
+            parsed.hopCount = dec.newHopCount
+          }
+        }
+
         if (node.mode === 'server') {
           if (!canForwardToTunnel(parsed)) return
           forwardToTunnel(parsed)
@@ -298,6 +512,14 @@ module.exports = function (RED) {
         if (node.serverKNX) {
           try { node.serverKNX.removeClient(node) } catch (e) { /* ignore */ }
         }
+        if (node.tunnelAdvertiseHostTimer) {
+          try { clearInterval(node.tunnelAdvertiseHostTimer) } catch (e) { /* ignore */ }
+          node.tunnelAdvertiseHostTimer = null
+        }
+        if (node.tunnelStatusRefreshTimer) {
+          try { clearInterval(node.tunnelStatusRefreshTimer) } catch (e) { /* ignore */ }
+          node.tunnelStatusRefreshTimer = null
+        }
         if (node.tunnelServer) {
           try { await node.tunnelServer.stop() } catch (e) { /* ignore */ }
           node.tunnelServer = null

package/nodes/knxUltimateRouterFilter.html

@@ -131,4 +131,4 @@
         <label for="node-input-srcRewriteRules"><i class="fa fa-random"></i> <span data-i18n="knxUltimateRouterFilter.properties.srcRewriteRules"></span></label>
         <textarea style="width:100%; height:90px;" id="node-input-srcRewriteRules" data-i18n="[placeholder]knxUltimateRouterFilter.placeholder.srcRewriteRules"></textarea>
     </div>
-</script>
+</script>