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

package/LICENSE.md

@@ -1,4 +1,33 @@
 
+# Commons Clause License Condition v1.0
+
+The Software is provided to you by the Licensor under the License, as
+defined below, subject to the following condition.
+
+Without limiting other conditions in the License, the grant of rights
+under the License will not include, and the License does not grant to
+you, the right to Sell the Software.
+
+For purposes of the foregoing, "Sell" means practicing any or all of
+the rights granted to you under the License to provide to third parties,
+for a fee or other consideration (including without limitation fees for
+hosting or consulting/support services related to the Software), a
+product or service whose value derives, entirely or substantially, from
+the functionality of the Software. Any license notice or attribution
+required by the License must also include this Commons Clause License
+Condition notice.
+
+**Software:** node-red-contrib-control
+
+**License:** Apache 2.0
+
+**Licensor:** buildingblocks
+
+For commercial licensing inquiries, contact the Licensor via the
+repository at https://github.com/BldgBlocks/node-red-contrib-control
+
+---
+
                                  Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/
@@ -187,11 +216,12 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2024-2026 buildingblocks
 
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
+   Licensed under the Apache License, Version 2.0, with Commons Clause
+   License Condition v1.0 (the "License"); you may not use this file
+   except in compliance with the License. You may obtain a copy of the
+   License at
 
        http://www.apache.org/licenses/LICENSE-2.0
 
@@ -199,4 +229,7 @@
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
-   limitations under the License.
+   limitations under the License.
+
+   This software is subject to the Commons Clause License Condition v1.0
+   as described at the top of this file.

package/README.md

@@ -43,3 +43,13 @@ Search for the package name and add to your project.
 - $ npm install node-red-contrib-buildingblocks-control
 # then restart node-red
 ```
+
+## Testing
+Tests use [Mocha](https://mochajs.org/) and [node-red-node-test-helper](https://github.com/node-red/node-red-node-test-helper) to run nodes in an isolated, in-memory Node-RED runtime. Your live Node-RED instance is never touched.
+
+```bash
+npm install   # install dev dependencies (mocha, test helper)
+npm test      # run all tests
+```
+
+Test files live in `test/` and follow the naming convention `*_spec.js`. Shared utilities are in `test/test-helpers.js`.

package/nodes/accumulate-block.html

@@ -61,9 +61,9 @@ Counts consecutive inputs from a configured property based on the selected mode,
 
 ### Details
 Counts inputs according to the selected mode, reading from the configured **Input Property** (default: `msg.payload`):
-- **Accumulate True**: counts consecutive `true` values (resets on `false` or explicit reset)
-- **Accumulate False**: counts consecutive `false` values (resets on `true` or explicit reset)
-- **Accumulate Flows**: counts all valid input messages (resets only on explicit reset)
+- **Accumulate True** counts consecutive `true` values (resets on `false` or explicit reset)
+- **Accumulate False** counts consecutive `false` values (resets on `true` or explicit reset)
+- **Accumulate Flows** counts all valid input messages (resets only on explicit reset)
 
 Reset via `msg.context = "reset"` with `msg.payload = true`.
 

package/nodes/alarm-collector.html

@@ -96,6 +96,7 @@
     <div class="form-row">
         <label for="node-input-message"><i class="fa fa-comment"></i> Message</label>
         <input type="text" id="node-input-message" placeholder="Zone exceeds setpoint">
+        <input type="hidden" id="node-input-messageType">
     </div>
 
     <div class="form-row">
@@ -131,6 +132,7 @@
             topic: { value: "Alarms_Default" },
             title: { value: "Alarm" },
             message: { value: "Condition triggered" },
+            messageType: { value: "str" },
             tags: { value: "" },
             units: { value: "°F" }
         },
@@ -197,6 +199,15 @@
                 typeField: "#node-input-inputFieldType"
             }).typedInput("type", node.inputFieldType || "msg").typedInput("value", node.inputField || "payload");
 
+            // Setup message typedInput: static string or from msg property
+            $("#node-input-message").typedInput({
+                types: [
+                    "str",
+                    "msg"
+                ],
+                typeField: "#node-input-messageType"
+            }).typedInput("type", node.messageType || "str").typedInput("value", node.message || "Condition triggered");
+
             // Show/hide sections based on inputMode
             const updateDisplay = () => {
                 let mode = $("#node-input-inputMode").val();

package/nodes/alarm-collector.js

@@ -20,6 +20,7 @@ module.exports = function(RED) {
         node.topic = config.topic || "Alarms_Default";
         node.title = config.title || "Alarm";
         node.message = config.message || "Condition triggered";
+        node.messageType = config.messageType || "str";
         node.tags = config.tags || "";
         node.units = config.units || "";
 
@@ -45,6 +46,20 @@ module.exports = function(RED) {
         node.conditionMet = false;
         node.valueChangedListener = null;
 
+        // Register with alarm-config at startup so the registry knows about this collector
+        if (node.alarmConfig) {
+            node.alarmConfig.register(node.id, {
+                name: node.name,
+                severity: node.priority,
+                status: 'cleared',
+                title: node.title,
+                message: node.message,
+                topic: node.topic,
+                value: null,
+                timestamp: new Date().toISOString()
+            });
+        }
+
         utils.setStatusOK(node, `idle`);
 
         // ====================================================================
@@ -179,15 +194,14 @@ module.exports = function(RED) {
 
             // Register/update alarm in registry
             if (node.alarmConfig) {
-                const alarmName = node.name;
-                node.alarmConfig.register(alarmName, {
-                    nodeId: node.id,
-                    pointId: node.currentValue,
+                node.alarmConfig.register(node.id, {
+                    name: node.name,
                     severity: node.priority,
                     status: node.alarmState ? 'active' : 'cleared',
                     title: node.title,
                     message: node.message,
                     topic: node.topic,
+                    value: node.currentValue,
                     timestamp: new Date().toISOString()
                 });
             }
@@ -257,6 +271,18 @@ module.exports = function(RED) {
                     }
                 }
 
+                // Resolve message dynamically if configured as msg property
+                if (node.messageType === "msg") {
+                    try {
+                        const resolved = await utils.evaluateNodeProperty(config.message, "msg", node, msg);
+                        if (resolved !== undefined && resolved !== null) {
+                            node.message = String(resolved);
+                        }
+                    } catch (e) {
+                        // Keep existing message on error
+                    }
+                }
+
                 evaluateAndEmit(inputValue);
             } catch (err) {
                 utils.setStatusError(node, `Error reading input: ${err.message}`);
@@ -275,7 +301,7 @@ module.exports = function(RED) {
 
             // Unregister alarm from registry
             if (node.alarmConfig) {
-                node.alarmConfig.unregister(node.name, node.id);
+                node.alarmConfig.unregister(node.id);
             }
 
             // Remove global value-changed listener

package/nodes/alarm-config.html

@@ -36,10 +36,10 @@
             const $list = $("#node-input-alarm-list");
 
             function loadAlarms() {
-                $.getJSON(`/alarm-config/list/${node.id}`, function(data) {
+                $.getJSON(`alarm-config/list/${node.id}`, function(data) {
                     $list.empty();
                     if (!data.length) {
-                        return $list.append('<li style="color:#999;">No alarms registered</li>');
+                        return $list.append('<li style="color:#999;">No alarms registered (deploy first if newly added)</li>');
                     }
 
                     // Data already sorted by server
@@ -63,9 +63,10 @@
                                 width: '16px'
                             });
 
-                        // Alarm info (name, severity, point)
+                        // Alarm info (name, severity, topic)
+                        const valuePart = alarm.value != null ? ` val:${alarm.value}` : '';
                         const infoText = $('<span>')
-                            .html(`<strong>${alarm.name}</strong> <span style="color:#666;font-size:0.9em;">[${alarm.severity}] #${alarm.pointId}</span>`)
+                            .html(`<strong>${alarm.name}</strong> <span style="color:#666;font-size:0.9em;">[${alarm.severity}] ${alarm.topic}${valuePart}</span>`)
                             .css({ flexGrow: 1 });
 
                         // Reveal button (find node on canvas)
@@ -80,8 +81,12 @@
                         li.append(statusDot, infoText, revealBtn);
                         $list.append(li);
                     });
-                }).fail(function() {
-                    $list.html('<li style="color:red;">Could not load alarms</li>');
+                }).fail(function(jqXHR) {
+                    if (jqXHR.status === 401 || jqXHR.status === 403) {
+                        $list.html('<li style="color:red;">Permission denied (alarm-config.read)</li>');
+                    } else {
+                        $list.html('<li style="color:red;">Could not load alarms (HTTP ' + jqXHR.status + ')</li>');
+                    }
                 });
             }
 

package/nodes/alarm-config.js

@@ -8,45 +8,39 @@ module.exports = function(RED) {
         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", ... } }
+        // The Map: stores alarm metadata keyed by collector node ID (always unique)
+        // Format: { "nodeId": { name: "Alarm Name", severity: "high", status: "active", ... } }
         node.alarms = new Map();
 
-        // Register an alarm in the registry
-        node.register = function(alarmName, meta) {
-            if (!alarmName || typeof alarmName !== 'string') {
+        // Register an alarm in the registry (keyed by nodeId for uniqueness)
+        node.register = function(nodeId, meta) {
+            if (!nodeId || typeof nodeId !== '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)
+            if (node.alarms.has(nodeId)) {
+                const existing = node.alarms.get(nodeId);
+                // Merge updates (preserving existing fields not in new meta)
                 meta = Object.assign({}, existing, meta);
             }
-            node.alarms.set(alarmName, meta);
+            node.alarms.set(nodeId, 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);
-            }
+        // Unregister an alarm by node ID
+        node.unregister = function(nodeId) {
+            node.alarms.delete(nodeId);
         };
 
-        // Lookup an alarm by name
-        node.lookup = function(alarmName) {
-            return node.alarms.get(alarmName);
+        // Lookup an alarm by node ID
+        node.lookup = function(nodeId) {
+            return node.alarms.get(nodeId);
         };
 
-        // Update alarm status
-        node.updateStatus = function(alarmName, status) {
-            if (node.alarms.has(alarmName)) {
-                const alarm = node.alarms.get(alarmName);
+        // Update alarm status by node ID
+        node.updateStatus = function(nodeId, status) {
+            if (node.alarms.has(nodeId)) {
+                const alarm = node.alarms.get(nodeId);
                 alarm.status = status;  // 'active' or 'cleared'
                 alarm.lastUpdate = new Date().toISOString();
                 return true;
@@ -57,8 +51,8 @@ module.exports = function(RED) {
         // Get all alarms
         node.getAll = function() {
             const arr = [];
-            for (const [name, meta] of node.alarms.entries()) {
-                arr.push({ name, ...meta });
+            for (const [nodeId, meta] of node.alarms.entries()) {
+                arr.push({ nodeId, ...meta });
             }
             return arr;
         };
@@ -73,7 +67,8 @@ module.exports = function(RED) {
         // Find the alarm-config node
         const configNode = RED.nodes.getNode(configId);
         if (!configNode) {
-            return res.status(404).json({ error: 'Configuration node not found' });
+            // Not deployed yet — return empty list so the editor can show a friendly message
+            return res.json([]);
         }
 
         // Get all alarms from this config
@@ -104,20 +99,24 @@ module.exports = function(RED) {
             return res.json({ status: result, warning: "Configuration not deployed" });
         }
 
-        // Check for the alarm
-        entry = configNode.lookup(alarmName);
+        // Check for the alarm — map is keyed by nodeId
+        entry = configNode.lookup(checkNodeId);
+
         if (entry) {
-            // Collision if alarm exists AND belongs to a different node
-            if (entry.nodeId !== checkNodeId) {
+            result = "assigned";
+        } else {
+            // Check if any other node has the same alarm name (name collision check)
+            const allAlarms = configNode.getAll();
+            const nameMatch = allAlarms.find(a => a.name === alarmName && a.nodeId !== checkNodeId);
+            if (nameMatch) {
                 collision = true;
+                entry = nameMatch;
             }
         }
 
         if (collision) {
             result = "collision";
-        } else if (!collision && entry) {
-            result = "assigned";
-        } else {
+        } else if (!entry) {
             result = "available";
         }
 

package/nodes/alarm-service.js

@@ -48,7 +48,7 @@ module.exports = function(RED) {
 
                 // Send alarm message with status
                 const msg = {
-                    payload: eventData,
+                    alarm: eventData,
                     status: { state: "triggered", transition: eventData.transition },
                     activeAlarmCount: activeCount,
                     alarmKey: key
@@ -71,7 +71,7 @@ module.exports = function(RED) {
 
                     // Send clear message with status
                     const msg = {
-                        payload: eventData,
+                        alarm: eventData,
                         status: { state: "cleared", transition: eventData.transition },
                         activeAlarmCount: activeCount,
                         alarmKey: key

package/nodes/and-block.js

@@ -48,7 +48,7 @@ module.exports = function(RED) {
                     node.inputs[slotVal.index - 1] = Boolean(msg.payload);
                     const result = node.inputs.every(v => v === true);
                     const isUnchanged = result === lastResult && node.inputs.every((v, i) => v === lastInputs[i]);
-                    const statusText = `in: [${node.inputs.join(", ")}], out: ${result}`;
+                    const statusText = `[${node.inputs.join(", ")}] -> ${result}`;
                     
                     // ================================================================
                     // Debounce: Suppress consecutive same outputs within 500ms

package/nodes/boolean-switch-block.html

@@ -4,6 +4,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-state" title="Initial switch state"><i class="fa fa-toggle-on"></i> State</label>
+        <input type="checkbox" id="node-input-state" style="width: auto;">
+    </div>
 </script>
 
 <!-- JavaScript Section -->
@@ -29,30 +33,39 @@
 
 <!-- Help Section -->
 <script type="text/markdown" data-help-name="boolean-switch-block">
-Routes input flows to one of three outputs based on a boolean switch state.
+A boolean gate that routes messages based on a `true`/`false` switch state.
 
 ### Inputs
-: context (string) : Configuration commands (`toggle`, `switch`, `inTrue`, `inFalse`).
-: payload (any) : Flow data for `"inTrue"` or `"inFalse"`.
+: context (string) : Message tag: `"in"`, `"inTrue"`, `"inFalse"`, `"toggle"`, or `"switch"`.
+: payload (any) : Flow data for `"in"` / `"inTrue"` / `"inFalse"`; boolean for `"switch"`.
+
+#### Contexts
+- **`"in"`** — Routes `msg` to `outTrue` when state is `true`, or `outFalse` when state is `false`. Always flows through.
+- **`"inTrue"`** — Passes `msg` to `outTrue` only when state is `true`. Blocked with warning when `false`.
+- **`"inFalse"`** — Passes `msg` to `outFalse` only when state is `false`. Blocked with warning when `true`.
+- **`"toggle"`** — Flips the switch state and emits new state on `outControl`.
+- **`"switch"`** — Sets the switch state to `!!msg.payload` and emits on `outControl`.
 
 ### Outputs
-: outTrue (msg) : Receives `msg` with `context "inTrue"` when switch is `true`.
-: outFalse (msg) : Receives `msg` with `context "inFalse"` when switch is `false`.
-: outControl (msg) : `msg.payload` set to switch state on toggle.
+: outTrue (msg) : Receives `msg` when state is `true` (via `"in"` or `"inTrue"`).
+: outFalse (msg) : Receives `msg` when state is `false` (via `"in"` or `"inFalse"`).
+: outControl (msg) : Emits `{ payload: <boolean> }` on `"toggle"` or `"switch"` only.
 
 ### Details
-Routes input messages to one of three outputs based on a boolean switch state (`true` or `false`).
+This node acts as a boolean gate/router.
 
-Messages with `msg.context = "inTrue"` are sent to `outTrue` when `state = true`, and messages with `msg.context = "inFalse"` are sent to `outFalse` when `state = false`.
+Use `"in"` to auto-route messages to the correct output based on state — messages always flow through.
+Use `"inTrue"`/`"inFalse"` for conditional gating — messages are blocked (with yellow warning) when state doesn't match.
 
-State can be controlled directly with the `"switch"` property given a `msg.payload` boolean value.
+State can be controlled with `"toggle"` (flip) or `"switch"` (set explicitly via payload).
+The `outControl` port fires only on state commands, not on routed data messages.
 
 ### Status
-- Green (dot): Configuration update
-- Blue (dot): State changed
-- Blue (ring): State unchanged
-- Red (ring): Error
-- Yellow (ring): Warning
+- **Green (dot)**: Message routed successfully
+- **Blue (dot)**: State changed (`toggle` / `switch`)
+- **Blue (ring)**: State unchanged (`switch` with same value)
+- **Yellow (ring)**: Message blocked (`inTrue` when false, `inFalse` when true) or unknown context
+- **Red (ring)**: Error (missing context, invalid message)
 
 ### References
 - [Node-RED Documentation](https://nodered.org/docs/)

package/nodes/boolean-switch-block.js

@@ -5,8 +5,8 @@ module.exports = function(RED) {
         RED.nodes.createNode(this, config);
         const node = this;
 
-        // Initialize state from config
-        node.state = config.state;
+        // Initialize state from config (coerce to boolean)
+        node.state = !!config.state;
 
         // Set initial status
         utils.setStatusOK(node, `state: ${node.state}`);
@@ -30,31 +30,41 @@ module.exports = function(RED) {
 
             // Handle context commands
             switch (msg.context) {
-                case "toggle":
+                case "toggle": {
                     node.state = !node.state;
                     utils.setStatusChanged(node, `state: ${node.state}`);
                     send([null, null, { payload: node.state }]);
                     break;
-                case "switch":
-                    node.state = !!msg.payload;
-                    utils.setStatusChanged(node, `state: ${node.state}`);
+                }
+
+                case "switch": {
+                    const newState = !!msg.payload;
+                    if (newState === node.state) {
+                        utils.setStatusUnchanged(node, `state: ${node.state}`);
+                    } else {
+                        node.state = newState;
+                        utils.setStatusChanged(node, `state: ${node.state}`);
+                    }
                     send([null, null, { payload: node.state }]);
                     break;
+                }
                 case "inTrue":
                     if (node.state) {
-                        utils.setStatusOK(node, `out: ${msg.payload}`);
-                        send([msg, null, { payload: node.state }]);
+                        utils.setStatusOK(node, `outTrue: ${msg.payload}`);
+                        send([msg, null, null]);
                     }
                     break;
+
                 case "inFalse":
                     if (!node.state) {
-                        utils.setStatusOK(node, `out: ${msg.payload}`);
-                        send([null, msg, { payload: node.state }]);
+                        utils.setStatusOK(node, `outFalse: ${msg.payload}`);
+                        send([null, msg, null]);
                     }
                     break;
+
                 default:
-                    utils.setStatusWarn(node, "unknown context");
-                    if (done) done("Unknown context");
+                    utils.setStatusWarn(node, `unknown context: ${msg.context}`);
+                    if (done) done("Unknown context: " + msg.context);
                     return;
             }
             if (done) done();