@bldgblocks/node-red-contrib-control 0.1.28 → 0.1.30

package/README.md

@@ -24,7 +24,7 @@ There are TONS of fantastic node libraries out there but usually focusing on one
 - Node commands, such as 'reset' or 'mode' or changing setpoints via messages.
 
 ## How To Use
-Pictures to come.
+<img width="1049" height="131" alt="Screenshot_20251204_194633" src="https://github.com/user-attachments/assets/d29fb46d-c23d-4185-a9e7-f01ff1efdb81" />
 
 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. 
 

package/nodes/frequency-block.html

@@ -39,9 +39,11 @@ Measures pulse frequency from boolean rising edges.
 
 ### Details
 Measures pulse frequency from rising edges in `msg.payload` (boolean, `true` for pulse), outputting a message with 
-`msg.payload = { ppm, pph, ppd }` (pulses per minute, hour, day) on the second and subsequent rising edges 
+`msg.payload = { ppm, pph, ppd, duty }` (pulses per minute, hour, day, duty/hr) on the second and subsequent rising edges 
 (first edge sets baseline). Resets state via `msg.context = "reset"` with `msg.payload = true`.
 
+Outputs a duty cycle in percentage of the last 60 minutes that the signal has been true.
+
 ### Status
 - Green (dot): Configuration
 - Blue (dot): Output, no alarm

package/nodes/frequency-block.js

@@ -11,7 +11,9 @@ module.exports = function(RED) {
             completeCycle: false,
             ppm: 0,
             pph: 0,
-            ppd: 0
+            ppd: 0,
+            pulseHistory: [], // Array to store {start: timestamp, duration: ms}
+            currentPulseStart: 0
         };
 
         node.status({ 
@@ -20,7 +22,37 @@ module.exports = function(RED) {
             text: "awaiting first pulse" 
         });
 
-        // FEATURE: I want a runtime percentage per hour duty cycle
+        function calculateDutyCycle(now, currentInputValue) {
+            const oneHourAgo = now - 3600000;
+            
+            // Clean up pulses older than 1 hour
+            node.runtime.pulseHistory = node.runtime.pulseHistory.filter(pulse => {
+                return (pulse.start + pulse.duration) > oneHourAgo;
+            });
+
+            let totalOnTime = 0;
+            
+            // Sum all pulse durations within the last hour
+            node.runtime.pulseHistory.forEach(pulse => {
+                const pulseEnd = pulse.start + pulse.duration;
+                const effectiveStart = Math.max(pulse.start, oneHourAgo);
+                const effectiveEnd = Math.min(pulseEnd, now);
+                if (effectiveEnd > effectiveStart) {
+                    totalOnTime += (effectiveEnd - effectiveStart);
+                }
+            });
+
+            // Add current ongoing pulse if active
+            if (currentInputValue && node.runtime.currentPulseStart > 0) {
+                const currentPulseTime = Math.max(node.runtime.currentPulseStart, oneHourAgo);
+                totalOnTime += (now - currentPulseTime);
+            }
+
+            return {
+                dutyCycle: (totalOnTime / 3600000) * 100,
+                onTime: totalOnTime
+            };
+        }
 
         node.on("input", function(msg, send, done) {
             send = send || function() { node.send.apply(node, arguments); };
@@ -52,6 +84,8 @@ module.exports = function(RED) {
                         node.runtime.ppm = 0;
                         node.runtime.pph = 0;
                         node.runtime.ppd = 0;
+                        node.runtime.pulseHistory = [];
+                        node.runtime.currentPulseStart = 0;
                         node.status({ fill: "green", shape: "dot", text: "reset" });
                     }
                     if (done) done();
@@ -77,16 +111,39 @@ module.exports = function(RED) {
                 return;
             }
 
+            const now = Date.now();
+
+            // Track pulse edges for duty cycle
+            if (inputValue && !node.runtime.lastIn) {
+                // Rising edge - start new pulse
+                node.runtime.currentPulseStart = now;
+            } else if (!inputValue && node.runtime.lastIn) {
+                // Falling edge - record completed pulse
+                if (node.runtime.currentPulseStart > 0) {
+                    const duration = now - node.runtime.currentPulseStart;
+                    node.runtime.pulseHistory.push({
+                        start: node.runtime.currentPulseStart,
+                        duration: duration
+                    });
+                    node.runtime.currentPulseStart = 0;
+                }
+            }
+
+            // Calculate duty cycle for the rolling hour
+            const dutyData = calculateDutyCycle(now, inputValue);
+
             // Initialize output
             let output = {
                 ppm: node.runtime.ppm,
                 pph: node.runtime.pph,
-                ppd: node.runtime.ppd
+                ppd: node.runtime.ppd,
+                dutyCycle: dutyData.dutyCycle.toFixed(2),
+                onTime: dutyData.onTime
             };
 
             // Detect rising edge
-            if (inputValue && !node.runtime.lastIn) { // Rising edge: true and lastIn was false
-                let now = Date.now();
+            if (inputValue && !node.runtime.lastIn) { 
+                // Rising edge: true and lastIn was false
                 if (!node.runtime.completeCycle) {
                     node.runtime.completeCycle = true;
                 } else {
@@ -114,14 +171,14 @@ module.exports = function(RED) {
                 node.status({
                     fill: "blue",
                     shape: "dot",
-                    text: `input: ${inputValue}, ppm: ${output.ppm.toFixed(2)}, pph: ${output.pph.toFixed(2)}, ppd: ${output.ppd.toFixed(2)}`
+                    text: `input: ${inputValue}, ppm: ${output.ppm.toFixed(2)}, pph: ${output.pph.toFixed(2)}, ppd: ${output.ppd.toFixed(2)}, duty: ${output.dutyCycle}%`
                 });
                 send({ payload: output });
             } else {
                 node.status({
                     fill: "blue",
                     shape: "ring",
-                    text: `input: ${inputValue}, ppm: ${node.runtime.ppm.toFixed(2)}, pph: ${node.runtime.pph.toFixed(2)}, ppd: ${node.runtime.ppd.toFixed(2)}`
+                    text: `input: ${inputValue}, ppm: ${node.runtime.ppm.toFixed(2)}, pph: ${node.runtime.pph.toFixed(2)}, ppd: ${node.runtime.ppd.toFixed(2)}, duty: ${output.dutyCycle}%`
                 });
             }
 

package/nodes/global-getter.html

@@ -0,0 +1,128 @@
+<script type="text/html" data-template-name="global-getter">
+    <div class="form-row">
+        <label for="node-input-name"><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-targetNode"><i class="fa fa-crosshairs"></i> Source</label>
+        <input type="text" id="node-input-targetNode" style="width: calc(70% - 45px);">
+        <button id="node-config-find-source" class="editor-button" style="margin-left: 5px; width: 40px;" title="Find Source Node">
+            <i class="fa fa-search"></i>
+        </button>
+    </div>
+    
+    <div class="form-row">
+        <label for="node-input-outputProperty"><i class="fa fa-arrow-right"></i> Output</label>
+        <input type="text" id="node-input-outputProperty" placeholder="payload" style="width:70%;">
+    </div>
+
+    <div class="form-tips">
+        <b>Note:</b> Targeting by Node ID allows the source path to change without breaking this link.
+    </div>
+</script>
+
+<script type="text/javascript">
+    RED.nodes.registerType('global-getter', {
+        category: 'control',
+        color: '#3FADB5',
+        defaults: {
+            name: { value: "" },
+            targetNode: { value: "", required: true },
+            outputProperty: { value: "payload", required: true }
+        },
+        inputs: 1,
+        outputs: 1,
+        icon: "font-awesome/fa-align-left",
+        label: function() {
+            if (this.targetNode) {
+                const target = RED.nodes.node(this.targetNode);
+                if (target) {
+                    let lbl = target.path || target.name;
+                    if(lbl && lbl.includes(":")) {
+                        lbl = lbl.split(":")[3];
+                    }
+                    return "Get: " + lbl;
+                }
+            }
+            return this.name || "global get";
+        },
+        paletteLabel: "global get",
+        oneditprepare: function() {
+            const node = this;
+            
+            // 1. Populate Dropdown
+            let candidateNodes = [];
+            RED.nodes.eachNode(function(n) {
+                if (n.type === 'global-setter') {
+                    let displayPath = n.path || "No Path";
+
+                    candidateNodes.push({
+                        value: n.id,
+                        label: displayPath + (n.name ? ` (${n.name})` : "")
+                    });
+                }
+            });
+
+            candidateNodes.sort((a, b) => a.label.localeCompare(b.label));
+
+            $("#node-input-targetNode").typedInput({
+                types: [{
+                    value: "target",
+                    options: candidateNodes
+                }]
+            });
+
+            // 2. Output Property Selector
+            $("#node-input-outputProperty").typedInput({
+                types: ['msg']
+            });
+
+            // 3. Find Button Logic
+            $("#node-config-find-source").on("click", function() {
+                const selectedId = $("#node-input-targetNode").val();
+                if (selectedId) {
+                    // Node-RED API to jump to a node
+                    RED.view.reveal(selectedId);
+                } else {
+                    RED.notify("Please select a source node first.", "warning");
+                }
+            });
+        }
+    });
+</script>
+
+<!-- Help Section -->
+<script type="text/markdown" data-help-name="global-getter">
+Manage a global variable in a repeatable way.
+
+### Inputs 
+: source (any) : Select the source 'global-setter' node to get the variable from.
+: output (string) : The output property to store the variable value in.
+
+### Outputs
+: payload (any) : The global variable value
+: topic (string) : The variable name/path used to store the value.
+: units (string) : The units associated with the value, if any. Also supports nested units at `msg.<inputProperty>.units`.
+: metadata (object) : Metadata about the global variable (store, path).
+
+### Details
+Global variables are meant to be retrieved in other places, this necessarily means managing the same string in multiple places. 
+
+This node allows you to get a global variable while supporting rename and deletion.
+
+It links to a `global-setter` node by Node ID, so if that node's path is changed, this node will still work.
+
+Configurable output property allows chaining multiple getters in series if only interested in the value.
+
+### 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/global-getter.js

@@ -0,0 +1,51 @@
+module.exports = function(RED) {
+    function GlobalGetterNode(config) {
+        RED.nodes.createNode(this, config);
+        const node = this;
+        node.targetNodeId = config.targetNode;
+        node.outputProperty = config.outputProperty || "payload";
+
+        node.on('input', function(msg) {
+            const setterNode = RED.nodes.getNode(node.targetNodeId);
+
+            if (setterNode && setterNode.varName) {
+                const globalContext = node.context().global;
+                const storedObject = globalContext.get(setterNode.varName, setterNode.storeName);
+                
+                if (storedObject !== undefined) {
+                    let val = storedObject;
+                    let units = null;
+                    let meta = {};
+
+                    // CHECK: Is this wrapper format?
+                    if (storedObject && typeof storedObject === 'object' && storedObject.hasOwnProperty('value') && storedObject.hasOwnProperty('meta')) {
+                        // Yes: Unwrap it
+                        val = storedObject.value;
+                        units = storedObject.units;
+                        meta = storedObject.meta;
+                    } else {
+                        // Legacy/Raw: Metadata is limited
+                        meta = { path: setterNode.varName, legacy: true };
+                    }
+                    
+                    RED.util.setMessageProperty(msg, node.outputProperty, val);
+                    
+                    msg.topic = setterNode.varName;
+                    
+                    msg.units = units;
+
+                    msg.metadata = meta; 
+                    
+                    node.status({ fill: "blue", shape: "dot", text: `Get: ${val}` });
+                    node.send(msg);
+                } else {
+                    node.status({ fill: "red", shape: "ring", text: "Global variable undefined" });
+                }
+            } else {
+                node.warn("Source node not found or not configured.");
+                node.status({ fill: "red", shape: "ring", text: "Source node not found" });
+            }
+        });
+    }
+    RED.nodes.registerType("global-getter", GlobalGetterNode);
+}

package/nodes/global-setter.html

@@ -0,0 +1,83 @@
+<script type="text/html" data-template-name="global-setter">
+    <div class="form-row">
+        <label for="node-input-name"><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-path"><i class="fa fa-sitemap"></i> Global Path</label>
+        <input type="text" id="node-input-path" style="width: 70%;" placeholder="furnace/outputs/heat">
+    </div>
+    <div class="form-row">
+        <label for="node-input-property"><i class="fa fa-ellipsis-h"></i> Input Property</label>
+        <input type="text" id="node-input-property" style="width:70%;">
+    </div>
+    <div class="form-tips">
+        <b>Note:</b> Use the dropdown inside the Path input to select a specific Context Store. 
+        When this node is redeployed or deleted, it will automatically remove the variable from memory.
+    </div>
+</script>
+
+<script type="text/javascript">
+    RED.nodes.registerType('global-setter', {
+        category: 'control',
+        color: '#E2D96E',
+        defaults: {
+            name: { value: "" },
+            path: { value: "", required: true },
+            property: { value: "payload", required: true }
+        },
+        inputs: 1,
+        outputs: 1,
+        icon: "font-awesome/fa-align-right",
+        label: function() {
+            let lbl = this.path;
+            if (lbl && lbl.startsWith("#") && lbl.includes(":")) {
+                lbl = lbl.split(":")[3];
+            }
+            return this.name || "Set: " + lbl || "global set";
+        },
+        paletteLabel: "global set",
+        oneditprepare: function() {
+            // RESTRICT TO GLOBAL ONLY
+            $("#node-input-path").typedInput({
+                types: ['global']
+            });
+
+            // Input Property Selector
+            $("#node-input-property").typedInput({
+                types: ['msg']
+            });
+        }
+    });
+</script>
+
+<!-- Help Section -->
+<script type="text/markdown" data-help-name="global-setter">
+Manage a global variable in a repeatable way.
+
+### Inputs 
+: payload (any) : Input payload is passed through unchanged.
+: property (string) : The input property where the value is taken from.
+: units (string) : The units associated with the value, if any. Also supports nested units at `msg.<inputProperty>.units`.
+
+### Outputs
+: payload (any) : Original payload.
+
+### Details
+Global variables are meant to be retrieved in other places, this necessarily means managing the same string in multiple places. 
+
+This node allows you to set a global variable in one place, and retrieve it elsewhere using the `global-getter` node while supporting rename and deletion.
+
+When this node is deleted or the flow is redeployed, it will automatically remove (prune) the variable from the selected Context Store.
+
+### 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/global-setter.js

@@ -0,0 +1,61 @@
+module.exports = function(RED) {
+    function GlobalSetterNode(config) {
+        RED.nodes.createNode(this, config);
+        const node = this;
+        
+        const parsed = RED.util.parseContextStore(config.path);
+        
+        node.varName = parsed.key;
+        node.storeName = parsed.store;
+        node.inputProperty = config.property;
+
+        node.on('input', function(msg) {
+            if (node.varName) {
+                // READ from the configured property
+                const valueToStore = RED.util.getMessageProperty(msg, node.inputProperty);
+
+                if (valueToStore !== undefined) {
+                    const globalContext = node.context().global;
+
+                    // 1. Try to find units in the standard location (msg.units)
+                    // 2. If not found, check if the input property itself is an object containing .units
+                    let capturedUnits = msg.units; 
+                    
+                    // Optional: Deep check if msg.payload was an object that contained units
+                    if (!capturedUnits && typeof valueToStore === 'object' && valueToStore !== null && valueToStore.units) {
+                         capturedUnits = valueToStore.units;
+                    }
+                    
+                    // Create wrapper with simplified metadata
+                    const storedObject = {
+                        value: valueToStore,
+                        topic: node.varName,
+                        units: capturedUnits,
+                        meta: {
+                            sourceId: node.id,
+                            sourceName: node.name || config.path,
+                            sourcePath: node.varName,
+                            lastSet: new Date().toISOString()
+                        }
+                    };
+                    
+                    node.status({ fill: "blue", shape: "dot", text: `Set: ${storedObject.value}` });
+                    globalContext.set(node.varName, storedObject, node.storeName);
+                }
+            }
+
+            node.send(msg);
+        });
+
+        // CLEANUP
+        node.on('close', function(removed, done) {
+            // Do NOT prune if Node-RED is simply restarting or deploying.
+            if (removed && node.varName) {
+                const globalContext = node.context().global;
+                globalContext.set(node.varName, undefined, node.storeName); 
+            }
+            done();
+        });
+    }
+    RED.nodes.registerType("global-setter", GlobalSetterNode);
+}

package/nodes/units-block.js

@@ -41,7 +41,7 @@ module.exports = function(RED) {
             unit: config.unit
         };
 
-        // Validate configuration (Req 8)
+        // Validate configuration
         if (!validUnits.includes(node.runtime.unit)) {
             node.runtime.unit = "°F";
             node.status({ fill: "red", shape: "ring", text: "invalid unit, using °F" });
@@ -83,11 +83,12 @@ module.exports = function(RED) {
                 }
 
                 // Process input
-                const outputMsg = RED.util.cloneMessage(msg);
                 const payloadPreview = msg.payload !== null ? (typeof msg.payload === "number" ? msg.payload.toFixed(2) : JSON.stringify(msg.payload).slice(0, 20)) : "none";
 
                 node.status({ fill: "blue", shape: "dot", text: `in: ${payloadPreview} unit: ${node.runtime.unit}` });
-                send(outputMsg);
+
+                msg.units = node.runtime.unit;
+                send(msg);
                 if (done) done();
             } catch (error) {
                 node.status({ fill: "red", shape: "ring", text: "processing error" });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bldgblocks/node-red-contrib-control",
-  "version": "0.1.28",
+  "version": "0.1.30",
   "description": "Sedona-inspired control nodes for Node-RED",
   "keywords": [ "node-red", "sedona", "control", "hvac" ],
   "files": ["nodes/*.js", "nodes/*.html"],
@@ -31,6 +31,8 @@
         "edge-block": "nodes/edge-block.js",
         "enum-switch-block": "nodes/enum-switch-block.js",
         "frequency-block": "nodes/frequency-block.js",
+        "global-getter": "nodes/global-getter.js",
+        "global-setter": "nodes/global-setter.js",
         "hysteresis-block": "nodes/hysteresis-block.js",
         "interpolate-block": "nodes/interpolate-block.js",
         "latch-block": "nodes/latch-block.js",