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

package/CHANGELOG.md

@@ -6,6 +6,17 @@
 
 # CHANGELOG
 
+**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/>
+- UI: updated **KNX Function** editor helper/snippet and Monaco typings so `getGAValue(...)` is suggested with `await` and exposed as a `Promise` in the editor.<br/>
+
+**Version 4.3.10** - April 2026<br/>
+
+- CHANGE: **KNX Function** `getGAValue(...)` now accepts an optional `readIfMissing` boolean. Default is `true` to preserve the current behaviour; pass `false` to use cache-only mode and immediately return `undefined` when the GA value is not available locally.<br/>
+- PERF: **KNX Function** `getGAValue(...)` and KNX cache lookups now use indexed GA access plus deduplicated pending reads, reducing overhead and avoiding duplicate simultaneous `GroupValue_Read` requests for the same GA.<br/>
+- Docs/help/wiki: updated **KNX DEVICE / KNX Function** help HTML and **Device** wiki pages in all supported languages (**EN/IT/DE/FR/ES/zh-CN**) to document the new `getGAValue(..., readIfMissing)` signature and cache-only mode.<br/>
+
 **Version 4.3.9** - April 2026<br/>
 
 - Bump KNX Engine to 5.5.3 (fixed umlaut issue in dpt16)<br/>

package/nodes/knxUltimate-config.js

@@ -200,6 +200,7 @@ module.exports = (RED) => {
     node.stopETSImportIfNoDatapoint = typeof config.stopETSImportIfNoDatapoint === 'undefined' ? 'stop' : config.stopETSImportIfNoDatapoint // 09/01/2020 Stop, Import Fake or Skip the import if a group address has unset datapoint
     node.userDir = path.join(RED.settings.userDir, 'knxultimatestorage') // 04/04/2021 Supergiovane: Storage for service files
     node.exposedGAs = []
+    node.exposedGAsByGa = new Map()
     node.loglevel = config.loglevel !== undefined ? config.loglevel : 'error' // 18/02/2020 Loglevel default error
     if (node.loglevel === 'trace') node.loglevel = 'debug' // Backward compatibility
     if (node.loglevel === 'silent') node.loglevel = 'disable' // Backward compatibility
@@ -208,6 +209,44 @@ module.exports = (RED) => {
       node.sysLogger = new loggerClass({ loglevel: node.loglevel, setPrefix: node.type + ' <' + (node.name || node.id || '') + '>' })
     } catch (error) { console.log(error.stack) }
     node.csv = readCSV(config.csv) // Array from ETS CSV Group Addresses {ga:group address, dpt: datapoint, devicename: full device name with main and subgroups}
+    node.csvByGa = new Map()
+    if (Array.isArray(node.csv)) {
+      node.csv.forEach((entry) => {
+        if (entry && typeof entry.ga === 'string' && entry.ga !== '') node.csvByGa.set(entry.ga, entry)
+      })
+    }
+
+    node.rebuildExposedGAIndex = () => {
+      node.exposedGAsByGa = new Map()
+      if (!Array.isArray(node.exposedGAs)) return
+      node.exposedGAs.forEach((entry) => {
+        if (entry && typeof entry.ga === 'string' && entry.ga !== '') node.exposedGAsByGa.set(entry.ga, entry)
+      })
+    }
+
+    node.getExposedGAEntry = (ga) => {
+      if (typeof ga !== 'string' || ga === '') return undefined
+      return node.exposedGAsByGa.get(ga)
+    }
+
+    node.upsertExposedGAEntry = (entry) => {
+      if (!entry || typeof entry.ga !== 'string' || entry.ga === '') return undefined
+      const existing = node.exposedGAsByGa.get(entry.ga)
+      if (existing) {
+        Object.assign(existing, entry)
+        return existing
+      }
+      node.exposedGAs.push(entry)
+      node.exposedGAsByGa.set(entry.ga, entry)
+      return entry
+    }
+
+    node.removeExposedGAEntry = (ga) => {
+      if (typeof ga !== 'string' || ga === '') return
+      node.exposedGAsByGa.delete(ga)
+      const index = node.exposedGAs.findIndex((item) => item.ga === ga)
+      if (index > -1) node.exposedGAs.splice(index, 1)
+    }
 
     // 12/11/2021 Connect at start delay
     node.autoReconnect = true // 20/03/2022 Default
@@ -764,10 +803,12 @@ module.exports = (RED) => {
       const sFile = path.join(node.userDir, 'knxpersistvalues', 'knxpersist' + node.id + '.json')
       try {
         node.exposedGAs = JSON.parse(fs.readFileSync(sFile, 'utf8'))
+        if (!Array.isArray(node.exposedGAs)) node.exposedGAs = []
       } catch (err) {
         node.exposedGAs = []
         node.sysLogger?.info('unable to read peristent file ' + sFile + ' ' + err.message)
       }
+      node.rebuildExposedGAIndex()
     }
 
     // ************************
@@ -856,7 +897,7 @@ module.exports = (RED) => {
             } else {
               try {
                 if (node.exposedGAs.length > 0) {
-                  const oExposedGA = node.exposedGAs.find((a) => a.ga === _oClient.topic)
+                  const oExposedGA = node.getExposedGAEntry(_oClient.topic)
                   if (oExposedGA !== undefined) {
                     // Retrieve the value from exposedGAs
                     const msg = buildInputMessage({
@@ -885,7 +926,7 @@ module.exports = (RED) => {
                     if (msg.payload === null) {
                       _oClient._hasCurrentPayload = false
                       // Delete the exposedGA
-                      node.exposedGAs = node.exposedGAs.filter((item) => item.ga !== _oClient.topic)
+                      node.removeExposedGAEntry(_oClient.topic)
                       _oClient.setNodeStatus({
                         fill: 'yellow',
                         shape: 'dot',
@@ -1384,16 +1425,14 @@ module.exports = (RED) => {
       if (typeof _dest === 'string' && _rawValue !== undefined && (_evt === 'GroupValue_Write' || _evt === 'GroupValue_Response')) {
         try {
           const ret = { ga: _dest, rawValue: _rawValue, dpt: undefined, devicename: undefined, updatedAt: Date.now() }
-          node.exposedGAs = node.exposedGAs.filter((item) => item.ga !== _dest) // Remove previous
-          if (node.csv !== undefined && node.csv !== '' && node.csv.length !== 0) {
-            // Add the dpt
-            const found = node.csv.find(a => a.ga === _dest)
+          if (node.csvByGa.size > 0) {
+            const found = node.csvByGa.get(_dest)
             if (found !== undefined) {
               ret.dpt = found.dpt
               ret.devicename = found.devicename
             }
           }
-          node.exposedGAs.push(ret) // add the new
+          node.upsertExposedGAEntry(ret)
         } catch (error) { }
       }
 

package/nodes/knxUltimate.html

@@ -271,10 +271,10 @@
             const knxFunctionHelperItems = [
                 {
                     id: 'getGAValue',
-                    label: 'getGAValue(address, dpt?)',
-                    aceValue: "getGAValue('1/1/1', '1.001')",
-                    snippet: "getGAValue('${1:1/1/1}', '${2:1.001}')",
-                    doc: 'Read the cached value of another group address. Provide the datapoint if the ETS import is not available.'
+                    label: 'getGAValue(address, dpt?, readIfMissing?)',
+                    aceValue: "await getGAValue('1/1/1', '1.001', false)",
+                    snippet: "await getGAValue('${1:1/1/1}', '${2:1.001}', ${3:false})",
+                    doc: 'Read another group address. This helper is async, so use await to get the real value. By default, if the value is not cached, a KNX read is sent. Pass false as third parameter to use cache-only mode.'
                 },
                 {
                     id: 'setGAValue',
@@ -465,8 +465,8 @@ return msg;`
                             });
 
                             monaco.languages.typescript.javascriptDefaults.addExtraLib([
-                                '/** Read the cached value of a KNX group address. */',
-                                'declare function getGAValue(address: string, dpt?: string): any;',
+                                '/** Read a KNX group address. This helper is async, so use await to get the real value. By default, if the value is not cached, a KNX read is sent. Pass false as third parameter to use cache-only mode. */',
+                                'declare function getGAValue(address: string, dptOrReadIfMissing?: string | boolean, readIfMissing?: boolean): Promise<any>;',
                                 '/** Send a value to a KNX group address. */',
                                 'declare function setGAValue(address: string, value: any, dpt?: string): void;',
                                 '/** Toggle (invert) this node\'s current value on the KNX bus. */',

package/nodes/knxUltimate.js

@@ -505,13 +505,33 @@ module.exports = function (RED) {
       }
     }
 
+    const pendingGAReads = new Map()
+    const findExposedGA = (ga) => {
+      if (!node.serverKNX) return undefined
+      if (typeof node.serverKNX.getExposedGAEntry === 'function') return node.serverKNX.getExposedGAEntry(ga)
+      return Array.isArray(node.serverKNX.exposedGAs) ? node.serverKNX.exposedGAs.find(a => a.ga === ga) : undefined
+    }
+
     // Used in the KNX Function TAB
-    const getGAValue = async function getGAValue(_ga = undefined, _dpt = undefined) {
+    const getGAValue = async function getGAValue(_ga = undefined, _dpt = undefined, _requestReadIfMissing = undefined) {
       if (_ga === undefined) return null
       // Strip devicename if present (e.g. "1/1/1 Light name" → "1/1/1")
       const blankSpacePosition = _ga.indexOf(' ')
       if (blankSpacePosition > -1) _ga = _ga.substring(0, blankSpacePosition)
 
+      // Overloads:
+      // - getGAValue('1/1/1')
+      // - getGAValue('1/1/1', '1.001')
+      // - getGAValue('1/1/1', '1.001', false)
+      // - getGAValue('1/1/1', false)
+      let dptRequested = _dpt
+      let requestReadIfMissing = _requestReadIfMissing
+      if (typeof dptRequested === 'boolean' && requestReadIfMissing === undefined) {
+        requestReadIfMissing = dptRequested
+        dptRequested = undefined
+      }
+      if (requestReadIfMissing === undefined) requestReadIfMissing = true
+
       const tryDecode = (rawValue, dpt) => {
         try {
           if (rawValue === null || rawValue === undefined) return undefined
@@ -531,30 +551,43 @@ module.exports = function (RED) {
       }
 
       // Check cache first
-      let found = node.serverKNX.exposedGAs.find(a => a.ga === _ga)
+      let found = findExposedGA(_ga)
       if (found !== undefined) {
-        const dptFinal = _dpt || found.dpt
+        const dptFinal = dptRequested || found.dpt
         if (!dptFinal) {
           RED.log.error('getGAValue: no DPT for ' + _ga + '. Provide it as second parameter.')
           return null
         }
         const val = tryDecode(found.rawValue, dptFinal)
         if (val !== undefined) return val
-        // rawValue present but decode failed (bad format) — fall through to read
+        // rawValue present but decode failed (bad format) — fall through to read, unless cache-only mode is requested.
+        if (requestReadIfMissing === false) return undefined
         RED.log.warn('getGAValue: cached rawValue for ' + _ga + ' could not be decoded, sending read request')
       }
 
-      // Not cached or decode failed: send read and poll up to 3 seconds
-      sendRead()
-      for (let i = 0; i < 30; i++) {
-        await new Promise(resolve => setTimeout(resolve, 100))
-        found = node.serverKNX.exposedGAs.find(a => a.ga === _ga)
-        if (found !== undefined) {
-          const dptFinal = _dpt || found.dpt
-          if (!dptFinal) return null
-          const val = tryDecode(found.rawValue, dptFinal)
-          if (val !== undefined) return val
-        }
+      if (requestReadIfMissing === false) return undefined
+
+      // Not cached or decode failed: send read and poll up to 3 seconds.
+      // Deduplicate concurrent reads to the same GA to avoid repeated bus reads and repeated polling loops.
+      let pendingRead = pendingGAReads.get(_ga)
+      if (!pendingRead) {
+        pendingRead = (async () => {
+          sendRead()
+          for (let i = 0; i < 30; i++) {
+            await new Promise(resolve => setTimeout(resolve, 100))
+            const updated = findExposedGA(_ga)
+            if (updated !== undefined) return updated
+          }
+          return null
+        })().finally(() => pendingGAReads.delete(_ga))
+        pendingGAReads.set(_ga, pendingRead)
+      }
+      found = await pendingRead
+      if (found !== null && found !== undefined) {
+        const dptFinal = dptRequested || found.dpt
+        if (!dptFinal) return null
+        const val = tryDecode(found.rawValue, dptFinal)
+        if (val !== undefined) return val
       }
       RED.log.warn('getGAValue: no response from KNX bus for ' + _ga + ' within 3 seconds')
       return null
@@ -569,7 +602,7 @@ module.exports = function (RED) {
         if (blankSpacePosition > -1) _ga = _ga.substring(0, blankSpacePosition)
         if (_dpt === undefined) {
           // Try getting dpt from ETS CSV
-          const found = node.serverKNX.exposedGAs.find(a => a.ga === _ga)
+          const found = findExposedGA(_ga)
           if (found === undefined || found.dpt === undefined) {
             const errM = 'setGAValue: node ID:' + node.id + ' ' + 'No CSV file imported. Please provide the dpt manually'
             RED.log.error(errM)

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?)` | Liest den Wert einer GA, z. B. `'1/0/1'` oder `'1/0/1 Bed table light'` (Text nach Leerzeichen wird ignoriert). DPT nur ohne ETS erforderlich. |
+| `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. |
 | `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`. |
@@ -81,7 +81,7 @@ Der Code läuft bei jeder Eingangs-Nachricht und bei jedem BUS-Telegramm. Bei Ak
 
 ```javascript
 
-const statusGA = getGAValue('0/0/09','1.001');
+const statusGA = await getGAValue('0/0/09','1.001');
 if (msg.payload !== statusGA){ return msg; } else { return; }
 ```
 
@@ -97,12 +97,13 @@ return msg;
 
 ```javascript
 
-msg.externalTemperature = getGAValue('0/0/10'); // ohne ETS: getGAValue('0/0/10','9.001')
+msg.externalTemperature = await getGAValue('0/0/10'); // ohne ETS: await getGAValue('0/0/10','9.001')
 return msg;
 ```
 
 ```javascript
-if (msg.payload === false && getGAValue('0/0/11','1.001') === false){ return; } else { return msg; }
+const otherGA = await getGAValue('0/0/11','1.001');
+if (msg.payload === false && otherGA === false){ return; } else { return msg; }
 ```
 
 ### Inputs

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) | 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'). |
+| 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. |
 | 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. |
@@ -92,7 +92,7 @@ We'll turn on the light only if it's status GA is off, and vice versa.
 
 ```javascript
 
-const statusGA = getGAValue('0/0/09','1.001');
+const statusGA = await getGAValue('0/0/09','1.001');
 if (msg.payload !== statusGA){ // "!==" means "not equal"
     return msg;
 }else{
@@ -122,7 +122,7 @@ The ouput msg to the flow will have also the external temp in the property `msg.
 ```javascript
 
 // 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'); // 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'); // In case the ETS file is missing, you must specify the dpt as well: await getGAValue('0/0/10','9.001')
 return msg;
 ```
 
@@ -130,7 +130,8 @@ In this other sample, we'll not emit a msg to the flow, in case msg.payload and
 
 ```javascript
 
-if (msg.payload === false && getGAValue('0/0/11','1.001') === false){
+const otherGA = await getGAValue('0/0/11','1.001');
+if (msg.payload === false && otherGA === false){
     // Both false, don't emit the msg to the flow.
     return;
 }else{

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) | Obtenga 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**. **DPT** es opcional con ETS; si no, debe indicarlo (por ejemplo `'1.001'`). |
+| 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. |
 | 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. |
@@ -92,7 +92,7 @@ Encenderemos la luz solo si su estado GA está apagado y viceversa.
 
 ```javascript
 
-const statusGA = getGAValue('0/0/09','1.001');
+const statusGA = await getGAValue('0/0/09','1.001');
 if (msg.payload !== statusGA){ // "!==" means "not equal"
     return msg;
 }else{
@@ -122,7 +122,7 @@ El mensaje de salida al flujo también tendrá la temperatura externa en la prop
 ```javascript
 
 // 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'); // 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'); // Si falta el archivo ETS: await getGAValue('0/0/10','9.001')
 return msg;
 ```
 
@@ -130,7 +130,8 @@ En esta otra muestra, no emitiremos un MSG al flujo, en el caso de MSG.PayLoad y
 
 ```javascript
 
-if (msg.payload === false && getGAValue('0/0/11','1.001') === false){
+const otherGA = await getGAValue('0/0/11','1.001');
+if (msg.payload === false && otherGA === false){
     // Both false, don't emit the msg to the flow.
     return;
 }else{

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 facultatif DPT) | Obtenez 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 dans le champ **Recherche GA**. **DPT** est facultatif avec ETS; sinon vous devez le spécifier (par exemple `'1.001'`). |
+| 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. |
 | 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. |
@@ -92,7 +92,7 @@ Nous allons allumer la lumière uniquement si son statut GA est éteint, et vice
 
 ```javascript
 
-const statusGA = getGAValue('0/0/09','1.001');
+const statusGA = await getGAValue('0/0/09','1.001');
 if (msg.payload !== statusGA){ // "!==" means "not equal"
     return msg;
 }else{
@@ -122,7 +122,7 @@ Le msg ouput au flux aura également la température externe dans la propriété
 ```javascript
 
 // 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'); // 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'); // En l'absence du fichier ETS: await getGAValue('0/0/10','9.001')
 return msg;
 ```
 
@@ -130,7 +130,8 @@ Dans cet autre échantillon, nous n'émettons pas de msg au flux, au cas où msg
 
 ```javascript
 
-if (msg.payload === false && getGAValue('0/0/11','1.001') === false){
+const otherGA = await getGAValue('0/0/11','1.001');
+if (msg.payload === false && otherGA === false){
     // Both false, don't emit the msg to the flow.
     return;
 }else{

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.) | 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'`. |
+| `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. |
 | `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`. |
@@ -90,7 +90,7 @@ Invia al BUS solo se un altro GA ha valore opposto:
 
 ```javascript
 
-const statusGA = getGAValue('0/0/09','1.001');
+const statusGA = await getGAValue('0/0/09','1.001');
 if (msg.payload !== statusGA){
   return msg;
 } else {
@@ -116,7 +116,7 @@ Allega all'output anche la temperatura esterna letta da un altro GA:
 ```javascript
 
 // msg.payload contiene la temperatura interna; aggiungi la esterna
-msg.externalTemperature = getGAValue('0/0/10'); // senza ETS: getGAValue('0/0/10','9.001')
+msg.externalTemperature = await getGAValue('0/0/10'); // senza ETS: await getGAValue('0/0/10','9.001')
 return msg;
 ```
 
@@ -124,7 +124,8 @@ Non emettere nulla se `msg.payload` e un altro GA sono entrambi false:
 
 ```javascript
 
-if (msg.payload === false && getGAValue('0/0/11','1.001') === false){
+const otherGA = await getGAValue('0/0/11','1.001');
+if (msg.payload === false && otherGA === false){
   return; // non emettere
 } else {
   return msg;

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

@@ -71,7 +71,7 @@
 |对象/函数|说明|
 |--|--|
 | `msg` | 当前消息对象。|
-| `getGAValue(GA, DPT?)` | 读取 GA 值，如 `'1/0/1'` 或 `'1/0/1 Bed table light'`（空格后的文字被忽略）。未导入 ETS 时需提供 DPT。|
+| `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。|
 | `setGAValue(GA, value, DPT?)` | 设置 GA 值；DPT 同上。|
 | `self(value)` | 设置当前节点的值并发送到总线（注意循环）。|
 | `toggle()` | 切换当前值并发送到总线。|
@@ -81,7 +81,7 @@
 
 ```javascript
 
-const statusGA = getGAValue('0/0/09','1.001');
+const statusGA = await getGAValue('0/0/09','1.001');
 if (msg.payload !== statusGA){ return msg; } else { return; }
 ```
 
@@ -97,12 +97,13 @@ return msg;
 
 ```javascript
 
-msg.externalTemperature = getGAValue('0/0/10'); // 未导入 ETS：getGAValue('0/0/10','9.001')
+msg.externalTemperature = await getGAValue('0/0/10'); // 未导入 ETS：await getGAValue('0/0/10','9.001')
 return msg;
 ```
 
 ```javascript
-if (msg.payload === false && getGAValue('0/0/11','1.001') === false){ return; } else { return msg; }
+const otherGA = await getGAValue('0/0/11','1.001');
+if (msg.payload === false && otherGA === false){ return; } else { return msg; }
 ```
 
 ### 输入（Inputs）

package/package.json

@@ -3,7 +3,7 @@
   "engines": {
     "node": ">=20.18.1"
   },
-  "version": "4.3.9",
+  "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.",
   "files": [
     "nodes/",
@@ -82,7 +82,7 @@
     "IOT",
     "philips hue"
   ],
-  "author": "Supergiovane",
+  "author": "Massimo Saccani (Supergiovane)",
   "license": "MIT",
   "scripts": {
     "build": "npm run knx-ai:build && npm run knx-viewer:build",
@@ -117,4 +117,4 @@
     "vite": "^7.1.3",
     "vue": "^3.5.21"
   }
-}
+}