node-red-contrib-3dm-space 2.1.0 → 2.2.0

package/README.md

@@ -1,5 +1,18 @@
 
+
+
+
+
+
+
 ![This is an alt text.](https://github.com/smithtekIOT/ArtWork/blob/master/3dm%20github.png?raw=true")
+
+
+
+
+
+
+
 # node-red-contrib-3dm-space
 
 Node-RED nodes for connecting Smithtek PassPort gateways to **3DM.space SCADA Cloud**.
@@ -46,7 +59,9 @@ This package includes four nodes:
 - **3DM Out**
 - **3DM In**
 - **3DM Config Store**
-![This is an alt text.](https://github.com/smithtekIOT/ArtWork/blob/master/3dm%20nodes.jpg?raw=true")
+- **3DM Join**
+
+![This is an alt text.](https://github.com/smithtekIOT/ArtWork/blob/master/3dm%204%20nodes.jpg?raw=true)
 
 ---
 
@@ -1343,8 +1358,231 @@ output2 skipped - output disabled
 
 Increase Active Outputs or change the item to `output1`.
 
+---
+---
+
+# 3DM Join
+![This is an alt text.](https://github.com/smithtekIOT/ArtWork/blob/master/3DM%20join%20nodes.jpg?raw=true)
+The **3DM Join** node collects multiple JSON payloads, merges them into one payload, then sends one combined message after a configurable timeout.
+
+It is useful when data arrives from multiple sources at slightly different times, but the user wants one clean telemetry update sent to 3DM.space.
+
+Typical use:
+
+```text
+Mako RF Station 1
+Mako RF Station 2
+Mako RF Station 3
+        ↓
+3DM Join
+        ↓
+3DM Out
+        ↓
+3DM.space
+```
+
+---
+
+## Why Use 3DM Join
+
+The 3DM Join node simplifies flows where telemetry is collected from more than one source.
+
+Instead of sending each small payload separately to 3DM.space, the Join node can collect the values first and send them as one larger JSON object.
+
+This is ideal for RF systems where each remote station may respond a few seconds apart, but the user is happy with one complete site update every minute.
+
+Example:
+
+```text
+Bore 1 data arrives
+Bore 2 data arrives
+Tank data arrives
+Weather data arrives
+        ↓
+3DM Join waits for the timeout
+        ↓
+One combined payload is sent to 3DM Out
+```
+
+---
+
+## Input Data Type
+
+The 3DM Join node expects `msg.payload` to be a JSON object.
+
+Correct:
+
+```json
+{
+  "b1 dc": 24.3
+}
+```
+
+Correct:
+
+```json
+{
+  "b2 flow": 88.5
+}
+```
+
+Incorrect:
+
+```json
+24.3
+```
+
+Incorrect:
+
+```text
+b1 dc
+```
+
+Invalid payloads are ignored.
+
+---
+
+## Timeout
+
+The timeout starts when the first valid message arrives.
+
+The timer does not restart when more messages arrive.
+
+Example:
+
+```text
+Timeout: 10 seconds
+```
+
+If the first message arrives at 12:00:00, the joined output is sent at 12:00:10.
+
+Any valid JSON payloads received during that 10 second window are merged together.
+
 ---
 
+## Duplicate Keys
+
+If the same key arrives more than once during the timeout window, the latest value is used.
+
+Example:
+
+```json
+{
+  "b1 dc": 24.1
+}
+```
+
+then:
+
+```json
+{
+  "b1 dc": 24.4
+}
+```
+
+Final joined output:
+
+```json
+{
+  "b1 dc": 24.4
+}
+```
+
+---
+
+## Example Joined Output
+
+Incoming message 1:
+
+```json
+{
+  "b1 dc": 24.3,
+  "b1 fb": 1
+}
+```
+
+Incoming message 2:
+
+```json
+{
+  "b2 dc": 24.1,
+  "b2 fb": 0
+}
+```
+
+Incoming message 3:
+
+```json
+{
+  "tank level": 76.5
+}
+```
+
+Output after timeout:
+
+```json
+{
+  "b1 dc": 24.3,
+  "b1 fb": 1,
+  "b2 dc": 24.1,
+  "b2 fb": 0,
+  "tank level": 76.5
+}
+```
+
+---
+
+## Recommended Use With 3DM Out
+
+The 3DM Join node is normally placed before the **3DM Out** node.
+
+```text
+RF / PLC / Sensor Inputs
+        ↓
+3DM Join
+        ↓
+3DM Out
+```
+
+This keeps telemetry updates cleaner and helps reduce the number of separate cloud messages.
+
+For example, an RF system may poll several stations over 30 to 45 seconds, then send one complete site update to 3DM.space every minute.
+
+---
+
+## 3DM Join Status Messages
+
+### waiting
+
+The node is waiting for the first valid JSON payload.
+
+### collecting
+
+The node has received at least one valid payload and is collecting keys until the timeout expires.
+
+### sent
+
+The timeout expired and the combined payload was sent.
+
+### bad payload
+
+The incoming `msg.payload` was not a JSON object.
+
+Check the payload going into the 3DM Join node.
+
+---
+
+## Notes
+
+- Use 3DM Join to combine multiple telemetry payloads before 3DM Out.
+- The timeout starts from the first valid message.
+- The timer does not reset when more messages arrive.
+- Payloads must be JSON objects.
+- Duplicate keys are overwritten by the latest value.
+- The output is one combined `msg.payload` object.
+- This is useful for RF polling systems, multi-device sites, PLC data blocks and grouped telemetry updates.
+
+---
 # 3DM SCADA Canvas Smart Control Integration
 
 ![This is an alt text.](https://github.com/smithtekIOT/ArtWork/blob/master/Canvas%20SCADA%203dm.jpg?raw=true)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-red-contrib-3dm-space",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Node-RED nodes for 3DM.space SCADA Cloud telemetry, attributes, and local config storage",
   "main": "3dm-cloud-config.js",
   "license": "GPL-3.0-or-later",