node-red-contrib-3dm-space 1.0.0 → 1.0.3

package/README.md

@@ -2,52 +2,238 @@
 
 Node-RED nodes for connecting Smithtek PassPort gateways to **3DM.space SCADA Cloud**.
 
-This package is designed to make 3DM.space cloud communication simple for users. The cloud connection, formatting, timing, storage and recovery handling are managed inside the nodes.
-
-Users only need to copy the device credentials from 3DM.space into Node-RED.
-
----
-
-## What This Package Does
-
-This package allows a PassPort gateway to:
-
-- Send telemetry values to 3DM.space
-- Receive cloud commands or control updates from 3DM.space
-- Store telemetry locally if the cloud connection is unavailable
-- Automatically send stored telemetry when the connection returns
-
----
+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
 
-The shared login node used by the 3DM input and output nodes.
+Stores the 3DM.space device login used by the 3DM nodes.
 
-The settings match the credential order shown in 3DM.space:
+The fields match the order shown in 3DM.space:
 
 1. **Client ID**
 2. **User Name***
 3. **Password**
 4. **Node Name**
 
-The **Node Name** is only used inside Node-RED to make the login easier to identify.
-
----
+**Node Name** is optional and is only used inside Node-RED to make the login easier to identify.
 
 ### 3DM Out
 
-Sends telemetry data from Node-RED to 3DM.space.
+Sends telemetry from Node-RED to 3DM.space.
+
+Use this node when the PassPort needs to send live values such as:
+
+- Tank level
+- Pump status
+- Flow rate
+- Pressure
+- Battery voltage
+- Fault status
+- Run hours
+- Totaliser values
+
+The node automatically prepares the data for 3DM.space.
+
+If the connection is unavailable, valid data is stored locally and sent later when the connection returns.
+
+### 3DM In
+
+Receives values sent from 3DM.space to the PassPort.
+
+Use this node when 3DM.space needs to send values down to Node-RED, such as:
+
+- Pump commands
+- Mode changes
+- Reset commands
+- Setpoints
+- Scheduler updates
+- Control settings
+- Remote configuration values
+
+The node can receive all values, or it can be filtered to only pass through one selected key.
+
+### 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. You can turn outputs not used to minimize the node size saving flow editor space.
+
+## 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. You can turn outputs not used off,  the outputs will align with the 3DM scada canvas node and other schedule and control nodes that have reference to 24 outputs.
+
+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.
+
+If the cloud connection is unavailable, valid telemetry is stored locally on the gateway.
+
+When the connection returns, stored telemetry is sent automatically.
+
+This helps prevent data loss during temporary connection outages.
+
+## Safe Sending Limits
+
+The **3DM Out** node includes safe sending protection.
+
+This helps prevent users from accidentally sending data too quickly.
+
+Stored data is handled automatically when the connection returns.
+
+## Typical Flows
+
+Sending telemetry:
+
+Sensor / PLC Data
+        ↓
+Function Node
+        ↓
+3DM Out
+        ↓
+3DM.space
+
+Receiving commands:
+
+3DM.space
+        ↓
+3DM In
+        ↓
+Function Node
+        ↓
+PLC / Output Logic
+
+Receiving saved settings:
+
+3DM.space
+        ↓
+3DM In
+        ↓
+3DM Config Store
+        ↓
+24 Local Outputs
+
+## Notes
+
+- Use **3DM Out** to send live data to 3DM.space. This can be read on 3DM devices via "Latest telemetry" under the device properties
+- Use **3DM In** to receive commands and settings from 3DM.space. Data can be sent from 3DM.space to the PassPort via "Attributes" under the device properties 
+- 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
 
-The input must be a JSON object.
+Smithtek
 
-Example:
+## License
 
-```json
-{
-  "pump_run": true,
-  "flow_lpm": 125.5,
-  "tank_level_percent": 64,
-  "dc_voltage": 24.1
-}
+GPL-3.0-or-later

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "node-red-contrib-3dm-space",
-  "version": "1.0.0",
-  "description": "Node-RED nodes for 3DM.space SCADA Cloud telemetry and attributes",
+  "version": "1.0.3",
+  "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": [
@@ -12,13 +12,16 @@
     "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": {
@@ -27,4 +30,4 @@
   "optionalDependencies": {
     "node-persistent-queue": "^0.3.1"
   }
-}
+}