@bldgblocks/node-red-contrib-control 0.1.33 → 0.1.36

package/nodes/history-config.html

@@ -230,7 +230,19 @@
 </script>
 
 <script type="text/markdown" data-help-name="history-config">
-Store configuration for history series selections.
+Configuration node for the History Collector. Defines storage behavior and data retention policies.
 
+### Details
 
+This node does not process messages directly. It serves as a configuration reference for one or more History Collector nodes. The properties you set here determine how data is collected, stored, and aged out of the history buffer.
+
+Configure the node in the editor panel on the right.
+
+### Status
+- Green (dot): Configuration valid
+- Red (ring): Error in configuration
+
+### References
+- [Node-RED Documentation](https://nodered.org/docs/)
+- [GitHub Repository](https://github.com/BldgBlocks/node-red-contrib-buildingblocks-control.git)
 </script>

package/nodes/history-service.html

@@ -0,0 +1,84 @@
+<script type="text/html" data-template-name="history-service">
+    <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-historyConfig" title="History configuration to relay events from"><i class="fa fa-database"></i> History Config</label>
+        <input type="text" id="node-input-historyConfig">
+    </div>
+</script>
+
+<script type="text/javascript">
+    RED.nodes.registerType("history-service", {
+        category: "bldgblocks history",
+        color: "#b9f2ff",
+        defaults: {
+            name: { value: "" },
+            historyConfig: {
+                value: "",
+                required: true,
+                type: "history-config"
+            }
+        },
+        inputs: 0,
+        outputs: 1,
+        outputLabels: ["records"],
+        icon: "font-awesome/fa-database",
+        paletteLabel: "history-service",
+        label: function() {
+            const historyNode = RED.nodes.node(this.historyConfig);
+            const configName = historyNode ? historyNode.name : "unknown";
+            return this.name ? `${this.name} (${configName})` : `history-service (${configName})`;
+        }
+    });
+</script>
+
+<script type="text/markdown" data-help-name="history-service">
+Event relay for history collectors.
+
+### Purpose
+Receives events emitted by **history-collector** nodes and outputs them as individual records. Acts as an event-to-message bridge, allowing collectors to emit data without needing output wires.
+
+### Configuration
+- **History Config**: The history-config node to relay events from
+
+### Outputs
+: payload (object) : History record object containing:
+  - `measurement` (string): Measurement name
+  - `timestamp` (number): Nanosecond Unix timestamp
+  - `fields` (object): Values (typically `{value: number}`)
+  - `tags` (object): Metadata tags including `historyGroup`
+  - `lineProtocol` (string): Pre-formatted InfluxDB line protocol
+  - `seriesName` (string): Original series name from collector
+  - `historyConfigId` (string): Config ID
+  - `historyConfigName` (string): Config name
+
+### Details
+This node listens for events emitted by all **history-collector** nodes configured with the same history-config. Each incoming record is output immediately.
+
+**Typical wiring**:
+```
+[history-collector] ──(event)──> [history-service] ──> [join] ──> [influxdb batch]
+                                                          (batches)
+```
+
+Use the **join** node to batch records if needed:
+- Set join mode: "Custom"
+- Build: "Array"
+- Count: number of records to batch (e.g., 5000)
+- Or timeout: seconds to wait before sending partial batch
+
+This design decouples collection from storage and lets you choose batching strategy.
+
+### Status
+- Green (dot): Ready and listening
+- Blue (dot): Just relayed a record
+- Red (ring): Configuration error
+
+### References
+- [history-collector](history-collector.html) - Emits events to this service
+- [history-config](history-config.html) - Configuration node
+- [Node-RED join node](https://nodered.org/docs/nodes/core/flow/join) - For batching
+- [Node-RED Documentation](https://nodered.org/docs/)
+</script>

package/nodes/history-service.js

@@ -0,0 +1,52 @@
+module.exports = function(RED) {
+    const utils = require("./utils")(RED);
+
+    function HistoryServiceNode(config) {
+        RED.nodes.createNode(this, config);
+        this.historyConfig = RED.nodes.getNode(config.historyConfig);
+        const node = this;
+
+        // Validate configuration
+        if (!node.historyConfig) {
+            utils.setStatusError(node, "missing history config");
+            return;
+        }
+
+        // Generate matching event name based on history-config ID
+        const eventName = `bldgblocks:history:${node.historyConfig.id}`;
+
+        // Listen for events from history-collector nodes with this config
+        const eventListener = (eventData) => {
+            // Guard against invalid event data
+            if (!eventData || typeof eventData !== 'object') {
+                utils.setStatusError(node, "invalid event data");
+                node.warn("Invalid event data received");
+                return;
+            }
+
+            // Create output message with the event data as payload
+            // Preserve topic if it exists in the event data
+            const msg = { 
+                payload: eventData,
+                topic: eventData.topic
+            };
+            
+            node.send(msg);
+            
+            // Update status
+            utils.setStatusChanged(node, `relayed: ${eventData.seriesName || 'data'}`);
+        };
+
+        // Subscribe to events
+        RED.events.on(eventName, eventListener);
+        utils.setStatusOK(node, `listening on ${node.historyConfig.name}`);
+
+        node.on("close", function(done) {
+            // Unsubscribe from events on close
+            RED.events.off(eventName, eventListener);
+            done();
+        });
+    }
+
+    RED.nodes.registerType("history-service", HistoryServiceNode);
+};

package/nodes/hysteresis-block.html

@@ -4,6 +4,10 @@
         <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-inputProperty" title="Message property to read input from"><i class="fa fa-folder-open"></i> Input Property</label>
+        <input type="text" id="node-input-inputProperty" placeholder="payload">
+    </div>
     <div class="form-row">
         <label for="node-input-upperLimit"><i class="fa fa-arrow-up"></i> Upper Limit (turn on)</label>
         <input type="text" id="node-input-upperLimit" placeholder="50">
@@ -34,6 +38,7 @@
     color: "#301934",
     defaults: {
         name: { value: "" },
+        inputProperty: { value: "payload" },
         upperLimit: { value: 50, required: true },
         upperLimitType: { value: "num" },
         lowerLimit: { value: 30, required: true },

package/nodes/hysteresis-block.js

@@ -5,6 +5,7 @@ module.exports = function(RED) {
         RED.nodes.createNode(this, config);
         const node = this;
         node.name = config.name;
+        node.inputProperty = config.inputProperty || "payload";
         node.state = "within";
         node.isBusy = false;
         node.upperLimit = parseFloat(config.upperLimit);
@@ -16,7 +17,7 @@ module.exports = function(RED) {
             send = send || function() { node.send.apply(node, arguments); };
 
             if (!msg) {
-                node.status({ fill: "red", shape: "ring", text: "invalid message" });
+                utils.setStatusError(node, "invalid message");
                 if (done) done();
                 return;
             }
@@ -27,7 +28,7 @@ module.exports = function(RED) {
                 // Check busy lock
                 if (node.isBusy) {
                     // Update status to let user know they are pushing too fast
-                    node.status({ fill: "yellow", shape: "ring", text: "busy - dropped msg" });
+                    utils.setStatusBusy(node, "busy - dropped msg");
                     if (done) done(); 
                     return;
                 }
@@ -107,27 +108,27 @@ module.exports = function(RED) {
                     const value = parseFloat(msg.payload);
                     if (!isNaN(value) && value >= 0) {
                         node.upperLimitThreshold = value;
-                        node.status({ fill: "green", shape: "dot", text: `upperLimitThreshold: ${value}` });
+                        utils.setStatusOK(node, `upperLimitThreshold: ${value}`);
                     }
                 } else if (msg.context === "lowerLimitThreshold") {
                     const value = parseFloat(msg.payload);
                     if (!isNaN(value) && value >= 0) {
                         node.lowerLimitThreshold = value;
-                        node.status({ fill: "green", shape: "dot", text: `lowerLimitThreshold: ${value}` });
+                        utils.setStatusOK(node, `lowerLimitThreshold: ${value}`);
                     }
                 }
                 if (done) done();
                 return;
             }
 
-            if (!msg.hasOwnProperty("payload")) {
-                node.status({ fill: "red", shape: "ring", text: "missing payload" });
-                if (done) done();
-                return;
+            let inputValue;
+            try {
+                inputValue = parseFloat(RED.util.getMessageProperty(msg, node.inputProperty));
+            } catch (err) {
+                inputValue = NaN;
             }
-            const inputValue = parseFloat(msg.payload);
             if (isNaN(inputValue)) {
-                node.status({ fill: "red", shape: "ring", text: "invalid payload" });
+                utils.setStatusError(node, "invalid input");
                 if (done) done();
                 return;
             }
@@ -140,7 +141,7 @@ module.exports = function(RED) {
 
             // Add validation to ensure numbers
             if (isNaN(upperTurnOn) || isNaN(upperTurnOff) || isNaN(lowerTurnOn) || isNaN(lowerTurnOff)) {
-                node.status({ fill: "red", shape: "ring", text: "invalid limits calculation" });
+                utils.setStatusError(node, "invalid limits calculation");
                 if (done) done();
                 return;
             }
@@ -179,11 +180,7 @@ module.exports = function(RED) {
                 { payload: newState === "below" }
             ];
 
-            node.status({
-                fill: "blue",
-                shape: "dot",
-                text: `in: ${inputValue.toFixed(2)}, state: ${newState}`
-            });
+            utils.setStatusChanged(node, `in: ${inputValue.toFixed(2)}, state: ${newState}`);
 
             node.state = newState;
             send(output);

package/nodes/interpolate-block.html

@@ -3,6 +3,10 @@
         <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-inputProperty" title="Message property to read input from"><i class="fa fa-folder-open"></i> Input Property</label>
+        <input type="text" id="node-input-inputProperty" placeholder="payload">
+    </div>
     <div class="form-row">
         <label for="node-input-points" title="Default points table for interpolation (array of {x, y} objects, ≥2 points)"><i class="fa fa-table"></i> Points</label>
         <textarea id="node-input-points" placeholder='[{"x": 0, "y": 0}, {"x": 100, "y": 100}]' style="height: 100px;"></textarea>
@@ -15,6 +19,7 @@
         color: "#301934",
         defaults: {
             name: { value: "" },
+            inputProperty: { value: "payload" },
             points: {
                 value: JSON.stringify([{ x: 0, y: 0 }, { x: 100, y: 100 }], null, 2),
                 required: true,
@@ -43,11 +48,24 @@
 </script>
 
 <script type="text/markdown" data-help-name="interpolate-block">
-Linearly interpolates a numeric input using a configurable points table.
+Linearly interpolates numeric input from a configured property using a points table.
 
 ### Inputs
+: input-property (number) : Numeric value to interpolate, read from the configured Input Property.
 : context (string) : Configures points table (`"points"`).
-: payload (number | array) : Number for interpolation, or array of `{x, y}` objects for points configuration.
+: payload (array, for context) : Array of `{x, y}` objects for points configuration.
+
+### Outputs
+: payload (number) : Interpolated output value.
+
+### Properties
+: name (string) : Display name in editor.
+: inputProperty (string) : Message property to read input from (default: `payload`). Supports nested properties (e.g., `data.value`).
+: points (array) : Array of `{x, y}` objects defining the interpolation curve (minimum 2 points).
+
+### Details
+Linearly interpolates numeric input (read from the configured **Input Property**, default: `msg.payload`) using a configurable points table.
+Points can be updated dynamically via `msg.context = "points"` with an array of `{x, y}` objects in `msg.payload`.
 
 ### Outputs
 : payload (number) : Interpolated output value.

package/nodes/interpolate-block.js

@@ -1,34 +1,31 @@
 module.exports = function(RED) {
+    const utils = require('./utils')(RED);
     function InterpolateBlockNode(config) {
         RED.nodes.createNode(this, config);
         
         const node = this;
         
         // Initialize runtime state
-        node.runtime = {
-            name: config.name,
-            points: null,
-            lastOutput: null
-        };
+        // Initialize state
+        node.name = config.name;
+        node.inputProperty = config.inputProperty || "payload";
+        node.points = null;
+        node.lastOutput = null;
 
         // Initialize points
         try {
-            node.runtime.points = config.points ? JSON.parse(config.points) : [{ x: 0, y: 0 }, { x: 100, y: 100 }];
-            if (!Array.isArray(node.runtime.points) || node.runtime.points.length < 2 ||
-                !node.runtime.points.every(p => typeof p.x === "number" && !isNaN(p.x) &&
+            node.points = config.points ? JSON.parse(config.points) : [{ x: 0, y: 0 }, { x: 100, y: 100 }];
+            if (!Array.isArray(node.points) || node.points.length < 2 ||
+                !node.points.every(p => typeof p.x === "number" && !isNaN(p.x) &&
                                                 typeof p.y === "number" && !isNaN(p.y))) {
-                node.runtime.points = [{ x: 0, y: 0 }, { x: 100, y: 100 }];
-                node.status({ fill: "red", shape: "ring", text: "invalid points, using default" });
+                node.points = [{ x: 0, y: 0 }, { x: 100, y: 100 }];
+                utils.setStatusError(node, "invalid points, using default");
             } else {
-                node.status({
-                    fill: "green",
-                    shape: "dot",
-                    text: `name: ${node.runtime.name}, points: ${node.runtime.points.length}`
-                });
+                utils.setStatusOK(node, `name: ${node.name}, points: ${node.points.length}`);
             }
         } catch (e) {
-            node.runtime.points = [{ x: 0, y: 0 }, { x: 100, y: 100 }];
-            node.status({ fill: "red", shape: "ring", text: "invalid points, using default" });
+            node.points = [{ x: 0, y: 0 }, { x: 100, y: 100 }];
+            utils.setStatusError(node, "invalid points, using default");
         }
 
         node.on("input", function(msg, send, done) {
@@ -36,7 +33,7 @@ module.exports = function(RED) {
 
             // Guard against invalid msg
             if (!msg) {
-                node.status({ fill: "red", shape: "ring", text: "invalid message" });
+                utils.setStatusError(node, "invalid message");
                 if (done) done();
                 return;
             }
@@ -44,12 +41,12 @@ module.exports = function(RED) {
             // Handle configuration messages
             if (msg.context) {
                 if (typeof msg.context !== "string" || !msg.context.trim()) {
-                    node.status({ fill: "yellow", shape: "ring", text: "unknown context" });
+                    utils.setStatusWarn(node, "unknown context");
                     if (done) done();
                     return;
                 }
                 if (!msg.hasOwnProperty("payload")) {
-                    node.status({ fill: "red", shape: "ring", text: "missing payload" });
+                    utils.setStatusError(node, "missing payload");
                     if (done) done();
                     return;
                 }
@@ -59,49 +56,43 @@ module.exports = function(RED) {
                         if (Array.isArray(newPoints) && newPoints.length >= 2 &&
                             newPoints.every(p => typeof p.x === "number" && !isNaN(p.x) &&
                                                 typeof p.y === "number" && !isNaN(p.y))) {
-                            node.runtime.points = newPoints;
-                            node.status({
-                                fill: "green",
-                                shape: "dot",
-                                text: `points: ${newPoints.length}`
-                            });
+                            node.points = newPoints;
+                            utils.setStatusOK(node, `points: ${newPoints.length}`);
                         } else {
-                            node.status({ fill: "red", shape: "ring", text: "invalid points" });
+                            utils.setStatusError(node, "invalid points");
                         }
                     } catch (e) {
-                        node.status({ fill: "red", shape: "ring", text: "invalid points" });
+                        utils.setStatusError(node, "invalid points");
                     }
                     if (done) done();
                     return;
                 } else {
-                    node.status({ fill: "yellow", shape: "ring", text: "unknown context" });
+                    utils.setStatusWarn(node, "unknown context");
                     if (done) done();
                     return;
                 }
             }
 
-            // Check for missing payload
-            if (!msg.hasOwnProperty("payload")) {
-                node.status({ fill: "red", shape: "ring", text: "missing payload" });
-                if (done) done();
-                return;
+            // Check for missing input property
+            let inputValue;
+            try {
+                inputValue = parseFloat(RED.util.getMessageProperty(msg, node.inputProperty));
+            } catch (err) {
+                inputValue = NaN;
             }
-
-            // Process input
-            const inputValue = parseFloat(msg.payload);
             if (isNaN(inputValue)) {
-                node.status({ fill: "red", shape: "ring", text: "invalid input" });
+                utils.setStatusError(node, "missing or invalid input property");
                 if (done) done();
                 return;
             }
 
             // Linear interpolation
             let outputValue = NaN;
-            const isPositiveSlope = node.runtime.points.length >= 2 && node.runtime.points[1].x > node.runtime.points[0].x;
+            const isPositiveSlope = node.points.length >= 2 && node.points[1].x > node.points[0].x;
 
-            for (let i = 0; i < node.runtime.points.length - 1; i++) {
-                let x1 = node.runtime.points[i].x, y1 = node.runtime.points[i].y;
-                let x2 = node.runtime.points[i + 1].x, y2 = node.runtime.points[i + 1].y;
+            for (let i = 0; i < node.points.length - 1; i++) {
+                let x1 = node.points[i].x, y1 = node.points[i].y;
+                let x2 = node.points[i + 1].x, y2 = node.points[i + 1].y;
                 if (isPositiveSlope ? (inputValue >= x1 && inputValue <= x2) : (inputValue <= x1 && inputValue >= x2)) {
                     let m = (y2 - y1) / (x2 - x1);
                     let b = y1 - (m * x1);
@@ -111,21 +102,19 @@ module.exports = function(RED) {
             }
 
             if (isNaN(outputValue)) {
-                node.status({ fill: "red", shape: "ring", text: "input out of range" });
+                utils.setStatusError(node, "input out of range");
                 if (done) done();
                 return;
             }
 
             // Check if output value has changed
-            const isUnchanged = outputValue === node.runtime.lastOutput;
-            node.status({
-                fill: "blue",
-                shape: isUnchanged ? "ring" : "dot",
-                text: `in: ${inputValue.toFixed(2)}, out: ${outputValue.toFixed(2)}`
-            });
+            const isUnchanged = outputValue === node.lastOutput;
+            const statusShape = isUnchanged ? "ring" : "dot";
+            utils.setStatusOK(node, `in: ${inputValue.toFixed(2)}, out: ${outputValue.toFixed(2)}`);
+            if (statusShape === "ring") utils.setStatusUnchanged(node, `in: ${inputValue.toFixed(2)}, out: ${outputValue.toFixed(2)}`);
 
             if (!isUnchanged) {
-                node.runtime.lastOutput = outputValue;
+                node.lastOutput = outputValue;
                 send({ payload: outputValue });
             }
 

package/nodes/join.html

@@ -0,0 +1,78 @@
+<!-- Data Template -->
+<script type="text/html" data-template-name="bldgblocks-join">
+    <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-count"><i class="fa fa-sort-numeric-asc"></i> Key Count</label>
+        <input type="number" id="node-input-count" placeholder="4">
+    </div>
+
+    <div class="form-row">
+        <label for="node-input-excludedKeys"><i class="fa fa-ban"></i> Exclude</label>
+        <input type="text" id="node-input-excludedKeys" placeholder="status, req, res">
+        <div style="font-size: 0.8em; color: #888; margin-left: 105px;">Comma separated list of properties to ignore</div>
+    </div>
+
+    <div class="form-tips">
+        <b>Note:</b> Works with root properties only and must all be unique. Nested properties are not supported.
+        Instead of incoming properties like 'outdoor.temp' (a nested object), consider using outdoor/temp or outdoorTemp as property names.
+    </div>
+</script>
+
+<!-- Registration & logic -->
+<script type="text/javascript">
+    RED.nodes.registerType('bldgblocks-join', {
+        category: "bldgblocks control",
+        color: '#301934',
+        defaults: {
+            name: { value: "" },
+            count: { value: 4, required: true, validate: RED.validators.number() },
+            excludedKeys: { value: "status" } // Default to 'status' to maintain previous behavior
+        },
+        inputs: 1,
+        outputs: 1,
+        icon: "font-awesome/fa-compress",
+        label: function() {
+            return this.name || "join (" + this.count + ")";
+        },
+        paletteLabel: "join",
+        oneditprepare: function() {
+            // Optional: visual tweaks when opening the edit dialog
+        }
+    });
+</script>
+
+<!-- Help Section -->
+<script type="text/markdown" data-help-name="bldgblocks-join">
+Joins multiple messages into a single message by accumulating unique properties. 
+This differs from the standard Node-RED Join node by focusing on unique keys rather than message counts or parts
+and combines to root level using property names.
+
+### Inputs 
+: all (any) : All unique properties from incoming messages.
+: Key Count (number) : The number of unique keys required before the node emits the accumulated message.
+: Exclude (string) : A comma-separated list of properties to ignore (e.g., `status, topic`).
+
+### Outputs
+: msg (any) : All unique properties combined at root level into a single message.
+
+### Details
+1. The node stores a running list of properties from every `msg` it receives.
+2. It ignores properties starting with `_` (like `_msgid`).
+3. It ignores any properties listed in the `Exclude` configuration.
+4. When the number of stored unique keys equals or exceeds the `Key Count`, it emits the combined object as a new message.
+
+### 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/join.js

@@ -0,0 +1,78 @@
+module.exports = function(RED) {
+    const utils = require('./utils')(RED);
+    function BldgBlocksJoinNode(config) {
+        RED.nodes.createNode(this, config);
+        const node = this;
+        
+        // Get configuration from the UI
+        node.targetCount = parseInt(config.count) || 4;
+        
+        // Parse excluded keys string into a Set for fast lookup
+        // Split by comma, trim whitespace, and remove empty entries
+        const exclusionString = config.excludedKeys || "";
+        const excludedSet = new Set(
+            exclusionString.split(',').map(s => s.trim()).filter(s => s.length > 0)
+        );
+
+        // --- INPUT HANDLER ---
+        node.on('input', function(msg, send, done) {
+            send = send || function() { node.send.apply(node, arguments); };
+
+            // Get current state from context
+            let valueMap = node.context().get("valueMap") || {};
+            
+            // Add properties from incoming message to the state
+            Object.keys(msg).forEach(key => {
+                // Logic:
+                // 1. Value must exist (not undefined/null)
+                // 2. Key must NOT start with '_' (internal Node-RED props)
+                // 3. Key must NOT be in the user-defined excluded list
+                if (
+                    msg[key] !== undefined &&  
+                    !key.startsWith('_') && 
+                    !excludedSet.has(key)
+                ) {
+                    valueMap[key] = msg[key];
+                }
+            });
+
+            // Calculate current unique key count
+            const currentCount = Object.keys(valueMap).length;
+
+            // Update status
+            if (currentCount >= node.targetCount) {
+                utils.setStatusOK(node, `${currentCount}/${node.targetCount} keys`);
+            } else {
+                utils.setStatusChanged(node, `${currentCount}/${node.targetCount} keys`);
+            }
+
+            // Save state back to context
+            node.context().set("valueMap", valueMap);
+
+            // Check if we hit the target
+            if (currentCount >= node.targetCount) {
+                // Clone the map to create the output message
+                const outputMsg = RED.util.cloneMessage(valueMap);
+                
+                // Ensure we have a msgid
+                if (!outputMsg._msgid) {
+                    outputMsg._msgid = RED.util.generateId();
+                }
+
+                send(outputMsg);
+            }
+
+            if (done) {
+                done();
+            }
+        });
+
+        node.on('close', function(removed, done) {
+            if (removed) {
+                node.context().set("valueMap", undefined);
+            }
+            done();
+        });
+    }
+    RED.nodes.registerType("bldgblocks-join", BldgBlocksJoinNode);
+}