node-red-contrib-uos-nats 0.1.63 → 0.1.65

package/README.md

@@ -36,6 +36,56 @@ Restart Node-RED. The nodes appear in the **"u-OS DataHub NATS"** category in th
 
 ---
 
+## Why NATS Instead of REST API?
+
+The u-OS Data Hub offers both **NATS** (this package) and **REST API** access. Here's why NATS is the better choice for Node-RED:
+
+### Feature Comparison
+
+| Feature | NATS Protocol | REST API |
+|---------|---------------|----------|
+| **Real-time Updates** | ✅ Event-driven (instant) | ❌ Polling required (delays) |
+| **Performance** | ✅ Binary protocol, high-throughput | ❌ HTTP/JSON overhead |
+| **Communication** | ✅ Bidirectional (Pub/Sub + Request/Reply) | ❌ Client-initiated only |
+| **Provider Registration** | ✅ Dynamic discovery & auto-registration | ❌ Static endpoints |
+| **Scalability** | ✅ Many-to-many connections | ❌ Point-to-point requests |
+| **Network Efficiency** | ✅ Push notifications (no polling waste) | ❌ Repeated GET requests |
+
+### Event-Driven Architecture
+
+**NATS enables true event-driven workflows:**
+
+```
+Sensor changes value
+       ↓
+Data Hub publishes event via NATS
+       ↓
+Node-RED receives update INSTANTLY (0ms delay)
+       ↓
+Process & forward to other systems
+```
+
+**With REST API you'd need:**
+- Constant polling (e.g., every 100ms)
+- Increased network traffic
+- Delayed reactions
+- Higher CPU usage
+
+### Use NATS when:
+
+✅ You need **real-time reactions** to value changes  
+✅ You want to **create providers** (publish data to Data Hub)  
+✅ You need **event subscriptions** (get notified on changes)  
+✅ You're building **scalable industrial workflows**  
+
+### Use REST API when:
+
+⚠️ You only need **occasional manual reads**  
+⚠️ You're debugging or doing one-time queries  
+⚠️ NATS port (49360) is blocked in your network  
+
+---
+
 ## 1. u-OS Config Node
 
 ### Purpose
@@ -161,7 +211,25 @@ Click **"Add Variable"** for each entry.
 ## 3. DataHub - OUT Node (Write Variables)
 
 ### Purpose
-Publish variables to the Data Hub (creates your own provider that other apps can read).
+**Creates a real Data Hub provider** that publishes variables to the u-OS Data Hub. Other applications, devices, or even other Node-RED instances can **subscribe to your data in real-time**.
+
+### How It Works
+
+The OUT node:
+1. **Registers as a Provider** on the Data Hub (e.g., provider ID: `nodered`)
+2. **Publishes variable definitions** automatically when new variables are sent
+3. **Sends value updates** via NATS when you send JSON messages
+4. **Answers read requests** from other consumers (apps can query your latest values)
+5. **Supports event-driven subscriptions** - other apps get updates **instantly** when values change
+
+**Important:** This provider only exists **while Node-RED is running**. When you restart Node-RED, the provider re-registers automatically.
+
+### Real-World Use Cases
+
+✅ **IoT Data Collection:** Node-RED reads sensor data (Modbus, MQTT, etc.) and publishes it to the Data Hub  
+✅ **Edge Processing:** Process data locally in Node-RED, then share results with other apps  
+✅ **System Integration:** Bridge between different protocols (e.g., OPC UA → Data Hub)  
+✅ **Custom Dashboards:** Other apps can subscribe to Node-RED's variables for visualization  
 
 ### Setup Steps
 
@@ -172,6 +240,8 @@ Publish variables to the Data Hub (creates your own provider that other apps can
 - **Leave EMPTY** to use the `Client Name` from your Config (recommended)
 - Or enter a custom provider ID (e.g., `my-machine-data`)
 
+**Example:** If your Config's Client Name is `nodered`, the provider will be `nodered`
+
 #### Step 3: Send JSON Messages
 Send a JSON object with your data:
 
@@ -190,6 +260,28 @@ This creates variables:
 - `machine.status` → ID 1
 - `machine.speed` → ID 2
 
+**The variables are INSTANTLY available to other apps via:**
+- **Event subscriptions** (other apps get updates when values change)
+- **Read queries** (other apps can request current values)
+- **u-Control Web UI** (visible in Data Hub → Providers → `nodered`)
+
+### Event-Driven Communication
+
+When you send a message to the OUT node:
+
+```
+[Function: {"temp": 22.5}] → [DataHub - OUT] 
+                                    ↓
+                    ┌───────────────────────────────┐
+                    │   u-OS Data Hub (NATS)        │
+                    └───────────────────────────────┘
+                     ↓           ↓            ↓
+              [Python App]  [Dashboard]  [Other Node-RED]
+              (subscribes)  (subscribes)  (subscribes)
+```
+
+**All subscribers receive the update IMMEDIATELY** - no polling needed!
+
 #### Step 4: Deploy & Test
 1. Connect a **Function** or **Inject** node
 2. Click **Deploy**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-red-contrib-uos-nats",
-  "version": "0.1.63",
+  "version": "0.1.65",
   "description": "Node-RED nodes for Weidmüller u-OS Data Hub. Read and write variables via NATS protocol with OAuth2 authentication. Supports event-based subscriptions and manual variable mapping.",
   "author": {
     "name": "IoTUeli",