node-red-contrib-3dm-space 0.0.3 → 0.0.6

package/README.md

@@ -0,0 +1,139 @@
+# node-red-contrib-3dm-space
+
+Node-RED nodes for sending telemetry data to **3DM.space SCADA Cloud** and receiving cloud attribute commands.
+
+This package is designed for Smithtek PassPort gateways and provides simple 3DM Cloud communication without exposing MQTT details to the user.
+
+## Nodes Included
+
+### 3DM Cloud Login
+
+Shared configuration node used by the 3DM input and output nodes.
+
+The user only needs to enter:
+
+* Name
+* Username
+* Password
+* Optional Client ID
+
+Connection details are handled internally.
+
+### 3DM Out
+
+Sends JSON telemetry data to 3DM.space SCADA Cloud.
+
+The node automatically:
+
+* Adds a timestamp
+* Formats the payload for 3DM Cloud time-series data
+* Publishes to the correct cloud endpoint
+* Applies a publish rate limit
+* Stores messages locally if the cloud connection is offline
+* Replays stored messages when the connection returns
+
+Example input:
+
+```json
+{
+  "pump_run": true,
+  "flow_lpm": 125.5,
+  "tank_level_percent": 64,
+  "dc_voltage": 24.1
+}
+```
+
+### 3DM In
+
+Receives cloud attribute updates from 3DM.space.
+
+The node can:
+
+* Allow all incoming attributes through
+* Filter by a single key
+* Output the selected value only
+* Output an object containing the selected key and value
+
+Example cloud attribute:
+
+```json
+{
+  "pump_cmd": 1
+}
+```
+
+## Store and Forward
+
+The 3DM Out node includes built-in store and forward.
+
+If the cloud connection is lost, valid telemetry messages are stored locally using a persistent queue. Each message is timestamped when it arrives at the node, not when it is replayed.
+
+When the cloud connection returns, stored messages are replayed automatically.
+
+Default replay speed:
+
+```text
+250 ms per packet
+```
+
+This equals approximately:
+
+```text
+4 packets per second
+```
+
+## Rate Limiting
+
+The 3DM Out node includes a live publish throttle to prevent users from publishing too quickly.
+
+Default live publish limit:
+
+```text
+1 message every 10 seconds
+```
+
+If valid telemetry arrives faster than the live publish limit, it is queued rather than discarded.
+
+## Hidden Cloud Settings
+
+The following settings are handled internally and are not shown to the user:
+
+```text
+Host: 3dm.space
+Port: 1883
+Keepalive: 60
+Clean Session: true
+QoS: 1
+Telemetry Topic: v1/devices/me/telemetry
+Attributes Topic: v1/devices/me/attributes
+```
+
+## Installation
+
+From the Node-RED user directory:
+
+```bash
+cd ~/.node-red
+npm install ./node-red-contrib-3dm-space
+```
+
+Or from inside the development folder:
+
+```bash
+cd ~/.node-red/node-red-contrib-3dm-space
+npm install
+```
+
+Restart Node-RED after installation:
+
+```bash
+node-red-restart
+```
+
+## License
+
+GPL-3.0-or-later
+
+## Author
+
+Smithtek

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "node-red-contrib-3dm-space",
-  "version": "0.0.3",
+  "version": "0.0.6",
   "description": "Node-RED nodes for 3DM.space SCADA Cloud telemetry and attributes",
   "main": "3dm-cloud-config.js",
+  "license": "GPL-3.0-or-later",
   "keywords": [
     "node-red",
     "3dm",