node-red-contrib-uos-nats 1.3.46 → 1.3.55

package/README.md

@@ -1,9 +1,13 @@
-
 **Unofficial Node-RED Package for Weidmüller u-OS Data Hub**
 
 Read, write, and provide variables via NATS protocol using **OAuth2 authentication**.
 Optimized for high performance and real-time updates.
 
+> **IMPORTANT:**
+> These nodes **MUST** run directly on the **u-OS device** (e.g. as a simplified App or Snap).
+> The system's NATS server is **NOT accessible from the outside** (blocked by firewall/binding).
+> You cannot use this package from a remote Node-RED instance (e.g. on your Laptop) to connect to the device.
+
 Maintained by [IoTUeli](https://iotueli.ch). Source: [GitHub](https://github.com/uiff/nats-NodeRed-Node-uc20)
 
 ---
@@ -68,12 +72,28 @@ Reads values from existing providers (like `u_os_adm`).
 - **Provider ID:** Name of the source provider.
 - **Variables:** Use **Load Variables** to browse and select variables.
 - **Trigger:** "Event" (instant update) or "Poll" (interval).
+- **Dynamic Read:** Send `msg.payload` as an Array of keys (e.g. `["machine.status", "temp"]`) to trigger a specific snapshot, ignoring the node configuration.
 
 ### DataHub - Write
 Changes values in other providers.
-- **Single Mode:** Select a variable from the list. Send `msg.payload` = value.
-- **Batch Mode:** Select NO variable (clear selection). Send `msg.payload` as a JSON object: `{"var_key": value, "var2": value}`.
-- **Strict Mode:** Automatically handles Fingerprints for strict providers (e.g. `u_os_sbm`).
+-   **Single Mode:** Select a variable from the list. Send `msg.payload` = value.
+-   **Batch Mode:** Select NO variable (clear selection). Send `msg.payload` as a JSON object: `{"var_key": value, "var2": value}` (uses Configured Provider).
+-   **Dynamic Mode:** Send a full target object to write anywhere:
+    ```json
+    {
+      "provider": "target_provider_id",
+      "key": "variable_key",
+      "value": 123
+    }
+    ```json
+    {
+      "provider": "target_provider_id",
+      "key": "variable_key",
+      "value": 123
+    }
+    ```
+    Or send an **Array** of these objects to write to multiple providers in one go.
+-   **Strict Mode:** Automatically handles Fingerprints for strict providers (e.g. `u_os_sbm`).
 
 ### DataHub - Provider
 Publishes your own data to the Data Hub.
@@ -92,10 +112,11 @@ Publishes your own data to the Data Hub.
 ## Troubleshooting
 
 - **Provider not visible?** Ensure **Provider ID** matches your **Client ID**. Easiest way: Leave Provider ID empty in the node.
+- **Node Status is Green (Ring)?**
+  - `waiting for provider`: The node is connected to NATS (OK), but the target Provider (e.g. `u_os_sbm`) is currently offline. It will resume automatically.
 - **Node Status is Yellow?**
-  - `cooldown (10s)`: The node is waiting to protect the device. This is normal after an error.
-  - `provider offline`: The connection to NATS is OK, but the target (e.g. `u_os_sbm`) is not responding (503).
-  - `auth failed`: Check your OAuth Client Secret and Scopes.
+  - `cooldown (10s)`: The node is pausing after an error to protect the network.
+  - `auth failed`: OAuth credentials generated an error. Check Client Secret.
 - **Node Status is Red?**
   - `illegal ID`: You used a reserved name like `u_os_sbm`. Rename your Client/Provider.
   - `write error`: A command failed. Check Scopes (`hub.variables.readwrite`) or Fingerprint.

package/lib/payloads.js

@@ -79,8 +79,14 @@ export function buildReadVariablesQuery(ids) {
     const builder = new flatbuffers.Builder(128);
     let idsOffset = 0;
 
-    if (ids && ids.length > 0) {
-        idsOffset = ReadVariablesQueryRequest.createIdsVector(builder, ids);
+    // Safety: Filter invalid IDs to prevent crashes in C++ provider
+    // FlatBuffers requires strict types.
+    const validIds = (ids || [])
+        .map(id => Number(id))
+        .filter(id => Number.isInteger(id) && id >= 0);
+
+    if (validIds.length > 0) {
+        idsOffset = ReadVariablesQueryRequest.createIdsVector(builder, validIds);
     }
 
     ReadVariablesQueryRequest.startReadVariablesQueryRequest(builder);

package/nodes/datahub-input.html

@@ -348,4 +348,8 @@
         <li><b>Provider ID:</b> ID of the data source (e.g., <code>u_os_adm</code>). Use the search button to find available providers.</li>
         <li><b>Variables:</b> Click "Load Variables" to select specific data points. Leave empty to read everything.</li>
     </ol>
+    <p>
+        <b>Dynamic Read:</b> Send <code>msg.payload</code> as an Array of variable keys (e.g. <code>["var1", "var2"]</code>) 
+        to read specific variables on demand. This overrides the node's configuration for that single request.
+    </p>
 </script>

package/nodes/datahub-input.js

@@ -168,100 +168,134 @@ module.exports = function (RED) {
           return; // Stop here, do not start Interval or Subscription
         }
 
-        performSnapshot = async () => {
-          // Debugging connection state
+        performSnapshot = async (overrideItems) => {
           if (!nc || nc.isClosed()) {
             this.warn('Snapshot skipped: Connection is closed or not ready.');
             return;
           }
 
-          try {
-            // Resolve requested variable names to IDs
-            let targetIds = [];
-            let isWildcard = (this.variables.length === 0);
+          // Group items by Provider
+          // Default Provider: this.providerId
+          const requests = new Map(); // ProviderId -> Set<VariableId>
+
+          if (overrideItems) {
+            // Dynamic Mode: Resolve each item
+            for (const item of overrideItems) {
+              let pId = (typeof item === 'object' && item.provider) ? item.provider : this.providerId;
+              let key = (typeof item === 'object') ? item.key : item; // String or Object.key
 
+              if (!key) continue;
+
+              try {
+                // Use Config Node Resolution (Cache)
+                // This handles fetching definitions for ANY provider on demand
+                const resolved = await connection.resolveVariableId(pId, key);
+
+                if (!requests.has(pId)) requests.set(pId, new Set());
+                requests.get(pId).add(resolved.id);
+              } catch (e) {
+                this.warn(`Dynamic Read: Skipping '${key}' on '${pId}': ${e.message}`);
+              }
+            }
+          } else {
+            // Static Mode: Use local defMap for configured provider
+            const targetIds = new Set();
+            const isWildcard = (this.variables.length === 0);
             if (!isWildcard) {
-              // Reverse lookup: Find Def by Key
               const requestedKeys = new Set(this.variables);
-
               for (const def of defMap.values()) {
-                if (requestedKeys.has(def.key)) {
-                  targetIds.push(Number(def.id));
-                }
+                if (requestedKeys.has(def.key)) targetIds.add(def.id);
               }
-
-              // CRITICAL FIX: If user requested specific variables but we found NONE, 
-              // we MUST NOT send an empty list, because that would interpret as "Read All".
-              if (targetIds.length === 0) {
-                // Already handled by Gate above mostly, but good for safety
-                this.warn(`Snapshot Aborted: None of the ${this.variables.length} requested variables could be resolved to IDs.`);
+              if (targetIds.size === 0) {
+                this.warn(`Snapshot Aborted: None of the configured variables could be resolved.`);
                 return;
               }
             }
+            requests.set(this.providerId, targetIds); // Empty Set = Wildcard
+          }
 
-            // If Wildcard (empty targetIds and isWildcard=true) -> Request ALL.
-            // If Specific (targetIds has items) -> Request specific.
-            // Use serialRequest via Config Node to prevent concurrency issues on the connection
-            // Simple Snapshot Logic using Config Node Semaphore
-            // The Config Node now handles concurrency (max 3 parallel), preventing 503s naturally.
-            // We use a simple retry wrapper just in case.
-            let lastError;
-            for (let attempt = 1; attempt <= 3; attempt++) {
-              try {
-                let snapshotMsg;
-                // If config node has serialRequest (Semaphore), use it.
-                if (typeof connection.serialRequest === 'function') {
-                  snapshotMsg = await connection.serialRequest(subjects.readVariablesQuery(this.providerId), payloads.buildReadVariablesQuery(targetIds), { timeout: 10000 });
-                } else {
-                  // Fallback to direct request (unsafe)
-                  snapshotMsg = await nc.request(subjects.readVariablesQuery(this.providerId), payloads.buildReadVariablesQuery(targetIds), { timeout: 10000 });
-                }
+          if (requests.size === 0) {
+            this.warn("Snapshot Aborted: No valid variables resolved.");
+            return;
+          }
 
-                const bb = new flatbuffers.ByteBuffer(snapshotMsg.data);
-                const snapshotObj = ReadVariablesQueryResponse.getRootAsReadVariablesQueryResponse(bb);
-                const states = payloads.decodeVariableList(snapshotObj.variables());
-
-                const filteredSnapshot = processStates(states);
-                if (filteredSnapshot.length > 0) {
-                  this.send({ payload: { type: 'snapshot', variables: filteredSnapshot } });
-                  this.status({ fill: 'green', shape: 'dot', text: 'active' });
-                } else {
-                  // Handle empty/partial...
-                  this.status({ fill: 'green', shape: 'ring', text: 'active (empty)' });
-                }
-                return true; // Success
+          const allResults = [];
+          const errors = [];
 
-              } catch (err) {
-                lastError = err;
-                // If semaphore is full or timeout, wait a bit
-                await new Promise(r => setTimeout(r, 1000 * attempt));
-              }
-            }
-            if (lastError) {
-              const msg = lastError.message || '';
-              if (msg.includes('503') || msg.includes('no responders')) {
-                this.debug(`Snapshot skipped (Provider offline/503): ${msg}`);
-                this.status({ fill: 'yellow', shape: 'dot', text: 'provider offline' });
-              } else if (msg.includes('Cooldown')) {
-                this.debug(`Snapshot skipped (Cooldown): ${msg}`);
-                this.status({ fill: 'yellow', shape: 'ring', text: 'cooldown (10s)' });
-              } else if (msg.includes('Authorization') || msg.includes('Permission')) {
-                this.debug(`Snapshot skipped (Auth): ${msg}`);
-                this.status({ fill: 'yellow', shape: 'ring', text: 'auth failed' });
+          // Execute Requests (Serial or Parallel?) 
+          // Using Serial to be safe with connection bandwidth
+          for (const [pId, varIds] of requests) {
+            try {
+              let targetIdsArr = Array.from(varIds);
+
+              // Request
+              let snapshotMsg;
+              if (typeof connection.serialRequest === 'function') {
+                snapshotMsg = await connection.serialRequest(subjects.readVariablesQuery(pId), payloads.buildReadVariablesQuery(targetIdsArr), { timeout: 10000 });
               } else {
-                this.warn(`Snapshot failed: ${msg}`);
-                this.status({ fill: 'red', shape: 'ring', text: 'snapshot error' });
+                snapshotMsg = await nc.request(subjects.readVariablesQuery(pId), payloads.buildReadVariablesQuery(targetIdsArr), { timeout: 10000 });
               }
+
+              const bb = new flatbuffers.ByteBuffer(snapshotMsg.data);
+              const snapshotObj = ReadVariablesQueryResponse.getRootAsReadVariablesQueryResponse(bb);
+              const states = payloads.decodeVariableList(snapshotObj.variables());
+
+              // Add Provider Info to Result?
+              // ProcessStates adds keys, but we might want to know which provider it came from if mixed?
+              // The current `processStates` maps IDs back to Keys using `defMap`. 
+              // ISSUE: `defMap` only has local provider defs.
+              // If we read from foreign provider, `processStates` will return IDs or "Unknown".
+              // We need `resolveVariableId` to also START caching the reverse lookup or we assume result has IDs?
+              // Wait, `decodeVariableList` returns {id, value}.
+              // `processStates` tries to find Key.
+
+              // QUICK FIX for Dynamic Multi-Provider:
+              // If pId !== this.providerId, we don't have local defMap.
+              // But `resolveVariableId` (in config) caches definitions.
+              // We can ask config to resolve ID back to Key? Or just return ID?
+              // Better: We know the Keys we asked for.
+
+              // Let's modify processStates to accept a custom Map?
+              // Or simple: Just return the raw objects with IDs if we can't map them?
+              // Actually, for Dynamic Read, users might accept {id, value} or we try to enrich.
+
+              const enriched = states.map(s => {
+                // Try local defMap
+                if (pId === this.providerId && defMap.has(s.id)) {
+                  return { ...s, key: defMap.get(s.id).key, provider: pId };
+                }
+                // Try Config Node Cache (it has all fetched defs)
+                const cachedDef = connection.getProviderVariable(pId, s.id);
+                if (cachedDef) {
+                  return { ...s, key: cachedDef.key, provider: pId };
+                }
+                return { ...s, key: `id:${s.id}`, provider: pId };
+              });
+
+              allResults.push(...enriched);
+
+            } catch (err) {
+              errors.push(`${pId}: ${err.message}`);
             }
-          } catch (e) {
-            const msg = e.message || '';
-            if (msg.includes('503') || msg.includes('no responders')) {
-              this.debug(`Snapshot skipped (Provider offline/503): ${msg}`);
-            } else if (msg.includes('Cooldown')) {
-              // Ignore cooldown errors in outer catch
+          }
+
+          if (allResults.length > 0) {
+            this.send({ payload: { type: 'snapshot', variables: allResults } });
+            this.status({ fill: 'green', shape: 'dot', text: 'active' });
+          } else if (errors.length > 0) {
+            const errStr = errors.join('; ');
+            if (errStr.includes('503') || errStr.includes('no responders')) {
+              this.status({ fill: 'green', shape: 'ring', text: 'waiting for provider' });
+              this.debug(`Snapshot waiting: ${errStr}`);
+            } else if (errStr.includes('Authorization') || errStr.includes('Permission')) {
+              this.status({ fill: 'yellow', shape: 'ring', text: 'auth failed' });
+              this.warn(`Snapshot auth failed: ${errStr}`);
             } else {
-              this.warn(`Snapshot failed: ${msg}`);
+              this.status({ fill: 'red', shape: 'ring', text: 'error' });
+              this.warn(`Snapshot errors: ${errStr}`);
             }
+          } else {
+            this.status({ fill: 'green', shape: 'ring', text: 'empty' });
           }
         };
 
@@ -334,7 +368,17 @@ module.exports = function (RED) {
     };
 
     this.on('input', (msg, send, done) => {
-      performSnapshot()
+      let overrideItems = null;
+      if (msg.payload) {
+        if (Array.isArray(msg.payload) && msg.payload.length > 0) {
+          overrideItems = msg.payload;
+        } else if (typeof msg.payload === 'string' || (typeof msg.payload === 'object' && !Buffer.isBuffer(msg.payload))) {
+          // Allow single item dynamic read (convenience)
+          overrideItems = [msg.payload];
+        }
+      }
+
+      performSnapshot(overrideItems)
         .then(() => done())
         .catch((err) => done(err));
     });

package/nodes/datahub-write.html

@@ -248,5 +248,24 @@
         <li><b>Provider ID:</b> Target provider (e.g. <code>u_os_adm</code>). Use the search button to find it.</li>
         <li><b>Variable:</b> Select a target variable. <b>Only writable variables are shown.</b></li>
     </ol>
-    <p>If no variable is selected, the node works in <b>Batch Mode</b> (expects JSON object payload).</p>
-</script>
+    <p>If no variable is selected, the node works in <b>Batch Mode</b> or <b>Dynamic Mode</b>.</p>
+    <ul>
+        <li><b>Batch:</b> Send a JSON object to update multiple keys for the configured Provider: <code>{"key": value, "key2": value}</code></li>
+        <li><b>Dynamic:</b> Send a specific object to target ANY Provider/Key:
+            <code>
+            {
+                "provider": "u_os_sbm",
+                "key": "machine.outputs.DO01",
+                "value": true
+            }
+            </code>
+        </li>
+        <li><b>Mixed Array:</b> Send an array of dynamic objects to write to multiple providers at once:
+            <code>
+            [
+              { "provider": "u_os_sbm", "key": "doo1", "value": true },
+              { "provider": "other_provider", "key": "var2", "value": 123 }
+            ]
+            </code>
+        </li>
+    </ul>

package/nodes/datahub-write.js

@@ -170,7 +170,8 @@ module.exports = function (RED) {
                         node.resolvedId = this.variableId;
                         // Log as debug implies we handle it gracefully => No User Warn
                         node.debug(`ID Resolution failed for '${this.variableKey}' (${err.message}). Using configured ID: ${this.variableId}`);
-                        node.status({ fill: 'yellow', shape: 'dot', text: 'fallback (key missing)' });
+                        // User Request v1.3.48: Show Green 'ready' even if ID resolution failed (Dynamic Mode)
+                        node.status({ fill: 'green', shape: 'dot', text: 'ready' });
                     } else {
                         node.warn(`ID Resolution failed for '${this.variableKey}': ${err.message}`);
                         node.status({ fill: 'red', shape: 'dot', text: 'resolution failed' });
@@ -228,30 +229,40 @@ module.exports = function (RED) {
                         // Array: [{id:1, value:val}, {key:'k', value:val}]
                         items = rawPayload;
                     } else {
-                        // Object: { "key": val, "id:1": val }
-                        items = Object.entries(rawPayload).map(([k, v]) => {
-                            // Detect if key is actually an ID (e.g. "5" or "id:5")? 
-                            // Easier: treat all keys as Keys, unless user passes explicit Array.
-                            const asInt = parseInt(k, 10);
-                            if (!isNaN(asInt) && String(asInt) === k) {
-                                return { id: asInt, value: v };
-                            }
-                            return { key: k, value: v };
-                        });
+                        // Check for Single Dynamic Write Object
+                        // Format: { provider: "p", key: "k", value: "v" }
+                        if (rawPayload.provider || rawPayload.key || rawPayload.variableKey || rawPayload.variableId) {
+                            items = [rawPayload];
+                        } else {
+                            // Object: { "key": val, "id:1": val }
+                            items = Object.entries(rawPayload).map(([k, v]) => {
+                                // Detect if key is actually an ID (e.g. "5" or "id:5")? 
+                                // Easier: treat all keys as Keys, unless user passes explicit Array.
+                                const asInt = parseInt(k, 10);
+                                if (!isNaN(asInt) && String(asInt) === k) {
+                                    return { id: asInt, value: v };
+                                }
+                                return { key: k, value: v };
+                            });
+                        }
                     }
 
                     // Process Items
                     for (const item of items) {
-                        let targetId = item.id;
+                        let targetId = item.id || item.variableId;
                         let targetType = item.dataType; // Optional explicit type
 
                         if (targetId === undefined) {
-                            if (item.key) {
+                            const effectiveKey = item.key || item.variableKey;
+                            if (effectiveKey) {
                                 // Resolve Key
                                 try {
+                                    // Use Dynamic Provider if present, otherwise configured Provider
+                                    const effectiveProvider = item.provider || item.providerId || node.providerId;
+
                                     // Use Centralized Cache in Config Node
                                     if (typeof configNode.resolveVariableId === 'function') {
-                                        const resolved = await configNode.resolveVariableId(node.providerId, item.key);
+                                        const resolved = await configNode.resolveVariableId(effectiveProvider, effectiveKey);
                                         targetId = resolved.id;
                                         if (!targetType) targetType = resolved.dataType;
                                         if (resolved.fingerprint) currentFingerprint = resolved.fingerprint;
@@ -259,7 +270,7 @@ module.exports = function (RED) {
                                         throw new Error("Config Node too old");
                                     }
                                 } catch (e) {
-                                    node.warn(`Skipping key '${item.key}': ${e.message}`);
+                                    node.warn(`Skipping key '${effectiveKey}': ${e.message}`);
                                     continue;
                                 }
                             } else {

package/nodes/uos-config.html

@@ -230,6 +230,13 @@
 
   <h3>Troubleshooting</h3>
   
+  <p style="color:var(--red-ui-text-color-error); font-weight:bold; border:1px solid var(--red-ui-text-color-error); padding:5px; border-radius:3px;">
+      ⚠️ IMPORTANT:<br>
+      These nodes MUST run directly on the u-OS device (App/Snap).
+      The NATS server is NOT accessible from the outside.
+      You cannot use this node from a remote instance (e.g. Laptop).
+  </p>
+
   <h4>Test Connection fails</h4>
   <ul>
     <li>Check Host/Port are correct and device is reachable</li>

package/nodes/uos-config.js

@@ -559,8 +559,26 @@ module.exports = function (RED) {
       }
     };
 
-    this.on('close', (done) => {
-      this.release().finally(done);
+    this.on('close', async (done) => {
+      // Force Close Connection on Full Deploy (ignore reference count)
+      if (this.refreshTimer) {
+        clearTimeout(this.refreshTimer);
+        this.refreshTimer = null;
+      }
+
+      if (this.nc) {
+        const nc = this.nc;
+        this.nc = null;
+        this.users = 0;
+        try {
+          // Drain ensures all pending messages are sent before closing
+          await nc.drain();
+          // this.log('NATS Connection flushed and closed.');
+        } catch (err) {
+          this.warn(`Error closing NATS connection: ${err.message}`);
+        }
+      }
+      done();
     });
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-red-contrib-uos-nats",
-  "version": "1.3.46",
+  "version": "1.3.55",
   "description": "Node-RED nodes for Weidmüller u-OS Data Hub. Read, write, and provide variables via NATS protocol with OAuth2 authentication. Features: Variable Key resolution, custom icons, example flows, and provider definition caching.",
   "author": {
     "name": "IoTUeli",