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

package/CHANGELOG.md

@@ -6,6 +6,15 @@
 
 # CHANGELOG
 
+**Version 5.0.0** - June 2026<br/>
+
+- KNXUltimate engine: updated to **6.0.1** (see the engine [CHANGELOG](https://github.com/Supergiovane/knxultimate/blob/main/CHANGELOG.md)).<br/>
+- KNX config node: new **"Reveal keyring passwords"** button in the **Utility** tab, enabled only when **KNX Secure** is selected. It shows, in clear text, all the keyring passwords (interfaces, backbone, group addresses and devices keys/passwords) plus the general keyring password, decoded from the loaded keyring file. Localized in EN/IT/DE/FR/ES/zh-CN.<br/>
+
+**Version 4.3.24** - June 2026<br/>
+
+- Hue **Contact Sensor** and **Motion** nodes: fixed the state on the KNX bus getting stuck on a wrong value (e.g. a contact sensor showing **closed** while the door stayed open) after the Hue event-stream reconnected. The nodes now re-publish the authoritative state at startup and after every (re)connection, and ignore stale/out-of-order reports by checking the `contact_report.changed` / `motion_report.changed` timestamp. Closes [#514](https://github.com/Supergiovane/node-red-contrib-knx-ultimate/issues/514).<br/>
+
 **Version 4.3.23** - June 2026<br/>
 
 - Hue nodes: fixed the **help text** not appearing in the editor sidebar when selecting a node. The help is now declared inline in each node's main HTML file (sidebar reads help from there; the `locales/` files keep providing translations). Affected nodes: Light/Outlet, Area Motion, Battery, Button, Contact Sensor, Light Sensor, Motion, Scene, Tap Dial, Temperature Sensor, Zigbee Connectivity and Device Software Update. Also closed an unterminated template `<script>` tag in the Hue Light node.<br/>

package/nodes/commonFunctions.js

@@ -408,6 +408,121 @@ module.exports = (RED) => {
       }
     })
 
+    // 2026-06 Reveal all keyring passwords (and the general keyring password) in clear text.
+    // Used by the "Utility" tab button, enabled only when KNX Secure is selected.
+    RED.httpAdmin.get('/knxUltimateKeyringDump', RED.auth.needsPermission('knxUltimate-config.read'), async (req, res) => {
+      try {
+        let keyringContent = (req.query.keyring || '').toString()
+        let password = (req.query.pwd || '').toString()
+        // '__PWRD__' is the Node-RED placeholder for an unchanged password credential: ignore it.
+        if (password === '__PWRD__') password = ''
+        // Fill any missing field (keyring and/or password) from the existing config node.
+        if ((!keyringContent || !password) && req.query.serverId) {
+          const cfg = RED.nodes.getNode(req.query.serverId)
+          if (cfg) {
+            if (!keyringContent) { try { keyringContent = cfg.keyringFileXML || keyringContent } catch (e) { } }
+            if (!password) { try { password = (cfg.credentials && cfg.credentials.keyringFilePassword) ? cfg.credentials.keyringFilePassword : password } catch (e) { } }
+          }
+        }
+        if (!keyringContent || !password) {
+          return res.json({ ok: false, error: 'MISSING_KEYRING_OR_PASSWORD' })
+        }
+        let Keyring
+        try {
+          ({ Keyring } = require('knxultimate/build/secure/keyring'))
+        } catch (e) {
+          try { RED.log.error(`KNXUltimate: cannot load Keyring module: ${e.message}`) } catch (err) { }
+          return res.json({ ok: false, error: 'KEYRING_MODULE_UNAVAILABLE' })
+        }
+        const kr = new Keyring()
+        try {
+          await kr.load(keyringContent, password)
+        } catch (e) {
+          try { RED.log.error(`KNXUltimate: keyring load error: ${e.message}`) } catch (err) { }
+          return res.json({ ok: false, error: 'KEYRING_LOAD_FAILED' })
+        }
+
+        const toIAString = (value) => {
+          if (!value) return ''
+          return typeof value.toString === 'function' ? value.toString() : String(value)
+        }
+        const toBufferString = (value) => {
+          if (!value) return ''
+          if (Buffer.isBuffer(value)) return value.toString('hex')
+          return String(value)
+        }
+
+        const lines = []
+        lines.push('================ KNX Secure keyring passwords ================')
+        lines.push(`Created By: ${kr.getCreatedBy?.() || ''}`)
+        lines.push(`Created On: ${kr.getCreated?.() || ''}`)
+        lines.push(`General keyring password: ${password}`)
+        lines.push('')
+
+        lines.push('Interfaces:')
+        const interfaceMap = kr.getInterfaces?.()
+        const interfaces = Array.from(interfaceMap ? interfaceMap.values() : [])
+        if (interfaces.length === 0) {
+          lines.push('  (none)')
+        } else {
+          interfaces.forEach((iface, idx) => {
+            lines.push(`  [${idx + 1}] ${toIAString(iface.individualAddress) || '(unknown)'} (${iface.type || ''})`)
+            lines.push(`       Host: ${toIAString(iface.host) || ''}`)
+            lines.push(`       User ID: ${typeof iface.userId === 'number' ? iface.userId : ''}`)
+            lines.push(`       Password: ${iface.decryptedPassword || ''}`)
+            lines.push(`       Authentication: ${iface.decryptedAuthentication || ''}`)
+          })
+        }
+        lines.push('')
+
+        lines.push('Backbones:')
+        const backbones = kr.getBackbones?.() || []
+        if (backbones.length === 0) {
+          lines.push('  (none)')
+        } else {
+          backbones.forEach((backbone, idx) => {
+            lines.push(`  [${idx + 1}] Multicast: ${backbone.multicastAddress || ''}`)
+            lines.push(`       Key (hex): ${toBufferString(backbone.decryptedKey)}`)
+          })
+        }
+        lines.push('')
+
+        lines.push('Group Addresses:')
+        const groupAddressMap = kr.getGroupAddresses?.()
+        const groupAddresses = Array.from(groupAddressMap ? groupAddressMap.values() : [])
+        if (groupAddresses.length === 0) {
+          lines.push('  (none)')
+        } else {
+          groupAddresses.forEach((group, idx) => {
+            lines.push(`  [${idx + 1}] ${toIAString(group.address) || ''}`)
+            lines.push(`       Key (hex): ${toBufferString(group.decryptedKey)}`)
+          })
+        }
+        lines.push('')
+
+        lines.push('Devices:')
+        const deviceMap = kr.getDevices?.()
+        const devices = Array.from(deviceMap ? deviceMap.values() : [])
+        if (devices.length === 0) {
+          lines.push('  (none)')
+        } else {
+          devices.forEach((device, idx) => {
+            lines.push(`  [${idx + 1}] ${toIAString(device.individualAddress) || ''}`)
+            lines.push(`       Tool Key (hex): ${toBufferString(device.decryptedToolKey)}`)
+            lines.push(`       Management Password: ${device.decryptedManagementPassword || ''}`)
+            lines.push(`       Authentication: ${device.decryptedAuthentication || ''}`)
+            lines.push(`       Serial Number: ${device.serialNumber || ''}`)
+          })
+        }
+        lines.push('================ End of keyring passwords ================')
+
+        res.json({ ok: true, dump: lines.join('\n') })
+      } catch (error) {
+        try { RED.log.error(`KNXUltimate: knxUltimateKeyringDump error: ${error.message}`) } catch (e) { }
+        res.json({ ok: false, error: 'UNEXPECTED_ERROR' })
+      }
+    })
+
     RED.httpAdmin.get('/knxUltimateGetHueColor', (req, res) => {
       try {
         const serverId = RED.nodes.getNode(req.query.serverId) // Retrieve node.id of the config node.

package/nodes/knxUltimate-config.html

@@ -164,13 +164,13 @@
                 active: (node.knxSecureSelected === true || node.knxSecureSelected === 'true') ? 1 : 0,
                 activate: function (event, ui) {
                     node.knxSecureSelected = $(ui.newTab).index() === 1;
-                    try { updateTunnelIAVisibility(); updatePhysAddrVisibility(); updateSecureMulticastHint(); enforceProtocolFromIP(); } catch (e) { }
+                    try { updateTunnelIAVisibility(); updatePhysAddrVisibility(); updateSecureMulticastHint(); enforceProtocolFromIP(); updateRevealKeyringButton(); } catch (e) { }
                 }
             });
             // Ensure the correct tab is enforced after all UI init
             try {
                 const initialActive = (node.knxSecureSelected === true || node.knxSecureSelected === 'true') ? 1 : 0;
-                setTimeout(() => { $("#tabsMain").tabs("option", "active", initialActive); updateTunnelIAVisibility(); updatePhysAddrVisibility(); updateSecureMulticastHint(); enforceProtocolFromIP(); }, 0);
+                setTimeout(() => { $("#tabsMain").tabs("option", "active", initialActive); updateTunnelIAVisibility(); updatePhysAddrVisibility(); updateSecureMulticastHint(); enforceProtocolFromIP(); updateRevealKeyringButton(); }, 0);
             } catch (e) { }
 
             // Keyring ACE editor setup
@@ -1041,6 +1041,56 @@
                 } catch (e) { }
             });
 
+            // Utility: reveal all keyring passwords in clear text.
+            // Enabled only when KNX Secure is selected.
+            function updateRevealKeyringButton() {
+                try {
+                    const isSecure = isSecureTabActive();
+                    $("#revealkeyringpwd").prop('disabled', !isSecure)
+                        .css('opacity', isSecure ? 1 : 0.5)
+                        .css('cursor', isSecure ? 'pointer' : 'not-allowed');
+                } catch (e) { }
+            }
+            updateRevealKeyringButton();
+
+            $("#revealkeyringpwd").click(function () {
+                if (!isSecureTabActive()) return;
+                try {
+                    const keyring = (node._keyringEditor && typeof node._keyringEditor.getValue === 'function')
+                        ? node._keyringEditor.getValue()
+                        : $("#node-config-input-keyringFileXML").val();
+                    const pwd = $("#node-config-input-keyringFilePassword").val();
+                    const params = { serverId: node.id };
+                    if (typeof keyring === 'string' && keyring.trim() !== '') params.keyring = keyring.trim();
+                    // '__PWRD__' is the Node-RED placeholder for an unchanged password credential:
+                    // never send it, so the backend falls back to the real stored credential.
+                    if (typeof pwd === 'string' && pwd.trim() !== '' && pwd !== '__PWRD__') params.pwd = pwd.trim();
+                    $("#divDebugText").show();
+                    $("#debugText").val(node._('knxUltimate-config.utility.reveal_keyring_loading'));
+                    const scrollToDebugText = function () {
+                        try {
+                            const el = document.getElementById('debugText');
+                            if (el && typeof el.scrollIntoView === 'function') {
+                                el.scrollIntoView({ behavior: 'smooth', block: 'center' });
+                            }
+                        } catch (e) { }
+                    };
+                    scrollToDebugText();
+                    $.getJSON('knxUltimateKeyringDump', params, (data) => {
+                        if (data && data.ok) {
+                            $("#debugText").val(data.dump);
+                        } else {
+                            const code = (data && data.error) ? data.error : 'UNEXPECTED_ERROR';
+                            $("#debugText").val(node._('knxUltimate-config.utility.reveal_keyring_fail') + ' (' + code + ')');
+                        }
+                        scrollToDebugText();
+                    }).fail(function (jqXHR, textStatus, errorThrown) {
+                        const err = (errorThrown || textStatus || '').toString();
+                        $("#debugText").val(node._('knxUltimate-config.utility.reveal_keyring_fail') + (err ? (': ' + err) : ''));
+                    });
+                } catch (e) { }
+            });
+
 
 
         },
@@ -1569,8 +1619,14 @@
                     <input type="button" id="clearpersistga" class="ui-button ui-corner-all ui-widget"
                         style="background-color:#FFD2D2;width:150px" data-i18n="[value]knxUltimate-config.utility.clear_persist_button">
                 </div>
-	            
-	            <div class="form-row" id="divDebugText" style="display: none;">                
+
+                <div class="form-row">
+                    <label><i class="fa fa-key"></i> <span data-i18n="knxUltimate-config.utility.reveal_keyring_label"></span></label>
+                    <input type="button" id="revealkeyringpwd" class="ui-button ui-corner-all ui-widget"
+                        style="background-color:#FFE9B3;width:150px" data-i18n="[value]knxUltimate-config.utility.reveal_keyring_button">
+                </div>
+
+	            <div class="form-row" id="divDebugText" style="display: none;">
 	                <textarea rows="10" id="debugText" style="width:100%"></textarea>
 	            </div>
 	        </p>

package/nodes/knxUltimate-config.js

@@ -24,6 +24,12 @@ const loggerClass = require('./utils/sysLogger')
 const payloadRounder = require('./utils/payloadManipulation')
 const utils = require('./utils/utils')
 
+// Versions logged once at startup (node package + KNXUltimate engine)
+let NODE_VERSION = 'unknown'
+try { NODE_VERSION = require('../package.json').version } catch (e) { /* empty */ }
+let KNX_ENGINE_VERSION = 'unknown'
+try { KNX_ENGINE_VERSION = require('knxultimate/package.json').version } catch (e) { /* empty */ }
+
 // DATAPONT MANIPULATION HELPERS
 // ####################
 const sortBy = (field) => (a, b) => {
@@ -185,6 +191,11 @@ const findAutoEthernetInterface = (targetIP) => {
 }
 
 module.exports = (RED) => {
+  // Log node and KNXUltimate engine versions once, at Node-RED startup.
+  try {
+    RED.log.info(`KNXUltimate: node-red-contrib-knx-ultimate v${NODE_VERSION} (KNXUltimate engine v${KNX_ENGINE_VERSION})`)
+  } catch (e) { /* empty */ }
+
   function knxUltimateConfigNode (config) {
     RED.nodes.createNode(this, config)
     const node = this

package/nodes/knxUltimateHueContactSensor.js

@@ -23,7 +23,13 @@ module.exports = function (RED) {
     node.formatnegativevalue = 'leave'
     node.formatdecimalsvalue = 2
     node.hueDevice = config.hueDevice
-    node.initializingAtStart = false
+    // Re-publish the authoritative contact state at startup and after every event-stream
+    // (re)connection. Without this, any contact_report event missed during an SSE reconnect
+    // gap leaves KNX stuck on the last value seen (see issue #514).
+    node.initializingAtStart = (config.readStatusAtStartup === undefined || config.readStatusAtStartup === 'yes')
+    // Timestamp (ms) of the last contact_report.changed we already applied to KNX. Used to
+    // ignore stale/out-of-order reports (e.g. replays after a reconnect).
+    node.lastContactChangedTs = undefined
 
     const pushStatus = (status) => {
       if (!status) return
@@ -94,6 +100,18 @@ module.exports = function (RED) {
             return
           }
 
+          // contact_report.state is always the real current state (per Hue API v2), and
+          // contact_report.changed is when it last changed. Ignore reports that are not newer
+          // than the last one applied, so stale/replayed events after an SSE reconnect can't
+          // flip KNX to a wrong state (issue #514).
+          const changedTs = _event.contact_report.changed !== undefined ? new Date(_event.contact_report.changed).getTime() : NaN
+          if (!Number.isNaN(changedTs)) {
+            if (node.lastContactChangedTs !== undefined && changedTs <= node.lastContactChangedTs) {
+              return
+            }
+            node.lastContactChangedTs = changedTs
+          }
+
           const knxMsgPayload = {}
           knxMsgPayload.topic = config.GAcontact
           knxMsgPayload.dpt = config.dptcontact

package/nodes/knxUltimateHueMotion.js

@@ -23,7 +23,13 @@ module.exports = function (RED) {
     node.formatnegativevalue = 'leave'
     node.formatdecimalsvalue = 2
     node.hueDevice = config.hueDevice
-    node.initializingAtStart = false
+    // Re-publish the authoritative motion state at startup and after every event-stream
+    // (re)connection, so events missed during an SSE reconnect gap don't leave KNX stuck
+    // on a wrong value (same root cause as the contact sensor, issue #514).
+    node.initializingAtStart = (config.readStatusAtStartup === undefined || config.readStatusAtStartup === 'yes')
+    // Timestamp (ms) of the last motion_report.changed we already applied to KNX. Used to
+    // ignore stale/out-of-order reports (e.g. replays after a reconnect).
+    node.lastMotionChangedTs = undefined
     const pinsSetting = (config.enableNodePINS === undefined || config.enableNodePINS === 'yes' || config.enableNodePINS === true)
     node.enableNodePINS = pinsSetting ? 'yes' : 'no'
     node.outputs = pinsSetting ? 1 : 0
@@ -97,6 +103,18 @@ module.exports = function (RED) {
       try {
         if (_event.id === config.hueDevice) {
           if (!_event.hasOwnProperty('motion') || _event.motion.motion === undefined) return
+
+          // Ignore reports that are not newer than the last one applied, so stale/replayed
+          // events after an SSE reconnect can't push a wrong state to KNX (issue #514).
+          const motionChanged = _event.motion.motion_report !== undefined ? _event.motion.motion_report.changed : undefined
+          const changedTs = motionChanged !== undefined ? new Date(motionChanged).getTime() : NaN
+          if (!Number.isNaN(changedTs)) {
+            if (node.lastMotionChangedTs !== undefined && changedTs <= node.lastMotionChangedTs) {
+              return
+            }
+            node.lastMotionChangedTs = changedTs
+          }
+
           const knxMsgPayload = {}
           knxMsgPayload.topic = config.GAmotion
           knxMsgPayload.dpt = config.dptmotion

package/nodes/locales/de/knxUltimate-config.json

@@ -144,7 +144,11 @@
             "clear_persist_ok": "Löschen",
             "clear_persist_cancel": "Abbrechen",
             "clear_persist_done": "Persistenter GA-Cache gelöscht.",
-            "clear_persist_fail": "Persistenter GA-Cache konnte nicht gelöscht werden"
+            "clear_persist_fail": "Persistenter GA-Cache konnte nicht gelöscht werden",
+            "reveal_keyring_label": "Keyring-Passwörter im Klartext anzeigen (KNX Secure)",
+            "reveal_keyring_button": "Anzeigen",
+            "reveal_keyring_loading": "Keyring wird dekodiert, bitte warten...",
+            "reveal_keyring_fail": "Keyring konnte nicht dekodiert werden. Prüfen Sie die Keyring-Datei und das allgemeine Passwort."
         }
     }
 }

package/nodes/locales/en/knxUltimate-config.json

@@ -148,7 +148,11 @@
             "clear_persist_ok": "Delete",
             "clear_persist_cancel": "Cancel",
             "clear_persist_done": "Persisted GA cache deleted.",
-            "clear_persist_fail": "Unable to delete persisted GA cache"
+            "clear_persist_fail": "Unable to delete persisted GA cache",
+            "reveal_keyring_label": "Reveal keyring passwords in clear text (KNX Secure)",
+            "reveal_keyring_button": "Reveal",
+            "reveal_keyring_loading": "Decoding keyring, please wait...",
+            "reveal_keyring_fail": "Unable to decode the keyring. Check the keyring file and the general password."
         }
     }
 }

package/nodes/locales/es/knxUltimate-config.json

@@ -148,7 +148,11 @@
       "clear_persist_ok": "Eliminar",
       "clear_persist_cancel": "Cancelar",
       "clear_persist_done": "Caché persistente de GA eliminada.",
-      "clear_persist_fail": "No se puede eliminar la caché persistente de GA"
+      "clear_persist_fail": "No se puede eliminar la caché persistente de GA",
+      "reveal_keyring_label": "Mostrar las contraseñas del keyring en texto claro (KNX Secure)",
+      "reveal_keyring_button": "Mostrar",
+      "reveal_keyring_loading": "Decodificando el keyring, espere...",
+      "reveal_keyring_fail": "No se puede decodificar el keyring. Comprueba el archivo keyring y la contraseña general."
     }
   }
 }

package/nodes/locales/fr/knxUltimate-config.json

@@ -148,7 +148,11 @@
       "clear_persist_ok": "Supprimer",
       "clear_persist_cancel": "Annuler",
       "clear_persist_done": "Cache GA persistant supprimé.",
-      "clear_persist_fail": "Impossible de supprimer le cache GA persistant"
+      "clear_persist_fail": "Impossible de supprimer le cache GA persistant",
+      "reveal_keyring_label": "Afficher les mots de passe du keyring en clair (KNX Secure)",
+      "reveal_keyring_button": "Afficher",
+      "reveal_keyring_loading": "Décodage du keyring en cours, veuillez patienter...",
+      "reveal_keyring_fail": "Impossible de décoder le keyring. Vérifiez le fichier keyring et le mot de passe général."
     }
   }
 }

package/nodes/locales/it/knxUltimate-config.json

@@ -152,7 +152,11 @@
             "clear_persist_ok": "Elimina",
             "clear_persist_cancel": "Annulla",
             "clear_persist_done": "Cache persistente GA eliminata.",
-            "clear_persist_fail": "Impossibile eliminare la cache persistente GA"
+            "clear_persist_fail": "Impossibile eliminare la cache persistente GA",
+            "reveal_keyring_label": "Mostra le password del keyring in chiaro (KNX Secure)",
+            "reveal_keyring_button": "Mostra",
+            "reveal_keyring_loading": "Decodifica del keyring in corso, attendere...",
+            "reveal_keyring_fail": "Impossibile decodificare il keyring. Verifica il file keyring e la password generale."
         }
     }
 }

package/nodes/locales/zh-CN/knxUltimate-config.json

@@ -140,7 +140,11 @@
             "clear_persist_ok": "删除",
             "clear_persist_cancel": "取消",
             "clear_persist_done": "已删除持久化 GA 缓存。",
-            "clear_persist_fail": "无法删除持久化 GA 缓存"
+            "clear_persist_fail": "无法删除持久化 GA 缓存",
+            "reveal_keyring_label": "以明文显示密钥环密码 (KNX Secure)",
+            "reveal_keyring_button": "显示",
+            "reveal_keyring_loading": "正在解码密钥环，请稍候...",
+            "reveal_keyring_fail": "无法解码密钥环。请检查密钥环文件和通用密码。"
         }
     }
 }

package/package.json

@@ -3,7 +3,7 @@
   "engines": {
     "node": ">=20.18.1"
   },
-  "version": "4.3.23",
+  "version": "5.0.0",
   "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/",
@@ -19,7 +19,7 @@
     "dns-sync": "0.2.1",
     "google-translate-tts": "^0.3.0",
     "js-yaml": "4.1.1",
-    "knxultimate": "5.5.9",
+    "knxultimate": "6.0.1",
     "lodash": "4.18.1",
     "node-color-log": "12.0.1",
     "ping": "0.4.4",