node-red-contrib-knx-ultimate 4.2.2 → 4.2.5

package/CHANGELOG.md

@@ -6,6 +6,25 @@
 
 # CHANGELOG
 
+**Version 4.2.5** - March 2026<br/>
+
+- NEW: added the **KNX Flow Bubbles** editor plugin to visualize live KNX Device state directly on the workspace.<br/>
+- FIX: **KNX Flow Bubbles** are now removed correctly when disabled, and their visibility is evaluated per linked **KNX Gateway** config-node instead of globally.<br/>
+- UI: **KNX Flow Bubbles** shell is now fully round for a cleaner visual appearance.<br/>
+- Docs/help/wiki: documented the **Enable flow bubbles plugin** option in the gateway editor and supported documentation languages.<br/>
+- Docs: removed obsolete references to **Echo sent message to all node with same Group Address** and aligned the text with the current automatic local mirroring behavior.<br/>
+
+**Version 4.2.4** - March 2026<br/>
+
+- NEW: **KNX Viewer Web** added a new Vue-based web page, opened directly from the **KNXViewer** node editor, to visualize KNX lights and dimmers in a modern dashboard.<br/>
+- UI: **KNX Viewer Web** uses a visual style aligned with **KNX AI**, including live light/dimmer cards, search, node selection and auto-refresh.<br/>
+- IMPROVE: **KNX Viewer Web** ON lights now use a much stronger yellow highlight for clearer visual feedback.<br/>
+- CHANGE: package build/publish flow now also includes the **KNX Viewer Web** Vue bundle.<br/>
+
+**Version 4.2.3** - March 2026<br/>
+
+- IMPROVE: **KNX AI Flow Map** added a new toggle to show or hide `knxUltimate` nodes running in **Universal Mode**; they are now hidden by default to keep the topology cleaner.<br/>
+
 **Version 4.2.2** - March 2026<br/>
 
 - CHANGE: **KNX AI Web Page** is now the official Vue-based dashboard served from `/knxUltimateAI/sidebar/page`.<br/>
@@ -2094,7 +2113,7 @@ This is an interim version, to quick fix some issues. Please report any issue wi
 
 **Version 1.1.45** - March 2020 in Italy, we're locked down for Coronavirus<br/>
 
-- Update knxultimate-api. Yet the nodes connected to an IP Interface, behaves like the nodes connected to an IP Router. See option **Echo sent message to all node with same Group Address** in the Gateway configuration wiki.<br/>
+- Update knxultimate-api. Nodes connected to an IP Interface now behave like nodes connected to an IP Router, and local writes are mirrored automatically to nodes sharing the same Group Address.<br/>
 - I'm internationalizing the node **(Deutsch, Italiano, English)** with the help of **@svenflender**, so please be patient if some parts are still only in english. Internationalization is working with node-red version 1.0.3 and above. Versions below, does have issues in the i18n module, so knx-ultimate falls back to english. Please upgrade node-red.<br/>
 
 **Version 1.1.43** - March 2020 in the middle of Coronavirus emergency in Italy<br/>

package/nodes/hue-config.html

@@ -29,7 +29,7 @@
             var $clientKeyInput = $("#node-config-input-clientkey");
             var $manualCredentialsButton = $("#manualCredentials");
 
-            function renderHueBridgeOptions (bridges) {
+            function renderHueBridgeOptions(bridges) {
                 discoveredHueBridges = Array.isArray(bridges) ? bridges : [];
                 if ($bridgeDatalist.length) {
                     $bridgeDatalist.empty();
@@ -66,7 +66,7 @@
                 }
             }
 
-            function runHueBridgeDiscovery (options) {
+            function runHueBridgeDiscovery(options) {
                 var settings = options || {};
                 if ($refreshHueBridges.length) {
                     $refreshHueBridges.addClass("fa-spin");
@@ -117,7 +117,7 @@
 
             runHueBridgeDiscovery({ silent: true });
 
-            function loadHueCredentials () {
+            function loadHueCredentials() {
                 if (!node || !node.id) return;
                 $.getJSON("KNXUltimateGetPlainHueBridgeCredentials?serverId=" + node.id, function (data) {
                     if (data && !data.error) {
@@ -171,7 +171,7 @@
                     var inflightRequest = null;
                     var myNotification;
 
-                    function cleanupPolling () {
+                    function cleanupPolling() {
                         polling = false;
                         if (retryTimer) {
                             clearTimeout(retryTimer);
@@ -183,17 +183,17 @@
                         inflightRequest = null;
                     }
 
-                    function restoreEditorView () {
+                    function restoreEditorView() {
                         $("#mainWindow").show();
                         $("#waitWindow").hide();
                     }
 
-                    function scheduleRetry () {
+                    function scheduleRetry() {
                         if (!polling) return;
                         retryTimer = setTimeout(attemptRegistration, 2000);
                     }
 
-                    function handleRegistrationSuccess (registration) {
+                    function handleRegistrationSuccess(registration) {
                         cleanupPolling();
                         if (registration && registration.bridge) {
                             if (registration.bridge.data && registration.bridge.data.name) {
@@ -213,7 +213,7 @@
                         if (myNotification) myNotification.close();
                     }
 
-                    function handleRegistrationError (message, { retryAllowed = false } = {}) {
+                    function handleRegistrationError(message, { retryAllowed = false } = {}) {
                         if (retryAllowed) {
                             scheduleRetry();
                             return;
@@ -232,7 +232,7 @@
                         });
                     }
 
-                    function attemptRegistration () {
+                    function attemptRegistration() {
                         if (!polling) return;
                         inflightRequest = $.getJSON("KNXUltimateRegisterToHueBridge?IP=" + $("#node-config-input-host").val() + "&serverId=" + node.id, function (data) {
                             if (!polling) return;
@@ -358,7 +358,10 @@
                 <label for="node-config-input-clientkey"> <span data-i18n="hue-config.properties.client_key"></span></label>
                 <input type="text" id="node-config-input-clientkey" placeholder="">
             </div>
+
         </div>    
+
+
     </div>
  
 

package/nodes/knxUltimate-config.html

@@ -32,6 +32,7 @@
             tunnelUserPassword: { value: "" },
             tunnelUserId: { value: "" },
             autoReconnect: { value: "yes" },
+            enableFlowBubbles: { value: false },
             statusUpdateThrottle: { value: "0" },
             statusDateTimeFormat: { value: "legacy" },
             statusDateTimeCustom: { value: "DD MMM HH:mm" },
@@ -1415,6 +1416,17 @@
                 </label>
             </div>
 
+            <div class="form-row form-row-checkbox">
+                <input type="checkbox" id="node-config-input-enableFlowBubbles"
+                    style="display:inline-block; width:auto; vertical-align:top;">
+                <label for="node-config-input-enableFlowBubbles">
+                    <i class="fa fa-commenting-o"></i>
+                    <span data-i18n="knxUltimate-config.advanced.enable_flow_bubbles"></span>
+                </label>
+            </div>
+            <div class="form-tips" data-i18n="knxUltimate-config.advanced.enable_flow_bubbles_help"></div>
+
+
             <div class="form-row">
                 <label for="node-config-input-delaybetweentelegrams">
                     <i class="fa fa-hourglass-start"></i>
@@ -1553,4 +1565,15 @@
 
     </div>
   
-</script>
+</script>
+
+<script type="text/html" data-help-name="knxUltimate-config">
+    <div data-i18n="knxUltimate-config.help.intro"></div>
+    <h3 data-i18n="knxUltimate-config.help.flow_bubbles_title"></h3>
+    <ul>
+        <li data-i18n="knxUltimate-config.help.flow_bubbles_enable"></li>
+        <li data-i18n="knxUltimate-config.help.flow_bubbles_scope"></li>
+        <li data-i18n="knxUltimate-config.help.flow_bubbles_tooltip"></li>
+        <li data-i18n="knxUltimate-config.help.flow_bubbles_stale"></li>
+    </ul>
+</script>

package/nodes/knxUltimate-config.js

@@ -216,6 +216,7 @@ module.exports = (RED) => {
     } else {
       node.autoReconnect = true
     }
+    node.enableFlowBubbles = config.enableFlowBubbles === true || config.enableFlowBubbles === 'true'
     node.ignoreTelegramsWithRepeatedFlag = config.ignoreTelegramsWithRepeatedFlag === undefined ? false : config.ignoreTelegramsWithRepeatedFlag
     const throttleSecondsRaw = Number(config.statusUpdateThrottle)
     node.statusUpdateThrottleMs = Number.isFinite(throttleSecondsRaw) && throttleSecondsRaw > 0

package/nodes/knxUltimate.js

@@ -3,6 +3,63 @@ const loggerClass = require('./utils/sysLogger')
 const coerceBoolean = (value) => (value === true || value === 'true')
 
 let buttonEndpointRegistered = false
+let liveStateEndpointRegistered = false
+const knxUltimateLiveState = new Map()
+
+const resolveBubbleColor = (status = {}) => {
+  const fill = typeof status.fill === 'string' ? status.fill.trim().toLowerCase() : ''
+  if (typeof status.payload === 'boolean') return status.payload ? '#ffd84d' : '#a5afbf'
+  if (typeof status.payload === 'number' && Number.isFinite(status.payload)) {
+    if (status.payload > 0) return '#ffd84d'
+    if (status.payload === 0) return '#a5afbf'
+  }
+  switch (fill) {
+    case 'green':
+      return '#58c96a'
+    case 'yellow':
+      return '#ffd84d'
+    case 'blue':
+      return '#61a8ff'
+    case 'red':
+      return '#f06b6b'
+    case 'grey':
+    case 'gray':
+      return '#a5afbf'
+    default:
+      return '#d4d8e2'
+  }
+}
+
+const normalizePayloadForBubble = (payload) => {
+  if (payload === undefined || payload === null || payload === '') return ''
+  if (typeof payload === 'object') {
+    try {
+      return JSON.stringify(payload)
+    } catch (error) {
+      return String(payload)
+    }
+  }
+  return String(payload)
+}
+
+const storeKnxUltimateLiveState = (node, status = {}) => {
+  if (!node || !node.id) return
+  const payload = Object.prototype.hasOwnProperty.call(status, 'payload') ? status.payload : node.currentPayload
+  knxUltimateLiveState.set(node.id, {
+    id: node.id,
+    topic: node.topic || '',
+    name: node.name || '',
+    dpt: node.dpt || '',
+    listenallga: node.listenallga === true || node.listenallga === 'true',
+    fill: status.fill || '',
+    shape: status.shape || '',
+    text: status.text || '',
+    payload,
+    payloadText: normalizePayloadForBubble(payload),
+    bubbleColor: resolveBubbleColor({ fill: status.fill, payload }),
+    updatedAt: Date.now()
+  })
+}
 
 /* eslint-disable max-len */
 module.exports = function (RED) {
@@ -225,6 +282,18 @@ module.exports = function (RED) {
     })
     buttonEndpointRegistered = true
   }
+
+  if (!liveStateEndpointRegistered) {
+    RED.httpAdmin.get('/knxUltimate/editorLiveState', RED.auth.needsPermission('knxUltimate-config.read'), (req, res) => {
+      try {
+        const nodes = Array.from(knxUltimateLiveState.values())
+        res.json({ nodes, updatedAt: Date.now() })
+      } catch (error) {
+        res.status(500).json({ error: error.message || String(error) })
+      }
+    })
+    liveStateEndpointRegistered = true
+  }
   const _ = require('lodash')
   const KNXUtils = require('knxultimate')
   const payloadRounder = require('./utils/payloadManipulation')
@@ -244,6 +313,7 @@ module.exports = function (RED) {
     }
 
     if (node.serverKNX === undefined) {
+      storeKnxUltimateLiveState(node, { fill: 'red', shape: 'dot', text: '[THE GATEWAY NODE HAS BEEN DISABLED]', payload: node.currentPayload })
       pushStatus({ fill: 'red', shape: 'dot', text: '[THE GATEWAY NODE HAS BEEN DISABLED]' })
       return
     }
@@ -254,6 +324,7 @@ module.exports = function (RED) {
     }) => {
       try {
         if (node.serverKNX === null) { pushStatus({ fill: 'red', shape: 'dot', text: '[NO GATEWAY SELECTED]' }); return }
+        const rawPayload = payload
         if (node.icountMessageInWindow == -999) return // Locked out, doesn't change status.
         const dDate = new Date()
         const ts = (node.serverKNX && typeof node.serverKNX.formatStatusTimestamp === 'function')
@@ -265,6 +336,7 @@ module.exports = function (RED) {
         dpt = (typeof dpt === 'undefined' || dpt == '') ? '' : ` DPT${dpt}`
         payload = typeof payload === 'object' ? JSON.stringify(payload) : payload
         const statusText = `${GA + payload + (node.listenallga === true ? ` ${devicename}` : '')} (${ts}) ${text}`
+        storeKnxUltimateLiveState(node, { fill, shape, text: statusText, payload: rawPayload })
         pushStatus({ fill, shape, text: statusText })
         // 16/02/2020 signal errors to the server
         if (fill.toUpperCase() === 'RED') {
@@ -356,6 +428,12 @@ module.exports = function (RED) {
     node.buttonStaticValue = config.buttonStaticValue || ''
     node.buttonToggleInitial = coerceBoolean(config.buttonToggleInitial)
     node._buttonToggleState = node.buttonToggleInitial
+    storeKnxUltimateLiveState(node, {
+      fill: 'grey',
+      shape: 'ring',
+      text: 'Waiting for KNX traffic',
+      payload: node.currentPayload
+    })
     node.periodicSend = coerceBoolean(config.periodicSend)
     node.periodicSendInterval = Number(config.periodicSendInterval)
     if (!Number.isFinite(node.periodicSendInterval) || node.periodicSendInterval <= 0) node.periodicSendInterval = 0
@@ -871,6 +949,7 @@ module.exports = function (RED) {
       if (node.timerTTLInputMessage !== null) clearTimeout(node.timerTTLInputMessage)
       clearPeriodicSendTimer()
       node.inputmessage = {}
+      knxUltimateLiveState.delete(node.id)
       if (node.serverKNX) {
         node.serverKNX.removeClient(node)
         try {

package/nodes/knxUltimateAI.js

@@ -1766,7 +1766,8 @@ module.exports = function (RED) {
               payload: '',
               lastSeenAtMs: 0,
               inFlow: true,
-              anomalyCount: 0
+              anomalyCount: 0,
+              listenAllGA: false
             }, entry))
             return
           }
@@ -1778,6 +1779,7 @@ module.exports = function (RED) {
           cur.inFlow = entry.inFlow !== undefined ? !!entry.inFlow : cur.inFlow
           cur.lastSeenAtMs = Math.max(Number(cur.lastSeenAtMs || 0), Number(entry.lastSeenAtMs || 0))
           cur.anomalyCount = Math.max(Number(cur.anomalyCount || 0), Number(entry.anomalyCount || 0))
+          cur.listenAllGA = entry.listenAllGA !== undefined ? !!entry.listenAllGA : !!cur.listenAllGA
           graphNodes.set(id, cur)
         }
 
@@ -1827,7 +1829,8 @@ module.exports = function (RED) {
             payload: String(nodeLastPayload[nid] || '').trim(),
             lastSeenAtMs: Number(nodeLastSeenMs[nid] || 0),
             inFlow: true,
-            anomalyCount: 0
+            anomalyCount: 0,
+            listenAllGA: !!(nodeInfo && nodeInfo.listenAllGA)
           })
         }
 

package/nodes/knxUltimateViewer.html

@@ -50,9 +50,13 @@
             try {
                 RED.sidebar.show("help");
             } catch (error) { }
-
-
-
+            const nodeId = this.id;
+            $("#knx-viewer-open-web-page").on("click", function (evt) {
+                evt.preventDefault();
+                const target = "knxUltimateViewer/page" + (nodeId ? ("?nodeId=" + encodeURIComponent(nodeId)) : "");
+                const wnd = window.open(target, "_blank", "noopener,noreferrer");
+                try { if (wnd && typeof wnd.focus === "function") wnd.focus(); } catch (e) { }
+            });
         },
         oneditsave: function () {
             // Return to the info tab
@@ -97,6 +101,15 @@
     <input type="text" id="node-input-name" data-i18n="[placeholder]knxUltimateViewer.node-input-name" style="flex:1 1 240px; min-width:240px; max-width:240px;" />
 </div>
 
+<div class="form-row">
+    <label><i class="fa fa-external-link"></i> Web UI</label>
+    <div style="display:flex; gap:8px; flex-wrap:wrap;">
+        <button type="button" class="red-ui-button" id="knx-viewer-open-web-page" style="background-color:#2bb673; border-color:#2bb673; color:#ffffff !important; -webkit-text-fill-color:#ffffff;">
+            <i class="fa fa-leaf" style="color:#10341f !important;"></i> <span style="color:#10341f !important;">Open KNX Viewer Web Page</span>
+        </button>
+    </div>
+</div>
+
 
 
 </script>