@bldgblocks/node-red-contrib-control 0.1.4

package/README.md

@@ -0,0 +1,43 @@
+# node-red-contrib-buildingblocks-control
+Sedona-inspired control nodes for stateful logic.
+
+This is a rather large node collection. Contributions are appreciated.
+
+## Intro
+This is intended for HVAC usage but the logic applies to anything. 
+
+Industry visual scripting tools, with Sedona being the original open source solution, use a stateful multi-in/out architecture. Any paradigm can be used in NodeRED but you need to standardize on how things are done. 
+
+Logic should be general, combinable, reusable and easily updated. NodeRED is like a blank canvas and I see this project as a way to provide some standardization with the logic. Seemingly simple, foundational, logic functions standardized. It helps me wrap my head around how to get things done and follow flows when I can wire things in branches that store an outcome and the ability to track which inputs are doing what...
+
+There are TONS of fantastic node libraries out there but usually focusing on one area, or even one node. For my purposes, I want a core set of nodes all in one library that work in a certain, stateful way.
+
+- Full status display of many states
+- Full help sections
+- Stateful node operation
+- Multiple inputs through data tagging
+- Many node types. Math, logic, test functions (sqaure wave, sine wave, tick tock, ...), specialized
+- Most nodes utilize the Typed Input type to assign global variables
+- Validation. Runtime validation is relied on in most cases to evaluate Typed Inputs and provides a status message to indicate errors encountered.
+- Node commands, such as 'reset' or 'mode' or changing setpoints via messages.
+
+## How To Use
+Pictures to come.
+
+The help section of every node describes the expected msg.context (data tag) for the intended msg.payload incoming. You can of course do this as you process data through a 'change' block, or use the provided 'contextual label' block which makes it easier to add and remove tags, more compact (especially if label hidden), and more transparent of the data flowing (ALL nodes contain complete status usage). Most nodes use a simple in1, in2, and so on. 
+
+##### Example
+An 'and' block set to 4 slots must recieve `true` values on each inX at some point to evaluate to a `true` output. Where as, an 'or' block set to 4 inputs could have any input trigger a `true` evaluation. However, a remaining `true` would prevent evaluating to `false`. So the flow may look like 4 small tagging nodes configured in1,in2,in3,in4 connecting to the 'and' block and just wiring your branches of logic to those inputs. You can also negate or have multiple connected to an input and you can watch as each comes in to evaluate. Just try to keep it clean.
+
+## Install
+##### Via NodeRED Palette Manager (Not Yet Available)
+
+Search for the package name and add to your project.
+
+##### Via NPM
+```
+# Navigate to Node-RED user directory (varies by installation)
+- $ cd ~/.node-red
+- $ npm install node-red-contrib-buildingblocks-control
+# then restart node-red
+```

package/nodes/accumulate-block.html

@@ -0,0 +1,71 @@
+<script type="text/html" data-template-name="accumulate-block">
+    <div class="form-row">
+        <label for="node-input-name" title="Display name shown on the canvas"><i class="fa fa-tag"></i> Name</label>
+        <input type="text" id="node-input-name" placeholder="Name">
+    </div>
+    <div class="form-row">
+        <label for="node-input-mode" title="Select accumulation mode"><i class="fa fa-cog"></i> Mode</label>
+        <select id="node-input-mode">
+            <option value="true">Accumulate True</option>
+            <option value="false">Accumulate False</option>
+            <option value="flows">Accumulate Flows</option>
+        </select>
+    </div>
+</script>
+
+<script type="text/javascript">
+    RED.nodes.registerType("accumulate-block", {
+        category: "control",
+        color: "#301934",
+        defaults: {
+            name: { value: "" },
+            mode: { value: "true", required: true }
+        },
+        inputs: 1,
+        outputs: 1,
+        inputLabels: ["input"],
+        outputLabels: ["count"],
+        icon: "font-awesome/fa-sort-numeric-asc",
+        paletteLabel: "accumulate",
+        label: function() {
+            if (this.name) return this.name;
+            const modeLabels = {
+                "true": "true accumulate",
+                "false": "false accumulate", 
+                "flows": "flows accumulate"
+            };
+            return modeLabels[this.mode] || "accumulate";
+        }
+    });
+</script>
+
+<script type="text/markdown" data-help-name="accumulate-block">
+Counts consecutive inputs based on the selected mode, resetting on specific conditions.
+
+### Inputs
+: context (string) : Configuration commands = reset (`"reset"` to clear count).
+: payload (boolean) : For `Accumulate True`, `true` increments count, `false` resets; for `Accumulate False`, `false` increments count, `true` resets; ignored in `Accumulate Flows`.
+
+### Outputs
+: payload (number) : Current count based on mode.
+
+### Details
+Counts inputs according to the selected mode 
+- `Accumulate True` counts consecutive `true` `msg.payload` inputs (reset on `false` or explicit reset)
+- `Accumulate False` counts consecutive `false` `msg.payload` inputs (reset on `true` or explicit reset)
+- `Accumulate Flows` counts all valid input messages (reset only on explicit reset). 
+
+Reset via `msg.context = "reset"` with `msg.payload = true` applies immediately;
+
+Used to track sustained events or message frequency.
+
+### Status
+- Green (dot): Configuration
+- Blue (dot): Output sent
+- Red (ring): Errors
+- Yellow (ring): Unknown context
+
+### References
+- [Node-RED Documentation](https://nodered.org/docs/)
+- [GitHub Repository](https://github.com/BldgBlocks/node-red-contrib-buildingblocks-control.git)
+</script>

package/nodes/accumulate-block.js

@@ -0,0 +1,104 @@
+module.exports = function(RED) {
+    function AccumulateBlockNode(config) {
+        RED.nodes.createNode(this, config);
+        const node = this;
+
+        // Initialize runtime state
+        node.runtime = {
+            name: config.name,
+            mode: config.mode,
+            count: 0,
+            lastCount: null
+        };
+
+        // Set initial status
+        node.status({
+            fill: "green",
+            shape: "dot",
+            text: `mode: ${node.runtime.mode}, name: ${node.runtime.name || node.runtime.mode + " accumulate"}`
+        });
+
+        node.on("input", function(msg, send, done) {
+            send = send || function() { node.send.apply(node, arguments); };
+
+            // Guard against invalid msg
+            if (!msg) {
+                node.status({ fill: "red", shape: "ring", text: "missing message" });
+                node.warn("Missing message");
+                if (done) done();
+                return;
+            }
+
+            // Handle reset command with intentional payload requirement
+            if (msg.context === "reset") {
+                if (msg.payload === true) {
+                    count = 0;
+                    updateStatus();
+                    if (done) done();
+                    return;
+                }
+                // payload !== true: treat as normal message, don't reset
+            }
+
+            // Process input based on mode
+            if (node.runtime.mode !== "flows") {
+                // Check for missing payload
+                if (!msg.hasOwnProperty("payload")) {
+                    node.status({ fill: "red", shape: "ring", text: "missing payload" });
+                    node.warn("Missing payload");
+                    if (done) done();
+                    return;
+                }
+
+                // Validate input
+                const inputValue = msg.payload;
+                if (typeof inputValue !== "boolean") {
+                    node.status({ fill: "red", shape: "ring", text: "invalid input" });
+                    node.warn("Invalid input: non-boolean payload");
+                    if (done) done();
+                    return;
+                }
+
+                // Prevent extended time running isues
+                if (node.runtime.count > 9999) {
+                    node.runtime.count = 0;
+                }
+
+                // Accumulate or reset count
+                if (node.runtime.mode === "true") {
+                    if (inputValue === true) {
+                        node.runtime.count++;
+                    } else {
+                        node.runtime.count = 0;
+                    }
+                } else if (node.runtime.mode === "false") {
+                    if (inputValue === false) {
+                        node.runtime.count++;
+                    } else {
+                        node.runtime.count = 0;
+                    }
+                }
+            } else {
+                // flows mode: count all valid messages
+                node.runtime.count++;
+            }
+
+            // Output only if count changed
+            if (node.runtime.lastCount !== node.runtime.count) {
+                node.runtime.lastCount = node.runtime.count;
+                node.status({ fill: "blue", shape: "dot", text: `out: ${node.runtime.count}` });
+                send({ payload: node.runtime.count });
+            } else {
+                node.status({ fill: "blue", shape: "ring", text: `out: ${node.runtime.count}` });
+            }
+
+            if (done) done();
+        });
+
+        node.on("close", function(done) {
+            done();
+        });
+    }
+
+    RED.nodes.registerType("accumulate-block", AccumulateBlockNode);
+};

package/nodes/add-block.html

@@ -0,0 +1,67 @@
+<script type="text/html" data-template-name="add-block">
+    <div class="form-row">
+        <label for="node-input-name" title="Display name shown on the canvas"><i class="fa fa-tag"></i> Name</label>
+        <input type="text" id="node-input-name" placeholder="Name">
+    </div>
+    <div class="form-row">
+        <label for="node-input-slots" title="Number of input slots (positive integer, e.g., 2)"><i class="fa fa-list-ol"></i> Slots</label>
+        <input type="number" id="node-input-slots" placeholder="2" min="2" step="1">
+    </div>
+</script>
+
+<script type="text/javascript">
+    RED.nodes.registerType("add-block", {
+        category: "control",
+        color: "#301934",
+        defaults: {
+            name: { value: "" },
+            slots: {
+                value: 2,
+                required: true,
+                validate: function(v) { return !isNaN(parseInt(v)) && parseInt(v) >= 2; }
+            }
+        },
+        inputs: 1,
+        outputs: 1,
+        inputLabels: ["input"],
+        outputLabels: ["sum"],
+        icon: "font-awesome/fa-plus",
+        paletteLabel: "add",
+        label: function() {
+            return this.name ? `${this.name} (${this.slots})` : `add (${this.slots})`;
+        }
+    });
+</script>
+
+<script type="text/markdown" data-help-name="add-block">
+Sums numeric inputs from multiple slots.
+
+### Inputs
+: context (string) : Configuration commands - `"reset"`, `"slots"` active slots count, `"in<x>"` identifies input slot (e.g., `"in1"`, `"in2"`).
+: payload (number | boolean) : Number for slot input or slots configuration, boolean for reset.
+
+### Outputs
+: payload (number) : Sum of all slot values.
+
+### Details
+Sums numeric `msg.payload` values from slots identified by `msg.context` (e.g., `"in1"`, `"in2"`).
+
+Values persist in context per slot. They may arrive and be set at different times.
+
+Slots (default: 2) are set via editor or `msg.context = "slots"` with positive integer greater than 2.
+
+Inputs default to 0, updated via `msg.context = "inX"`. Resets inputs to 0 via `msg.context = "reset"` with `msg.payload = true`.
+
+Outputs sum for each valid slot update.
+
+### Status
+- Green (dot): Configuration update
+- Blue (dot): State changed
+- Blue (ring): State unchanged
+- Red (ring): Error
+- Yellow: Warning
+
+### References
+- [Node-RED Documentation](https://nodered.org/docs/)
+- [GitHub Repository](https://github.com/BldgBlocks/node-red-contrib-buildingblocks-control.git)
+</script>

package/nodes/add-block.js

@@ -0,0 +1,97 @@
+module.exports = function(RED) {
+    function AddBlockNode(config) {
+        RED.nodes.createNode(this, config);
+        const node = this;
+        
+        // Initialize state
+        node.slots = parseInt(config.slots) || 2;
+        node.inputs = Array(parseInt(config.slots) || 2).fill(0);
+
+        let lastSum = null;
+
+        node.on("input", function(msg, send, done) {
+            send = send || function() { node.send.apply(node, arguments); };
+
+            // Guard against invalid msg
+            if (!msg) {
+                node.status({ fill: "red", shape: "ring", text: "invalid message" });
+                if (done) done();
+                return;
+            }
+
+            // Check for required properties
+            if (!msg.hasOwnProperty("context")) {
+                node.status({ fill: "red", shape: "ring", text: "missing context" });
+                if (done) done();
+                return;
+            }
+
+            if (!msg.hasOwnProperty("payload")) {
+                node.status({ fill: "red", shape: "ring", text: "missing payload" });
+                if (done) done();
+                return;
+            }
+
+            // Handle configuration messages
+            if (msg.context === "reset") {
+                if (typeof msg.payload !== "boolean") {
+                    node.status({ fill: "red", shape: "ring", text: "invalid reset" });
+                    if (done) done();
+                    return;
+                }
+                if (msg.payload === true) {
+                    node.inputs = Array(node.slots).fill(0);
+                    lastSum = null;
+                    node.status({ fill: "green", shape: "dot", text: "state reset" });
+                    if (done) done();
+                    return;
+                }
+            } else if (msg.context === "slots") {
+                let newSlots = parseInt(msg.payload);
+                if (isNaN(newSlots) || newSlots < 1) {
+                    node.status({ fill: "red", shape: "ring", text: "invalid slots" });
+                    if (done) done();
+                    return;
+                }
+                node.slots = newSlots;
+                node.inputs = Array(newSlots).fill(0);
+                lastSum = null;
+                node.status({ fill: "green", shape: "dot", text: `slots: ${node.slots}` });
+                if (done) done();
+                return;
+            } else if (msg.context.startsWith("in")) {
+                let slotIndex = parseInt(msg.context.slice(2)) - 1;
+                if (isNaN(slotIndex) || slotIndex < 0 || slotIndex >= node.slots) {
+                    node.status({ fill: "red", shape: "ring", text: `invalid input slot ${msg.context}` });
+                    if (done) done();
+                    return;
+                }
+                let newValue = parseFloat(msg.payload);
+                if (isNaN(newValue)) {
+                    node.status({ fill: "red", shape: "ring", text: "invalid input" });
+                    if (done) done();
+                    return;
+                }
+                node.inputs[slotIndex] = newValue;
+                // Calculate sum
+                const sum = node.inputs.reduce((acc, val) => acc + val, 0);
+                const isUnchanged = sum === lastSum;
+                node.status({ fill: "blue", shape: isUnchanged ? "ring" : "dot", text: `${msg.context}: ${newValue.toFixed(2)}, sum: ${sum.toFixed(2)}` });
+                lastSum = sum;
+                send({ payload: sum });
+                if (done) done();
+                return;
+            } else {
+                node.status({ fill: "yellow", shape: "ring", text: "unknown context" });
+                if (done) done();
+                return;
+            }
+        });
+
+        node.on("close", function(done) {
+            done();
+        });
+    }
+
+    RED.nodes.registerType("add-block", AddBlockNode);
+};

package/nodes/analog-switch-block.html

@@ -0,0 +1,65 @@
+<!-- UI Template Section: Defines the edit dialog -->
+<script type="text/html" data-template-name="analog-switch-block">
+    <div class="form-row">
+        <label for="node-input-name" title="Display name shown on the canvas"><i class="fa fa-tag"></i> Name</label>
+        <input type="text" id="node-input-name" placeholder="Name">
+    </div>
+    <div class="form-row">
+        <label for="node-input-slots" title="Number of input slots (integer >= 1)"><i class="fa fa-th-list"></i> Slots</label>
+        <input type="number" id="node-input-slots" placeholder="2" min="1" step="1">
+    </div>
+</script>
+
+<!-- JavaScript Section: Registers the node and handles editor logic -->
+<script type="text/javascript">
+    RED.nodes.registerType("analog-switch-block", {
+        category: "control",
+        color: "#301934",
+        defaults: {
+            name: { value: "" },
+            slots: { value: 2, required: true, validate: function(v) { return Number.isInteger(Number(v)) && Number(v) >= 1; } }
+        },
+        inputs: 1,
+        outputs: 1,
+        inputLabels: ["input"],
+        outputLabels: ["output"],
+        icon: "font-awesome/fa-exchange",
+        paletteLabel: "analog switch",
+        label: function() {
+            return this.name ? `${this.name} (${this.slots})` : `analog switch (${this.slots})`;
+        }
+    });
+</script>
+
+<!-- Help Section -->
+<script type="text/markdown" data-help-name="analog-switch-block">
+Selects one numeric input from multiple slots based on a switch value.
+
+### Inputs
+: context (string) : Configures slots (`"slots"`), switch (`"switch"`), or input slot (`"inX"`, e.g., `in1`). Unmatched values trigger error.
+: payload (number | integer) : Number for input slot, integer for slots or switch configuration.
+
+### Outputs
+: payload (number) : Selected input value based on switch setting.
+
+### Properties
+: slots (integer) : Number of input slots (≥ 1). Default 2.
+
+### Details
+Selects one numeric input from multiple slots (`in1`, `in2`, etc.) based on a switch value (1 to slots) 
+set via `msg.context = "switch"` with integer `msg.payload`. Slots configurable via editor or `msg.context = "slots"` with 
+integer `msg.payload` (≥ 1). Inputs default to 0, updated via `msg.context = "inX"` with numeric `msg.payload`. 
+
+Outputs a new `msg.payload` when the active slot is updated, switch changes to a valid slot, or slots change affects the output.
+
+### Status
+- Green (dot): Configuration update
+- Blue (dot): State changed
+- Blue (ring): State unchanged
+- Red (ring): Error
+- Yellow (ring): Warning
+
+### References
+- [Node-RED Documentation](https://nodered.org/docs/)
+- [GitHub Repository](https://github.com/BldgBlocks/node-red-contrib-buildingblocks-control.git)
+</script>

package/nodes/analog-switch-block.js

@@ -0,0 +1,129 @@
+module.exports = function(RED) {
+    function AnalogSwitchBlockNode(config) {
+        RED.nodes.createNode(this, config);
+        const node = this;
+
+        // Initialize runtime state
+        node.runtime = {
+            name: config.name,
+            slots: parseInt(config.slots, 10),
+            inputs: Array(parseInt(config.slots, 10) || 2).fill(0),
+            switch: 1
+        };
+
+        node.on("input", function(msg, send, done) {
+            send = send || function() { node.send.apply(node, arguments); };
+
+            // Guard against invalid message
+            if (!msg) {
+                node.status({ fill: "red", shape: "ring", text: "invalid message" });
+                if (done) done();
+                return;
+            }
+
+            // Validate context
+            if (!msg.hasOwnProperty("context") || typeof msg.context !== "string") {
+                node.status({ fill: "red", shape: "ring", text: "missing context" });
+                if (done) done();
+                return;
+            }
+
+            // Validate payload
+            if (!msg.hasOwnProperty("payload")) {
+                node.status({ fill: "red", shape: "ring", text: "missing payload" });
+                if (done) done();
+                return;
+            }
+
+            let shouldOutput = false;
+            const prevSwitch = node.runtime.switch;
+
+            switch (msg.context) {
+                case "slots":
+                    const slotValue = parseInt(msg.payload, 10);
+                    if (isNaN(slotValue) || slotValue < 1) {
+                        node.status({ fill: "red", shape: "ring", text: "invalid slots" });
+                        if (done) done();
+                        return;
+                    }
+                    node.runtime.slots = slotValue;
+                    const newInputs = Array(node.runtime.slots).fill(0);
+                    for (let i = 0; i < Math.min(node.runtime.inputs.length, node.runtime.slots); i++) {
+                        newInputs[i] = node.runtime.inputs[i];
+                    }
+                    node.runtime.inputs = newInputs;
+                    if (node.runtime.switch > node.runtime.slots) {
+                        node.runtime.switch = 1;
+                        shouldOutput = true;
+                    }
+                    node.status({
+                        fill: "green",
+                        shape: "dot",
+                        text: `slots: ${node.runtime.slots}`
+                    });
+                    break;
+                case "switch":
+                    const switchValue = parseInt(msg.payload, 10);
+                    if (isNaN(switchValue) || switchValue < 1 || switchValue > node.runtime.slots) {
+                        node.status({ fill: "red", shape: "ring", text: "invalid switch" });
+                        if (done) done();
+                        return;
+                    }
+                    node.runtime.switch = switchValue;
+                    shouldOutput = prevSwitch !== node.runtime.switch;
+                    node.status({
+                        fill: "green",
+                        shape: "dot",
+                        text: `switch: ${node.runtime.switch}`
+                    });
+                    break;
+                default:
+                    if (msg.context.startsWith("in")) {
+                        const index = parseInt(msg.context.slice(2), 10);
+                        if (isNaN(index) || index < 1 || index > node.runtime.slots) {
+                            node.status({ fill: "red", shape: "ring", text: `invalid input index ${index}` });
+                            if (done) done();
+                            return;
+                        }
+                        const value = parseFloat(msg.payload);
+                        if (isNaN(value)) {
+                            node.status({ fill: "red", shape: "ring", text: `invalid in${index}` });
+                            if (done) done();
+                            return;
+                        }
+                        node.runtime.inputs[index - 1] = value;
+                        shouldOutput = index === node.runtime.switch;
+                        node.status({
+                            fill: "green",
+                            shape: "dot",
+                            text: `in${index}: ${value.toFixed(2)}`
+                        });
+                    } else {
+                        node.status({ fill: "yellow", shape: "ring", text: "unknown context" });
+                        if (done) done("Unknown context");
+                        return;
+                    }
+                    break;
+            }
+
+            // Output new message if the active slot is updated or switch/slots change affects output
+            if (shouldOutput) {
+                const out = node.runtime.inputs[node.runtime.switch - 1] ?? node.runtime.inputs[0];
+                node.status({
+                    fill: "blue",
+                    shape: "dot",
+                    text: `slots: ${node.runtime.slots}, switch: ${node.runtime.switch}, out: ${out.toFixed(2)}`
+                });
+                send({ payload: out });
+            }
+
+            if (done) done();
+        });
+
+        node.on("close", function(done) {
+            done();
+        });
+    }
+    
+    RED.nodes.registerType("analog-switch-block", AnalogSwitchBlockNode);
+};

package/nodes/and-block.html

@@ -0,0 +1,64 @@
+<script type="text/html" data-template-name="and-block">
+    <div class="form-row">
+        <label for="node-input-name" title="Display name shown on the canvas"><i class="fa fa-tag"></i> Name</label>
+        <input type="text" id="node-input-name" placeholder="Name">
+    </div>
+    <div class="form-row">
+        <label for="node-input-slots" title="Number of boolean inputs (integer ≥ 2)"><i class="fa fa-list"></i> Slots</label>
+        <input type="number" id="node-input-slots" placeholder="2" min="2" step="1">
+    </div>
+</script>
+
+<script type="text/javascript">
+    RED.nodes.registerType("and-block", {
+        category: "control",
+        color: "#301934",
+        defaults: {
+            name: { value: "" },
+            slots: {
+                value: 2,
+                required: true,
+                validate: function(v) {
+                    const num = parseInt(v, 10);
+                    return !isNaN(num) && num >= 2;
+                }
+            }
+        },
+        inputs: 1,
+        outputs: 1,
+        inputLabels: ["input"],
+        outputLabels: ["output"],
+        icon: "font-awesome/fa-check-square-o",
+        paletteLabel: "and",
+        label: function() {
+            return this.name ? `${this.name} (${this.slots})` : `and (${this.slots})`;
+        }
+    });
+</script>
+
+<script type="text/markdown" data-help-name="and-block">
+Computes the logical AND of multiple boolean inputs, outputting a new message with the result.
+
+### Inputs
+: context (string) : Configuration commands - Identifies the input slot (e.g., `"in1"`, `"in2"`).
+: payload (any) : Value for the slot, converted to boolean (`true`, `1` → `true`; `false`, `0`, `null` → `false`).
+
+### Outputs
+: payload (boolean) : `true` if all slots are `true`, `false` otherwise.
+
+### Details
+Evaluates the logical AND of a fixed number of boolean inputs (`slots` ≥ 2, set in editor). 
+
+Each slot is updated via `msg.context = "inX"` (e.g., `"in1"`, `"in2"`) with `msg.payload` converted to boolean. 
+
+### Status
+- Green (dot): Configuration update
+- Blue (dot): State changed
+- Blue (ring): State unchanged
+- Red (ring): Error
+- Yellow (ring): Warning
+
+### References
+- [Node-RED Documentation](https://nodered.org/docs/)
+- [GitHub Repository](https://github.com/BldgBlocks/node-red-contrib-buildingblocks-control.git)
+</script>