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

package/README.md

@@ -2,16 +2,16 @@
 
 **Unofficial Node-RED Package for u-OS Data Hub**
 
-Built and maintained by [IoTUeli](https://www.linkedin.com/in/iotueli/). This is **not** an official Weidmüller product.  
+Built and maintained by [IoTUeli](https://iotueli.ch). This is **not** an official Weidmüller product.  
 Repository: <https://github.com/uiff/nats-NodeRed-Node-uc20>
 
 ---
 
 ## What is this?
 
-Node-RED nodes to **read** and **write** variables from the **u-OS Data Hub** via NATS protocol.
+Node-RED nodes to **read** and **write** variables from the **Weidmüller u-OS Data Hub** via NATS protocol.
 
-### The Three Nodes:
+### The Three Nodes
 
 1. **u-OS Config** – Connection settings (Host, OAuth credentials, NATS connection)
 2. **DataHub - IN** – Read variables from Data Hub providers
@@ -71,14 +71,14 @@ Process & forward to other systems
 - Delayed reactions
 - Higher CPU usage
 
-### Use NATS when:
+### 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:
+### Use REST API when
 
 ⚠️ You only need **occasional manual reads**  
 ⚠️ You're debugging or doing one-time queries  
@@ -86,164 +86,174 @@ Process & forward to other systems
 
 ---
 
-## 1. u-OS Config Node
+## Quick Start Guide
 
-### Purpose
-Stores connection details and OAuth credentials. All DataHub nodes share this configuration.
+### Step 1: Create OAuth Client in u-OS
+
+Before configuring Node-RED, create an OAuth client on your u-OS device:
 
-### Setup Steps
+1. Open the **u-OS Web Interface** (e.g., `http://192.168.10.100`)
+2. Go to **System** → **Access Control** → **OAuth Clients**
+3. Click **"Add Client"**
+4. Enter:
+   - **Name:** `nodered`
+   - **Scopes:** Select **all** `hub.variables.*` scopes:
+     - `hub.variables.provide` (for creating providers)
+     - `hub.variables.readonly` (for reading)
+     - `hub.variables.readwrite` (for writing)
+5. **Save** and copy the **Client ID** and **Client Secret**
 
-1. **Add a Config Node:**
-   - Open any DataHub node (IN or OUT)
-   - Click the pencil icon next to "Config"
-   - Click "Add new uos-config..."
+### Step 2: Configure u-OS Config Node in Node-RED
 
-2. **Fill in the Fields:**
+1. Drag any **DataHub - IN** or **DataHub - OUT** node onto the canvas
+2. Double-click it to open settings
+3. Click the **pencil icon** next to "Config"
+4. Select **"Add new uos-config..."**
+5. Fill in:
 
 | Field | Example | Description |
 |-------|---------|-------------|
-| **Host** | `192.168.10.100` | IP address of your u-Control device |
-| **Port** | `49360` | NATS port (default: 49360) |
-| **Client Name** | `nodered` | Unique name for this Node-RED instance |
-| **Client ID** | `my-oauth-client` | OAuth2 Client ID (from Control Center) |
-| **Client Secret** | `****************` | OAuth2 Client Secret (from Control Center) |
-| **Scopes** | `hub.variables.*` | Leave default or customize (see below) |
-
-3. **Create OAuth Client in Control Center:**
-   - Open the u-Control Web Interface
-   - Go to **System** → **Access Control** → **OAuth Clients**
-   - Click **"Add Client"**
-   - **Name:** `nodered`
-   - **Scopes:** Select all `hub.variables.*` (provide, readonly, readwrite)
-   - **Copy the Client ID and Secret** into Node-RED
+| **Host** | `192.168.10.100` | IP of your u-OS device |
+| **Port** | `49360` | NATS port (default) |
+| **Client Name** | `nodered` | Unique name for this instance |
+| **Client ID** | `my-oauth-client` | From Step 1 |
+| **Client Secret** | `****************` | From Step 1 |
 
-4. **Test Connection:**
-   - Click **"Test Connection"** button
-   - ✅ Success: Shows "Connected" + granted scopes
-   - ❌ Error: Check Host/Port/Credentials
+6. Click **"Test Connection"** to verify
+7. On success, click **"Add"** then **"Done"**
 
----
+### Step 3: Deploy Your First Flow
 
-## 2. DataHub - IN Node (Read Variables)
+Import this example flow to test both reading and writing:
 
-### Purpose
-Subscribe to variables from a Data Hub provider and output their values as JSON messages.
+```json
+[{"id":"cdad2fa96dc6eeec","type":"datahub-input","z":"c221537c994b056a","name":"","connection":"a0ba0e15c8dad779","providerId":"u_os_adm","manualVariables":"digital_nameplate.address_information.zipcode:2","triggerMode":"poll","pollingInterval":"100","x":110,"y":40,"wires":[["315d179d66bf9b93"]]},{"id":"315d179d66bf9b93","type":"debug","z":"c221537c994b056a","name":"debug 7","active":false,"tosidebar":true,"console":false,"tostatus":false,"complete":"false","statusVal":"","statusType":"auto","x":740,"y":40,"wires":[]},{"id":"09f29f6bfc4e1be2","type":"inject","z":"c221537c994b056a","name":"","props":[{"p":"payload"},{"p":"topic","vt":"str"}],"repeat":"","crontab":"","once":false,"onceDelay":0.1,"topic":"","payload":"","payloadType":"date","x":120,"y":140,"wires":[["43b2fcf73c370f7c"]]},{"id":"43b2fcf73c370f7c","type":"function","z":"c221537c994b056a","name":"Random Data","func":"function randomBetween(min, max) {\n    return Math.random() * (max - min) + min;\n}\n\nmsg.payload = {\n    machine: {\n        status: \"running\",\n        details: {\n            temp: randomBetween(30, 80)\n        }\n    }\n};\n\nreturn msg;","outputs":1,"timeout":0,"noerr":0,"initialize":"","finalize":"","libs":[],"x":300,"y":140,"wires":[["a90304487fe19b3a"]]},{"id":"a90304487fe19b3a","type":"datahub-output","z":"c221537c994b056a","name":"","connection":"a0ba0e15c8dad779","providerId":"","x":500,"y":140,"wires":[["e53fa58e4c1987ba"]]},{"id":"e53fa58e4c1987ba","type":"debug","z":"c221537c994b056a","name":"debug 6","active":false,"tosidebar":true,"console":false,"tostatus":false,"complete":"payload","targetType":"msg","statusVal":"","statusType":"auto","x":740,"y":140,"wires":[]},{"id":"a0ba0e15c8dad779","type":"uos-config","host":"127.0.0.1","port":49360,"clientName":"hub","scope":"hub.variables.provide hub.variables.readwrite hub.variables.readonly"}]
+```
 
-### Setup Steps
+**What this flow does:**
 
-#### Step 1: Select Config
-- Choose your **u-OS Config** node
+**Top Row** (Reading):
+- **DataHub - IN** reads `zipcode` variable from provider `u_os_adm`
+- Polls every 100ms
+- Outputs to Debug node
 
-#### Step 2: Enter Provider ID
-- **What is it?** The name of the data source (e.g., `u_os_sbm`, `hub`, `custom-provider`)
-- **Where to find it?**
-  - u-Control Web Interface → **Data Hub** → **Providers**
-  - Or use the Python sample's `PROVIDER_ID`
+**Bottom Row** (Writing):
+- **Inject** node triggers data generation
+- **Function** node creates random temperature data
+- **DataHub - OUT** publishes to Data Hub as provider `hub`
+- Creates variables: `machine.status` and `machine.details.temp`
 
-**Example:** `u_os_sbm`
+**To customize:**
+1. Edit the **DataHub - IN** node:
+   - Change `Provider ID` to match your system
+   - Update variable mappings in the table
+2. Edit the **Function** node to generate your data structure
+3. Click **Deploy**
 
-#### Step 3: Add Variables (Manual Table)
-Since auto-discovery often fails due to permissions, you **manually map** variable names to their IDs.
+---
 
-**How to find Variable IDs:**
+## Finding Variable IDs
 
-**Option A: From Python Config**
-```python
-# Your working Python config.py
-VARIABLE_DEFINITIONS = [
-    {"id": 0, "key": "manufacturer_name", ...},
-    {"id": 2, "key": "machine.details.temp", ...}
-]
-```
-→ Use these IDs!
+The **DataHub - IN** node requires variable IDs (numbers). Here's how to find them:
+
+### Option 1: u-OS Web Interface
+
+1. Open **Data Hub** → **Providers**
+2. Click on your target provider (e.g., `u_os_adm`)
+3. Click **Variables** tab
+4. Note the **ID** column (e.g., `0`, `1`, `2`)
 
-**Option B: From u-Control Web UI**
-1. Open **Data Hub** → **Providers** → Select your provider
-2. Click on **Variables**
-3. Note the **ID** column (usually 0, 1, 2, ...)
+### Option 2: REST API Query
 
-**Option C: From REST API**
 ```bash
 curl -H "Authorization: Bearer $TOKEN" \
-  http://192.168.10.100/datahub/v1/providers/u_os_sbm/variables
+  http://192.168.10.100/datahub/v1/providers/u_os_adm/variables
 ```
 
-**Fill the Table:**
+Response shows variable definitions with IDs:
+```json
+{
+  "variables": [
+    {"id": 0, "key": "manufacturer_name", ...},
+    {"id": 2, "key": "digital_nameplate.address_information.zipcode", ...}
+  ]
+}
+```
+
+### Option 3: Check Other Apps
+
+If you have other Data Hub clients (apps, PLCs), check their variable definitions to find the IDs.
+
+---
+
+## DataHub - IN Node (Read Variables)
+
+### Purpose
+Subscribe to variables from a Data Hub provider and output their values as JSON messages.
+
+### Configuration
+
+1. **Config Node:** Select your u-OS connection
+2. **Provider ID:** Enter the provider name (e.g., `u_os_adm`, `hub`, `u_os_sbm`)
+3. **Variables Table:** Manually map variable names to IDs
 
 | Variable Name | ID |
 |--------------|-----|
 | `manufacturer_name` | `0` |
-| `machine.details.temp` | `2` |
+| `zipcode` | `2` |
 
 Click **"Add Variable"** for each entry.
 
-#### Step 4: Choose Trigger Mode
-
-| Mode | When to Use |
-|------|-------------|
-| **Event (on change)** | Default. Efficient. Outputs only when values change. |
-| **Poll (interval)** | Forces periodic reads (e.g., every 1000ms). Less efficient. |
-
-#### Step 5: Deploy & Test
-1. Click **Deploy**
-2. Connect a **Debug** node to the output
-3. Send a message to the **Input Port** (using an **Inject** node) to trigger a read
-4. Check the Debug panel for output:
-   ```json
-   {
-     "type": "snapshot",
-     "variables": [
-       {"providerId": "u_os_sbm", "id": 0, "key": "manufacturer_name", "value": "Weidmüller", ...}
-     ]
-   }
-   ```
-
-### Troubleshooting
-
-| Problem | Solution |
-|---------|----------|
-| No output | Check: (1) Config deployed? (2) Provider ID correct? (3) Variable IDs correct? (4) Inject signal sent? |
-| "Variable not found" | Double-check IDs in the table. Use Python config or Web UI to verify. |
-| Permission errors | This is expected! That's why we use the manual table. |
+4. **Trigger Mode:**
+   - **Event (on change):** Efficient. Outputs only when values change.
+   - **Poll (interval):** Forces periodic reads (e.g., every 100ms).
+
+### Output Format
+
+```json
+{
+  "type": "snapshot",
+  "variables": [
+    {
+      "providerId": "u_os_adm",
+      "id": 2,
+      "key": "zipcode",
+      "value": "12345",
+      "quality": "GOOD",
+      "timestampNs": 1234567890000000000
+    }
+  ]
+}
+```
+
+### Triggering Reads
+
+Connect an **Inject** node to the input port to trigger manual reads.
 
 ---
 
-## 3. DataHub - OUT Node (Write Variables)
+## DataHub - OUT Node (Write Variables)
 
 ### Purpose
-**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**.
+Creates a real Data Hub provider that publishes variables. Other applications 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`)
+1. **Registers as a Provider** on the Data Hub (uses `Client Name` from Config)
 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
+4. **Answers read requests** from other consumers
+5. **Supports event-driven subscriptions** - other apps get updates **instantly**
 
-✅ **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  
+### Configuration
 
-### Setup Steps
+1. **Config Node:** Select your u-OS connection
+2. **Provider ID:** Leave **empty** to use `Client Name` (recommended)
 
-#### Step 1: Select Config
-- Choose your **u-OS Config** node
+### Send Data
 
-#### Step 2: Provider ID (Optional)
-- **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:
+Send JSON to the input:
 
 ```json
 {
@@ -255,66 +265,65 @@ Send a JSON object with your data:
 }
 ```
 
-This creates variables:
-- `temperature` → ID 0
-- `machine.status` → ID 1
-- `machine.speed` → ID 2
+This creates:
+- `temperature` → Variable ID 0
+- `machine.status` → Variable ID 1
+- `machine.speed` → Variable 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`)
+**Other apps can now:**
+- Subscribe to value changes (event-driven, instant updates)
+- Query current values (on-demand reads)
+- View in u-OS Web UI (**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)
+[Node-RED: DataHub - OUT] → [u-OS Data Hub (NATS)]
+                                      ↓
+                        ┌─────────────┼─────────────┐
+                        ↓             ↓             ↓
+                  [Other Apps]  [Dashboards]  [PLCs]
+                  (subscribe)   (subscribe)   (subscribe)
 ```
 
-**All subscribers receive the update IMMEDIATELY** - no polling needed!
-
-#### Step 4: Deploy & Test
-1. Connect a **Function** or **Inject** node
-2. Click **Deploy**
-3. Check the u-Control Web Interface → **Data Hub** → Your Provider
+**All subscribers receive updates IMMEDIATELY** - no polling needed!
 
 ---
 
-## Example Flow
+## Troubleshooting
 
-```
-[Inject] → [DataHub - IN] → [Debug]
-           (u_os_sbm)
+### No Output from IN Node
 
-[Inject: {"temp": 22}] → [DataHub - OUT]
-                         (nodered)
-```
+✓ Config node deployed?  
+✓ Provider ID correct? (check u-OS Web UI → Data Hub → Providers)  
+✓ Variable IDs correct? (check u-OS Web UI → Variables)  
+✓ Inject signal sent to input port?  
 
-**Copy this flow:**
-```json
-[{"id":"inject1","type":"inject","name":"Trigger Read"},
- {"id":"datahub-in","type":"datahub-input","connection":"config1","providerId":"u_os_sbm","manualVariables":"manufacturer_name:0"},
- {"id":"debug1","type":"debug"}]
-```
+### "Variable not found" Error
+
+- Double-check IDs in the Variables table
+- Verify IDs match those in u-OS Web UI
+
+### Connection Test Fails
+
+- Check Host/Port are correct and device is reachable
+- Verify Client ID/Secret match exactly
+- Ensure OAuth client exists in u-OS
+- Verify all `hub.variables.*` scopes are granted
+
+### Why Manual IDs?
+
+Auto-discovery requires special permissions on the provider definition endpoint, which are often restricted for security. The manual table works **without** this permission by querying specific IDs directly.
 
 ---
 
 ## FAQ
 
-### Q: Why manual IDs? Can't it auto-discover?
-**A:** Auto-discovery requires `hub.variables.readonly` permission on the **provider definition** endpoint, which is often restricted. The manual table works **without** this permission because it queries specific IDs directly.
+### Q: Can I use the provider created by OUT node in the IN node?
+**A:** **No, don't do this!** The OUT provider only exists while Node-RED runs. On restart, it disappears and the IN node fails. Read from **system providers** (`u_os_sbm`, `u_os_adm`) or other persistent apps instead.
 
 ### Q: Where do I get Client ID/Secret?
-**A:** u-Control Web Interface → **System** → **Access Control** → **OAuth Clients** → **Add Client**
+**A:** u-OS Web Interface → **System** → **Access Control** → **OAuth Clients** → **Add Client**
 
 ### Q: What are the required OAuth scopes?
 **A:** 
@@ -323,23 +332,17 @@ When you send a message to the OUT node:
 - **Recommended:** Select all `hub.variables.*` scopes when creating the client
 
 ### Q: Can I use this outside the local network?
-**A:** Yes, if your u-Control device is reachable over the network and you configure the correct Host/Port.
+**A:** Yes, if your u-OS device is reachable over the network and you configure the correct Host/Port.
 
 ### Q: Event vs Poll - which is better?
 **A:** **Event** (default) is more efficient. Use **Poll** only if you need guaranteed periodic readings regardless of value changes.
 
 ---
 
-## Changelog
-
-See [GitHub Releases](https://github.com/uiff/nats-NodeRed-Node-uc20/releases)
-
----
-
 ## Support
 
 **Issues, Questions, or Feature Requests:**  
-Contact [IoTUeli](https://www.linkedin.com/in/iotueli/) or open an issue on [GitHub](https://github.com/uiff/nats-NodeRed-Node-uc20)
+Contact [IoTUeli](https://iotueli.ch) or open an issue on [GitHub](https://github.com/uiff/nats-NodeRed-Node-uc20)
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-red-contrib-uos-nats",
-  "version": "0.1.65",
+  "version": "0.1.66",
   "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",