@bldgblocks/node-red-contrib-control 0.1.34 → 0.1.37

package/nodes/alarm-collector.js

@@ -0,0 +1,292 @@
+module.exports = function(RED) {
+    const utils = require('./utils')(RED);
+
+    function AlarmCollectorNode(config) {
+        RED.nodes.createNode(this, config);
+        const node = this;
+
+        // Initialize configuration
+        node.name = config.name || "alarm-collector";
+        node.alarmConfigId = config.alarmConfig;
+        node.inputMode = config.inputMode || "value";
+        node.inputField = config.inputField || "payload";
+        node.alarmWhenTrue = config.alarmWhenTrue !== false;
+        node.highThreshold = parseFloat(config.highThreshold) || 85;
+        node.lowThreshold = parseFloat(config.lowThreshold) || 68;
+        node.compareMode = config.compareMode || "either";
+        node.hysteresisTime = parseInt(config.hysteresisTime) || 500;
+        node.hysteresisMagnitude = parseFloat(config.hysteresisMagnitude) || 2;
+        node.priority = config.priority || "normal";
+        node.topic = config.topic || "Alarms_Default";
+        node.title = config.title || "Alarm";
+        node.message = config.message || "Condition triggered";
+        node.tags = config.tags || "";
+        node.units = config.units || "";
+
+        // Get reference to alarm-config node
+        node.alarmConfig = RED.nodes.getNode(node.alarmConfigId);
+        if (!node.alarmConfig) {
+            utils.setStatusWarn(node, "Alarm registry not configured");
+        }
+
+        // Getter pattern: optional target global-setter node selection
+        node.sourceNodeId = config.sourceNode || null;
+        node.sourceNodeType = config.sourceNodeType || "wired";
+        let setterNode = null;
+        if (node.sourceNodeType === "setter" && node.sourceNodeId) {
+            setterNode = RED.nodes.getNode(node.sourceNodeId);
+        }
+
+        // Runtime state
+        node.currentValue = null;
+        node.alarmState = false;
+        node.lastEmittedState = null;
+        node.hysteresisTimer = null;
+        node.conditionMet = false;
+        node.valueChangedListener = null;
+
+        utils.setStatusOK(node, `idle`);
+
+        // ====================================================================
+        // Helper: Evaluate alarm condition and emit event if state changed
+        // ====================================================================
+        function evaluateAndEmit(inputValue) {
+            // Evaluate alarm condition based on input mode
+            let conditionNowMet = false;
+            let numericValue = null;
+
+            if (node.inputMode === "boolean") {
+                // Boolean mode: compare directly with alarmWhenTrue
+                conditionNowMet = (inputValue === node.alarmWhenTrue);
+                node.currentValue = inputValue;
+            } else {
+                // Value mode: parse as numeric and check thresholds
+                numericValue = inputValue;
+                if (typeof inputValue === 'object' && inputValue !== null && inputValue.value !== undefined) {
+                    numericValue = inputValue.value;
+                }
+                numericValue = parseFloat(numericValue);
+                
+                if (isNaN(numericValue)) {
+                    utils.setStatusError(node, "Invalid numeric input");
+                    return;
+                }
+                
+                node.currentValue = numericValue;
+
+                // Check thresholds
+                if (node.compareMode === "either") {
+                    conditionNowMet = (numericValue > node.highThreshold) || (numericValue < node.lowThreshold);
+                } else if (node.compareMode === "high-only") {
+                    conditionNowMet = (numericValue > node.highThreshold);
+                } else if (node.compareMode === "low-only") {
+                    conditionNowMet = (numericValue < node.lowThreshold);
+                }
+            }
+
+            // Time-based hysteresis logic
+            if (conditionNowMet && !node.conditionMet) {
+                // Condition just became true - start hysteresis timer
+                node.conditionMet = true;
+                
+                if (node.hysteresisTimer) clearTimeout(node.hysteresisTimer);
+
+                node.hysteresisTimer = setTimeout(() => {
+                    if (node.conditionMet && node.alarmState === false) {
+                        // Condition stayed true for hysteresisTime ms
+                        node.alarmState = true;
+                        emitAlarmEvent("false → true");
+                    }
+                    node.hysteresisTimer = null;
+                }, node.hysteresisTime);
+
+            } else if (!conditionNowMet && node.conditionMet) {
+                // Condition just became false - cancel pending timer
+                node.conditionMet = false;
+                
+                if (node.hysteresisTimer) {
+                    clearTimeout(node.hysteresisTimer);
+                    node.hysteresisTimer = null;
+                }
+
+                // Check magnitude hysteresis before clearing
+                let shouldClear = true;
+                if (node.inputMode === "value" && node.alarmState === true) {
+                    if (node.compareMode === "either" || node.compareMode === "high-only") {
+                        const clearThreshold = node.highThreshold - node.hysteresisMagnitude;
+                        if (numericValue > clearThreshold) {
+                            shouldClear = false;
+                        }
+                    }
+                    if (node.compareMode === "either" || node.compareMode === "low-only") {
+                        const clearThreshold = node.lowThreshold + node.hysteresisMagnitude;
+                        if (numericValue < clearThreshold) {
+                            shouldClear = false;
+                        }
+                    }
+                }
+
+                if (shouldClear && node.alarmState === true) {
+                    node.alarmState = false;
+                    emitAlarmEvent("true → false");
+                }
+            }
+
+            // Update status display
+            let statusText;
+            if (node.inputMode === "boolean") {
+                statusText = `${inputValue ? "true" : "false"}`;
+            } else {
+                statusText = `${numericValue.toFixed(2)} ${node.units}`;
+            }
+
+            if (node.alarmState) {
+                utils.setStatusError(node, statusText + " [ALARM]");
+            } else if (node.conditionMet) {
+                utils.setStatusWarn(node, statusText + " (hysteresis)");
+            } else {
+                utils.setStatusOK(node, statusText);
+            }
+        }
+
+        // ====================================================================
+        // Emit alarm event (only on state transition)
+        // ====================================================================
+        function emitAlarmEvent(transition) {
+            if (node.lastEmittedState === node.alarmState) {
+                return;
+            }
+
+            node.lastEmittedState = node.alarmState;
+
+            const eventData = {
+                nodeId: node.id,
+                nodeName: node.name,
+                value: node.currentValue,
+                highThreshold: node.inputMode === "value" ? node.highThreshold : undefined,
+                lowThreshold: node.inputMode === "value" ? node.lowThreshold : undefined,
+                compareMode: node.inputMode === "value" ? node.compareMode : undefined,
+                state: node.alarmState,
+                priority: node.priority,
+                topic: node.topic,
+                title: node.title,
+                message: node.message,
+                tags: node.tags,
+                units: node.units,
+                timestamp: new Date().toISOString(),
+                transition: transition
+            };
+
+            // Register/update alarm in registry
+            if (node.alarmConfig) {
+                const alarmName = node.name;
+                node.alarmConfig.register(alarmName, {
+                    nodeId: node.id,
+                    pointId: node.currentValue,
+                    severity: node.priority,
+                    status: node.alarmState ? 'active' : 'cleared',
+                    title: node.title,
+                    message: node.message,
+                    topic: node.topic,
+                    timestamp: new Date().toISOString()
+                });
+            }
+
+            // Emit to fixed event - service listens here
+            RED.events.emit("bldgblocks:alarms:state-change", eventData);
+        }
+
+        // ====================================================================
+        // Setup listeners based on mode (wired or target node)
+        // ====================================================================
+
+        // If target global-setter selected, listen to value changes (same as global-getter)
+        if (setterNode && setterNode.varName) {
+            node.valueChangedListener = function(evt) {
+                if (evt.key === setterNode.varName && evt.store === setterNode.storeName) {
+                    // Extract value from the global data object
+                    let val = evt.data;
+                    if (val && typeof val === 'object' && val.hasOwnProperty('value')) {
+                        val = val.value;
+                    }
+                    if (val !== undefined && val !== null) {
+                        evaluateAndEmit(val);
+                    }
+                }
+            };
+
+            RED.events.on("bldgblocks:global:value-changed", node.valueChangedListener);
+            utils.setStatusOK(node, `monitoring ${setterNode.varName}`);
+        }
+
+        // Wired input handler
+        node.on("input", async function(msg, send, done) {
+            send = send || function() { node.send.apply(node, arguments); };
+
+            if (!msg) {
+                utils.setStatusError(node, "invalid message");
+                if (done) done();
+                return;
+            }
+
+            // If using target node, ignore wired input
+            if (setterNode) {
+                if (done) done();
+                return;
+            }
+
+            // Get input value from configured msg property using evaluateNodeProperty
+            try {
+                let inputValue = await utils.evaluateNodeProperty(node.inputField, node.inputFieldType || "msg", node, msg);
+                
+                if (inputValue === undefined || inputValue === null) {
+                    utils.setStatusError(node, `missing field: ${node.inputField}`);
+                    if (done) done();
+                    return;
+                }
+
+                // Evaluate based on input mode
+                if (node.inputMode === "boolean") {
+                    inputValue = Boolean(inputValue);
+                } else {
+                    inputValue = parseFloat(inputValue);
+                    if (isNaN(inputValue)) {
+                        utils.setStatusError(node, "invalid numeric input");
+                        if (done) done();
+                        return;
+                    }
+                }
+
+                evaluateAndEmit(inputValue);
+            } catch (err) {
+                utils.setStatusError(node, `Error reading input: ${err.message}`);
+                node.error(err);
+            }
+            
+            if (done) done();
+        });
+
+        node.on("close", function(done) {
+            // Cleanup timers
+            if (node.hysteresisTimer) {
+                clearTimeout(node.hysteresisTimer);
+                node.hysteresisTimer = null;
+            }
+
+            // Unregister alarm from registry
+            if (node.alarmConfig) {
+                node.alarmConfig.unregister(node.name, node.id);
+            }
+
+            // Remove global value-changed listener
+            if (node.valueChangedListener) {
+                RED.events.off("bldgblocks:global:value-changed", node.valueChangedListener);
+                node.valueChangedListener = null;
+            }
+
+            done();
+        });
+    }
+
+    RED.nodes.registerType("alarm-collector", AlarmCollectorNode);
+};

package/nodes/alarm-config.html

@@ -0,0 +1,129 @@
+<script type="text/html" data-template-name="alarm-config">
+    <div class="form-row">
+        <label for="node-config-input-name"><i class="fa fa-tag"></i> Name</label>
+        <input type="text" id="node-config-input-name" placeholder="Alarm Registry">
+    </div>
+    <div class="form-tips">
+        <p><b>Alarm Registry</b></p>
+        <p>This node maintains all active alarms and their current status (active/cleared).</p>
+    </div>
+
+    <div class="form-row">
+        <label><i class="fa fa-exclamation-triangle"></i> Alarms</label>
+        <div id="node-input-alarm-list-div"
+             style="
+                 border:1px solid #ccc;
+                 height:250px;
+                 overflow-y:auto;
+                 padding:5px;
+                 box-sizing:border-box;">
+            <ul id="node-input-alarm-list" style="margin:0;padding-left:1.2em;"></ul>
+        </div>
+    </div>
+</script>
+
+<script type="text/javascript">
+    RED.nodes.registerType("alarm-config", {
+        category: 'config',
+        defaults: {
+            name: { value: "" }
+        },
+        label: function() {
+            return this.name || "Alarm Registry";
+        },
+        oneditprepare: function() {
+            const node = this;
+            const $list = $("#node-input-alarm-list");
+
+            function loadAlarms() {
+                $.getJSON(`/alarm-config/list/${node.id}`, function(data) {
+                    $list.empty();
+                    if (!data.length) {
+                        return $list.append('<li style="color:#999;">No alarms registered</li>');
+                    }
+
+                    // Data already sorted by server
+                    data.forEach(alarm => {
+                        const li = $('<li>')
+                            .css({
+                                display: 'flex',
+                                alignItems: 'center',
+                                padding: '4px 0',
+                                borderBottom: '1px solid #eee'
+                            });
+
+                        // Status indicator (colored circle)
+                        const statusColor = alarm.status === 'active' ? '#d32f2f' : '#4caf50';
+                        const statusIcon = alarm.status === 'active' ? 'fa-circle' : 'fa-check-circle';
+                        const statusDot = $('<i>')
+                            .addClass(`fa ${statusIcon}`)
+                            .css({
+                                color: statusColor,
+                                marginRight: '8px',
+                                width: '16px'
+                            });
+
+                        // Alarm info (name, severity, point)
+                        const infoText = $('<span>')
+                            .html(`<strong>${alarm.name}</strong> <span style="color:#666;font-size:0.9em;">[${alarm.severity}] #${alarm.pointId}</span>`)
+                            .css({ flexGrow: 1 });
+
+                        // Reveal button (find node on canvas)
+                        const revealBtn = $('<button type="button" class="editor-button">')
+                            .attr('title', 'Reveal alarm collector on canvas')
+                            .html('<i class="fa fa-search"></i>')
+                            .on('click', function(e) {
+                                e.stopPropagation();
+                                RED.view.reveal(alarm.nodeId);
+                            });
+
+                        li.append(statusDot, infoText, revealBtn);
+                        $list.append(li);
+                    });
+                }).fail(function() {
+                    $list.html('<li style="color:red;">Could not load alarms</li>');
+                });
+            }
+
+            // Load alarms on editor open
+            loadAlarms();
+
+            // Optionally: reload on a timer for live updates
+            // setInterval(loadAlarms, 2000);
+        }
+    });
+</script>
+
+<script type="text/markdown" data-help-name="alarm-config">
+Maintains a registry of active alarms and their status.
+
+### Details
+The Alarm Registry keeps track of all active alarms generated by alarm-collector nodes. Each alarm has:
+- **Name**: Unique identifier (usually derived from point ID and condition)
+- **Status**: Current state (active or cleared)
+- **Severity**: Level assigned by the alarm-collector
+- **Point ID**: Source network point that triggered the alarm
+
+This config node is referenced by alarm-collector nodes and used by the alarm-service node to subscribe to alarm updates.
+
+### Features
+- **Live Status Display**: Shows all active alarms with color-coded status (red = active, green = cleared)
+- **Reveal Button**: Click to find an alarm collector on the canvas
+- **Severity Indication**: See the priority level of each alarm at a glance
+
+### Usage
+1. Create a single alarm-config node for your workflow
+2. Reference it from each alarm-collector node
+3. The alarm-service node listens to events from all collectors and uses this registry for state tracking
+
+### API for Developers
+* `register(alarmName, meta)`: Register an alarm
+* `unregister(alarmName, nodeId)`: Remove an alarm
+* `lookup(alarmName)`: Find alarm details by name
+* `updateStatus(alarmName, status)`: Update alarm state
+* `getAll()`: Get all alarms
+
+### References
+- [Node-RED Documentation](https://nodered.org/docs/)
+- [GitHub Repository](https://github.com/BldgBlocks/node-red-contrib-buildingblocks-control.git)
+</script>

package/nodes/alarm-config.js

@@ -0,0 +1,126 @@
+module.exports = function(RED) {
+    
+    function AlarmConfigNode(config) {
+        RED.nodes.createNode(this, config);
+        const node = this;
+        
+        // Register this registry with utils for global lookup
+        const utils = require('./utils')(RED);
+        utils.registerRegistryNode(node);
+        
+        // The Map: stores alarm metadata by name
+        // Format: { "alarmName": { nodeId: "abc.123", pointId: 101, severity: "high", status: "active", ... } }
+        node.alarms = new Map();
+
+        // Register an alarm in the registry
+        node.register = function(alarmName, meta) {
+            if (!alarmName || typeof alarmName !== 'string') {
+                return false;
+            }
+
+            if (node.alarms.has(alarmName)) {
+                const existing = node.alarms.get(alarmName);
+                // Allow update if it's the same node
+                if (existing.nodeId !== meta.nodeId) {
+                    return false;
+                }
+                // Merge updates (preserving status if provided)
+                meta = Object.assign({}, existing, meta);
+            }
+            node.alarms.set(alarmName, meta);
+            return true;
+        };
+
+        // Unregister an alarm
+        node.unregister = function(alarmName, nodeId) {
+            if (node.alarms.has(alarmName) && node.alarms.get(alarmName).nodeId === nodeId) {
+                node.alarms.delete(alarmName);
+            }
+        };
+
+        // Lookup an alarm by name
+        node.lookup = function(alarmName) {
+            return node.alarms.get(alarmName);
+        };
+
+        // Update alarm status
+        node.updateStatus = function(alarmName, status) {
+            if (node.alarms.has(alarmName)) {
+                const alarm = node.alarms.get(alarmName);
+                alarm.status = status;  // 'active' or 'cleared'
+                alarm.lastUpdate = new Date().toISOString();
+                return true;
+            }
+            return false;
+        };
+
+        // Get all alarms
+        node.getAll = function() {
+            const arr = [];
+            for (const [name, meta] of node.alarms.entries()) {
+                arr.push({ name, ...meta });
+            }
+            return arr;
+        };
+    }
+    RED.nodes.registerType("alarm-config", AlarmConfigNode);
+
+    // --- HTTP Endpoint: List all alarms in a specific config ---
+    // Route: /alarm-config/list/<ConfigID>
+    RED.httpAdmin.get('/alarm-config/list/:configId', RED.auth.needsPermission('alarm-config.read'), function(req, res) {
+        const configId = req.params.configId;
+        
+        // Find the alarm-config node
+        const configNode = RED.nodes.getNode(configId);
+        if (!configNode) {
+            return res.status(404).json({ error: 'Configuration node not found' });
+        }
+
+        // Get all alarms from this config
+        const alarms = configNode.getAll();
+        
+        // Sort by name
+        alarms.sort((a, b) => a.name.localeCompare(b.name));
+        
+        res.json(alarms);
+    });
+
+    // --- HTTP Endpoint: Check if alarm exists ---
+    // Route: /alarm-config/check/<ConfigID>/<AlarmName>/<CurrentNodeID>
+    RED.httpAdmin.get('/alarm-config/check/:configId/:alarmName/:nodeId', RED.auth.needsPermission('alarm-config.read'), function(req, res) {
+        const configId = req.params.configId;
+        const alarmName = decodeURIComponent(req.params.alarmName);
+        const checkNodeId = req.params.nodeId;
+        
+        // Find the alarm-config node
+        const configNode = RED.nodes.getNode(configId);
+        
+        let entry = null;
+        let result = "unavailable";
+        let collision = false;
+
+        if (!configNode) {
+            // Config exists in editor but not deployed yet, or doesn't exist
+            return res.json({ status: result, warning: "Configuration not deployed" });
+        }
+
+        // Check for the alarm
+        entry = configNode.lookup(alarmName);
+        if (entry) {
+            // Collision if alarm exists AND belongs to a different node
+            if (entry.nodeId !== checkNodeId) {
+                collision = true;
+            }
+        }
+
+        if (collision) {
+            result = "collision";
+        } else if (!collision && entry) {
+            result = "assigned";
+        } else {
+            result = "available";
+        }
+
+        res.json({ status: result, details: entry });
+    });
+};

package/nodes/alarm-service.html

@@ -0,0 +1,96 @@
+<script type="text/html" data-template-name="alarm-service">
+    <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="Alarm Relay">
+    </div>
+
+    <div class="form-row">
+        <label for="node-input-filterTopic"><i class="fa fa-filter"></i> Filter by Topic (optional)</label>
+        <input type="text" id="node-input-filterTopic" placeholder="Leave blank to relay all topics">
+    </div>
+
+    <div class="form-row">
+        <label for="node-input-filterPriority"><i class="fa fa-exclamation-triangle"></i> Filter by Priority (optional)</label>
+        <select id="node-input-filterPriority">
+            <option value="">All Priorities</option>
+            <option value="urgent">Urgent</option>
+            <option value="high">High</option>
+            <option value="normal">Normal</option>
+            <option value="low">Low</option>
+        </select>
+    </div>
+</script>
+
+<script type="text/javascript">
+    RED.nodes.registerType("alarm-service", {
+        category: "bldgblocks alarms",
+        color: "#800020",
+        defaults: {
+            name: { value: "" },
+            filterTopic: { value: "" },
+            filterPriority: { value: "" }
+        },
+        inputs: 0,
+        outputs: 1,
+        outputLabels: ["alarm events"],
+        icon: "font-awesome/fa-bell",
+        label: function() {
+            return this.name || "alarm-service";
+        }
+    });
+</script>
+
+<script type="text/markdown" data-help-name="alarm-service">
+Listens to alarm events from all collectors and relays them downstream with status information.
+
+### Configuration
+- **Node Name**: Display name for this relay instance
+- **Filter by Topic** (optional): Only relay alarms matching a specific topic (e.g., "Alarms_HVAC")
+- **Filter by Priority** (optional): Only relay alarms with specific priority level
+
+### Outputs
+Single output with status included in message:
+- **payload** (object): Full alarm event data with topic, priority, title, message, etc.
+- **status** (object): `{ state: "triggered" | "cleared", transition: "false → true" | "true → false" }`
+- **activeAlarmCount** (number): Current number of active alarms being tracked
+- **alarmKey** (string): Topic or auto-generated ID for grouping related alarms
+
+### How It Works
+1. Listens to `bldgblocks:alarms:state-change` event emitted by all collectors
+2. Filters alarms by topic and priority (if configured)
+3. Tracks state transitions (cleared→alarmed or alarmed→cleared)
+4. Includes transition state in `msg.status` for downstream routing logic
+5. Updates status showing number of active alarms
+
+### Status
+- **Green dot**: Service running, no current alarms
+- **Yellow ring**: Multiple alarms active
+- **Red ring**: Alarm(s) active
+
+### Downstream Routing
+
+Route using `msg.status.state` field:
+
+```
+[alarm-service]
+    ├─ [Switch node] → status.state == "triggered"
+    │  ├─ [Format for ntfy] → [HTTP POST] → ntfy.sh (push notification)
+    │  ├─ [InfluxDB out] → InfluxDB (record alarm trigger)
+    │  └─ [Email] → Send alert email
+    │
+    └─ [Switch node] → status.state == "cleared"
+       ├─ [Format for ntfy] → [HTTP POST] → ntfy.sh (all clear)
+       └─ [InfluxDB out] → InfluxDB (record alarm cleared)
+```
+
+### Control Messages
+
+Send control messages via wired input (optional):
+- `{ context: "getStatus" }` — Returns array of active alarms
+- `{ context: "clearAll", payload: true }` — Clears alarm tracking (for testing/reset)
+
+### References
+- Pair with [alarm-collector] nodes to monitor conditions
+- Use `msg.status.state` to conditionally handle triggered vs cleared alarms
+- Multiple services can listen to same collectors (fan-out/routing pattern)
+</script>