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

package/nodes/network-point-read.js

@@ -0,0 +1,230 @@
+module.exports = function(RED) {
+    const utils = require('./utils')(RED);
+
+    function NetworkPointReadNode(config) {
+        RED.nodes.createNode(this, config);
+        const node = this;
+
+        // ====================================================================
+        // Initialize configuration
+        // ====================================================================
+        node.pointId = parseInt(config.pointId);
+        node.bridgeNodeId = config.bridgeNodeId;
+        node.outputProperty = config.outputProperty || "payload";
+        
+        // Validate pointId
+        if (isNaN(node.pointId) || node.pointId < 0) {
+            utils.setStatusError(node, "invalid pointId");
+            return;
+        }
+
+        // ====================================================================
+        // Initialize state
+        // ====================================================================
+        node.cache = {
+            value: null,
+            name: null,
+            timestamp: null  // When value was last updated
+        };
+        
+        node.isPollPending = false;
+
+        // ====================================================================
+        // Helper: Format status text
+        // ====================================================================
+        const getStatusText = function() {
+            // Try to look up metadata (name/path) for this point
+            const meta = utils.lookupPointMetadata(node.pointId);
+            let label = meta && meta.name ? meta.name : (meta && meta.path ? meta.path : null);
+            
+            // Use cached name from remote response if local lookup failed
+            if (!label && node.cache.name) {
+                label = node.cache.name;
+            }
+            
+            if (!label) label = `Point #${node.pointId}`;
+            
+            if (node.cache.value === null) {
+                return `${label}: waiting...`;
+            }
+            // Show value (truncate if too long)
+            let valDisplay = node.cache.value;
+            if (typeof valDisplay === 'object') {
+                valDisplay = JSON.stringify(valDisplay).substring(0, 20);
+            }
+            return `${label}: ${valDisplay}`;
+        };
+
+        // ====================================================================
+        // Send read request to bridge via event
+        // ====================================================================
+        const triggerRead = function() {
+            if (node.isPollPending) {
+                return;  // Already waiting for response
+            }
+            
+            node.isPollPending = true;
+            utils.setStatusUnchanged(node, `Fetching... ${getStatusText()}`);
+            
+            // Send read request to bridge node via event (cross-flow communication)
+            const requestId = `${node.id}_${node.pointId}_${Date.now()}`;
+            RED.events.emit('pointReference:read', {
+                sourceNodeId: node.id,
+                bridgeNodeId: node.bridgeNodeId,
+                pointId: node.pointId,
+                requestId: requestId
+            });
+        };
+
+        // ====================================================================
+        // Main message handler - triggered by external inject/timer
+        // ====================================================================
+        node.on("input", function(msg, send, done) {
+            send = send || function() { node.send.apply(node, arguments); };
+
+            // Guard against invalid msg
+            if (!msg) {
+                utils.setStatusError(node, "invalid message");
+                if (done) done();
+                return;
+            }
+
+            // ================================================================
+            // Handle trigger: any input message triggers a read request
+            // This is called by external inject node (user controls polling)
+            // ================================================================
+            if (msg.action === undefined || msg.action === "poll" || msg.action === "read") {
+                triggerRead();
+                if (done) done();
+                return;
+            }
+
+            // ================================================================
+            // Handle getPoint requests (from logic flows wanting cached value)
+            // ================================================================
+            if (msg.action === "getPoint") {
+                // Return cached value immediately (non-blocking)
+                const cacheAge = node.cache.timestamp ? Date.now() - node.cache.timestamp : null;
+                const responseMsg = RED.util.cloneMessage(msg);
+                responseMsg.action = "getPointResponse";
+                responseMsg.pointId = node.pointId;
+                responseMsg.value = node.cache.value;
+                responseMsg.cached = true;
+                responseMsg.age = cacheAge;
+                
+                send(responseMsg);
+                utils.setStatusUnchanged(node, `Served: ${getStatusText()}`);
+                if (done) done();
+                return;
+            }
+
+            // ================================================================
+            // Handle configuration commands
+            // ================================================================
+            if (msg.action === "resetCache") {
+                node.cache = { value: null, timestamp: null };
+                node.isPollPending = false;
+                utils.setStatusOK(node, "Cache reset");
+                if (done) done();
+                return;
+            }
+
+            // Unknown action - pass through (stack properties pattern)
+            send(msg);
+            if (done) done();
+        });
+
+        // ====================================================================
+        // Listen for responses from bridge via event
+        // ====================================================================
+        const responseHandler = function(data) {
+            // Only process responses meant for this node
+            if (data.sourceNodeId !== node.id) {
+                return;
+            }
+            
+            node.isPollPending = false;
+            
+            // Check for error response
+            if (data.error) {
+                const errorText = `Read failed for point #${node.pointId}: ${data.errorMessage || "Unknown error"}`;
+                utils.setStatusError(node, `Error: ${data.errorMessage || "Unknown error"}`);
+                node.error(errorText);  // Show in debug panel
+                // Don't update cache on error, keep stale value
+                return;
+            }
+            
+            let newValue = data.value;
+            
+            // Extract metadata if available
+            if (data.message) {
+                if (data.message.metadata) {
+                    node.cache.name = data.message.metadata.path || data.message.metadata.name;
+                }
+                
+                // If message available, try to robustly extract scalar value
+                if (data.message.value !== undefined) {
+                    newValue = data.message.value;
+                } else if (data.message.payload !== undefined && typeof data.message.payload !== 'object') {
+                    newValue = data.message.payload;
+                }
+            }
+
+            const valueChanged = node.cache.value !== newValue;
+
+            // Update cache with new value
+            node.cache.value = newValue;
+            node.cache.timestamp = Date.now();
+            
+            // Update status
+            if (valueChanged) {
+                utils.setStatusChanged(node, getStatusText());
+            } else {
+                utils.setStatusUnchanged(node, getStatusText());
+            }
+            
+            // Emit downstream (for wired alarm/history/logic)
+            // Uses node.send directly since this is event-triggered, not input-triggered
+            
+            const outMsg = {
+                pointId: node.pointId,
+                timestamp: node.cache.timestamp,
+                action: "pointUpdate"
+            };
+            
+            // Set output property (default: payload)
+            RED.util.setMessageProperty(outMsg, node.outputProperty, newValue);
+            
+            node.send(outMsg);
+        };
+        
+        RED.events.on('pointReference:response', responseHandler);
+
+        // ====================================================================
+        // Node lifecycle
+        // ====================================================================
+        node.on("close", function(done) {
+            // Remove event listener
+            RED.events.off('pointReference:response', responseHandler);
+            done();
+        });
+
+        // Set initial status
+        utils.setStatusOK(node, getStatusText());
+
+        // Update status again after a short delay to allow registry nodes to initialize
+        // This solves the race condition where this node loads before point-register nodes
+        setTimeout(() => {
+            const text = getStatusText();
+            // Only update if we are still in "waiting" or "initial" state (no value yet)
+            if (node.cache.value === null) {
+                utils.setStatusOK(node, text); 
+            } else {
+                // If we have a value, just update the label part
+                utils.setStatusChanged(node, text);
+            }
+        }, 2000);
+    }
+
+    RED.nodes.registerType("network-point-read", NetworkPointReadNode);
+};

package/nodes/{network-register.html → network-point-register.html}

@@ -1,4 +1,4 @@
-<script type="text/html" data-template-name="network-register">
+<script type="text/html" data-template-name="network-point-register">
     <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">
@@ -24,12 +24,12 @@
 </script>
 
 <script type="text/javascript">
-    RED.nodes.registerType('network-register', {
+    RED.nodes.registerType("network-point-register", {
         category: 'bldgblocks network',
         color: '#3090C7',
         defaults: {
             name: { value: "" },
-            registry: { value: "", type: "network-point-registry", required: true },
+            registry: { value: "", type: "network-service-registry", required: true },
             pointId: { value: null, required: true, validate: RED.validators.number() },
             writable: { value: false }
         },
@@ -38,9 +38,37 @@
         icon: "font-awesome/fa-book",
         label: function() {
             const id = this.pointId || "?";
-            return `(id:${id}) ${this.name || "network register"}`;
+            return `(id:${id}) ${this.name || "network point register"}`;
+        },
+        paletteLabel: "network point register",
+        onadd: function() {
+            // Fires when node is added to workspace (including paste/import)
+            const node = this;
+            const registry = node.registry;
+            
+            if (!registry || registry === "_ADD_") return;
+            
+            // Find max pointId and check for collision
+            let maxId = 0;
+            let collision = false;
+            const myId = parseInt(node.pointId);
+            
+            RED.nodes.eachNode(function(n) {
+                if (n.type === "network-point-register" && n.registry === registry && n.id !== node.id) {
+                    const pid = parseInt(n.pointId);
+                    if (!isNaN(pid)) {
+                        if (pid > maxId) maxId = pid;
+                        if (pid === myId) collision = true;
+                    }
+                }
+            });
+            
+            // If collision or no pointId, assign next available
+            if (collision || isNaN(myId) || myId === null) {
+                node.pointId = maxId + 1;
+                node.changed = true;
+            }
         },
-        paletteLabel: "network register",
         oneditprepare: function() {
             const nodeId = this.id;
             const statusSpan = $("#point-id-status");
@@ -85,11 +113,30 @@
 
             function loadNextFreeId(registry) {
                 if (!registry || registry === "_ADD_") { return; }
+                
+                // First, find highest pointId from ALL nodes in editor (deployed + not deployed)
+                let maxEditorId = 0;
+                RED.nodes.eachNode(function(n) {
+                    if (n.type === "network-point-register" && n.registry === registry && n.id !== nodeId) {
+                        const pid = parseInt(n.pointId);
+                        if (!isNaN(pid) && pid > maxEditorId) {
+                            maxEditorId = pid;
+                        }
+                    }
+                });
+
+                // Also check deployed registry for any points not visible in editor
                 $.getJSON(`/network-point-registry/list/${registry}`, function (data) {
-                    const next = data.reduce((max, pt) => Math.max(max, pt.id), 0) + 1;        
+                    const maxDeployedId = data.reduce((max, pt) => Math.max(max, pt.id), 0);
+                    const next = Math.max(maxEditorId, maxDeployedId) + 1;
                     idInput.val(next);
                 }).fail(function () {
-                    statusSpan.html('<i class="fa fa-exclamation-triangle" style="color:red;"></i> Cannot fetch points').show();
+                    // Fallback to editor-only max if server unavailable
+                    const next = maxEditorId + 1;
+                    idInput.val(next);
+                    if (maxEditorId === 0) {
+                        statusSpan.html('<i class="fa fa-exclamation-triangle" style="color:orange;"></i> Registry not deployed').show();
+                    }
                 });
             }
 
@@ -108,3 +155,43 @@
         }
     });
 </script>
+
+<!-- Help Section -->
+<script type="text/markdown" data-help-name="network-point-register">
+Register a data point in a network registry for shared access across devices, similar to BACnet usage.
+
+### Inputs
+: payload (object) : Expected flow from global-setter containing full network object properties.
+
+### Outputs
+: payload (any) : Current value of the registered network point.
+
+### Details
+Network Register nodes make data points discoverable from anywhere by assigning them a stable numeric ID within a registry.
+
+Each point requires a unique Point ID within its registry. The Point ID is used by other nodes (network-read, network-write) to reference this point without needing node links.
+
+Registry must be configured via a network-point-registry config node. Each registry is a separate namespace for point IDs.
+
+The Writable checkbox controls whether network-write nodes can update this point's value. Disabled by default.
+
+Usage: Set up your networking implementation, maybe websockets communication, discover available points using `action: "discover"` from that device for a list you can build from and set up network read flows to retrieve the data.
+
+Point ID Status:
+- Green check: Available or assigned to this node
+- Orange question: Registry not deployed  
+- Red exclamation: Point ID is taken by another node in the same registry
+
+The editor will auto-suggest the next available Point ID when creating a new node.
+
+### 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/{network-register.js → network-point-register.js}

@@ -1,6 +1,7 @@
 module.exports = function(RED) {
     const utils = require('./utils')(RED);
-    function NetworkRegisterNode(config) {
+
+    function NetworkPointRegisterNode(config) {
         RED.nodes.createNode(this, config);
         const node = this;
         
@@ -20,10 +21,10 @@ module.exports = function(RED) {
 
             if (success) {
                 node.isRegistered = true;
-                node.status({ fill: "yellow", shape: "ring", text: `ID: ${node.pointId} (Waiting)` });
+                utils.setStatusBusy(node, `ID: ${node.pointId} (Waiting)`);
             } else {
                 node.error(`Point ID ${node.pointId} is already in use.`);
-                node.status({ fill: "red", shape: "dot", text: "ID Conflict" });
+                utils.setStatusError(node, "ID Conflict");
             }
         }
 
@@ -90,6 +91,18 @@ module.exports = function(RED) {
                     return utils.sendSuccess(node, networkObject, done, statusText, node.pointId, "dot");
                 }
 
+                // Emit point-update event for reactive listeners (e.g., alarm-collector)
+                const pointUpdateData = {
+                    pointId: node.pointId,
+                    nodeId: node.id,
+                    value: msg.value,
+                    activePriority: msg.activePriority,
+                    units: msg.units || "",
+                    metadata: msg.metadata,
+                    timestamp: new Date().toISOString()
+                };
+                RED.events.emit("bldgblocks:network:point-update", pointUpdateData);
+
                 // Passthrough
                 const prefix = msg.activePriority === 'default' ? '' : 'P';
                 const statusText = `Passthrough: ${prefix}${msg.activePriority}:${msg.value}${msg.units}`;
@@ -108,5 +121,6 @@ module.exports = function(RED) {
             done();
         });
     }
-    RED.nodes.registerType("network-register", NetworkRegisterNode);
+    RED.nodes.registerType("network-point-register", NetworkPointRegisterNode);
+    RED.nodes.registerType("network-register", NetworkPointRegisterNode);
 }

package/nodes/network-point-write.html

@@ -0,0 +1,149 @@
+<script type="text/html" data-template-name="network-point-write">
+    <div class="form-row">
+        <label for="node-input-name" title="Display name shown on canvas"><i class="fa fa-tag"></i> Name</label>
+        <input type="text" id="node-input-name" placeholder="Write Zone Temp SP">
+    </div>
+    <div class="form-row">
+        <label for="node-input-pointId" title="Point ID to write to (e.g., 301)"><i class="fa fa-hashtag"></i> Point ID</label>
+        <input type="number" id="node-input-pointId" placeholder="301" min="0" required>
+    </div>
+    <div class="form-row">
+        <label for="node-input-priority" title="Write priority (1=highest, 16=lowest)"><i class="fa fa-sort-numeric-asc"></i> Priority</label>
+        <input type="number" id="node-input-priority" placeholder="16" min="1" max="16" required>
+    </div>
+    <div class="form-row">
+        <label for="node-input-inputProperty" title="Property to read value from (e.g., payload)"><i class="fa fa-sign-in"></i> Input Property</label>
+        <input type="text" id="node-input-inputProperty" placeholder="payload">
+    </div>
+    <hr style="margin: 10px 0;">
+    <div class="form-row">
+        <label for="node-input-bridgeNodeId" title="Select which network bridge to use"><i class="fa fa-link"></i> Network Bridge</label>
+        <input type="text" id="node-input-bridgeNodeId" style="width: calc(70% - 45px);">
+        <button id="node-config-find-bridge" class="editor-button" style="margin-left: 5px; width: 40px;" title="Find Bridge Node">
+            <i class="fa fa-search"></i>
+        </button>
+    </div>
+</script>
+
+<script type="text/javascript">
+    RED.nodes.registerType("network-point-write", {
+        category: "bldgblocks network",
+        color: "#3090C7",
+        defaults: {
+            name: { value: "" },
+            pointId: { 
+                value: 0, 
+                required: true,
+                validate: function(v) { 
+                    return !isNaN(parseInt(v)) && parseInt(v) >= 0; 
+                }
+            },
+            priority: {
+                value: 16,
+                required: true,
+                validate: function(v) {
+                    var p = parseInt(v);
+                    return !isNaN(p) && p >= 1 && p <= 16;
+                }
+            },
+            inputProperty: {
+                value: "payload",
+                required: true
+            },
+            bridgeNodeId: { 
+                value: "", 
+                required: true
+            }
+        },
+        inputs: 1,
+        outputs: 1,
+        inputLabels: ["value to write"],
+        outputLabels: ["write confirmation"],
+        icon: "font-awesome/fa-pencil",
+        paletteLabel: "network point write",
+        label: function() {
+            const id = this.pointId ? ` #${this.pointId}` : " (unconfigured)";
+            const pri = this.priority ? ` @${this.priority}` : "";
+            return this.name ? `${this.name}${id}${pri}` : `network point write${id}${pri}`;
+        },
+        oneditprepare: function() {
+            const node = this;
+            
+            let candidateNodes = [];
+            RED.nodes.eachNode(function(n) {
+                if (n.type === 'network-service-bridge') {
+                    candidateNodes.push({
+                        value: n.id,
+                        label: n.name || "(unnamed bridge)"
+                    });
+                }
+            });
+
+            candidateNodes.sort((a, b) => a.label.localeCompare(b.label));
+
+            $("#node-input-bridgeNodeId").typedInput({
+                types: [{ value: "bridge", options: candidateNodes }]
+            });
+
+            // Find button
+            $("#node-config-find-bridge").on("click", function() {
+                if (node.bridgeNodeId) {
+                    RED.viewport.reveal(node.bridgeNodeId);
+                }
+            });
+        },
+        oneditsave: function() {
+            // Optional: log configuration
+        }
+    });
+</script>
+
+<script type="text/markdown" data-help-name="network-point-write">
+Sends control commands to remote network points via service bridge.
+
+Validates payload before sending to prevent invalid network updates.
+
+### Inputs
+: payload (number | string | boolean) : Value to write from configured input property.
+: pointId (number) : Target remote point ID (e.g., 401).
+: priority (number) : Priority level (1-16, higher wins).
+: bridge (node) : Network service bridge for communication.
+
+### Outputs
+: payload (number | string | boolean) : Echo of sent value.
+: pointId (number) : Target point ID.
+: priority (number) : Priority used for this write.
+: timestamp (number) : Write timestamp (milliseconds since epoch).
+: action (string) : writeConfirmed or writeError.
+
+### Properties
+: name (string) : Display name in editor.
+: pointId (number) : The remote point ID to write to.
+: priority (number) : Write priority (1=highest, 16=lowest).
+: inputProperty (string) : Property to read value from (default payload).
+: bridgeNodeId (node) : The bridge node for network communication.
+
+### Details
+BACnet-style priority array (1-16):
+- 1: Manual Life Safety
+- 2: Automatic Life Safety
+- 5: Critical Equipment Control
+- 8: Manual Operator
+- 16: Default/Available (lowest)
+
+Configuration Commands:
+- pointId: Change target point
+- priority: Change write priority
+- release: Release priority (write null)
+
+### 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>