node-red-contrib-knx-ultimate 4.3.11 → 4.3.13

package/CHANGELOG.md

@@ -6,6 +6,15 @@
 
 # CHANGELOG
 
+**Version 4.3.13** - May 2026<br/>
+
+- Bump KNX Engine to 5.5.6<br/>
+
+**Version 4.3.12** - May 2026<br/>
+
+- Docs/help/wiki: refined **KNX DEVICE / KNX Function** wording in all supported languages (**EN/IT/DE/FR/ES/zh-CN**) to state explicitly that `getGAValue(...)` must always be used as **`await getGAValue(...)`**; without `await` the function returns a `Promise`, not the GA value.<br/>
+- UI: updated remaining **KNX Function** helper snippets to always use `await getGAValue(...)` in practical examples.<br/>
+
 **Version 4.3.11** - May 2026<br/>
 
 - Docs/help/wiki: clarified in **KNX DEVICE / KNX Function** help HTML and **Device** wiki pages in all supported languages (**EN/IT/DE/FR/ES/zh-CN**) that `getGAValue(...)` is async and should be used as **`await getGAValue(...)`**, even in cache-only mode.<br/>

package/nodes/locales/de/knxUltimate.html

@@ -71,7 +71,7 @@ Der Code läuft bei jeder Eingangs-Nachricht und bei jedem BUS-Telegramm. Bei Ak
 |Objekt/Funktion|Beschreibung|
 |--|--|
 | `msg` | Aktuelle Nachricht. |
-| `getGAValue(GA, DPT?, readIfMissing?)` | Liest den Wert einer GA, z. B. `'1/0/1'` oder `'1/0/1 Bed table light'` (Text nach Leerzeichen wird ignoriert). Mit importierter ETS ist DPT optional; sonst muss es angegeben werden. Standardmäßig sendet die Funktion bei fehlendem Cache-Wert ein `GroupValue_Read` und wartet auf die Antwort. Mit `false` als drittem Parameter, oder als zweitem wenn kein DPT nötig ist, arbeitet die Funktion nur mit dem Cache und liefert `undefined`, wenn lokal kein Wert vorhanden ist. `getGAValue` ist asynchron, daher solltest du `await getGAValue(...)` verwenden, wenn du den echten Wert brauchst. Auch im Cache-only-Modus bleibt `await` erforderlich, weil der Helper immer eine Promise zurückgibt. |
+| `getGAValue(GA, DPT?, readIfMissing?)` | Liest den Wert einer GA, z. B. `'1/0/1'` oder `'1/0/1 Bed table light'` (Text nach Leerzeichen wird ignoriert). Mit importierter ETS ist DPT optional; sonst muss es angegeben werden. Standardmäßig sendet die Funktion bei fehlendem Cache-Wert ein `GroupValue_Read` und wartet auf die Antwort. Mit `false` als drittem Parameter, oder als zweitem wenn kein DPT nötig ist, arbeitet die Funktion nur mit dem Cache und liefert `undefined`, wenn lokal kein Wert vorhanden ist. `getGAValue` ist asynchron, daher solltest du `await getGAValue(...)` verwenden, wenn du den echten Wert brauchst. Auch im Cache-only-Modus bleibt `await` erforderlich: ohne `await` erhältst du ein Promise-Objekt statt des GA-Werts. |
 | `setGAValue(GA, value, DPT?)` | Setzt den Wert der GA; DPT wie oben. |
 | `self(value)` | Setzt den eigenen Node-Wert und sendet ihn an den BUS (Achtung Schleifen). |
 | `toggle()` | Toggeln wie `self`. |

package/nodes/locales/en/knxUltimate.html

@@ -77,7 +77,7 @@ If enabled, "f(x)" indication will be added to node's name.
 |Object or Function|Description|
 |--|--|
 | msg (object) | The current msg object received by the node. |
-| getGAValue (string GA, optional string DPT, optional bool readIfMissing) | Get the specified GA's value, for example **'1/0/1'**, or also **'1/0/1 Bed table light'** (all text after a blank space will be ignored by the function). With the ETS file imported, you can also copy and paste the GA and GA Name directly from the **Search GA** field. **DPT** is optional if you've imported the ETS file, otherwise you must specify it (for example '1.001'). By default, if the value is not cached, the function sends a `GroupValue_Read` and waits for the reply. Pass `false` as the third parameter, or as the second one when no DPT is needed, to use cache-only mode and return `undefined` when the value is not available locally. `getGAValue` is async, so use `await getGAValue(...)` whenever you need the actual value. Even in cache-only mode, keep `await`, because the helper always returns a Promise. |
+| getGAValue (string GA, optional string DPT, optional bool readIfMissing) | Get the specified GA's value, for example **'1/0/1'**, or also **'1/0/1 Bed table light'** (all text after a blank space will be ignored by the function). With the ETS file imported, you can also copy and paste the GA and GA Name directly from the **Search GA** field. **DPT** is optional if you've imported the ETS file, otherwise you must specify it (for example '1.001'). By default, if the value is not cached, the function sends a `GroupValue_Read` and waits for the reply. Pass `false` as the third parameter, or as the second one when no DPT is needed, to use cache-only mode and return `undefined` when the value is not available locally. `getGAValue` is async, so use `await getGAValue(...)` whenever you need the actual value. Even in cache-only mode, keep `await`: without it, you'll get a Promise object, not the GA value. |
 | setGAValue (string GA, any value, optional string DPT) | Set the specified GA's value. The GA can be wrote for example **'1/0/1'**, or also **'1/0/1 Bed table light'** (all text after a blank space will be ignored by the function). With the ETS file imported, you can also copy and paste the GA and GA Name directly from the **Search GA** field. The **value** is mandatory (boolean/number/string/object). **DPT** is optional if you've imported the ETS file, otherwise you must specify it (for example '1.001'). |
 | self (any value) | Set the currend node's value and sends the value to the KNX BUS as well. For example, _self(false)_. Caution using **self** function in the _From KNX BUS to node's OUTPUT PIN_ code, because the code will be executed everytime a KNX telegram is received, so you coud have recurrency loops. |
 | toggle (nothing) | Toggle the currend node's value and sends the value to the KNX BUS as well. For example, _toggle()_. Caution using **toggle** function in the _From KNX BUS to node's OUTPUT PIN_ code, because the code will be executed everytime a KNX telegram is received, so you coud have recurrency loops. |

package/nodes/locales/es/knxUltimate.html

@@ -77,7 +77,7 @@ Si está habilitado, la indicación "F (x)" se agregará al nombre del nodo.
 | Objeto o función | Descripción |
 |-|-|
 | msg (objeto) | El objeto MSG actual recibido por el nodo. |
-| getGavalue (String ga, string opcional dpt, bool opcional readIfMissing) | Obtenga el valor de la GA especificada, por ejemplo **'1/0/1'** o **'1/0/1 Luz mesilla'** (el texto tras un espacio se ignora). Con el archivo ETS importado, también puede copiar y pegar la GA desde el campo **Búsqueda GA**. **DPT** es opcional con ETS; si no, debe indicarlo (por ejemplo `'1.001'`). Por defecto, si el valor no está en caché, la función envía un `GroupValue_Read` y espera la respuesta. Pase `false` como tercer parámetro, o como segundo si no necesita DPT, para usar el modo solo caché y devolver `undefined` cuando el valor no esté disponible localmente. `getGAValue` es asíncrona, así que use `await getGAValue(...)` cuando necesite el valor real. Incluso en modo solo caché, mantenga `await`, porque el helper siempre devuelve una Promise. |
+| getGavalue (String ga, string opcional dpt, bool opcional readIfMissing) | Obtenga el valor de la GA especificada, por ejemplo **'1/0/1'** o **'1/0/1 Luz mesilla'** (el texto tras un espacio se ignora). Con el archivo ETS importado, también puede copiar y pegar la GA desde el campo **Búsqueda GA**. **DPT** es opcional con ETS; si no, debe indicarlo (por ejemplo `'1.001'`). Por defecto, si el valor no está en caché, la función envía un `GroupValue_Read` y espera la respuesta. Pase `false` como tercer parámetro, o como segundo si no necesita DPT, para usar el modo solo caché y devolver `undefined` cuando el valor no esté disponible localmente. `getGAValue` es asíncrona, así que use `await getGAValue(...)` cuando necesite el valor real. Incluso en modo solo caché, mantenga `await`: sin `await` recibirá una Promise, no el valor de la GA. |
 | setgavalue (cadena ga, cualquier valor, cadena opcional dpt) | Establezca el valor de GA especificado, por ejemplo **'1/0/1'** o **'1/0/1 Luz mesilla'** (el texto tras un espacio se ignora). Con el archivo ETS importado, también puede copiar y pegar la GA desde el campo **Búsqueda GA**. El valor es obligatorio; **dpt** es opcional con ETS. |
 | yo (cualquier valor) | Establezca el valor del nodo de Currend y envía el valor al bus KNX también. Por ejemplo, _Self (False) _. PRECAUCIÓN Uso de ** Función ** ** En la _From KNX Bus hasta el código PIN_ de salida del nodo, porque el código se ejecutará cada vez que se reciba un telegrama KNX, por lo que usted tiene bucles de recurrencia. |
 | alternar (nada) | Alterne el valor del nodo de Currend y envía el valor al bus KNX también. Por ejemplo, _Toggle () _. PRECAUCIÓN Uso de la función ** Toggle** En el código _From KNX BUS al Código PIN_ de salida del nodo, porque el código se ejecutará cada vez que se reciba un Telegrama KNX, por lo que usted tiene bucles de recurrencia. |

package/nodes/locales/fr/knxUltimate.html

@@ -77,7 +77,7 @@ S'il est activé, l'indication "f (x)" sera ajoutée au nom du nœud.
 | Objet ou fonction | Description |
 |-|-|
 | msg (objet) | L'objet MSG actuel reçu par le nœud. |
-| getGavalue (String GA, String DPT facultatif, bool readIfMissing facultatif) | Obtenez la valeur de la GA spécifiée, par exemple **'1/0/1'** ou **'1/0/1 Light'** (le texte après un espace est ignoré). Avec le fichier ETS importé, vous pouvez également copier et coller le nom GA et GA directement dans le champ **Recherche GA**. **DPT** est facultatif avec ETS; sinon vous devez le spécifier (par exemple `'1.001'`). Par défaut, si la valeur n'est pas en cache, la fonction envoie un `GroupValue_Read` et attend la réponse. Passez `false` comme troisième paramètre, ou comme deuxième si aucun DPT n'est nécessaire, pour utiliser le mode cache uniquement et retourner `undefined` si la valeur n'est pas disponible localement. `getGAValue` est asynchrone: utilisez donc `await getGAValue(...)` quand vous avez besoin de la vraie valeur. Même en mode cache uniquement, gardez `await`, car le helper renvoie toujours une Promise. |
+| getGavalue (String GA, String DPT facultatif, bool readIfMissing facultatif) | Obtenez la valeur de la GA spécifiée, par exemple **'1/0/1'** ou **'1/0/1 Light'** (le texte après un espace est ignoré). Avec le fichier ETS importé, vous pouvez également copier et coller le nom GA et GA directement dans le champ **Recherche GA**. **DPT** est facultatif avec ETS; sinon vous devez le spécifier (par exemple `'1.001'`). Par défaut, si la valeur n'est pas en cache, la fonction envoie un `GroupValue_Read` et attend la réponse. Passez `false` comme troisième paramètre, ou comme deuxième si aucun DPT n'est nécessaire, pour utiliser le mode cache uniquement et retourner `undefined` si la valeur n'est pas disponible localement. `getGAValue` est asynchrone: utilisez donc `await getGAValue(...)` quand vous avez besoin de la vraie valeur. Même en mode cache uniquement, gardez `await` : sans `await`, vous obtenez une Promise et non la valeur de la GA. |
 | setGavalue (String ga, n'importe quelle valeur, chaîne facultative dpt) | Définissez la valeur de GA spécifiée, par exemple **'1/0/1'** ou **'1/0/1 Light'** (le texte après un espace est ignoré). Avec le fichier ETS importé, vous pouvez également copier et coller le nom GA et GA directement depuis le champ **Recherche GA**. La valeur est obligatoire; **dpt** est facultatif avec ETS. |
 | self (toute valeur) | Définissez la valeur du nœud Currend et envoie également la valeur au bus KNX. Par exemple, _self (false) _. ATTENTION UTILISATION ** Self** Fonction dans le code Pin_ de sortie du bus KNX _From pour le nœud, car le code sera exécuté à chaque fois qu'un télégramme KNX est reçu, vous avez donc Coud ayant des boucles de récurrence. |
 | basculer (rien) | Basculez la valeur du nœud Currend et envoie également la valeur au bus KNX. Par exemple, _toggle () _. ATTENTION en utilisant ** Toggle** Fonction dans le code Pin_ de sortie du bus KNX _From à la sortie du nœud, car le code sera exécuté à chaque fois qu'un télégramme KNX est reçu, de sorte que vous avez des boucles de récurrence. |

package/nodes/locales/it/knxUltimate.html

@@ -76,7 +76,7 @@ Lo script viene eseguito a ogni msg in ingresso o a ogni telegramma ricevuto dal
 |Oggetto/Funzione|Descrizione|
 |--|--|
 | `msg` (object) | Il msg corrente ricevuto dal nodo. |
-| `getGAValue` (string GA, string DPT opz., bool readIfMissing opz.) | Restituisce il valore del GA, ad es. `'1/0/1'` o `'1/0/1 Bed table light'` (tutto dopo lo spazio viene ignorato). Con ETS importato, DPT è opzionale; altrimenti va specificato, per es. `'1.001'`. Per default, se il valore non è in cache, viene inviato un `GroupValue_Read` e la funzione attende la risposta. Passando `false` come terzo parametro, oppure come secondo se il DPT non serve, la funzione lavora in modalità solo-cache e restituisce `undefined` se il valore non è disponibile localmente. `getGAValue` è asincrona, quindi quando ti serve il valore reale devi usare `await getGAValue(...)`. Anche in modalità solo-cache va mantenuto `await`, perché l'helper restituisce sempre una Promise. |
+| `getGAValue` (string GA, string DPT opz., bool readIfMissing opz.) | Restituisce il valore del GA, ad es. `'1/0/1'` o `'1/0/1 Bed table light'` (tutto dopo lo spazio viene ignorato). Con ETS importato, DPT è opzionale; altrimenti va specificato, per es. `'1.001'`. Per default, se il valore non è in cache, viene inviato un `GroupValue_Read` e la funzione attende la risposta. Passando `false` come terzo parametro, oppure come secondo se il DPT non serve, la funzione lavora in modalità solo-cache e restituisce `undefined` se il valore non è disponibile localmente. `getGAValue` è asincrona, quindi quando ti serve il valore reale devi usare `await getGAValue(...)`. Anche in modalità solo-cache va mantenuto `await`: senza `await` ottieni una Promise, non il valore del GA. |
 | `setGAValue` (string GA, any value, string DPT opz.) | Imposta il valore del GA indicato. Valgono le stesse regole di notazione del GA; il valore può essere boolean/number/string; DPT opzionale con ETS, altrimenti obbligatorio. |
 | `self` (any) | Imposta il valore del nodo corrente e lo invia anche al BUS KNX (es.: `self(false)`). Attenzione nell'handler "From KNX BUS to OUTPUT”, per evitare loop. |
 | `toggle`() | Inverte il valore del nodo e lo invia al BUS. Stesse cautele di `self`. |

package/nodes/locales/zh-CN/knxUltimate.html

@@ -71,7 +71,7 @@
 |对象/函数|说明|
 |--|--|
 | `msg` | 当前消息对象。|
-| `getGAValue(GA, DPT?, readIfMissing?)` | 读取 GA 的值，例如 `'1/0/1'` 或 `'1/0/1 Bed table light'`（空格后的文字会被忽略）。导入 ETS 后，DPT 为可选；未导入时则必须提供。默认情况下，如果缓存中没有该值，函数会发送一个 `GroupValue_Read` 并等待响应。若将第三个参数设为 `false`，或者在不需要 DPT 时将第二个参数设为 `false`，则函数只使用缓存；如果本地没有值，则返回 `undefined`。`getGAValue` 是异步的，所以当你需要真实值时，应写成 `await getGAValue(...)`。即使使用只读缓存模式，也要保留 `await`，因为该 helper 始终返回 Promise。|
+| `getGAValue(GA, DPT?, readIfMissing?)` | 读取 GA 的值，例如 `'1/0/1'` 或 `'1/0/1 Bed table light'`（空格后的文字会被忽略）。导入 ETS 后，DPT 为可选；未导入时则必须提供。默认情况下，如果缓存中没有该值，函数会发送一个 `GroupValue_Read` 并等待响应。若将第三个参数设为 `false`，或者在不需要 DPT 时将第二个参数设为 `false`，则函数只使用缓存；如果本地没有值，则返回 `undefined`。`getGAValue` 是异步的，所以当你需要真实值时，应写成 `await getGAValue(...)`。即使使用只读缓存模式，也要保留 `await`：不加 `await` 得到的是 Promise 对象，不是 GA 的值。|
 | `setGAValue(GA, value, DPT?)` | 设置 GA 值；DPT 同上。|
 | `self(value)` | 设置当前节点的值并发送到总线（注意循环）。|
 | `toggle()` | 切换当前值并发送到总线。|

package/package.json

@@ -3,8 +3,8 @@
   "engines": {
     "node": ">=20.18.1"
   },
-  "version": "4.3.11",
-  "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, and KNX routing between interfaces. Easy to use and highly configurable.",
+  "version": "4.3.13",
+  "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/",
     "resources/",
@@ -19,7 +19,7 @@
     "dns-sync": "0.2.1",
     "google-translate-tts": "^0.3.0",
     "js-yaml": "4.1.1",
-    "knxultimate": "5.5.3",
+    "knxultimate": "5.5.6",
     "lodash": "4.18.1",
     "node-color-log": "12.0.1",
     "ping": "0.4.4",

package/resources/KNXReceiveSnippets.js

@@ -35,7 +35,7 @@ return msg`
       title: 'Add property to msg',
       code: `// @ts-nocheck
 // The current msg contains the internal temperature in the "msg.payload" property, but we want to emit the external temperature as well.
-msg.externalTemperature = getGAValue('0/0/10 Garden temperature sensor'); // In case the ETS file is missing, you must specify the dpt as well: getGAValue('0/0/10','9.001')
+msg.externalTemperature = await getGAValue('0/0/10 Garden temperature sensor'); // In case the ETS file is missing, you must specify the dpt as well: await getGAValue('0/0/10','9.001')
 return msg;`
     },
     {
@@ -45,7 +45,7 @@ return msg;`
 // When a motion detector sends a telegram, switch on the corridor light only if
 // the outdoor lux sensor reports a value lower than 80 lux.
 if (msg.payload === true) {
-  const currentLux = getGAValue('0/2/5 Garden lux sensor', '9.004');
+  const currentLux = await getGAValue('0/2/5 Garden lux sensor', '9.004');
   if (typeof currentLux === 'number' && currentLux < 80) {
     return msg;
   }

package/resources/KNXSendSnippets.js

@@ -5,7 +5,7 @@
             title: 'Status GA check',
             code: `// @ts-nocheck
 // Replace '' with the real status group address.
-const statusGA = getGAValue('','1.001');
+const statusGA = await getGAValue('','1.001');
 if (msg.payload !== statusGA){ // " !==" means " not equal"
     return msg;
  }else{
@@ -29,7 +29,7 @@ return msg;`
             title: 'Toggle value (with status check)',
             code: `// @ts-nocheck
 // Get the current value of the status GA. insert the actual STATUS GA here.
-let prevValue = getGAValue('InsertHereTheStatusGA', '1.001')
+let prevValue = await getGAValue('InsertHereTheStatusGA', '1.001')
 if (prevValue === null)
 {
     // If the status of the light is not defined, at the