node-red-contrib-3dm-space 0.0.8 → 1.0.2

package/README.md

@@ -1,104 +1,239 @@
 # node-red-contrib-3dm-space
 
-Node-RED nodes for sending telemetry data to **3DM.space SCADA Cloud** and receiving cloud attribute commands.
+Node-RED nodes for connecting Smithtek PassPort gateways to **3DM.space SCADA Cloud**.
 
-This package is designed for Smithtek PassPort gateways and provides simple 3DM Cloud communication without exposing MQTT details to the user.
+This package is designed to keep setup simple. Users copy the device details from 3DM.space into Node-RED, then use the nodes to send data, receive commands, store settings, and run local control logic.
 
 ## Nodes Included
 
 ### 3DM Cloud Login
 
-Shared configuration node used by the 3DM input and output nodes.
+Stores the 3DM.space device login used by the 3DM nodes.
 
-The user only needs to enter:
+The fields match the order shown in 3DM.space:
 
-* Name
-* Username
-* Password
-* Optional Client ID
+1. **Client ID**
+2. **User Name***
+3. **Password**
+4. **Node Name**
 
-Connection details are handled internally.
+**Node Name** is optional and is only used inside Node-RED to make the login easier to identify.
 
 ### 3DM Out
 
-Sends JSON telemetry data to 3DM.space SCADA Cloud.
+Sends telemetry from Node-RED to 3DM.space.
 
-The node automatically:
+Use this node when the PassPort needs to send live values such as:
 
-* 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
+- Tank level
+- Pump status
+- Flow rate
+- Pressure
+- Battery voltage
+- Fault status
+- Run hours
+- Totaliser values
 
-Example input:
+The node automatically prepares the data for 3DM.space.
 
-```json
-{
-  "pump_run": true,
-  "flow_lpm": 125.5,
-  "tank_level_percent": 64,
-  "dc_voltage": 24.1
-}
-```
+If the connection is unavailable, valid data is stored locally and sent later when the connection returns.
 
 ### 3DM In
 
-Receives cloud attribute updates from 3DM.space.
+Receives values sent from 3DM.space to the PassPort.
 
-The node can:
+Use this node when 3DM.space needs to send values down to Node-RED, such as:
 
-* Allow all incoming attributes through
-* Filter by a single key
-* Output the selected value only
-* Output an object containing the selected key and value
+- Pump commands
+- Mode changes
+- Reset commands
+- Setpoints
+- Scheduler updates
+- Control settings
+- Remote configuration values
 
-Example cloud attribute:
+The node can receive all values, or it can be filtered to only pass through one selected key.
 
-```json
-{
-  "pump_cmd": 1
-}
-```
+### 3DM Config Store
+
+Stores settings sent from 3DM.space and uses them locally on the PassPort.
+
+This node is normally placed after a **3DM In** node.
+
+3DM In → 3DM Config Store → Local Outputs
+
+Use this node for settings that need to be remembered and used by the PassPort, such as:
+
+- Pump schedules
+- Irrigation schedules
+- Start and stop levels
+- Pressure setpoints
+- Alarm settings
+- Control limits
+- Run time settings
+- Site configuration values
+
+The Config Store saves the latest settings locally.
+
+If Node-RED restarts, the last saved settings are loaded again automatically.
+
+The node has **24 outputs** that can be used for local control.
+
+## Basic Setup
+
+### 1. Create or Open a Device in 3DM.space
+
+Log in to **3DM.space**.
+
+Create a new device, or open the existing device you want the PassPort to connect to.
+
+Open the device credentials section.
+
+Copy these values:
+
+- Client ID
+- User Name*
+- Password
+
+### 2. Add a 3DM Cloud Login in Node-RED
+
+Open a **3DM Out** or **3DM In** node.
+
+Create a new **3DM Cloud Login**.
+
+Paste the values from 3DM.space into the matching fields.
+
+| 3DM.space | Node-RED |
+|---|---|
+| Client ID | Client ID |
+| User Name* | User Name* |
+| Password | Password |
+
+Give it a simple Node Name if needed, such as:
+
+Main PassPort
+
+### 3. Send Telemetry
+
+Add a **3DM Out** node.
+
+Select the **3DM Cloud Login**.
+
+Connect your live data into the node.
+
+The values will appear against the selected device in 3DM.space.
+
+### 4. Receive Commands
+
+Add a **3DM In** node.
+
+Select the same **3DM Cloud Login**.
+
+Leave **Attribute Key** blank to receive all incoming values.
+
+Enter an **Attribute Key** if you only want one value to pass through.
+
+For example, you may use a key such as:
+
+pump_cmd
+
+Only that value will then be passed through the node.
+
+### 5. Store Settings
+
+Add a **3DM Config Store** node after a **3DM In** node.
+
+Use this when settings from 3DM.space need to be saved on the PassPort.
+
+This is useful for:
+
+- Scheduler widgets
+- Setpoint widgets
+- Control widgets
+- Site setup widgets
+- Remote configuration screens
+
+The Config Store saves the settings locally and keeps using them even after a restart.
+
+### 6. Run Local Outputs
+
+The **3DM Config Store** node has 24 outputs.
+
+These outputs can be used to control local logic in Node-RED.
+
+Typical uses include:
+
+- Starting a pump on schedule
+- Stopping a pump on level
+- Running irrigation zones
+- Enabling or disabling control logic
+- Sending commands to a PLC
+- Triggering local relays or outputs
 
 ## Store and Forward
 
-The 3DM Out node includes built-in 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.
+If the cloud connection is unavailable, valid telemetry is stored locally on the gateway.
 
-When the cloud connection returns, stored messages are replayed automatically.
+When the connection returns, stored telemetry is sent automatically.
 
-Default replay speed:
+This helps prevent data loss during temporary connection outages.
 
-```text
-250 ms per packet
-```
+## Safe Sending Limits
 
-This equals approximately:
+The **3DM Out** node includes safe sending protection.
 
-```text
-4 packets per second
-```
+This helps prevent users from accidentally sending data too quickly.
 
-## Rate Limiting
+Stored data is handled automatically when the connection returns.
 
-The 3DM Out node includes a live publish throttle to prevent users from publishing too quickly.
+## Typical Flows
 
-Default live publish limit:
+Sending telemetry:
 
-```text
-1 message every 10 seconds
-```
+Sensor / PLC Data
+        ↓
+Function Node
+        ↓
+3DM Out
+        ↓
+3DM.space
 
-If valid telemetry arrives faster than the live publish limit, it is queued rather than discarded.
+Receiving commands:
 
+3DM.space
+        ↓
+3DM In
+        ↓
+Function Node
+        ↓
+PLC / Output Logic
 
-## License
+Receiving saved settings:
 
-GPL-3.0-or-later
+3DM.space
+        ↓
+3DM In
+        ↓
+3DM Config Store
+        ↓
+24 Local Outputs
+
+## Notes
+
+- Use **3DM Out** to send live data to 3DM.space.
+- Use **3DM In** to receive commands and settings from 3DM.space.
+- Use **3DM Config Store** to save settings and run local control logic.
+- Device credentials should be copied directly from 3DM.space.
+- Node Name fields are optional and are only used inside Node-RED.
+- Store and forward is handled automatically.
+- Saved settings are stored locally on the PassPort.
 
 ## Author
 
 Smithtek
+
+## License
+
+GPL-3.0-or-later

package/package.json

@@ -1,26 +1,33 @@
 {
   "name": "node-red-contrib-3dm-space",
-  "version": "0.0.8",
-  "description": "Node-RED nodes for 3DM.space SCADA Cloud telemetry and attributes",
+  "version": "1.0.2",
+  "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",
   "keywords": [
     "node-red",
+    "node-red-contrib",
     "3dm",
     "3dm.space",
+    "smithtek",
     "scada",
     "telemetry",
-    "store-and-forward"
+    "store-and-forward",
+    "config-store",
+    "scheduler"
   ],
   "node-red": {
     "nodes": {
       "3dm-cloud-config": "3dm-cloud-config.js",
       "3dm-cloud-out": "3dm-cloud-out.js",
-      "3dm-cloud-in": "3dm-cloud-in.js"
+      "3dm-cloud-in": "3dm-cloud-in.js",
+      "3dm-config-store": "3dm-config-store.js"
     }
   },
   "dependencies": {
-    "mqtt": "~4.3.7",
+    "mqtt": "~4.3.7"
+  },
+  "optionalDependencies": {
     "node-persistent-queue": "^0.3.1"
   }
 }