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

package/3dm-config-store.html

@@ -0,0 +1,236 @@
+<script type="text/javascript">
+    RED.nodes.registerType("3dm-config-store", {
+        category: "3DM.space",
+        color: "#6D6D6D",
+        defaults: {
+            name: { value: "" },
+            configName: { value: "" },
+            tickSeconds: {
+                value: 20,
+                validate: function (v) {
+                    var n = Number(v);
+                    return !isNaN(n) && n >= 1 && n <= 60;
+                }
+            },
+            outputMode: { value: "change" },
+            configOutput: { value: 0 },
+            emitConfigOnUpdate: { value: false }
+        },
+        inputs: 1,
+        outputs: 24,
+        icon: "font-awesome/fa-database",
+        label: function () {
+            return this.name || "3DM config store";
+        },
+        paletteLabel: "3DM config store",
+        outputLabels: function (index) {
+            return "Output " + (index + 1);
+        }
+    });
+</script>
+
+<script type="text/html" data-template-name="3dm-config-store">
+    <div class="form-row">
+        <label for="node-input-name">
+            <i class="fa fa-tag"></i> Node Name
+        </label>
+        <input type="text" id="node-input-name" placeholder="Optional, e.g. Pump Config Store">
+    </div>
+
+    <div class="form-row">
+        <label for="node-input-configName">
+            <i class="fa fa-folder-open"></i> Config Name
+        </label>
+        <input type="text" id="node-input-configName" placeholder="Optional, e.g. mainScheduler">
+    </div>
+
+    <div class="form-row">
+        <label for="node-input-tickSeconds">
+            <i class="fa fa-clock-o"></i> Check Every
+        </label>
+        <input type="number" id="node-input-tickSeconds" min="1" max="60" placeholder="20" style="width:100px;">
+        <span> seconds</span>
+    </div>
+
+    <div class="form-row">
+        <label for="node-input-outputMode">
+            <i class="fa fa-sign-out"></i> Output Mode
+        </label>
+        <select id="node-input-outputMode" style="width:70%;">
+            <option value="change">Only when output changes</option>
+            <option value="always">Every check</option>
+        </select>
+    </div>
+
+    <div class="form-row">
+        <label for="node-input-configOutput">
+            <i class="fa fa-share-square-o"></i> Config Output
+        </label>
+        <select id="node-input-configOutput" style="width:70%;">
+            <option value="0">Disabled</option>
+            <option value="1">Output 1</option>
+            <option value="2">Output 2</option>
+            <option value="3">Output 3</option>
+            <option value="4">Output 4</option>
+            <option value="5">Output 5</option>
+            <option value="6">Output 6</option>
+            <option value="7">Output 7</option>
+            <option value="8">Output 8</option>
+            <option value="9">Output 9</option>
+            <option value="10">Output 10</option>
+            <option value="11">Output 11</option>
+            <option value="12">Output 12</option>
+            <option value="13">Output 13</option>
+            <option value="14">Output 14</option>
+            <option value="15">Output 15</option>
+            <option value="16">Output 16</option>
+            <option value="17">Output 17</option>
+            <option value="18">Output 18</option>
+            <option value="19">Output 19</option>
+            <option value="20">Output 20</option>
+            <option value="21">Output 21</option>
+            <option value="22">Output 22</option>
+            <option value="23">Output 23</option>
+            <option value="24">Output 24</option>
+        </select>
+    </div>
+
+    <div class="form-row">
+        <label for="node-input-emitConfigOnUpdate">
+            <i class="fa fa-refresh"></i> Send Config
+        </label>
+        <input type="checkbox" id="node-input-emitConfigOnUpdate" style="display:inline-block; width:auto; vertical-align:top;">
+        <span> send stored config when updated</span>
+    </div>
+
+    <div class="form-tips">
+        <b>Tip:</b> Leave Config Name blank to allow this node to store and use all config blocks sent under <code>configStore</code>.
+    </div>
+</script>
+
+<script type="text/html" data-help-name="3dm-config-store">
+    <p>
+        Stores configuration sent from 3DM.space and runs local schedule/control logic.
+    </p>
+
+    <p>
+        This node is normally placed after a <b>3DM In</b> node.
+    </p>
+
+    <pre>3DM In → 3DM Config Store → 24 outputs</pre>
+
+    <h3>Config Store Format</h3>
+
+    <p>
+        Incoming messages should contain a main <code>configStore</code> object.
+        Each config block inside it should have its own name.
+    </p>
+
+    <pre>{
+  "configStore": {
+    "mainScheduler": {
+      "type": "scheduler",
+      "data": []
+    },
+    "pumpSetpoints": {
+      "type": "setpoints",
+      "data": {
+        "startLevel": 30,
+        "stopLevel": 80
+      }
+    }
+  }
+}</pre>
+
+    <h3>Scheduler Config</h3>
+
+    <p>
+        Scheduler blocks use <code>type: "scheduler"</code>.
+    </p>
+
+    <pre>{
+  "configStore": {
+    "mainScheduler": {
+      "type": "scheduler",
+      "data": [
+        {
+          "name": "Pump 1 Morning Run",
+          "output": "output1",
+          "controlType": "schedule",
+          "mode": "Auto Schedule",
+          "days": ["mon", "tue", "wed", "thu", "fri"],
+          "startHour": 6,
+          "startMinute": 0,
+          "runHour": 1,
+          "runMinute": 30
+        }
+      ]
+    }
+  }
+}</pre>
+
+    <h3>Control Config</h3>
+
+    <p>
+        Control entries can use live input values and stored setpoints.
+    </p>
+
+    <pre>{
+  "name": "Tank Level Control",
+  "output": "output1",
+  "controlType": "control",
+  "mode": "AUTO",
+  "variable": "tank_level",
+  "lowSetpointKey": "pumpSetpoints.data.startLevel",
+  "highSetpointKey": "pumpSetpoints.data.stopLevel",
+  "direction": "in"
+}</pre>
+
+    <h3>Config Name</h3>
+
+    <p>
+        Leave <b>Config Name</b> blank to allow all config blocks.
+    </p>
+
+    <p>
+        Enter a name such as <code>mainScheduler</code> if this node should only use one config block.
+    </p>
+
+    <h3>Outputs</h3>
+
+    <p>
+        The node has 24 outputs.
+    </p>
+
+    <p>
+        Scheduler and control items use output names such as:
+    </p>
+
+    <pre>output1
+output2
+output3</pre>
+
+    <p>
+        If multiple schedule/control entries use the same output, they are combined using OR logic.
+        If any entry wants the output ON, the final output is ON.
+    </p>
+
+    <h3>Local Storage</h3>
+
+    <p>
+        Config is saved locally on the gateway. If Node-RED restarts, the last saved config is loaded again.
+    </p>
+
+    <h3>Output Mode</h3>
+
+    <ul>
+        <li><b>Only when output changes</b>: sends an output only when the final state changes.</li>
+        <li><b>Every check</b>: sends outputs every check cycle.</li>
+    </ul>
+
+    <h3>Config Output</h3>
+
+    <p>
+        Optional. Select an output if you want the full stored config sent out as a message.
+    </p>
+</script>

package/3dm-config-store.js

@@ -0,0 +1,883 @@
+module.exports = function (RED) {
+    "use strict";
+
+    var fs = require("fs");
+    var path = require("path");
+
+    function asBool(value) {
+        return value === true || value === "true" || value === 1 || value === "1";
+    }
+
+    function asNumber(value) {
+        var n = parseFloat(value);
+        return Number.isNaN(n) ? NaN : n;
+    }
+
+    function clampNumber(value, min, max, fallback) {
+        var n = parseInt(value, 10);
+
+        if (Number.isNaN(n)) {
+            return fallback;
+        }
+
+        return Math.max(min, Math.min(n, max));
+    }
+
+    function safeParseJson(value) {
+        if (typeof value !== "string") {
+            return value;
+        }
+
+        try {
+            return JSON.parse(value);
+        } catch (err) {
+            return value;
+        }
+    }
+
+    function hasOwn(obj, key) {
+        return Object.prototype.hasOwnProperty.call(obj, key);
+    }
+
+    function getNestedValue(obj, key) {
+        if (!obj || key === null || key === undefined || key === "") {
+            return undefined;
+        }
+
+        if (typeof obj !== "object") {
+            return undefined;
+        }
+
+        if (hasOwn(obj, key)) {
+            return obj[key];
+        }
+
+        var current = obj;
+        var parts = String(key).split(".");
+
+        for (var i = 0; i < parts.length; i += 1) {
+            var part = parts[i];
+
+            if (!current || typeof current !== "object" || !hasOwn(current, part)) {
+                return undefined;
+            }
+
+            current = current[part];
+        }
+
+        return current;
+    }
+
+    function makeDir(dir) {
+        try {
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+        } catch (err) {
+            try {
+                fs.mkdirSync(dir);
+            } catch (err2) {
+                throw err;
+            }
+        }
+    }
+
+    function dateKey(date) {
+        return (
+            date.getFullYear() + "-" +
+            (date.getMonth() + 1) + "-" +
+            date.getDate()
+        );
+    }
+
+    function outputNumberFromKey(outputKey, fallbackIndex) {
+        var match = String(outputKey || "").match(/output(\d+)/i);
+
+        if (match) {
+            var number = parseInt(match[1], 10);
+
+            if (number >= 1 && number <= 24) {
+                return number;
+            }
+        }
+
+        return Math.max(1, Math.min(fallbackIndex + 1, 24));
+    }
+
+    function normaliseMode(value, fallback) {
+        if (value === null || value === undefined || value === "") {
+            return fallback;
+        }
+
+        return String(value);
+    }
+
+    function isManualOn(mode) {
+        return String(mode).toUpperCase() === "ON";
+    }
+
+    function isManualOff(mode) {
+        return String(mode).toUpperCase() === "OFF";
+    }
+
+    function isAutoSchedule(mode) {
+        var text = String(mode || "").toLowerCase();
+        return text === "auto schedule" || text === "auto" || text === "schedule";
+    }
+
+    function isSchedulerType(type) {
+        var text = String(type || "").toLowerCase();
+        return text === "scheduler" || text === "schedule" || text === "consched" || text === "control-schedule";
+    }
+
+    function ThreeDMConfigStoreNode(config) {
+        RED.nodes.createNode(this, config);
+
+        var node = this;
+
+        node.name = config.name;
+        node.configName = String(config.configName || "").trim();
+        node.tickSeconds = clampNumber(config.tickSeconds || 20, 1, 60, 20);
+        node.outputMode = config.outputMode || "change";
+        node.configOutput = clampNumber(config.configOutput || 0, 0, 24, 0);
+        node.emitConfigOnUpdate = asBool(config.emitConfigOnUpdate);
+
+        var userDir = RED.settings && RED.settings.userDir
+            ? RED.settings.userDir
+            : process.cwd();
+
+        var storeDir = path.join(userDir, "3dm-config-store");
+        var storeFile = path.join(storeDir, "3dm-config-store-" + node.id + ".json");
+
+        var closed = false;
+        var latestPayload = {};
+        var latestStore = {};
+        var outputStates = {};
+        var stoppedScheduleRuns = new Map();
+        var controlItemStates = new Map();
+        var lastStatusText = "";
+        var lastWarnText = "";
+        var lastWarnTime = 0;
+
+        function warnOncePerMinute(text) {
+            var now = Date.now();
+
+            if (text !== lastWarnText || (now - lastWarnTime) > 60000) {
+                lastWarnText = text;
+                lastWarnTime = now;
+                node.warn(text);
+            }
+        }
+
+        function setStatus(fill, shape, text) {
+            var shortText = String(text || "");
+
+            if (shortText.length > 90) {
+                shortText = shortText.slice(0, 87) + "...";
+            }
+
+            var key = fill + "|" + shape + "|" + shortText;
+
+            if (lastStatusText !== key) {
+                lastStatusText = key;
+                node.status({ fill: fill, shape: shape, text: shortText });
+            }
+        }
+
+        function saveToDisk() {
+            try {
+                makeDir(storeDir);
+
+                fs.writeFileSync(
+                    storeFile,
+                    JSON.stringify({
+                        version: 1,
+                        updatedAt: new Date().toISOString(),
+                        configStore: latestStore
+                    }, null, 2)
+                );
+            } catch (err) {
+                warnOncePerMinute("Failed to write 3DM config store to disk: " + (err.message || err));
+            }
+        }
+
+        function loadFromDisk() {
+            try {
+                if (!fs.existsSync(storeFile)) {
+                    latestStore = {};
+                    return;
+                }
+
+                var data = JSON.parse(fs.readFileSync(storeFile, "utf8"));
+
+                if (data && typeof data === "object" && data.configStore && typeof data.configStore === "object") {
+                    latestStore = data.configStore;
+                } else if (data && typeof data === "object") {
+                    latestStore = data;
+                } else {
+                    latestStore = {};
+                }
+            } catch (err) {
+                latestStore = {};
+                warnOncePerMinute("Failed to load saved 3DM config store: " + (err.message || err));
+            }
+        }
+
+        function shouldAcceptConfigName(configName) {
+            if (!node.configName) {
+                return true;
+            }
+
+            return String(configName) === node.configName;
+        }
+
+        function inferBlockType(configName, block) {
+            if (block && typeof block === "object" && !Array.isArray(block) && block.type) {
+                return String(block.type);
+            }
+
+            if (Array.isArray(block)) {
+                return "scheduler";
+            }
+
+            if (block && typeof block === "object" && Array.isArray(block.schedule)) {
+                return "scheduler";
+            }
+
+            if (String(configName || "").toLowerCase().indexOf("sched") !== -1) {
+                return "scheduler";
+            }
+
+            return "settings";
+        }
+
+        function normaliseConfigBlock(configName, block) {
+            var type = inferBlockType(configName, block);
+            var data = block;
+
+            if (block && typeof block === "object" && !Array.isArray(block) && hasOwn(block, "data")) {
+                data = block.data;
+            } else if (block && typeof block === "object" && !Array.isArray(block) && Array.isArray(block.schedule)) {
+                data = block.schedule;
+            }
+
+            return {
+                name: configName,
+                type: type,
+                data: data,
+                updatedAt: new Date().toISOString()
+            };
+        }
+
+        function extractConfigStore(msg) {
+            var payload = safeParseJson(msg.payload);
+
+            if (payload && typeof payload === "object" && hasOwn(payload, "configStore")) {
+                return payload.configStore;
+            }
+
+            if (msg.key === "configStore" || msg.topic === "configStore") {
+                return payload;
+            }
+
+            if (payload && typeof payload === "object" && payload.shared && hasOwn(payload.shared, "configStore")) {
+                return payload.shared.configStore;
+            }
+
+            if (payload && typeof payload === "object" && payload.client && hasOwn(payload.client, "configStore")) {
+                return payload.client.configStore;
+            }
+
+            return null;
+        }
+
+        function storeConfig(configStore) {
+            var savedNames = [];
+
+            if (!configStore || typeof configStore !== "object" || Array.isArray(configStore)) {
+                return savedNames;
+            }
+
+            Object.keys(configStore).forEach(function (configName) {
+                if (!shouldAcceptConfigName(configName)) {
+                    return;
+                }
+
+                latestStore[configName] = normaliseConfigBlock(configName, configStore[configName]);
+                savedNames.push(configName);
+            });
+
+            if (savedNames.length > 0) {
+                saveToDisk();
+            }
+
+            return savedNames;
+        }
+
+        function storedConfigValue(key) {
+            if (!key) {
+                return undefined;
+            }
+
+            var cleanKey = String(key);
+
+            var direct = getNestedValue({ configStore: latestStore }, cleanKey);
+
+            if (direct !== undefined) {
+                return direct;
+            }
+
+            direct = getNestedValue(latestStore, cleanKey);
+
+            if (direct !== undefined) {
+                return direct;
+            }
+
+            var names = Object.keys(latestStore);
+
+            for (var i = 0; i < names.length; i += 1) {
+                var block = latestStore[names[i]];
+
+                if (!block) {
+                    continue;
+                }
+
+                direct = getNestedValue(block, cleanKey);
+
+                if (direct !== undefined) {
+                    return direct;
+                }
+
+                direct = getNestedValue(block.data, cleanKey);
+
+                if (direct !== undefined) {
+                    return direct;
+                }
+            }
+
+            return undefined;
+        }
+
+        function resolveValue(key) {
+            var value = getNestedValue(latestPayload, key);
+
+            if (value !== undefined) {
+                return value;
+            }
+
+            return storedConfigValue(key);
+        }
+
+        function resolveSetpoint(item, valueKeys, fixedKeys) {
+            for (var i = 0; i < valueKeys.length; i += 1) {
+                var valueKeyName = valueKeys[i];
+
+                if (item[valueKeyName] !== undefined && item[valueKeyName] !== null && item[valueKeyName] !== "") {
+                    var resolved = resolveValue(item[valueKeyName]);
+
+                    if (resolved !== undefined) {
+                        return resolved;
+                    }
+                }
+            }
+
+            for (var j = 0; j < fixedKeys.length; j += 1) {
+                var fixedKeyName = fixedKeys[j];
+
+                if (item[fixedKeyName] !== undefined && item[fixedKeyName] !== null && item[fixedKeyName] !== "") {
+                    return item[fixedKeyName];
+                }
+            }
+
+            return undefined;
+        }
+
+        function itemMemoryKey(item, index, outputKey, configName) {
+            var explicitId = item.id || item.scheduleId || item.controlId || item.uid || item.uuid;
+
+            if (explicitId !== undefined && explicitId !== null && String(explicitId) !== "") {
+                return String(configName || "config") + "::" + String(item.controlType || "schedule") + "::" + String(explicitId);
+            }
+
+            var variableName = item.scheduleVariable || item.variable || item.key || item.keyName || "";
+
+            return JSON.stringify({
+                configName: configName || "",
+                type: item.controlType || "schedule",
+                output: outputKey,
+                name: item.name || "",
+                days: item.days || [],
+                startHour: item.startHour || "",
+                startMinute: item.startMinute || "",
+                runHour: item.runHour || "",
+                runMinute: item.runMinute || "",
+                variable: variableName,
+                direction: item.direction || "",
+                lowSetpoint: item.lowSetpoint || "",
+                highSetpoint: item.highSetpoint || "",
+                scheduleHighSetpoint: item.scheduleHighSetpoint || "",
+                index: index
+            });
+        }
+
+        function currentScheduleRun(item, now) {
+            var days = item.days || [];
+
+            if (typeof days === "string") {
+                days = days.split(",").map(function (day) {
+                    return day.trim().toLowerCase();
+                });
+            }
+
+            var startHour = parseInt(item.startHour || 0, 10);
+            var startMinute = parseInt(item.startMinute || 0, 10);
+            var runHour = parseInt(item.runHour || 0, 10);
+            var runMinute = parseInt(item.runMinute || 0, 10);
+
+            var startMinutes = startHour * 60 + startMinute;
+            var runMinutes = runHour * 60 + runMinute;
+
+            if (runMinutes <= 0) {
+                return null;
+            }
+
+            var dayNames = ["sun", "mon", "tue", "wed", "thu", "fri", "sat"];
+            var candidates = [new Date(now), new Date(now)];
+
+            candidates[1].setDate(candidates[1].getDate() - 1);
+
+            for (var i = 0; i < candidates.length; i += 1) {
+                var startDay = candidates[i];
+                var dayName = dayNames[startDay.getDay()];
+
+                if (days.length > 0 && days.indexOf(dayName) === -1) {
+                    continue;
+                }
+
+                var start = new Date(startDay);
+                start.setHours(Math.floor(startMinutes / 60), startMinutes % 60, 0, 0);
+
+                var end = new Date(start.getTime() + runMinutes * 60000);
+
+                if (now >= start && now < end) {
+                    return dateKey(start) + "@" + startMinutes;
+                }
+            }
+
+            return null;
+        }
+
+        function scheduleHighStopEnabled(item) {
+            return asBool(item.highStopEnabled);
+        }
+
+        function calculateScheduleState(item, itemKey) {
+            var mode = normaliseMode(item.mode, "Auto Schedule");
+
+            if (isManualOn(mode)) {
+                return 1;
+            }
+
+            if (isManualOff(mode)) {
+                return 0;
+            }
+
+            if (!isAutoSchedule(mode)) {
+                return null;
+            }
+
+            var runId = currentScheduleRun(item, new Date());
+
+            if (!runId) {
+                stoppedScheduleRuns.delete(itemKey);
+                return 0;
+            }
+
+            if (!scheduleHighStopEnabled(item)) {
+                return 1;
+            }
+
+            if (stoppedScheduleRuns.get(itemKey) === runId) {
+                return 0;
+            }
+
+            var keyName = item.scheduleVariable || item.variable || item.key || item.keyName;
+            var value = asNumber(resolveValue(keyName));
+
+            var highStopValue = resolveSetpoint(
+                item,
+                ["scheduleHighSetpointKey", "highStopKey", "highSetpointKey"],
+                ["scheduleHighSetpoint", "highStop", "highSetpoint"]
+            );
+
+            var highStop = asNumber(highStopValue);
+
+            if (Number.isNaN(value) || Number.isNaN(highStop)) {
+                return 1;
+            }
+
+            if (value >= highStop) {
+                stoppedScheduleRuns.set(itemKey, runId);
+                return 0;
+            }
+
+            return 1;
+        }
+
+        function calculateControlState(item, itemKey, outputKey) {
+            var mode = normaliseMode(item.mode, "AUTO");
+
+            if (isManualOn(mode)) {
+                controlItemStates.set(itemKey, 1);
+                return 1;
+            }
+
+            if (isManualOff(mode)) {
+                controlItemStates.set(itemKey, 0);
+                return 0;
+            }
+
+            var keyName = item.variable || item.key || item.keyName;
+            var value = asNumber(resolveValue(keyName));
+
+            var low = asNumber(resolveSetpoint(
+                item,
+                ["lowSetpointKey", "lowKey", "startSetpointKey"],
+                ["lowSetpoint", "low", "startSetpoint"]
+            ));
+
+            var high = asNumber(resolveSetpoint(
+                item,
+                ["highSetpointKey", "highKey", "stopSetpointKey"],
+                ["highSetpoint", "high", "stopSetpoint"]
+            ));
+
+            if (Number.isNaN(value) || Number.isNaN(low) || Number.isNaN(high)) {
+                return null;
+            }
+
+            var lastState = controlItemStates.has(itemKey)
+                ? controlItemStates.get(itemKey)
+                : (outputStates[outputKey] || 0);
+
+            var newState = lastState;
+            var direction = item.direction || "in";
+
+            if (direction === "in" || direction === "fill" || direction === "normal") {
+                if (value <= low) {
+                    newState = 1;
+                }
+
+                if (value >= high) {
+                    newState = 0;
+                }
+            } else {
+                if (value >= high) {
+                    newState = 1;
+                }
+
+                if (value <= low) {
+                    newState = 0;
+                }
+            }
+
+            controlItemStates.set(itemKey, newState);
+            return newState;
+        }
+
+        function getSchedulerItems() {
+            var items = [];
+            var configNames = Object.keys(latestStore);
+
+            configNames.forEach(function (configName) {
+                if (!shouldAcceptConfigName(configName)) {
+                    return;
+                }
+
+                var block = latestStore[configName];
+
+                if (!block || !isSchedulerType(block.type)) {
+                    return;
+                }
+
+                var list = [];
+
+                if (Array.isArray(block.data)) {
+                    list = block.data;
+                } else if (block.data && typeof block.data === "object" && Array.isArray(block.data.schedule)) {
+                    list = block.data.schedule;
+                }
+
+                list.forEach(function (item) {
+                    if (item && typeof item === "object") {
+                        items.push({
+                            configName: configName,
+                            item: item
+                        });
+                    }
+                });
+            });
+
+            return items;
+        }
+
+        function sendConfigSnapshot(eventName) {
+            if (node.configOutput < 1 || node.configOutput > 24) {
+                return;
+            }
+
+            var outputs = new Array(24).fill(null);
+
+            outputs[node.configOutput - 1] = {
+                topic: "configStore",
+                event: eventName || "configStore",
+                payload: {
+                    configStore: latestStore
+                },
+                configStore: latestStore
+            };
+
+            node.send(outputs);
+        }
+
+        function runConfigStore(isOffline, forceOutput) {
+            if (closed) {
+                return;
+            }
+
+            var outputs = new Array(24).fill(null);
+            var statusSummary = [];
+            var outputGroups = new Map();
+            var activeItemKeys = new Set();
+            var schedulerItems = getSchedulerItems();
+
+            schedulerItems.forEach(function (entry, index) {
+                var item = entry.item;
+                var configName = entry.configName;
+                var outputKey = item.output || ("output" + (index + 1));
+                var outputNumber = outputNumberFromKey(outputKey, index);
+                var itemKey = itemMemoryKey(item, index, outputKey, configName);
+
+                item.output = outputKey;
+                activeItemKeys.add(itemKey);
+
+                var newState = item.controlType === "control"
+                    ? calculateControlState(item, itemKey, outputKey)
+                    : calculateScheduleState(item, itemKey);
+
+                if (newState === null || newState === undefined) {
+                    statusSummary.push(outputKey + ": " + (item.name || "item") + " skipped");
+                    return;
+                }
+
+                if (!outputGroups.has(outputKey)) {
+                    outputGroups.set(outputKey, {
+                        outputKey: outputKey,
+                        outputNumber: outputNumber,
+                        states: [],
+                        names: [],
+                        controlTypes: new Set()
+                    });
+                }
+
+                var group = outputGroups.get(outputKey);
+
+                group.states.push(Number(newState) === 1 ? 1 : 0);
+                group.names.push(item.name || outputKey);
+                group.controlTypes.add(item.controlType || "schedule");
+            });
+
+            stoppedScheduleRuns.forEach(function (_value, key) {
+                if (!activeItemKeys.has(key)) {
+                    stoppedScheduleRuns.delete(key);
+                }
+            });
+
+            controlItemStates.forEach(function (_value, key) {
+                if (!activeItemKeys.has(key)) {
+                    controlItemStates.delete(key);
+                }
+            });
+
+            outputGroups.forEach(function (group) {
+                var activeRequests = group.states.filter(function (state) {
+                    return state === 1;
+                }).length;
+
+                var combinedState = activeRequests > 0 ? 1 : 0;
+                var lastState = outputStates[group.outputKey];
+
+                if (node.outputMode === "always" || forceOutput || lastState !== combinedState) {
+                    outputStates[group.outputKey] = combinedState;
+
+                    var controlType = group.controlTypes.size === 1
+                        ? Array.from(group.controlTypes)[0]
+                        : "combined";
+
+                    outputs[group.outputNumber - 1] = {
+                        payload: Boolean(combinedState),
+                        topic: group.outputKey,
+                        output: group.outputKey,
+                        outputNumber: group.outputNumber,
+                        controlType: controlType,
+                        activeRequests: activeRequests,
+                        totalRequests: group.states.length,
+                        name: group.names.length === 1
+                            ? group.names[0]
+                            : group.outputKey + " (" + group.names.length + " commands)"
+                    };
+                }
+
+                statusSummary.push(
+                    group.outputKey + ": " +
+                    (combinedState ? "ON" : "OFF") +
+                    " (" + activeRequests + "/" + group.states.length + " active)"
+                );
+            });
+
+            if (closed) {
+                return;
+            }
+
+            if (statusSummary.length === 0) {
+                var names = Object.keys(latestStore);
+
+                if (names.length === 0) {
+                    setStatus("yellow", "ring", "waiting for configStore");
+                } else {
+                    setStatus("blue", "dot", "config stored: " + names.join(", "));
+                }
+
+                return;
+            }
+
+            node.send(outputs);
+
+            setStatus(
+                isOffline ? "yellow" : "blue",
+                "dot",
+                (isOffline ? "Offline: " : "") + statusSummary.join(" | ")
+            );
+        }
+
+        function storeLatestPayload(msg) {
+            var payload = safeParseJson(msg.payload);
+
+            if (payload && typeof payload === "object" && !Array.isArray(payload)) {
+                latestPayload = payload;
+            } else {
+                latestPayload = {};
+            }
+        }
+
+        function handleGetRequest(msg) {
+            var payload = safeParseJson(msg.payload);
+
+            if (msg.getConfigStore === true) {
+                sendConfigSnapshot("requested");
+                return true;
+            }
+
+            if (payload && typeof payload === "object") {
+                if (payload.getConfigStore === true || payload.configStoreGet === true) {
+                    sendConfigSnapshot("requested");
+                    return true;
+                }
+            }
+
+            return false;
+        }
+
+        loadFromDisk();
+
+        if (Object.keys(latestStore).length > 0) {
+            setStatus("blue", "dot", "loaded saved config");
+        } else {
+            setStatus("yellow", "ring", "waiting for configStore");
+        }
+
+        var timer = setInterval(function () {
+            runConfigStore(false, false);
+        }, node.tickSeconds * 1000);
+
+        setTimeout(function () {
+            runConfigStore(false, true);
+        }, 500);
+
+        node.on("input", function (msg, send, done) {
+            send = send || function () {
+                node.send.apply(node, arguments);
+            };
+
+            if (closed) {
+                if (done) {
+                    done();
+                }
+
+                return;
+            }
+
+            try {
+                if (handleGetRequest(msg)) {
+                    if (done) {
+                        done();
+                    }
+
+                    return;
+                }
+
+                var configStore = extractConfigStore(msg);
+
+                if (configStore) {
+                    var savedNames = storeConfig(configStore);
+
+                    if (savedNames.length > 0) {
+                        setStatus("blue", "dot", "saved: " + savedNames.join(", "));
+
+                        if (node.emitConfigOnUpdate) {
+                            sendConfigSnapshot("updated");
+                        }
+
+                        runConfigStore(false, true);
+                    } else {
+                        setStatus("yellow", "ring", "configStore ignored");
+                    }
+
+                    if (done) {
+                        done();
+                    }
+
+                    return;
+                }
+
+                storeLatestPayload(msg);
+                runConfigStore(false, false);
+
+                if (done) {
+                    done();
+                }
+            } catch (err) {
+                setStatus("red", "ring", "config store error");
+                node.error("3DM Config Store error: " + (err.message || err), msg);
+
+                if (done) {
+                    done(err);
+                }
+            }
+        });
+
+        node.on("close", function (removed, done) {
+            if (typeof removed === "function") {
+                done = removed;
+            }
+
+            done = done || function () {};
+
+            closed = true;
+            clearInterval(timer);
+            done();
+        });
+    }
+
+    RED.nodes.registerType("3dm-config-store", ThreeDMConfigStoreNode);
+};

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.
+
+## 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.
+
+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.
+- 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
 
-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.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": [
@@ -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": {