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

package/README.md

@@ -1,27 +1,147 @@
+
+![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**.
 
-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.
+This package is designed to keep setup simple. A user copies the device credentials from 3DM.space into Node-RED, then uses the nodes to send telemetry, receive commands, store settings, and run local control logic on the PassPort.
 
-## Nodes Included
+The package is intended for Smithtek PassPort gateway projects using 3DM.space, Mako RF nodes, PLCs, sensors, relays, pump controllers, irrigation systems, water treatment systems, remote telemetry sites and SCADA control applications.
+
+---
+
+## Requirements
 
-### 3DM Cloud Login
+To use these nodes, you need:
 
-Stores the 3DM.space device login used by the 3DM nodes.
+- A current 3DM.space account
+- An active PassPort device created in 3DM.space
+- Device credentials copied from the PassPort device page
+- Node-RED running on the PassPort or gateway
+- A working internet connection when sending or receiving live cloud data
 
-The fields match the order shown in 3DM.space:
+To connect the 3DM nodes to your 3DM.space account:
+
+1. Log in to **3DM.space**
+2. Open the required PassPort device
+3. Open the device credentials section
+4. Copy the credentials into the **3DM Cloud Login** node in Node-RED
+
+The credentials are copied from 3DM.space into Node-RED in this order:
 
 1. **Client ID**
 2. **User Name***
 3. **Password**
 4. **Node Name**
 
-**Node Name** is optional and is only used inside Node-RED to make the login easier to identify.
 
-### 3DM Out
+![This is an alt text.](https://github.com/smithtekIOT/ArtWork/blob/master/3dm%20Creds.png?raw=true")
+---
+
+## Nodes Included
+
+This package includes four nodes:
+
+- **3DM Cloud Login**
+- **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 Cloud Login
+
+The **3DM Cloud login** node stores the 3DM.space device login used by the 3DM nodes.
+
+This is a configuration node. It does not appear as a wired node in the flow by itself. It is selected inside the **3DM Out** and **3DM In** nodes.
+
+---
+
+## 3DM Cloud Login Fields
+
+### Client ID
+
+The Client ID from the PassPort device credentials in 3DM.space.
+
+Only enter this if 3DM.space provides one for the device, you can auto create one or create your own!.
+
+### User Name*
+
+The device username from 3DM.space.
+
+This field is required,you can auto create one or create your own!..
+
+### Password
+
+The device password from 3DM.space,you can auto create one or create your own!.
+
+After deploy, Node-RED may show the password field as blank. This is normal for password fields. The password is secured and stored internally.
+
+### Node Name
+
+Optional.
+
+This is only used inside Node-RED to make the login easier to identify.
+
+Example:
+
+```text
+Main PassPort
+```
+
+---
+
+## What 3DM Cloud Login Does
+
+The 3DM Cloud Login node:
+
+- Stores the device credentials
+- Creates the cloud connection used by 3DM In and 3DM Out
+- Allows multiple 3DM nodes to use the same login
+- Handles reconnecting after a connection drop
+- Shares connection state with the 3DM In and 3DM Out nodes
+
+---
+
+## 3DM Cloud Login Common Problems
+
+### Password looks blank after deploy
+
+This can be normal.
+
+Node-RED often hides password values after deploy.
+
+Check whether the 3DM In or 3DM Out node still connects.
+
+### Login rejected
+
+Check:
+
+- Client ID
+- User Name*
+- Password
+- The correct PassPort device was selected in 3DM.space
+- Check the passport exisits in 3DM.space
+- No extra spaces were copied into the fields
+
+### Node stays offline
+
+Check:
+
+- Internet connection
+- Device credentials
+- 3DM.space device is active
+- The correct 3DM Cloud Login is selected in the 3DM In or 3DM Out node
+- The PassPort is powered
+- If it is spcific RF data thats offline, check the RF antennas are OK.
+---
+
+# 3DM Out
+
+![This is an alt text.](https://github.com/smithtekIOT/ArtWork/blob/master/3dm%20out%20node.jpg?raw=true")
 
-Sends telemetry from Node-RED to 3DM.space.
+The **3DM Out** node sends telemetry from Node-RED to 3DM.space.
 
 Use this node when the PassPort needs to send live values such as:
 
@@ -33,14 +153,245 @@ Use this node when the PassPort needs to send live values such as:
 - Fault status
 - Run hours
 - Totaliser values
+- PLC values
+- Mako RF node values
+- Site data
 
 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.
+If the cloud connection is unavailable, valid data is stored locally and sent later when the connection returns.
+
+---
+
+## 3DM Out Input Data Type
+
+The 3DM Out node expects `msg.payload` to be a JSON object.
+
+Correct:
+
+```json
+{
+  "tank_level": 65.2,
+  "pump_run": true,
+  "dc_voltage": 24.4
+}
+```
+
+Incorrect:
+
+```json
+65.2
+```
+
+Incorrect:
+
+```text
+pump_run
+```
+
+Incorrect:
+
+```json
+[
+  1,
+  2,
+  3
+]
+```
+
+The payload must be an object containing key/value pairs.
+
+
+---
+
+## Recommended Mako RF Payload
+
+The Mako RF node should normally pass a flat JSON object into the 3DM Out node.
+
+Example:
+
+```json
+{
+  "cl level": 672.06,
+  "cl ppm": 1.2,
+  "cl dc": 24.46,
+  "ty et level": 1607.38,
+  "ty lph": 0,
+  "ty l1": 239.85,
+  "ty l2": 237.95,
+  "ty l3": 241.25,
+  "ty i1": 0.09,
+  "ty i2": 0.09,
+  "ty i3": 0.10,
+  "ty kwh": 0.003,
+  "ty totalizer": 25,
+  "cl fault": false,
+  "cl p1": false,
+  "cl p2": false
+}
+```
+
+This format is ideal because each key becomes a usable telemetry key in 3DM.space.
+-It is important that each asset has a different key name, if you have multiple of the same asset, for example 3 bore pumpinh station, use a prefix like "b1 flowrate"   then for the next bore "b2 flow rate", this ensures the data telemetry doesnt cancel over overide each other and it ensures you can find your data telemetry keys when building and designing dashbaords.
+
+---
+
+## Supported Value Types
+
+The 3DM Out node can send values such as:
+
+```json
+{
+  "level": 1234.5,
+  "pump_run": true,
+  "mode": "AUTO",
+  "fault_code": 0
+}
+```
+
+Supported values:
+
+- Number
+- Boolean
+- String
+
+Avoid sending large nested objects unless they are needed.
+
+---
+
+## 3DM Out Sending Speed Limit
+
+The 3DM Out node includes safe sending protection.
+
+Live telemetry should be sent no faster than:
+
+```text
+1 message every 60 seconds.
+```
+
+This helps prevent accidental flooding from fast inject nodes, loops, or badly configured flows.
+
+Example safe setup:
+
+```text
+Inject / PLC / Mako RF
+        ↓
+Function Node
+        ↓
+3DM Out
+```
+
+Use an inject, polling, or scheduler rate of 60 seconds or slower.
+
+---
+
+## 3DM Out Store and Forward
+
+The 3DM Out node includes built-in store and forward.
+
+If the connection to 3DM.space 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.
+
+Store and forward is useful for:
+
+- 4G dropouts
+- Remote site outages
+- Satellite connection gaps
+- Router restarts
+- Temporary 3DM.space connection loss
+- Poor signal sites
+
+Stored data keeps the timestamp from when it arrived at the 3DM Out node.
+
+---
+
+## Live Data vs Stored Data
+
+Live data is protected by the 60 second sending limit.
+
+Stored data is handled separately.
+
+When the connection returns, stored messages may be sent faster than the normal live limit so the gateway can catch up.
+
+This means:
+
+```text
+Live telemetry        = protected by speed limit
+Stored telemetry replay = handled automatically
+```
+
+---
+
+## 3DM Out Status Messages
+
+The 3DM Out node shows a status under the node in Node-RED.
+
+### connected
+
+The node is connected to 3DM.space and ready to send telemetry.
+
+### sent
+
+The latest telemetry message was sent successfully.
+
+### storing offline
+
+The node is not connected to 3DM.space, so valid telemetry is being stored locally.
+
+This usually means:
+
+- No internet connection
+- 3DM.space connection is unavailable
+- Credentials are wrong
+- The cloud login has not connected yet
+
+### queued
+
+The message has been placed in the local queue.
+
+This can happen when stored messages are being processed or when the node needs to preserve message order.
+
+### backhauling
+
+The connection has returned and the node is sending stored data from the local queue.
+
+### queue high
+
+The local queue has a large number of stored messages.
+
+This may happen after a long outage or if data is being sent too fast.
 
-### 3DM In
+### bad payload
 
-Receives values sent from 3DM.space to the PassPort.
+The incoming `msg.payload` was not a valid JSON object.
+
+Check the data going into the 3DM Out node.
+
+### rate limited
+
+The live payloads are arriving too quickly.
+
+Slow the input down to 60 seconds or slower.
+
+### store/forward unavailable
+
+The store and forward queue could not open.
+
+Live sending may still work, but offline storage may not.
+
+Check the Node-RED log.
+
+---
+
+# 3DM In
+
+![This is an alt text.](https://github.com/smithtekIOT/ArtWork/blob/master/3dm%20in%20node.jpg?raw=true")
+
+The **3DM In** node receives values sent from 3DM.space to the PassPort.
+The data is sent using `"Attributes"` in 3DM.space, you can create attributes in the chosen device or manually add them when building dashboards.
 
 Use this node when 3DM.space needs to send values down to Node-RED, such as:
 
@@ -51,16 +402,201 @@ Use this node when 3DM.space needs to send values down to Node-RED, such as:
 - Scheduler updates
 - Control settings
 - Remote configuration values
+- SCADA button commands
+- Config Store updates
+
+---
+
+## 3DM In Typical Uses
+
+### Simple command
+
+Widgets will automatically send the commands in simlar data formats to 3DM.space sends:
+
+```json
+{
+  "pump_cmd": 1
+}
+```
+Or
+```json
+{
+  "setpoint": 1225
+}
+```
+
+Node-RED receives the command and then it can be forward sent to a PLC, relay, function node, or Mako RF node, or any other node in NodeRED.
+
+### Setpoint command
+
+3DM.space sends:
+
+```json
+{
+  "start_level": 40,
+  "stop_level": 90
+}
+```
+
+Node-RED receives the values and uses them in local logic. It could be for high and low tank level pump start top logic.
+
+### Config Store command
+
+3DM.space sends:
+
+```json
+{
+  "configStore": {
+    "b1": {
+      "type": "scheduler",
+      "data": []
+    }
+  }
+}
+```
+
+Node-RED passes the config into the 3DM Config Store node. This data is sent to the PassPort to be used for schedules, smar logic if the coms goes down. More details mentioned below
+
+---
+
+## 3DM In Attribute Key Field
+
+The 3DM In node can receive all incoming values, or it can filter for one selected key.
+
+---
+
+### Leave Attribute Key Blank
+
+Use this when you want all incoming values to pass through.
+
+Recommended when feeding the 3DM Config Store node.
+
+Example:
+
+```text
+Attribute Key: blank
+```
+
+Flow:
+
+```text
+3DM In
+    ↓
+3DM Config Store
+```
+
+This allows the full incoming config to reach the Config Store node.
+
+---
+
+### Enter an Attribute Key
+
+Use this when you only want one value to pass through.
+
+Example:
+
+```text
+Attribute Key: pump_cmd
+```
+
+If 3DM.space sends:
+
+```json
+{
+  "pump_cmd": 1,
+  "other_value": 55
+}
+```
+
+only `pump_cmd` is passed through.
+
+---
+
+## 3DM In Modes
+
+The 3DM In node is normally used in one of two ways.
+
+---
+
+### All Values Mode
+
+Leave the Attribute Key blank.
+
+Use this for:
+
+- Config Store
+- Scheduler updates
+- Smart control settings
+- Multiple setpoints
+- Receiving several cloud values at once
+
+---
+
+### Single Key Mode
+
+Enter one Attribute Key.
+
+Use this for:
+
+- One pump command
+- One reset command
+- One setpoint
+- One mode command
+- One control value
+
+---
+
+## 3DM In Status Messages
 
-The node can receive all values, or it can be filtered to only pass through one selected key.
+### connected
 
-### 3DM Config Store
+The node is connected and listening for values from 3DM.space.
 
-Stores settings sent from 3DM.space and uses them locally on the PassPort.
+### waiting
+
+The node is waiting for the 3DM Cloud Login connection.
+
+### connecting
+
+The node is waiting for the cloud connection to become available.
+
+### received
+
+The node received a value from 3DM.space.
+
+### filtered
+
+The node received data, but it did not match the selected Attribute Key.
+
+### offline
+
+The selected 3DM Cloud Login is not connected.
+
+Check:
+
+- Internet connection
+- Device credentials
+- 3DM Cloud Login node
+- 3DM.space device credentials
+
+---
+
+# 3DM Config Store
+
+
+![This is an alt text.](https://github.com/smithtekIOT/ArtWork/blob/master/3dm%20config%20store%20node.jpg?raw=true")
+
+The **3DM Config Store** node 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
+```text
+3DM In
+    ↓
+3DM Config Store
+    ↓
+Local Outputs
+```
 
 Use this node for settings that need to be remembered and used by the PassPort, such as:
 
@@ -72,168 +608,1764 @@ Use this node for settings that need to be remembered and used by the PassPort,
 - Control limits
 - Run time settings
 - Site configuration values
+- SCADA Canvas smart controls
 
 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
+## 3DM Config Store Active Outputs
 
-### 1. Create or Open a Device in 3DM.space
+The 3DM Config Store node supports up to 24 outputs.
 
-Log in to **3DM.space**.
+You can select how many outputs are active.
 
-Create a new device, or open the existing device you want the PassPort to connect to.
+Example:
 
-Open the device credentials section.
+```text
+Active Outputs: 1
+```
 
-Copy these values:
+Only output 1 is visible.
 
-- Client ID
-- User Name*
-- Password
+Example:
 
-### 2. Add a 3DM Cloud Login in Node-RED
+```text
+Active Outputs: 8
+```
 
-Open a **3DM Out** or **3DM In** node.
+Outputs 1 to 8 are visible.
 
-Create a new **3DM Cloud Login**.
+Example:
 
-Paste the values from 3DM.space into the matching fields.
+```text
+Active Outputs: 24
+```
 
-| 3DM.space | Node-RED |
-|---|---|
-| Client ID | Client ID |
-| User Name* | User Name* |
-| Password | Password |
+All 24 outputs are visible.
 
-Give it a simple Node Name if needed, such as:
+This keeps the Node-RED flow cleaner when only a few outputs are needed.
 
-Main PassPort
+---
 
-### 3. Send Telemetry
+## 3DM Config Store Output Names
 
-Add a **3DM Out** node.
+Config Store items use output names such as:
 
-Select the **3DM Cloud Login**.
+```text
+output1
+output2
+output3
+```
 
-Connect your live data into the node.
+The output name must match the output number.
 
-The values will appear against the selected device in 3DM.space.
+Example:
 
-### 4. Receive Commands
+```json
+{
+  "output": "output1"
+}
+```
 
-Add a **3DM In** node.
+This sends to output 1.
 
-Select the same **3DM Cloud Login**.
+Example:
 
-Leave **Attribute Key** blank to receive all incoming values.
+```json
+{
+  "output": "output5"
+}
+```
 
-Enter an **Attribute Key** if you only want one value to pass through.
+This sends to output 5.
 
-For example, you may use a key such as:
+If an item uses an output higher than the active output count, that item is skipped.
 
-pump_cmd
+Example:
 
-Only that value will then be passed through the node.
+```text
+Active Outputs: 1
+Item output: output2
+Result: skipped - output disabled
+```
 
-### 5. Store Settings
+---
 
-Add a **3DM Config Store** node after a **3DM In** node.
+## 3DM Config Store Config Name
 
-Use this when settings from 3DM.space need to be saved on the PassPort.
+The Config Name field controls which config block the node uses.
 
-This is useful for:
+---
 
-- Scheduler widgets
-- Setpoint widgets
-- Control widgets
-- Site setup widgets
-- Remote configuration screens
+### Blank Config Name
 
-The Config Store saves the settings locally and keeps using them even after a restart.
+Leave Config Name blank to accept all config blocks.
 
-### 6. Run Local Outputs
+Example:
 
-The **3DM Config Store** node has 24 outputs.
+```text
+Config Name: blank
+```
 
-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.
+This accepts:
 
-Typical uses include:
+```json
+{
+  "b1": {},
+  "b2": {},
+  "mainScheduler": {}
+}
+```
 
-- 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
+### Named Config
 
-The **3DM Out** node includes built-in store and forward.
+Enter a name to only accept one config block.
 
-If the cloud connection is unavailable, valid telemetry is stored locally on the gateway.
+Example:
 
-When the connection returns, stored telemetry is sent automatically.
+```text
+Config Name: b1
+```
 
-This helps prevent data loss during temporary connection outages.
+This node only uses:
 
-## Safe Sending Limits
+```json
+{
+  "b1": {}
+}
+```
 
-The **3DM Out** node includes safe sending protection.
+and ignores:
 
-This helps prevent users from accidentally sending data too quickly.
+```json
+{
+  "b2": {}
+}
+```
 
-Stored data is handled automatically when the connection returns.
+This is useful when using multiple Config Store nodes.
 
-## Typical Flows
+Example:
 
-Sending telemetry:
+```text
+Config Store node 1
+Config Name: b1
+Active Outputs: 1
 
-Sensor / PLC Data
-        ↓
-Function Node
-        ↓
-3DM Out
-        ↓
-3DM.space
+Config Store node 2
+Config Name: b2
+Active Outputs: 1
+```
 
-Receiving commands:
+Both nodes can receive the same incoming `configStore`, but each node only acts on its own config name.
 
-3DM.space
-        ↓
-3DM In
-        ↓
-Function Node
-        ↓
-PLC / Output Logic
+---
 
-Receiving saved settings:
+## 3DM Config Store Format
 
-3DM.space
-        ↓
-3DM In
-        ↓
-3DM Config Store
-        ↓
-24 Local Outputs
+The Config Store expects a main `configStore` object.
 
-## Notes
+Inside `configStore`, each block has its own name.
 
-- 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.
+Example:
 
-## Author
+```json
+{
+  "configStore": {
+    "b1": {
+      "type": "scheduler",
+      "data": [
+        {
+          "id": "b1_control",
+          "output": "output1",
+          "name": "Bore Pump 1",
+          "controlType": "control",
+          "mode": "AUTO",
+          "variable": "tank_level",
+          "lowSetpoint": 40,
+          "highSetpoint": 90,
+          "direction": "in"
+        }
+      ]
+    },
+    "b2": {
+      "type": "scheduler",
+      "data": [
+        {
+          "id": "b2_control",
+          "output": "output1",
+          "name": "Bore Pump 2",
+          "controlType": "control",
+          "mode": "AUTO",
+          "variable": "tank_level",
+          "lowSetpoint": 40,
+          "highSetpoint": 90,
+          "direction": "in"
+        }
+      ]
+    }
+  }
+}
+```
 
-Smithtek
+---
+
+## 3DM Config Store Check Every
+
+This sets how often the Config Store checks its local logic.
+
+Example:
+
+```text
+Check Every: 20 seconds
+```
+
+The node checks the saved schedules and controls every 20 seconds.
+
+Allowed range:
+
+```text
+1 to 60 seconds
+```
+
+---
+
+## 3DM Config Store Output Mode
+
+The Config Store has two output modes.
+
+---
+
+### Only When Output Changes
+
+This only sends an output when the final output state changes.
+
+Example:
+
+```text
+Output was false
+Tank drops below low start
+Output becomes true
+Node sends true once
+```
+
+This is normally the best mode for real equipment, or can be used to optimize and reduce RF transmissions.
+
+---
+
+### Every Check
+
+This sends the current output state every check interval.
+
+Example:
+
+```text
+Check Every: 20 seconds
+Output Mode: Every check
+```
+
+The node sends the output state every 20 seconds.
+
+Use this when downstream logic needs repeated true/false messages.
+
+---
+
+## 3DM Config Store Config Output
+
+Config Output is optional.
+
+It sends the stored config out of one selected output.
+
+Normal use:
+
+```text
+Config Output: Disabled
+```
+
+Debug use:
+
+```text
+Config Output: Output 24
+```
+
+This can be useful when testing what the Config Store has saved.
+
+Do not use the same output for control and Config Output at the same time.
+
+---
+
+## 3DM Config Store Send Config
+
+When enabled, the node sends the stored config when it is updated.
+
+This is mainly useful for debugging or passing the saved config to another part of the flow.
+
+Normal use:
+
+```text
+Send Config: off
+```
+
+---
+
+# Config Store Control Modes
+
+The Config Store supports local control logic.
+
+The most common control modes are:
+
+- ON
+- OFF
+- AUTO
+
+---
+
+## ON Mode
+
+ON forces the output on.
+
+Example:
+
+```json
+{
+  "mode": "ON"
+}
+```
+
+Result:
+
+```text
+Output = true
+```
+
+---
+
+## OFF Mode
+
+OFF forces the output off.
+
+Example:
+
+```json
+{
+  "mode": "OFF"
+}
+```
+
+Result:
+
+```text
+Output = false
+```
+
+---
+
+## AUTO Mode
+
+AUTO uses a live input value and setpoints.
+
+Example:
+
+```json
+{
+  "mode": "AUTO",
+  "variable": "tank_level",
+  "lowSetpoint": 40,
+  "highSetpoint": 90,
+  "direction": "in"
+}
+```
+
+The node watches:
+
+```text
+tank_level
+```
+
+and compares it to:
+
+```text
+Low Start: 40
+High Stop: 90
+```
+
+---
+
+## Pump In / Fill Direction
+
+Use `direction: "in"` for filling.
+
+Logic:
+
+```text
+Value <= Low Start  → Output ON
+Value >= High Stop  → Output OFF
+Between setpoints   → Hold last state
+```
+
+Example:
+
+```text
+Tank level = 30
+Low Start = 40
+High Stop = 90
+Direction = Pump In / Fill
+Result = ON
+```
+
+Example:
+
+```text
+Tank level = 95
+Low Start = 40
+High Stop = 90
+Direction = Pump In / Fill
+Result = OFF
+```
+
+---
+
+## Pump Out / Empty Direction
+
+Use `direction: "out"` for emptying.
+
+Logic:
+
+```text
+Value >= High Stop  → Output ON
+Value <= Low Start  → Output OFF
+Between setpoints   → Hold last state
+```
+
+Example:
+
+```text
+Tank level = 95
+Low Start = 40
+High Stop = 90
+Direction = Pump Out / Empty
+Result = ON
+```
+
+Example:
+
+```text
+Tank level = 30
+Low Start = 40
+High Stop = 90
+Direction = Pump Out / Empty
+Result = OFF
+```
+
+---
+
+## Hysteresis
+
+AUTO mode uses hysteresis.
+
+That means the output does not constantly flick on and off while the value is between the low and high setpoints.
+
+Example:
+
+```text
+Low Start: 40
+High Stop: 90
+Current value: 60
+```
+
+The value is between the setpoints, so the node holds the last output state.
+
+---
+
+# Remote Key To Watch
+
+The Remote Key To Watch is the live payload key the Config Store checks in AUTO mode.
+
+Example incoming payload:
+
+```json
+{
+  "ty et level": 1607.38
+}
+```
+
+Remote Key To Watch:
+
+```text
+ty et level
+```
+
+The key must match the payload exactly.
+
+Spaces are allowed.
+
+---
+
+## Flat Payload Keys
+
+For a flat payload:
+
+```json
+{
+  "ty et level": 1607.38
+}
+```
+
+Use:
+
+```text
+ty et level
+```
+
+---
+
+## Wrapped Payload Keys
+
+For a wrapped payload:
+
+```json
+{
+  "ty et level": {
+    "value": 1607.38,
+    "timestamp": 1788329806635
+  }
+}
+```
+
+Use:
+
+```text
+ty et level.value
+```
+
+---
+
+## Mixed Payload Example
+
+Example:
+
+```json
+{
+  "cl level": {
+    "value": 672.06,
+    "timestamp": 1788329806635
+  },
+  "cl fault": 0,
+  "b2 fb": 0
+}
+```
+
+Use:
+
+```text
+cl level.value
+```
+
+for the wrapped value.
+
+Use:
+
+```text
+cl fault
+```
+
+for the direct value.
+
+Use:
+
+```text
+b2 fb
+```
+
+for the direct value.
+
+---
+
+# Config Store Status Messages
+
+The Config Store node shows status text under the node.
+
+---
+
+## waiting for configStore
+
+The node has not received any valid config yet.
+
+Check:
+
+- 3DM In node is connected
+- 3DM In Attribute Key is blank
+- 3DM.space has sent a `configStore`
+- The selected device is correct
+
+---
+
+## loaded saved config
+
+The node loaded the last saved config from local storage after Node-RED started.
+
+This means it can keep using the previous config even before a new cloud update arrives.
+
+---
+
+## saved: b1
+
+The node received and saved the `b1` config block.
+
+Example:
+
+```text
+saved: b1
+```
+
+This means the Config Name matched and the config was stored locally.
+
+---
+
+## saved: b1, b2
+
+The node received and saved multiple config blocks.
+
+This usually happens when Config Name is blank.
+
+---
+
+## config unchanged: b1
+
+The node received a config block that matched, but it was the same as the one already stored.
+
+No forced output update was needed.
+
+---
+
+## configStore ignored
+
+The node received a configStore, but it did not match this node's Config Name.
+
+Example:
+
+```text
+Config Name: b2
+Received: b1
+Result: ignored
+```
+
+Check that the Config Name in Node-RED matches the Config Name from the SCADA Canvas control.
+
+---
+
+## output1: tank skipped
+
+The node found the config item, but could not calculate the output.
+
+Common causes:
+
+- The live payload does not contain the Remote Key To Watch
+- The key name is wrong
+- The payload is wrapped and needs `.value`
+- Low Start is blank
+- High Stop is blank
+- The value is not numeric
+
+Example problem:
+
+```json
+{
+  "tank": {
+    "value": 50
+  }
+}
+```
+
+Remote Key To Watch is incorrectly set to:
+
+```text
+tank
+```
+
+Correct:
+
+```text
+tank.value
+```
+
+---
+
+## output1: ON
+
+The final output state is ON.
+
+The node will send:
+
+```json
+true
+```
+
+from output 1.
+
+---
+
+## output1: OFF
+
+The final output state is OFF.
+
+The node will send:
+
+```json
+false
+```
+
+from output 1.
+
+---
+
+## skipped - output disabled
+
+The config item is trying to use an output that is not active.
+
+Example:
+
+```text
+Active Outputs: 1
+Item output: output2
+```
+
+Result:
+
+```text
+output2 skipped - output disabled
+```
+
+Increase Active Outputs or change the item to `output1`.
+
+---
+
+# 3DM SCADA Canvas Smart Control Integration
+
+![This is an alt text.](https://github.com/smithtekIOT/ArtWork/blob/master/Canvas%20SCADA%203dm.jpg?raw=true)
+
+---
+
+# 3DM SCADA Canvas Widget
+
+The **3DM SCADA Canvas** is the main default dashboard-building widget for 3DM.space.
+
+It is designed to give users one flexible widget that can be used to build complete SCADA-style screens without needing a different widget for every display, control, indicator, gauge or setpoint.
+
+The canvas can be used to create dashboards for pumps, tanks, bores, irrigation systems, treatment plants, generators, remote sites, telemetry systems and general automation projects.
+
+It can display live values, show equipment status, add background images, create process-style layouts, send commands, adjust setpoints, and link directly into the 3DM Node-RED nodes running on the PassPort gateway.
+
+##-Important-##
+
+`To run the SCADA press save then live mode button`
+`To edit the scada and make changes press the edit button`
+
+Typical canvas items include:
+
+- Text labels
+- Value displays
+- Gauges
+- Vertical level bars
+- Horizontal bars
+- Tables
+- LED indicators
+- Spinning run indicators
+- Control buttons
+- Setpoint tables
+- Action buttons
+- Lines, panels and layout shapes
+- Background images
+
+The widget is built so a dashboard can be assembled visually. Items can be added, moved, resized and configured directly on the canvas.
+
+This makes it suitable for both simple dashboards and more detailed SCADA-style views.
+
+---
+
+## How the Canvas Works With 3DM Nodes
+
+The SCADA Canvas works directly with the 3DM Node-RED nodes.
+
+Live data is normally sent from the PassPort to 3DM.space using the **3DM Out** node.
+
+Commands and settings are sent from the SCADA Canvas back to the PassPort using the **3DM In** node.
+
+Smart local control settings are stored and run locally using the **3DM Config Store** node.
+
+Typical telemetry flow:
+
+```text
+Mako RF / PLC / Sensor Data
+        ↓
+Node-RED Function Logic
+        ↓
+3DM Out
+        ↓
+3DM.space
+        ↓
+SCADA Canvas Display
+```
+
+Typical command flow:
+
+```text
+SCADA Canvas Button / Setpoint
+        ↓
+3DM.space Shared Attribute
+        ↓
+3DM In
+        ↓
+Function Node / PLC Logic / Mako RF Command
+```
+
+Typical smart control flow:
+
+```text
+SCADA Canvas Smart Control
+        ↓
+configStore Shared Attribute
+        ↓
+3DM In
+        ↓
+3DM Config Store
+        ↓
+Local Output Logic
+```
+
+---
+
+## Data Variables and Attributes
+
+When first adding the SCADA Canvas widget to a dashboard, the live telemetry variables must be added to the widget datasource.
+
+![This is an alt text.](https://github.com/smithtekIOT/ArtWork/blob/master/Select%20Data%203dm.jpg?raw=true)
+These are the values the canvas needs to display. Press the + button to select data from the selected device, in this image the device is called "PassPort no 567"
+
+Examples:
+
+```text
+tank_level
+pump_run
+pump_fault
+dc_voltage
+flow_lpm
+pressure_kpa
+ty et level
+b1 fb
+b2 fb
+```
+
+These data variables are used by display items such as:
+
+- Values
+- Gauges
+- Bars
+- Tables
+- LEDs
+- Run indicators
+
+Attributes do not need to be added as data variables.
+
+The SCADA Canvas handles attributes internally through the widget settings and control settings.
+
+This means command keys, setpoints and smart control configuration do not need to be manually added to the widget datasource as data keys.
+
+Examples of attributes handled by the widget:
+
+```text
+pump_cmd
+reset_cmd
+configStore
+start_level
+stop_level
+```
+
+Only add the live telemetry variables that need to be displayed or used visually on the canvas.
+
+---
+## Widgets
+![This is an alt text.](https://github.com/smithtekIOT/ArtWork/blob/master/3dm%20widgets.jpg?raw=true)
+
+---
+
+The SCADA Canvas includes the SCADA widget main items needed to build a complete dashboard screen from one widget.
+
+### Background Image
+
+Adds a site image, process diagram, map, equipment photo or custom SCADA graphic behind the canvas items.
+
+Use for:
+
+- Site layouts
+- Pump station diagrams
+- Tank layouts
+- Process backgrounds
+- Branded dashboard screens
+
+---
+
+### Text Label
+
+Adds fixed text to the canvas.
+
+Use for:
+
+- Equipment names
+- Area labels
+- Section headings
+- Notes
+- Units or descriptions
+
+Example:
+
+```text
+Bore Pump 1
+Main Tank
+Discharge Pressure
+```
+
+---
+
+### Value Display
+
+Shows a live telemetry value from the selected device.
+
+Use for:
+
+- Level
+- Pressure
+- Flow
+- Voltage
+- Current
+- Run hours
+- Totalisers
+
+Example:
+
+```text
+Data Key: tank_level
+Display: 76 %
+```
+
+---
+
+### Gauge
+
+Shows a live value as a gauge.
+
+Use for values that are easier to read visually.
+
+Use for:
+
+- Pressure
+- Flow
+- Tank level
+- Battery voltage
+- Speed
+- Current
+
+Example:
+
+```text
+Data Key: pressure_kpa
+Range: 0 to 600
+```
+
+---
+
+### Vertical Bar
+
+Shows a live value as a vertical fill bar.
+
+Best for tanks, levels and storage values.
+
+Use for:
+
+- Tank level
+- Bore level
+- Chemical level
+- Silo level
+- Battery level
+
+Example:
+
+```text
+Data Key: ty et level
+Low: 0
+High: 4000
+```
+
+---
+
+### Horizontal Bar
+
+Shows a live value as a horizontal fill bar.
+
+Best for progress-style values.
+
+Use for:
+
+- Flow percentage
+- Pump speed
+- Battery percentage
+- Load percentage
+- Process progress
+
+Example:
+
+```text
+Data Key: pump_speed
+Range: 0 to 100
+```
+
+---
+
+### LED Indicator
+
+Shows equipment state using colour.
+
+Use for:
+
+- Pump running
+- Pump fault
+- Valve open
+- Comms status
+- Alarm state
+- Relay feedback
+
+Example:
+
+```text
+Data Key: b1 fb
+0 = Off
+1 = Running
+```
+
+---
+
+### Spinning Wheel
+
+Shows a rotating run indicator when a value is active.
+
+Use for:
+
+- Pump running
+- Motor running
+- Fan running
+- Mixer running
+- Generator running
+
+Example:
+
+```text
+Data Key: pump_run
+Spin when value = 1
+```
+
+---
+
+### Table
+
+Shows multiple live values in a compact list.
+
+Use for:
+
+- Electrical values
+- Pump data
+- Water quality
+- Site summary
+- Multiple sensor readings
+
+Example:
+
+```text
+Voltage
+Current
+Power
+Run Hours
+Totaliser
+```
+
+---
+
+### Control Button
+
+Adds ON / OFF / AUTO style controls to the canvas.
+
+Use for:
+
+- Pump commands
+- Mode selection
+- Manual control
+- Auto control
+- Reset commands
+
+The control button can work as a simple command button or as a Smart Local Control linked to the 3DM Config Store.
+
+---
+
+### Basic Button Command
+
+Sends a direct command value back to the PassPort.
+
+Use for simple commands.
+
+Example:
+
+```text
+ON  → pump_cmd = 1
+OFF → pump_cmd = 0
+```
+
+The value is sent to Node-RED through the **3DM In** node.
+
+---
+
+### Smart Local Control
+
+Sends control settings to the **3DM Config Store** node.
+
+Use when the PassPort should run the control locally.
+
+Example:
+
+```text
+Mode: AUTO
+Watch: ty et level
+Low Start: 1500
+High Stop: 1700
+Direction: Pump In / Fill
+```
+
+The PassPort can keep running this logic locally, even during a temporary cloud outage.
+
+---
+
+### Setpoint Table
+
+Allows users to enter and send setpoints from the dashboard.
+
+Use for:
+
+- Start levels
+- Stop levels
+- Pressure limits
+- Alarm limits
+- Flow limits
+- Site settings
+
+Example:
+
+```text
+Low Start: 1500
+High Stop: 1700
+```
+
+Setpoints are sent back to Node-RED through the **3DM In** node.
+
+---
+
+### Action Button
+
+Runs a dashboard action configured in 3DM.space.
+
+Use for:
+
+- Opening detail screens
+- Opening popups
+- Opening trend views
+- Opening alarm pages
+- Moving between dashboard states
+
+Example:
+
+```text
+Button: Pump Details
+Action: Open pump detail popup
+```
+
+---
+
+### Line
+
+Adds a simple line to the canvas.
+
+Use for:
+
+- Pipework
+- Flow paths
+- Cable paths
+- Separators
+- Simple process diagrams
+
+---
+
+### Panel / Rectangle
+
+Adds a visual panel or box behind other items.
+
+Use for:
+
+- Grouping related values
+- Creating equipment cards
+- Highlighting sections
+- Building clean dashboard layouts
+
+---
+
+## Widget Setup Note
+
+When first adding the SCADA Canvas widget, add the telemetry data variables that need to be displayed on the canvas.
+
+Examples:
+
+```text
+tank_level
+pump_run
+pump_fault
+dc_voltage
+flow_lpm
+ty et level
+b1 fb
+b2 fb
+```
+
+You do not need to add command attributes as data keys.
+
+The widget handles attributes internally through the widget settings and control settings.
+
+Examples that do not need to be added as data variables:
+
+```text
+pump_cmd
+reset_cmd
+configStore
+start_level
+stop_level
+```
+
+
+## Control Buttons
+
+The SCADA Canvas includes control buttons that can send commands back to the PassPort.
+
+There are two main control styles:
+
+```text
+Basic Button Command
+Smart Local Control
+```
+
+**Basic Button Command** is used when the button sends a simple command value.
+
+Example:
+
+```text
+ON  → pump_cmd = 1
+OFF → pump_cmd = 0
+```
+
+**Smart Local Control** is used when the PassPort should handle the control logic locally.
+
+Example:
+
+```text
+AUTO mode
+Watch tank level
+Start below low setpoint
+Stop above high setpoint
+Run logic locally in Node-RED
+```
+
+Smart Local Control sends its settings to the **3DM Config Store** node, where the logic continues to run locally on the PassPort.
+
+This means the PassPort can continue running the control logic even if the cloud connection is temporarily unavailable.
+
+---
+
+## Why Use the SCADA Canvas
+
+The SCADA Canvas reduces the need to build many separate dashboard widgets.
+
+Instead of using one widget for a value, another for a gauge, another for a button, another for an LED and another for setpoints, the canvas allows these items to be built into one screen.
+
+This helps keep dashboards cleaner, easier to manage and better suited to real site layouts.
+
+It is especially useful for projects that need:
+
+- A visual overview of a site
+- Pump and tank control
+- Remote start/stop commands
+- Local automatic control
+- Setpoint adjustment
+- Live feedback indicators
+- Simple process diagrams
+- Custom SCADA-style screens
+
+---
+
+## Basic Button Command
+
+Basic mode sends a simple shared attribute key/value.
+
+Example:
+
+```text
+Control Attribute Key: pump_cmd
+ON Value: 1
+OFF Value: 0
+AUTO Value: auto
+```
+
+Pressing ON sends:
+
+```json
+{
+  "pump_cmd": 1
+}
+```
+
+Use Basic mode for simple direct commands.
+
+---
+
+## Smart Local Control
+
+Smart Local Control sends settings into `configStore`.
+
+Use this when Node-RED should handle the control locally.
+
+Example fields:
+
+```text
+Config Name: b1
+Remote Key To Watch: ty et level
+Low Start Setpoint: 1500
+High Stop Setpoint: 1700
+Direction: Pump In / Fill
+```
+
+This creates a config block that the Config Store node can run locally.
+
+---
+
+## Control Attribute Key vs Remote Key To Watch
+
+### Control Attribute Key
+
+Used for Basic button command mode.
+
+It decides which shared attribute key is written when a button is pressed.
+
+Example:
+
+```text
+pump_cmd
+```
+
+### Remote Key To Watch
+
+Used for Smart Local Control AUTO mode.
+
+It decides which live payload key the Config Store node watches.
+
+Example:
+
+```text
+ty et level
+```
+
+These are different jobs.
+
+---
+
+## Smart Control Button Light
+
+For Smart Local Control, the canvas button should remember the last selected mode.
+
+Example:
+
+```text
+Press AUTO
+AUTO stays highlighted
+```
+
+The button light is only a visual indication of the last selected mode.
+
+For real-world feedback, use separate indicator variables, LED widgets, or telemetry feedback keys from the device.
+
+Recommended setup:
+
+```text
+Control button = sends selected mode
+LED / indicator = shows actual pump feedback
+```
+
+---
+
+## Updating Setpoints Safely
+
+When using Smart Local Control, changing Low Start or High Stop should be saved using the SCADA Canvas Save button.
+
+Recommended behaviour:
+
+```text
+Change setpoint
+Press Save
+Layout saves
+configStore updates
+Mode stays AUTO
+No need to press ON/OFF/AUTO again
+```
+
+Avoid changing setpoints by pressing OFF then AUTO on a live pump, because that can affect field equipment.
+
+---
+
+# Typical Flows
+
+## Sending telemetry to 3DM.space
+
+```text
+Mako RF / PLC / Sensor Data
+        ↓
+Function Node
+        ↓
+3DM Out
+        ↓
+3DM.space
+```
+
+---
+
+## Receiving a simple command
+
+```text
+3DM.space
+        ↓
+3DM In
+        ↓
+Function Node
+        ↓
+PLC / Relay / Output Logic
+```
+
+---
+
+## Receiving saved settings
+
+```text
+3DM.space
+        ↓
+3DM In
+        ↓
+3DM Config Store
+        ↓
+Local Outputs
+```
+
+---
+
+## Smart local pump control
+
+```text
+3DM SCADA Canvas
+        ↓
+configStore
+        ↓
+3DM In
+        ↓
+3DM Config Store
+        ↓
+Output 1
+        ↓
+Pump logic / PLC / Mako RF command
+```
+
+---
+
+# Example Function Node Before 3DM Out
+
+Use this type of structure before 3DM Out:
+
+```js
+msg.payload = {
+    "tank_level": 65.2,
+    "pump_run": true,
+    "dc_voltage": 24.4
+};
+
+return msg;
+```
+
+Do not send a raw value directly into 3DM Out.
+
+---
+
+# Example Function Node For Config Store Testing
+
+Use this to test a Config Store AUTO control watching `tank`:
+
+```js
+msg.payload = {
+    tank: Number(msg.payload)
+};
+
+return msg;
+```
+
+Then inject:
+
+```text
+30
+```
+
+to test low start.
+
+Then inject:
+
+```text
+110
+```
+
+to test high stop.
+
+---
+
+# Troubleshooting
+
+---
+
+## 3DM Out says storing offline
+
+Check:
+
+- Internet connection
+- 3DM Cloud Login credentials
+- 3DM.space device credentials
+- Correct login selected in the 3DM Out node
+- Node-RED has been restarted after installing the package
+
+Also check the Node-RED log.
+
+---
+
+## 3DM Out says bad payload
+
+The payload is not a JSON object.
+
+Correct:
+
+```json
+{
+  "level": 123
+}
+```
+
+Incorrect:
+
+```json
+123
+```
+
+---
+
+## 3DM Out says rate limited
+
+The input is sending too fast.
+
+Slow the data down to one message every 60 seconds or slower.
+
+---
+
+## Password disappears after deploy
+
+This can be normal.
+
+Node-RED hides password fields.
+
+Check whether the node still connects.
+
+---
+
+## Unknown node appears in Node-RED
+
+This usually means the package did not load correctly.
+
+Check:
+
+- The package was installed properly
+- The `.html` and `.js` files are named correctly
+- `package.json` points to the right files
+- Node-RED was restarted after install
+- Browser was refreshed with Ctrl+F5
+
+---
+
+## Config Store says waiting for configStore
+
+The node has not received config yet.
+
+Check:
+
+- 3DM In is connected
+- 3DM In Attribute Key is blank
+- The SCADA Canvas has sent the config
+- The correct device is selected in 3DM.space
+- The config is saved as shared attributes
+
+---
+
+## Config Store says configStore ignored
+
+The Config Name does not match.
+
+Example:
+
+```text
+Node-RED Config Name: b2
+Incoming config only contains: b1
+```
+
+Fix by matching the names.
+
+---
+
+## Config Store says output1 skipped
+
+The config matched, but the node could not calculate the output.
+
+Check:
+
+- Remote Key To Watch is correct
+- The live payload is reaching the Config Store node
+- The live value is numeric
+- Low Start is set
+- High Stop is set
+- Use `.value` if the payload is wrapped
+
+---
+
+## AUTO mode does not turn on
+
+For Pump In / Fill mode, the value must go below or equal to Low Start.
+
+Example:
+
+```text
+Value: 30
+Low Start: 40
+Result: ON
+```
+
+---
+
+## AUTO mode does not turn off
+
+For Pump In / Fill mode, the value must go above or equal to High Stop.
+
+Example:
+
+```text
+Value: 95
+High Stop: 90
+Result: OFF
+```
+
+---
+
+## Value is between setpoints and nothing changes
+
+This is normal.
+
+AUTO mode holds the last state while inside the setpoint band.
+
+Example:
+
+```text
+Low Start: 40
+High Stop: 90
+Current Value: 60
+Result: hold last output state
+```
+
+---
+
+## Two Config Store nodes respond together
+
+Use Config Name filtering.
+
+Example:
+
+```text
+Node 1 Config Name: b1
+Node 2 Config Name: b2
+```
+
+Also use:
+
+```text
+Output Mode: Only when output changes
+```
+
+Use:
+
+```text
+Output Mode: Every check
+```
+
+only when repeated output messages are required.
+
+---
+
+## Deleted SCADA control still remains in configStore
+
+Deleting a control from the SCADA Canvas layout may not automatically remove it from the saved `configStore`.
+
+Current clean-up method:
+
+```text
+Device
+    ↓
+Attributes
+    ↓
+Shared attributes
+    ↓
+Delete configStore
+```
+
+Then press Save or resend the remaining Smart Controls from the SCADA Canvas.
+
+---
+
+# Notes
+
+- Use **3DM Out** to send live telemetry 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 the PassPort device in 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.
+- Live telemetry should be sent no faster than one message every 30 seconds.
+- The Mako RF node should send a JSON object into 3DM Out.
+- For Config Store AUTO mode, the Remote Key To Watch must match the incoming local payload key.
+- For wrapped values, use `.value` in the Remote Key To Watch field.
+
+---
+
+# Author
+
+Smithtek
+
+---
 
-## License
+# License
 
 GPL-3.0-or-later