node-red-contrib-knx-ultimate 6.3.24 → 6.3.25

package/nodes/knxUltimateIoTBridge.js

@@ -98,13 +98,43 @@ module.exports = function (RED) {
       }
     }
 
+    const normaliseModbusArea = (value, legacyFunction = '') => {
+      switch (value) {
+        case 'coil':
+        case 'discrete-input':
+        case 'holding-register':
+        case 'input-register':
+          return value
+        default: {
+          const fn = sanitizeString(legacyFunction).toLowerCase()
+          if (fn.includes('discrete')) return 'discrete-input'
+          if (fn.includes('input') && fn.includes('register')) return 'input-register'
+          if (fn.includes('coil')) return 'coil'
+          return 'holding-register'
+        }
+      }
+    }
+
+    const normaliseModbusDataType = (value, area) => {
+      if (area === 'coil' || area === 'discrete-input') return 'bool'
+      switch (value) {
+        case 'bool':
+        case 'uint16':
+        case 'int16':
+          return value
+        default:
+          return 'uint16'
+      }
+    }
+
     const ensureId = (value) => {
       const id = sanitizeString(value)
       return id !== '' ? id : (RED.util && typeof RED.util.generateId === 'function' ? RED.util.generateId() : Math.random().toString(16).slice(2))
     }
 
     const cleanMapping = (raw) => {
-      const mapping = { ...raw }
+      const source = raw && typeof raw === 'object' ? raw : {}
+      const mapping = { ...source }
       mapping.id = ensureId(mapping.id)
       mapping.label = sanitizeString(mapping.label) || mapping.id
       mapping.ga = sanitizeString(mapping.ga)
@@ -114,8 +144,27 @@ module.exports = function (RED) {
       mapping.target = sanitizeString(mapping.target)
       mapping.method = sanitizeString(mapping.method) || 'POST'
       mapping.modbusFunction = sanitizeString(mapping.modbusFunction) || 'writeHoldingRegister'
-      mapping.scale = safeNumber(mapping.scale, 1)
-      mapping.offset = safeNumber(mapping.offset, 0)
+      // Existing flows emitted a generic scalar Modbus message. Keep that exact contract unless
+      // a mapping explicitly opts into the direct node-red-contrib-modbus Flex message shape.
+      mapping.modbusMessageFormat = source.modbusMessageFormat === 'flex' ? 'flex' : 'legacy'
+      mapping.modbusArea = normaliseModbusArea(mapping.modbusArea, mapping.modbusFunction)
+      mapping.modbusDataType = normaliseModbusDataType(mapping.modbusDataType, mapping.modbusArea)
+      if (mapping.modbusMessageFormat === 'flex' && ['discrete-input', 'input-register'].includes(mapping.modbusArea)) {
+        mapping.direction = 'iot-to-knx'
+      }
+      mapping.modbusUnitId = mapping.modbusUnitId === undefined || mapping.modbusUnitId === null || mapping.modbusUnitId === ''
+        ? 1
+        : mapping.modbusUnitId
+      mapping.modbusAddress = mapping.modbusAddress === undefined || mapping.modbusAddress === null || mapping.modbusAddress === ''
+        ? mapping.target
+        : mapping.modbusAddress
+      if (mapping.modbusMessageFormat === 'flex') {
+        mapping.scale = mapping.scale === undefined || mapping.scale === null || mapping.scale === '' ? 1 : Number(mapping.scale)
+        mapping.offset = mapping.offset === undefined || mapping.offset === null || mapping.offset === '' ? 0 : Number(mapping.offset)
+      } else {
+        mapping.scale = safeNumber(mapping.scale, 1)
+        mapping.offset = safeNumber(mapping.offset, 0)
+      }
       mapping.template = sanitizeString(mapping.template)
       mapping.property = sanitizeString(mapping.property)
       mapping.enabled = mapping.enabled !== false
@@ -277,6 +326,92 @@ module.exports = function (RED) {
       return Boolean(value)
     }
 
+    const toStrictBoolean = (value) => {
+      if (typeof value === 'boolean') return value
+      if (typeof value === 'number' && Number.isFinite(value)) {
+        if (value === 0) return false
+        if (value === 1) return true
+      }
+      if (typeof value === 'string') {
+        const lowered = value.trim().toLowerCase()
+        if (['true', '1', 'on', 'yes', 'open'].includes(lowered)) return true
+        if (['false', '0', 'off', 'no', 'close', 'closed'].includes(lowered)) return false
+      }
+      throw new Error(`Invalid Modbus boolean value: ${JSON.stringify(value)}`)
+    }
+
+    const strictInteger = (value, field, min, max) => {
+      if (value === '' || value === null || value === undefined || typeof value === 'boolean') {
+        throw new Error(`${field} must be an integer between ${min} and ${max}`)
+      }
+      const parsed = Number(value)
+      if (!Number.isInteger(parsed) || parsed < min || parsed > max) {
+        throw new Error(`${field} must be an integer between ${min} and ${max}`)
+      }
+      return parsed
+    }
+
+    const validateModbusScale = (mapping) => {
+      if (!Number.isFinite(mapping.scale) || mapping.scale === 0) {
+        throw new Error('Modbus scale must be a finite number other than zero')
+      }
+      if (!Number.isFinite(mapping.offset)) {
+        throw new Error('Modbus offset must be a finite number')
+      }
+    }
+
+    const getModbusUnitId = (mapping) => strictInteger(mapping.modbusUnitId, 'Modbus Unit ID', 0, 255)
+    const getModbusAddress = (mapping) => strictInteger(mapping.modbusAddress, 'Modbus address', 0, 65535)
+
+    const getModbusReadFunctionCode = (mapping) => {
+      switch (mapping.modbusArea) {
+        case 'coil': return 1
+        case 'discrete-input': return 2
+        case 'holding-register': return 3
+        case 'input-register': return 4
+        default: throw new Error(`Unsupported Modbus area: ${mapping.modbusArea}`)
+      }
+    }
+
+    const getModbusWriteFunctionCode = (mapping) => {
+      if (mapping.modbusArea === 'coil') return 5
+      if (mapping.modbusArea === 'holding-register') return 6
+      throw new Error(`The Modbus area ${mapping.modbusArea} is read-only`)
+    }
+
+    const encodeModbusWriteValue = (mapping, value) => {
+      validateModbusScale(mapping)
+      if (mapping.modbusArea === 'coil') return toStrictBoolean(value)
+
+      if (value === '' || value === null || value === undefined) {
+        throw new Error('Modbus register value must be numeric')
+      }
+      const numeric = Number(value)
+      if (!Number.isFinite(numeric)) throw new Error('Modbus register value must be finite')
+
+      if (mapping.modbusDataType === 'bool') return toStrictBoolean(value) ? 1 : 0
+
+      const rounded = Math.round(numeric)
+      if (mapping.modbusDataType === 'int16') {
+        if (rounded < -32768 || rounded > 32767) throw new Error('Modbus int16 value is outside -32768..32767')
+        return rounded < 0 ? 0x10000 + rounded : rounded
+      }
+      if (rounded < 0 || rounded > 65535) throw new Error('Modbus uint16 value is outside 0..65535')
+      return rounded
+    }
+
+    const decodeModbusReadValue = (mapping, rawValue) => {
+      validateModbusScale(mapping)
+      if (mapping.modbusArea === 'coil' || mapping.modbusArea === 'discrete-input') {
+        return toStrictBoolean(rawValue)
+      }
+
+      const word = strictInteger(rawValue, 'Modbus register value', 0, 65535)
+      if (mapping.modbusDataType === 'bool') return word !== 0
+      if (mapping.modbusDataType === 'int16') return word > 0x7fff ? word - 0x10000 : word
+      return word
+    }
+
     const applyScale = (value, mapping) => {
       if (typeof value === 'number' && Number.isFinite(value)) {
         return (value * mapping.scale) + mapping.offset
@@ -318,6 +453,31 @@ module.exports = function (RED) {
         .replace(/{{\s*isoTimestamp\s*}}/g, new Date().toISOString())
     }
 
+    const buildModbusFlexWrite = (mapping, value) => {
+      const unitid = getModbusUnitId(mapping)
+      const address = getModbusAddress(mapping)
+      const fc = getModbusWriteFunctionCode(mapping)
+      return {
+        request: {
+          value: encodeModbusWriteValue(mapping, value),
+          fc,
+          unitid,
+          address,
+          quantity: 1
+        },
+        metadata: {
+          contract: 'flex-v1',
+          operation: 'write',
+          unitid,
+          address,
+          quantity: 1,
+          fc,
+          area: mapping.modbusArea,
+          dataType: mapping.modbusDataType
+        }
+      }
+    }
+
     const buildOutMessage = (mapping, value, meta) => {
       const context = {
         value,
@@ -328,11 +488,18 @@ module.exports = function (RED) {
         isoTimestamp: new Date().toISOString()
       }
 
-      const payload = renderTemplate(mapping.template, context)
-      const topic = mapping.iotType === 'mqtt'
+      let payload = renderTemplate(mapping.template, context)
+      let topic = mapping.iotType === 'mqtt'
         ? (mapping.target || node.outputtopic || mapping.ga)
         : (node.outputtopic || mapping.target || mapping.ga)
 
+      let modbusFlex = null
+      if (mapping.iotType === 'modbus' && mapping.modbusMessageFormat === 'flex') {
+        modbusFlex = buildModbusFlexWrite(mapping, value)
+        payload = modbusFlex.request
+        topic = `knxultimate/modbus/${node.id}/${mapping.id}/write`
+      }
+
       const out = {
         topic,
         payload,
@@ -369,11 +536,17 @@ module.exports = function (RED) {
         out.headers = meta.headers || {}
       }
       if (mapping.iotType === 'modbus') {
-        out.modbusFunction = mapping.modbusFunction
-        out.address = mapping.target
+        out.modbusFunction = modbusFlex
+          ? (modbusFlex.request.fc === 5 ? 'writeCoil' : 'writeHoldingRegister')
+          : mapping.modbusFunction
+        out.address = modbusFlex ? modbusFlex.request.address : mapping.target
         if (mapping.property) out.property = mapping.property
         out.timeout = mapping.timeout
         out.retry = mapping.retry
+        if (modbusFlex) {
+          out.bridge.modbusFunction = out.modbusFunction
+          out.bridge.modbus = modbusFlex.metadata
+        }
       }
       if (mapping.iotType === 'mqtt' && mapping.property) {
         out.property = mapping.property
@@ -395,6 +568,30 @@ module.exports = function (RED) {
       node.stateById.set(mapping.id, current)
     }
 
+    const rememberKnxEchoToSuppress = (mapping, value) => {
+      const current = node.stateById.get(mapping.id) || {}
+      current.suppressKnxEchoValue = value
+      current.suppressKnxEchoUntil = Date.now() + 2000
+      node.stateById.set(mapping.id, current)
+    }
+
+    const shouldSuppressKnxEcho = (mapping, value, msg) => {
+      if (mapping.iotType !== 'modbus' || mapping.modbusMessageFormat !== 'flex') return false
+      const current = node.stateById.get(mapping.id)
+      if (!current) return false
+      if (current.suppressKnxEchoUntil < Date.now()) {
+        delete current.suppressKnxEchoValue
+        delete current.suppressKnxEchoUntil
+        return false
+      }
+      const isEchoed = msg && (msg.echoed === true || (msg.knx && msg.knx.echoed === true))
+      if (!isEchoed) return false
+      if (!valuesAreEqual(current.suppressKnxEchoValue, value)) return false
+      delete current.suppressKnxEchoValue
+      delete current.suppressKnxEchoUntil
+      return true
+    }
+
     const shouldEmitKnxValue = (mapping, value) => {
       if (!node.emitOnChangeOnly) return true
       const current = node.stateById.get(mapping.id)
@@ -402,8 +599,113 @@ module.exports = function (RED) {
       return !valuesAreEqual(current.lastKnxValue, value)
     }
 
+    const shouldWriteModbusValueToKnx = (mapping, value) => {
+      if (!node.emitOnChangeOnly) return true
+      const current = node.stateById.get(mapping.id)
+      if (!current || current.lastIoTValue === undefined) return true
+      return !valuesAreEqual(current.lastIoTValue, value)
+    }
+
     const findMappingsByGA = (ga) => node.gaIndex.get(ga) || []
 
+    const getModbusRequestFromMessage = (msg) => {
+      if (!msg || typeof msg !== 'object') return null
+      if (msg.modbusRequest && typeof msg.modbusRequest === 'object') return msg.modbusRequest
+      if (msg.input && msg.input.payload && typeof msg.input.payload === 'object' && !Array.isArray(msg.input.payload) && Object.prototype.hasOwnProperty.call(msg.input.payload, 'fc')) {
+        return msg.input.payload
+      }
+      if (msg.responseBuffer && msg.payload && typeof msg.payload === 'object' && !Array.isArray(msg.payload) && Object.prototype.hasOwnProperty.call(msg.payload, 'fc')) {
+        return msg.payload
+      }
+      if (msg.responseBuffer && msg.values && typeof msg.values === 'object' && !Array.isArray(msg.values) && Object.prototype.hasOwnProperty.call(msg.values, 'fc')) {
+        return msg.values
+      }
+      if (msg.bridge && msg.bridge.modbus && typeof msg.bridge.modbus === 'object') return msg.bridge.modbus
+      return null
+    }
+
+    const isModbusTransportMessage = (msg) => {
+      if (!msg || typeof msg !== 'object') return false
+      const hasInputRequest = msg.input && msg.input.payload && typeof msg.input.payload === 'object' && Object.prototype.hasOwnProperty.call(msg.input.payload, 'fc')
+      const hasExplicitFlexContract = msg.bridge && msg.bridge.modbus && msg.bridge.modbus.contract === 'flex-v1'
+      return Boolean(
+        msg.modbusRequest ||
+        msg.responseBuffer ||
+        Object.prototype.hasOwnProperty.call(msg, 'values') ||
+        hasInputRequest ||
+        hasExplicitFlexContract
+      ) && getModbusRequestFromMessage(msg) !== null
+    }
+
+    const asModbusDataArray = (value) => {
+      if (Array.isArray(value)) return value
+      if (Buffer.isBuffer(value)) return Array.from(value)
+      if (value && typeof value === 'object' && Array.isArray(value.data)) return value.data
+      return null
+    }
+
+    const getModbusResponseData = (msg, request) => {
+      const candidates = [
+        msg && msg.payload,
+        msg && msg.values,
+        msg && msg.responseBuffer && msg.responseBuffer.data,
+        msg && msg.responseBuffer
+      ]
+      for (const candidate of candidates) {
+        const data = asModbusDataArray(candidate)
+        if (data) return data
+      }
+      const quantity = Number(request && request.quantity)
+      if (quantity === 1 && msg && (typeof msg.payload === 'number' || typeof msg.payload === 'boolean')) return [msg.payload]
+      return null
+    }
+
+    const findMappingsForModbusResponse = (request, dataLength) => {
+      const fc = strictInteger(request.fc, 'Modbus function code', 1, 4)
+      const unitid = strictInteger(request.unitid !== undefined ? request.unitid : request.unitId, 'Modbus Unit ID', 0, 255)
+      const address = strictInteger(request.address, 'Modbus address', 0, 65535)
+      const quantityValue = request.quantity === undefined || request.quantity === null || request.quantity === '' ? dataLength : request.quantity
+      const quantity = strictInteger(quantityValue, 'Modbus quantity', 1, 65536)
+      if (address + quantity > 65536) throw new Error('Modbus address plus quantity exceeds 65536')
+
+      const matches = []
+      for (const mapping of node.mappings) {
+        if (mapping.iotType !== 'modbus' || mapping.modbusMessageFormat !== 'flex') continue
+        if (mapping.direction === 'knx-to-iot') continue
+        try {
+          if (getModbusUnitId(mapping) !== unitid) continue
+          if (getModbusReadFunctionCode(mapping) !== fc) continue
+          const mappingAddress = getModbusAddress(mapping)
+          if (mappingAddress < address || mappingAddress >= address + quantity) continue
+          matches.push({ mapping, offset: mappingAddress - address })
+        } catch (error) {
+          node.setNodeStatus({ fill: 'red', shape: 'dot', text: error.message, mapping })
+        }
+      }
+      return matches
+    }
+
+    const findMappingsForModbusWriteResponse = (request) => {
+      const fc = strictInteger(request.fc, 'Modbus function code', 5, 16)
+      const unitid = strictInteger(request.unitid !== undefined ? request.unitid : request.unitId, 'Modbus Unit ID', 0, 255)
+      const address = strictInteger(request.address, 'Modbus address', 0, 65535)
+      const matches = []
+
+      for (const mapping of node.mappings) {
+        if (mapping.iotType !== 'modbus' || mapping.modbusMessageFormat !== 'flex') continue
+        if (mapping.direction === 'iot-to-knx') continue
+        try {
+          if (getModbusUnitId(mapping) !== unitid) continue
+          if (getModbusAddress(mapping) !== address) continue
+          if (getModbusWriteFunctionCode(mapping) !== fc) continue
+          matches.push(mapping)
+        } catch (error) {
+          node.setNodeStatus({ fill: 'red', shape: 'dot', text: error.message, mapping })
+        }
+      }
+      return matches
+    }
+
     const matchMappingForIoT = (msg) => {
       const bridge = msg.bridge || {}
       const type = bridge.type || (msg.iotType) || 'mqtt'
@@ -450,6 +752,131 @@ module.exports = function (RED) {
       }
     }
 
+    const buildIoTToKnxAck = (mapping, value, modbusRequest) => {
+      const ack = {
+        topic: mapping.ga,
+        payload: value,
+        bridge: {
+          id: mapping.id,
+          label: mapping.label,
+          type: mapping.iotType,
+          direction: 'iot-to-knx',
+          target: mapping.target,
+          method: mapping.method,
+          modbusFunction: mapping.modbusFunction,
+          property: mapping.property,
+          timeout: mapping.timeout,
+          retry: mapping.retry
+        }
+      }
+      if (mapping.iotType === 'rest') {
+        ack.url = mapping.target || ''
+        ack.method = mapping.method || 'POST'
+      }
+      if (mapping.iotType === 'modbus') {
+        ack.address = mapping.modbusMessageFormat === 'flex' ? getModbusAddress(mapping) : mapping.target
+        ack.modbusFunction = mapping.modbusFunction
+        if (mapping.modbusMessageFormat === 'flex') {
+          ack.bridge.modbus = {
+            contract: 'flex-v1',
+            operation: 'read',
+            unitid: getModbusUnitId(mapping),
+            address: getModbusAddress(mapping),
+            quantity: 1,
+            fc: modbusRequest ? Number(modbusRequest.fc) : getModbusReadFunctionCode(mapping),
+            area: mapping.modbusArea,
+            dataType: mapping.modbusDataType
+          }
+        }
+      }
+      return ack
+    }
+
+    const handleModbusTransportInput = (msg, send) => {
+      if (!isModbusTransportMessage(msg)) return { handled: false }
+      const request = getModbusRequestFromMessage(msg)
+      const fc = Number(request && request.fc)
+      const hasExplicitFlexContract = msg.bridge && msg.bridge.modbus && msg.bridge.modbus.contract === 'flex-v1'
+      const routedMapping = matchMappingForIoT(msg)
+      const routedToFlexMapping = routedMapping && routedMapping.iotType === 'modbus' && routedMapping.modbusMessageFormat === 'flex'
+      let matches = []
+
+      try {
+        if ([1, 2, 3, 4].includes(fc)) {
+          const probeLength = Number.isInteger(Number(request.quantity)) && Number(request.quantity) > 0
+            ? Number(request.quantity)
+            : 1
+          matches = findMappingsForModbusResponse(request, probeLength)
+        } else if ([5, 6, 15, 16].includes(fc)) {
+          matches = findMappingsForModbusWriteResponse(request)
+        }
+      } catch (error) {
+        const routedToModbusMapping = routedMapping && routedMapping.iotType === 'modbus'
+        if (!hasExplicitFlexContract && !(msg.error && routedToModbusMapping)) return { handled: false }
+        node.setNodeStatus({ fill: 'red', shape: 'dot', text: error.message })
+        return { handled: true, error }
+      }
+
+      // Preserve the generic scalar path for old mappings (and for MQTT/REST messages that
+      // merely carry Modbus metadata). A message is owned by this adapter only when the request
+      // matches a Flex mapping or carries this bridge's explicit Flex contract.
+      if (msg.error && (hasExplicitFlexContract || matches.length > 0 || (routedMapping && routedMapping.iotType === 'modbus'))) {
+        const error = msg.error instanceof Error ? msg.error : new Error(String(msg.error))
+        const operation = [5, 6, 15, 16].includes(fc) ? 'write' : 'read'
+        node.setNodeStatus({ fill: 'red', shape: 'dot', text: `Modbus ${operation}: ${error.message}` })
+        return { handled: true, error }
+      }
+      if (!hasExplicitFlexContract && routedMapping && !routedToFlexMapping) return { handled: false }
+      if (!hasExplicitFlexContract && matches.length === 0 && !routedToFlexMapping) return { handled: false }
+
+      // Flex Write responses are acknowledgements, not device state. They must never be
+      // interpreted as a value to write onto KNX, even if wired back to this node by mistake.
+      if ([5, 6, 15, 16].includes(fc)) return { handled: true }
+      if (![1, 2, 3, 4].includes(fc)) return { handled: true }
+
+      const data = getModbusResponseData(msg, request)
+      if (!data || data.length === 0) {
+        const error = new Error('Modbus read response has no data')
+        node.setNodeStatus({ fill: 'red', shape: 'dot', text: error.message })
+        return { handled: true, error }
+      }
+
+      try {
+        matches = findMappingsForModbusResponse(request, data.length)
+      } catch (error) {
+        node.setNodeStatus({ fill: 'red', shape: 'dot', text: error.message })
+        return { handled: true, error }
+      }
+
+      if (matches.length === 0) {
+        node.setNodeStatus({ fill: 'yellow', shape: 'ring', text: 'No Modbus mapping for response', payload: request.address })
+        return { handled: true }
+      }
+
+      let firstError = null
+      for (const match of matches) {
+        const mapping = match.mapping
+        try {
+          if (match.offset >= data.length) throw new Error('Modbus read response is shorter than the configured mapping')
+          const rawValue = decodeModbusReadValue(mapping, data[match.offset])
+          let value = typeof rawValue === 'number' ? revertScale(rawValue, mapping) : rawValue
+          if (isBooleanDpt(mapping.dpt)) value = toBoolean(value)
+          if (!shouldWriteModbusValueToKnx(mapping, value)) continue
+
+          sendToKNX(mapping, value)
+          rememberIoTValue(mapping, value)
+          rememberKnxEchoToSuppress(mapping, value)
+          const ack = buildIoTToKnxAck(mapping, value, request)
+          node.setNodeStatus({ fill: 'blue', shape: 'dot', text: 'Modbus→KNX', mapping, payload: value })
+          if (send) send([null, ack]); else node.send([null, ack])
+        } catch (error) {
+          if (!firstError) firstError = error
+          node.setNodeStatus({ fill: 'red', shape: 'dot', text: error.message, mapping })
+        }
+      }
+      return { handled: true, error: firstError }
+    }
+
     // Home Assistant mode: mirror a decoded KNX telegram to MQTT. Works with a telegram coming
     // from the gateway (standalone) or from the input pin (flow mode); both share the shape
     // produced by the KNXUltimate universal node ({ payload, knx: { destination, event } }).
@@ -491,19 +918,24 @@ module.exports = function (RED) {
 
         for (const mapping of mappings) {
           if (mapping.direction === 'iot-to-knx') continue
-          let value = msg.payload
-          if (isBooleanDpt(mapping.dpt)) {
-            value = toBoolean(value)
-          }
-          if (typeof value === 'number') {
-            value = applyScale(value, mapping)
-          }
-          if (!shouldEmitKnxValue(mapping, value)) continue
+          // A Modbus write is a command. Never turn a KNX read response/status telegram into
+          // that command; this also prevents readOnDeploy from changing a Modbus device.
+          if (mapping.iotType === 'modbus' && mapping.modbusMessageFormat === 'flex' && meta.event !== 'GroupValue_Write') continue
+          try {
+            let value = msg.payload
+            if (isBooleanDpt(mapping.dpt)) value = toBoolean(value)
+            if (shouldSuppressKnxEcho(mapping, value, msg)) continue
+            if (typeof value === 'number') value = applyScale(value, mapping)
+            if (!shouldEmitKnxValue(mapping, value)) continue
 
-          const outMsg = buildOutMessage(mapping, value, meta)
-          rememberKnxValue(mapping, value)
-          node.setNodeStatus({ fill: 'green', shape: 'dot', text: 'KNX→IoT', mapping, payload: value })
-          node.send([outMsg, null])
+            const outMsg = buildOutMessage(mapping, value, meta)
+            rememberKnxValue(mapping, value)
+            node.setNodeStatus({ fill: 'green', shape: 'dot', text: 'KNX→IoT', mapping, payload: value })
+            node.send([outMsg, null])
+          } catch (error) {
+            node.setNodeStatus({ fill: 'red', shape: 'dot', text: error.message, mapping })
+            if (node.sysLogger) node.sysLogger.error(`KNX→IoT mapping failed (${mapping.ga}): ${error.message}`)
+          }
         }
       } catch (error) {
         if (node.sysLogger) {
@@ -529,6 +961,13 @@ module.exports = function (RED) {
         if (done) done()
         return
       }
+
+      const modbusResult = handleModbusTransportInput(msg, send)
+      if (modbusResult.handled) {
+        if (done) done(modbusResult.error)
+        return
+      }
+
       const bridgeMapping = matchMappingForIoT(msg)
       if (!bridgeMapping) {
         node.setNodeStatus({ fill: 'yellow', shape: 'ring', text: 'No mapping for input', payload: msg.topic })
@@ -541,6 +980,19 @@ module.exports = function (RED) {
         return
       }
 
+      if (bridgeMapping.iotType === 'modbus' && bridgeMapping.modbusMessageFormat === 'flex') {
+        try {
+          validateModbusScale(bridgeMapping)
+          getModbusUnitId(bridgeMapping)
+          getModbusAddress(bridgeMapping)
+          getModbusReadFunctionCode(bridgeMapping)
+        } catch (error) {
+          node.setNodeStatus({ fill: 'red', shape: 'dot', text: error.message, mapping: bridgeMapping })
+          if (done) done(error)
+          return
+        }
+      }
+
       let value = msg.payload
       if (isBooleanDpt(bridgeMapping.dpt)) {
         value = toBoolean(value)
@@ -554,31 +1006,8 @@ module.exports = function (RED) {
 
       try {
         sendToKNX(bridgeMapping, value)
-        rememberIoTValue(bridgeMapping, msg.payload)
-        const ack = {
-          topic: bridgeMapping.ga,
-          payload: value,
-          bridge: {
-            id: bridgeMapping.id,
-            label: bridgeMapping.label,
-            type: bridgeMapping.iotType,
-            direction: 'iot-to-knx',
-            target: bridgeMapping.target,
-            method: bridgeMapping.method,
-            modbusFunction: bridgeMapping.modbusFunction,
-            property: bridgeMapping.property,
-            timeout: bridgeMapping.timeout,
-            retry: bridgeMapping.retry
-          }
-        }
-        if (bridgeMapping.iotType === 'rest') {
-          ack.url = bridgeMapping.target || ''
-          ack.method = bridgeMapping.method || 'POST'
-        }
-        if (bridgeMapping.iotType === 'modbus') {
-          ack.address = bridgeMapping.target
-          ack.modbusFunction = bridgeMapping.modbusFunction
-        }
+        rememberIoTValue(bridgeMapping, value)
+        const ack = buildIoTToKnxAck(bridgeMapping, value)
         node.setNodeStatus({ fill: 'blue', shape: 'dot', text: 'IoT→KNX', mapping: bridgeMapping, payload: msg.payload })
         if (send) send([null, ack]); else node.send([null, ack])
         if (done) done()
@@ -635,6 +1064,7 @@ module.exports = function (RED) {
       if (!node.serverKNX || typeof node.serverKNX.sendKNXTelegramToKNXEngine !== 'function') return
       for (const mapping of node.mappings) {
         if (mapping.direction === 'iot-to-knx') continue
+        if (mapping.iotType === 'modbus' && mapping.modbusMessageFormat === 'flex') continue
         if (!mapping.ga) continue
         try {
           node.serverKNX.sendKNXTelegramToKNXEngine({

package/nodes/locales/de/knxUltimateIoTBridge.html

@@ -45,7 +45,8 @@ Der Rest dieser Hilfe beschreibt den klassischen **IoT-Bridge**-Modus.
 ## Zuordnungsfelder
 
 - **Richtung** — wählen Sie KNX→IoT, IoT→KNX oder bidirektional.
-- **Kanaltyp** — MQTT verwendet das Target als Topic, REST als Basis-URL, Modbus als Registerkennung.
+- **Kanaltyp** — MQTT verwendet das Target als Topic, REST als Basis-URL; bei Modbus ist **Target** die nullbasierte Protokolladresse (0–65535).
+- **Modbus-Format / Unit-ID / Bereich / Datentyp** — wählen Sie für neue Zuordnungen **Mit Flex Write kompatibel** und danach Einheit, Speicherbereich sowie `bool`, `uint16` oder `int16`. Fehlt das Format, bleibt der alte Skalarvertrag aktiv, damit bestehende Flows weiter funktionieren.
 - **Skalierung & Offset** — werden für KNX→IoT angewandt; IoT→KNX nutzt die inverse Transformation.
 - **Template** — optionale Zeichenkette mit Platzhaltern `{{value}}`, `{{ga}}`, `{{label}}`, `{{target}}`, `{{type}}`, `{{isoTimestamp}}`.
 - **Timeout / Wiederholungen** — Informationsfelder im Output zur Steuerung von Retries und Zeitfenstern in nachfolgenden Nodes.
@@ -88,7 +89,32 @@ Der Rest dieser Hilfe beschreibt den klassischen **IoT-Bridge**-Modus.
 
 ### Modbus-Register-Sync
 
-- Kombinieren Sie den Bridge mit `modbus-flex-write`-Nodes aus `node-red-contrib-modbus`. Ausgang 1 enthält die Modbus-Adresse in `msg.address` und den Wert in `msg.payload`.
+Die Bridge ist ein Nachrichtenadapter für `node-red-contrib-modbus`; sie öffnet selbst keine TCP-/serielle Verbindung und fragt kein Gerät ab. Installieren Sie eine mit Ihrer Node-RED-Laufzeit kompatible Paketversion und verwenden Sie dann dessen Client- und Transport-Nodes.
+
+|Bereich|Lesen|Schreiben|Zulässige Richtung|
+|--|--|--|--|
+| Coil | FC1 | FC5 | Beide Richtungen |
+| Discrete Input | FC2 | — | Nur Modbus → KNX |
+| Holding Register | FC3 | FC6 | Beide Richtungen |
+| Input Register | FC4 | — | Nur Modbus → KNX |
+
+Wählen Sie bei einer neuen Zuordnung `Format = Mit Flex Write kompatibel`. Für KNX → Modbus kann Ausgang 1 direkt mit einem `modbus-flex-write`-Node verbunden werden und gibt Folgendes aus:
+
+```
+msg.payload = {
+  value: 215,
+  fc: 6,
+  unitid: 1,
+  address: 9,
+  quantity: 1
+}
+```
+
+`address` ist immer nullbasiert: bezeichnet ein Gerätehandbuch ein Holding Register als `40010`, lautet seine Protokolladresse üblicherweise `9`; prüfen Sie die Konvention des Handbuchs. Die Bridge unterstützt pro Zuordnung ein Bit oder ein einzelnes 16-Bit-Register. Mehrere Wörter, 32-Bit-/Float-Werte und Byte-/Wortreihenfolge werden derzeit nicht verarbeitet.
+
+Für Modbus → KNX verbinden Sie den Datenausgang eines `modbus-flex-getter`- oder `modbus-read`-Nodes mit dem Eingang der Bridge. Flex Getter stellt die Anfrage (`fc`, `unitid`, `address`, `quantity`) in `msg.modbusRequest` bereit; Modbus Read behält sie in `msg.input.payload`. Das zurückgegebene Werte-Array kann in `msg.payload` oder `msg.values` liegen. Die Bridge unterstützt beide Nachrichtenformen, ordnet alle von der Antwort abgedeckten Flex-Zuordnungen zu und verwendet das passende Array-Element. Aktivieren Sie **Keep Msg Properties** am Flex Getter. Skalierung und Offset folgen `raw = KNX × Skalierung + Offset`; eingehend wird die inverse Umrechnung angewendet.
+
+`KNX-Werte beim Deploy lesen` liest nur KNX; planen Sie Modbus-Lesevorgänge im externen Modbus-Flow. Legacy-Zuordnungen (einschließlich solcher ohne `modbusMessageFormat`) geben weiterhin den bisherigen skalaren Payload mit `msg.address`/`msg.modbusFunction` auf oberster Ebene aus.
 
 ## Beispiel-Flow