node-red-contrib-knx-ultimate 5.0.0 → 5.0.2

package/nodes/knxUltimateIoTBridge.js

@@ -22,7 +22,7 @@ module.exports = function (RED) {
       return
     }
 
-    node.name = config.name || 'KNX IoT Bridge'
+    node.name = config.name || 'KNX MQTT - IoT'
     node.outputtopic = config.outputtopic || ''
 
     node.listenallga = true
@@ -40,6 +40,27 @@ module.exports = function (RED) {
 
     node.mappings = Array.isArray(config.mappings) ? config.mappings : []
 
+    // Operation mode: 'iot' (classic IoT mappings, default) or 'homeassistant' (native
+    // MQTT bridge with Home Assistant discovery for every group address + cover/climate).
+    node.nodeMode = config.nodeMode === 'homeassistant' ? 'homeassistant' : 'iot'
+    // Home Assistant bus wiring: 'standalone' (default) talks to the KNX gateway directly,
+    // 'flow' uses the node's input/output pins instead (wire a KNXUltimate universal node to
+    // both): the input pin feeds KNX bus telegrams in, the output pin emits telegrams to write.
+    node.haBusMode = config.haBusMode === 'flow' ? 'flow' : 'standalone'
+    node.mqttUrl = typeof config.mqttUrl === 'string' ? config.mqttUrl.trim() : ''
+    node.mqttBaseTopic = typeof config.mqttBaseTopic === 'string' && config.mqttBaseTopic.trim() !== '' ? config.mqttBaseTopic.trim() : 'knx-ultimate'
+    node.mqttDiscovery = config.mqttDiscovery !== false && config.mqttDiscovery !== 'false'
+    node.mqttDiscoveryPrefix = typeof config.mqttDiscoveryPrefix === 'string' && config.mqttDiscoveryPrefix.trim() !== '' ? config.mqttDiscoveryPrefix.trim() : 'homeassistant'
+    node.mqttCustomEntities = Array.isArray(config.mqttCustomEntities) ? config.mqttCustomEntities : []
+    // Group addresses to expose as simple entities. Once the user curates the list
+    // (mqttExposeConfigured), only the listed GAs are exposed; otherwise all imported GAs are.
+    node.mqttExposeConfigured = config.mqttExposeConfigured === true
+    node.mqttExposedGAs = Array.isArray(config.mqttExposedGAs) ? config.mqttExposedGAs : []
+    // Group addresses the user marked as read-only: they are still exposed (state is
+    // published to HA) but never accept commands back to the KNX bus.
+    node.mqttReadOnlyGAs = Array.isArray(config.mqttReadOnlyGAs) ? config.mqttReadOnlyGAs : []
+    node.mqttBridge = null
+
     const safeNumber = (value, fallback = 0) => {
       if (value === null || value === undefined || value === '') return fallback
       const parsed = Number(value)
@@ -143,6 +164,98 @@ module.exports = function (RED) {
       }
     }
 
+    // HOME ASSISTANT (MQTT) BRIDGE -----------------------------------------------------------
+    node.startMqttBridge = () => {
+      if (node.mqttBridge !== null) return // already running
+      if (!node.mqttUrl) {
+        pushStatus({ fill: 'red', shape: 'dot', text: 'MQTT broker URL missing' })
+        return
+      }
+      try {
+        // Lazy-require so the node still loads if the optional mqtt dependency is missing.
+        const { createMqttBridge } = require('./lib/mqtt-bridge.js')
+        node.mqttBridge = createMqttBridge({
+          node,
+          url: node.mqttUrl,
+          baseTopic: node.mqttBaseTopic,
+          discovery: node.mqttDiscovery,
+          discoveryPrefix: node.mqttDiscoveryPrefix,
+          username: node.credentials ? node.credentials.mqttUsername : undefined,
+          password: node.credentials ? node.credentials.mqttPassword : undefined,
+          groupAddresses: (node.serverKNX && Array.isArray(node.serverKNX.csv)) ? node.serverKNX.csv : [],
+          customEntities: node.mqttCustomEntities,
+          // null => expose all imported GAs (until the user curates the list).
+          exposedGAs: node.mqttExposeConfigured ? node.mqttExposedGAs : null,
+          // GAs exposed as read-only (state only, no command topic back to KNX).
+          readOnlyGAs: node.mqttReadOnlyGAs,
+          onCommand: ({ ga, dpt, value }) => {
+            // A Home Assistant command arrived: write it to the KNX bus.
+            try {
+              if (node.haBusMode === 'flow') {
+                // Flow mode: emit a message on the (single) output pin for a downstream
+                // KNXUltimate universal node to write to the bus (destination + dpt + payload).
+                node.send({
+                  topic: ga,
+                  destination: ga,
+                  dpt: dpt || '',
+                  payload: value
+                })
+                return
+              }
+              node.serverKNX.sendKNXTelegramToKNXEngine({
+                grpaddr: ga,
+                payload: value,
+                dpt,
+                outputtype: 'write',
+                nodecallerid: node.id
+              })
+            } catch (error) {
+              if (node.sysLogger) node.sysLogger.error('HA bridge write failed (' + ga + '): ' + error.message)
+            }
+          },
+          onStatus: (status) => {
+            if (!status) return
+            if (status.state === 'connected') {
+              pushStatus({ fill: 'green', shape: 'dot', text: 'HA connected (' + (status.detail || '0') + ' entities)' })
+            } else if (status.state === 'error') {
+              pushStatus({ fill: 'red', shape: 'dot', text: 'MQTT ' + (status.detail || 'error') })
+            } else if (status.state === 'reconnect' || status.state === 'offline') {
+              pushStatus({ fill: 'yellow', shape: 'ring', text: 'MQTT ' + status.state })
+            }
+          }
+        })
+        node.mqttBridge.connect()
+        pushStatus({ fill: 'grey', shape: 'ring', text: 'HA mode: connecting (' + node.mqttBridge.entityCount + ' entities)' })
+      } catch (error) {
+        node.mqttBridge = null
+        if (node.sysLogger) node.sysLogger.error('startMqttBridge failed: ' + error.message)
+        pushStatus({ fill: 'red', shape: 'dot', text: 'MQTT bridge: ' + error.message })
+      }
+    }
+
+    node.stopMqttBridge = (done) => {
+      const bridge = node.mqttBridge
+      node.mqttBridge = null
+      let called = false
+      const cb = () => {
+        if (called) return
+        called = true
+        if (typeof done === 'function') {
+          try { done() } catch (error) { /* ignore */ }
+        }
+      }
+      if (!bridge) {
+        cb()
+        return
+      }
+      try {
+        bridge.close(cb)
+      } catch (error) {
+        if (node.sysLogger) node.sysLogger.error('stopMqttBridge error: ' + (error && error.message))
+        cb()
+      }
+    }
+
     const isBooleanDpt = (dpt) => typeof dpt === 'string' && dpt.startsWith('1.')
 
     const toBoolean = (value) => {
@@ -333,12 +446,30 @@ module.exports = function (RED) {
       }
     }
 
+    // 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 } }).
+    const publishKnxToMqtt = (msg) => {
+      if (!msg || !node.mqttBridge) return
+      const destination = msg.knx && msg.knx.destination ? msg.knx.destination : sanitizeString(msg.topic)
+      if (!destination) return
+      const event = msg.knx ? msg.knx.event : undefined
+      if (event === 'GroupValue_Read') return // read requests carry no value
+      node.mqttBridge.publishState(destination, msg.payload)
+    }
+
     const handleKnxTelegram = (msg) => {
       try {
         if (!msg) return
         const destination = msg.knx && msg.knx.destination ? msg.knx.destination : sanitizeString(msg.topic)
         if (!destination) return
 
+        // Home Assistant mode: mirror the decoded value to MQTT and stop (no IoT mappings).
+        if (node.nodeMode === 'homeassistant') {
+          publishKnxToMqtt(msg)
+          return
+        }
+
         const meta = {
           event: msg.knx ? msg.knx.event : undefined,
           source: msg.knx ? msg.knx.source : undefined,
@@ -382,6 +513,14 @@ module.exports = function (RED) {
     node.handleSend = handleKnxTelegram
 
     node.on('input', (msg, send, done) => {
+      // In Home Assistant mode, commands flow in over MQTT, not via the flow input. The one
+      // exception is 'flow' bus mode, where the input pin carries KNX bus telegrams (from a
+      // KNXUltimate universal node) that must be mirrored to MQTT.
+      if (node.nodeMode === 'homeassistant') {
+        if (node.haBusMode === 'flow') publishKnxToMqtt(msg)
+        if (done) done()
+        return
+      }
       if (!node.acceptFlowInput) {
         if (done) done()
         return
@@ -446,14 +585,30 @@ module.exports = function (RED) {
     })
 
     node.on('close', (done) => {
-      if (node.serverKNX && typeof node.serverKNX.removeClient === 'function') {
-        try {
-          node.serverKNX.removeClient(node)
-        } catch (error) {
-          /* empty */
+      // Always call done() exactly once, even if something throws, so a deploy / Node-RED exit
+      // is never blocked by the bridge teardown.
+      let finished = false
+      const finish = () => {
+        if (finished) return
+        finished = true
+        if (typeof done === 'function') {
+          try { done() } catch (error) { /* ignore */ }
         }
       }
-      if (done) done()
+      try {
+        if (node.serverKNX && typeof node.serverKNX.removeClient === 'function') {
+          try {
+            node.serverKNX.removeClient(node)
+          } catch (error) {
+            /* empty */
+          }
+        }
+        // Stop the MQTT bridge (best-effort, hard-capped so redeploy never blocks on the broker).
+        node.stopMqttBridge(finish)
+      } catch (error) {
+        if (node.sysLogger) node.sysLogger.error('close handler error: ' + (error && error.message))
+        finish()
+      }
     })
 
     const registerClient = () => {
@@ -491,10 +646,22 @@ module.exports = function (RED) {
       }
     }
 
-    registerClient()
-    updateIdleStatus()
-    issueInitialReads()
+    // In HA 'flow' mode the KNX telegrams arrive on the input pin, so we must NOT subscribe to
+    // the gateway's client feed (that would double-publish and bypass the intended wiring).
+    const useFlowBus = node.nodeMode === 'homeassistant' && node.haBusMode === 'flow'
+    if (!useFlowBus) registerClient()
+    if (node.nodeMode === 'homeassistant') {
+      node.startMqttBridge()
+    } else {
+      updateIdleStatus()
+      issueInitialReads()
+    }
   }
 
-  RED.nodes.registerType('knxUltimateIoTBridge', knxUltimateIoTBridge)
+  RED.nodes.registerType('knxUltimateIoTBridge', knxUltimateIoTBridge, {
+    credentials: {
+      mqttUsername: { type: 'text' },
+      mqttPassword: { type: 'password' }
+    }
+  })
 }

package/nodes/lib/knx-home-assistant.js

@@ -0,0 +1,171 @@
+'use strict'
+
+// Shared Home Assistant mapping helpers for the native KNX MQTT bridge.
+//
+// A KNX gateway exposes many group addresses (GA), each carrying a Datapoint Type (DPT).
+// Home Assistant, on the other hand, models things as typed entities (switch, sensor,
+// binary_sensor, number, text...). This module is the translation layer between the two:
+//
+// - mapDptToHa(dpt)            -> { domain, deviceClass?, unit?, min?, max?, step? }
+// - formatValueForMqtt(value)  -> string to publish on a HA state topic
+// - parseCommandFromMqtt(text, dpt) -> JS value to write on the KNX bus (or null)
+//
+// The mapping is intentionally pragmatic: it covers the common DPTs and falls back to a
+// read-only "sensor" for everything else, so an unknown DPT never breaks discovery.
+
+// Extract the main/sub parts of a DPT string ("DPT9.001", "9.001", "9" ...).
+function splitDpt (dptRaw) {
+  const clean = String(dptRaw == null ? '' : dptRaw).replace(/^dpt/i, '').trim()
+  const parts = clean.split('.')
+  const main = parseInt(parts[0], 10)
+  const sub = parts.length > 1 ? parts[1].trim() : ''
+  return { main: Number.isFinite(main) ? main : null, sub }
+}
+
+// Unit + HA device_class for the most common 2-byte float DPTs (DPT 9.xxx).
+function unitForFloat (sub) {
+  switch (sub) {
+    case '001': return { unit: '°C', deviceClass: 'temperature' }
+    case '002': return { unit: 'K' }
+    case '003': return { unit: 'K/h' }
+    case '004': return { unit: 'lx', deviceClass: 'illuminance' }
+    case '005': return { unit: 'm/s', deviceClass: 'wind_speed' }
+    case '006': return { unit: 'Pa', deviceClass: 'pressure' }
+    case '007': return { unit: '%', deviceClass: 'humidity' }
+    case '008': return { unit: 'ppm' }
+    case '009': return { unit: 'mg/m³' }
+    case '010': return { unit: 'm/s' }
+    case '011': return { unit: 's' }
+    case '020': return { unit: 'mV', deviceClass: 'voltage' }
+    case '021': return { unit: 'mA', deviceClass: 'current' }
+    case '022': return { unit: 'W/m²', deviceClass: 'irradiance' }
+    case '024': return { unit: 'K' }
+    case '025': return { unit: '1/h' }
+    case '026': return { unit: 'l/h' }
+    case '027': return { unit: '°F', deviceClass: 'temperature' }
+    case '028': return { unit: 'km/h', deviceClass: 'wind_speed' }
+    default: return {}
+  }
+}
+
+// Map a KNX DPT to a Home Assistant entity descriptor.
+// `domain` is the HA MQTT platform; the extra fields tune the discovery config.
+function mapDptToHa (dptRaw) {
+  const { main, sub } = splitDpt(dptRaw)
+
+  if (main === 1) {
+    // 1-bit boolean. A handful of subtypes are clearly read-only states; the rest are
+    // treated as controllable switches.
+    const readOnly = ['005', '011', '019']
+    if (readOnly.includes(sub)) {
+      const deviceClass = sub === '005' ? 'problem' : (sub === '019' ? 'opening' : undefined)
+      return { domain: 'binary_sensor', deviceClass, writable: false }
+    }
+    return { domain: 'switch', writable: true }
+  }
+
+  if (main === 5) {
+    if (sub === '001') return { domain: 'number', min: 0, max: 100, step: 1, unit: '%', writable: true } // scaling
+    if (sub === '003') return { domain: 'number', min: 0, max: 360, step: 1, unit: '°', writable: true } // angle
+    return { domain: 'number', min: 0, max: 255, step: 1, writable: true }
+  }
+
+  if (main === 6) return { domain: 'sensor', writable: false } // 1-byte signed
+  if (main === 7) return { domain: 'sensor', writable: false } // 2-byte unsigned
+  if (main === 8) return { domain: 'sensor', writable: false } // 2-byte signed
+
+  if (main === 9) {
+    const u = unitForFloat(sub)
+    return { domain: 'sensor', unit: u.unit, deviceClass: u.deviceClass, writable: false }
+  }
+
+  if (main === 12) return { domain: 'sensor', writable: false } // 4-byte unsigned
+  if (main === 13) {
+    if (sub === '010') return { domain: 'sensor', unit: 'Wh', deviceClass: 'energy', writable: false }
+    if (sub === '013') return { domain: 'sensor', unit: 'kWh', deviceClass: 'energy', writable: false }
+    return { domain: 'sensor', writable: false } // 4-byte signed
+  }
+
+  if (main === 14) {
+    // 4-byte float (engineering values). A few well-known subtypes carry a clear unit.
+    if (sub === '056') return { domain: 'sensor', unit: 'W', deviceClass: 'power', writable: false }
+    if (sub === '027') return { domain: 'sensor', unit: 'V', deviceClass: 'voltage', writable: false }
+    if (sub === '019') return { domain: 'sensor', unit: 'A', deviceClass: 'current', writable: false }
+    if (sub === '068') return { domain: 'sensor', unit: '°C', deviceClass: 'temperature', writable: false }
+    return { domain: 'sensor', writable: false }
+  }
+
+  if (main === 16) return { domain: 'text', writable: true } // character string
+
+  // Scenes (17/18), HVAC modes (20), colours (232) and anything else: expose as a
+  // read-only sensor so the value is visible without risking a wrong write encoding.
+  return { domain: 'sensor', writable: false }
+}
+
+// Render a KNX-decoded JS value to the string published on a HA state topic.
+function formatValueForMqtt (value) {
+  if (value === null || value === undefined) return ''
+  if (typeof value === 'boolean') return value ? 'true' : 'false'
+  if (typeof value === 'object') {
+    try {
+      return JSON.stringify(value)
+    } catch (_err) {
+      return ''
+    }
+  }
+  return String(value)
+}
+
+// Parse a HA command payload (string) into the JS value to write on the KNX bus.
+// Returns null when the payload can't be coerced to the DPT (the write is then skipped).
+function parseCommandFromMqtt (text, dptRaw) {
+  const { main } = splitDpt(dptRaw)
+  const s = (text == null ? '' : String(text)).trim()
+  if (s === '') return null
+
+  if (main === 1) {
+    const low = s.toLowerCase()
+    if (['true', 'on', '1', 'open', 'up', 'yes'].includes(low)) return true
+    if (['false', 'off', '0', 'closed', 'close', 'down', 'no'].includes(low)) return false
+    return null
+  }
+
+  if ([5, 6, 7, 8, 9, 12, 13, 14].includes(main)) {
+    const n = Number(s)
+    return Number.isFinite(n) ? n : null
+  }
+
+  if (main === 16) return s
+
+  // Unknown/structured DPT: accept JSON objects, otherwise pass the raw string through.
+  if (s.startsWith('{') || s.startsWith('[')) {
+    try {
+      return JSON.parse(s)
+    } catch (_err) {
+      return s
+    }
+  }
+  return s
+}
+
+// Default KNX DPTs for the roles of composite (cover/climate) entities. Used to encode
+// writes when the role GA is not present in the ETS CSV (so its DPT can't be resolved).
+const COVER_DEFAULT_DPT = {
+  upDown: '1.008', // 0 = Up/Open, 1 = Down/Close
+  stop: '1.007', // step/stop
+  position: '5.001' // 0..100 %
+}
+const CLIMATE_DEFAULT_DPT = {
+  currentTemp: '9.001',
+  setpoint: '9.001',
+  onOff: '1.001'
+}
+
+module.exports = {
+  splitDpt,
+  mapDptToHa,
+  formatValueForMqtt,
+  parseCommandFromMqtt,
+  COVER_DEFAULT_DPT,
+  CLIMATE_DEFAULT_DPT
+}