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

package/nodes/network-service-bridge.js

@@ -0,0 +1,376 @@
+module.exports = function(RED) {
+    const utils = require('./utils')(RED);
+
+    function NetworkServiceBridgeNode(config) {
+        RED.nodes.createNode(this, config);
+        const node = this;
+
+        // ====================================================================
+        // Initialize configuration
+        // ====================================================================
+        node.startupDelay = parseInt(config.startupDelay) || 30;  // Delay in seconds
+        node.startupTime = Date.now();  // Track when node was deployed
+        node.startupComplete = false;
+
+        // ====================================================================
+        // Initialize state
+        // ====================================================================
+        node.pendingRequests = {};  // Track outstanding requests: { "pointId_timestamp": { pointId, timestamp, ... } }
+        node.stats = {
+            sent: 0,
+            received: 0
+        };
+
+        // ====================================================================
+        // Helper: Generate request ID
+        // ====================================================================
+        const generateRequestId = function(pointId) {
+            return `${pointId}_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+        };
+
+        // ====================================================================
+        // Helper: Update status
+        // ====================================================================
+        const updateStatus = function() {
+            // Check startup delay
+            if (!node.startupComplete) {
+                const elapsedSeconds = (Date.now() - node.startupTime) / 1000;
+                if (elapsedSeconds < node.startupDelay) {
+                    const remainingSeconds = Math.ceil(node.startupDelay - elapsedSeconds);
+                    utils.setStatusWarn(node, `Startup delay: ${remainingSeconds}s remaining...`);
+                    return;
+                } else {
+                    node.startupComplete = true;
+                }
+            }
+            
+            const pending = Object.keys(node.pendingRequests).length;
+            const successRate = node.stats.sent > 0 
+                ? Math.round((node.stats.received / node.stats.sent) * 100)
+                : 0;
+            
+            const statusText = `Listening (pending: ${pending}, success: ${successRate}%)`;
+            
+            if (pending === 0) {
+                utils.setStatusOK(node, statusText);
+            } else {
+                utils.setStatusUnchanged(node, statusText);
+            }
+        };
+
+        // ====================================================================
+        // Listen for read requests from point-reference nodes via event
+        // ====================================================================
+        const readRequestHandler = function(data) {
+            // Only process requests meant for this bridge
+            if (data.bridgeNodeId !== node.id) {
+                return;
+            }
+
+            // ================================================================
+            // Track if request is during startup phase (for error suppression)
+            // ================================================================
+            let isStartupPhase = false;
+            if (!node.startupComplete) {
+                const elapsedSeconds = (Date.now() - node.startupTime) / 1000;
+                if (elapsedSeconds < node.startupDelay) {
+                    isStartupPhase = true;
+                    const remainingSeconds = Math.ceil(node.startupDelay - elapsedSeconds);
+                    utils.setStatusWarn(node, `Startup delay: ${remainingSeconds}s - allowing retries...`);
+                } else {
+                    node.startupComplete = true;
+                    updateStatus();
+                }
+            }
+            
+            // Track this cross-flow request
+            node.pendingRequests[data.requestId] = {
+                requestId: data.requestId,
+                pointId: data.pointId,
+                timestamp: Date.now(),
+                sourceNodeId: data.sourceNodeId,  // Where to send response
+                isStartupPhase: isStartupPhase     // Mark if during startup (errors suppressed)
+            };
+
+            // Create outbound message for WebSocket
+            const outMsg = {
+                action: "read",
+                pointId: data.pointId,
+                requestId: data.requestId,
+                timestamp: Date.now()
+            };
+
+            // Send through WebSocket
+            node.send(outMsg);
+            
+            node.stats.sent++;
+            updateStatus();
+            
+            // Timeout: if no response after 10 seconds, clean up
+            setTimeout(() => {
+                if (node.pendingRequests[data.requestId]) {
+                    const pending = node.pendingRequests[data.requestId];
+                    delete node.pendingRequests[data.requestId];
+                    
+                    // Suppress error notification during startup phase
+                    // (allows network to come online without nuisance errors)
+                    if (pending.isStartupPhase) {
+                        // Silently drop timeout during startup
+                        return;
+                    }
+                    
+                    const errorText = `Read timeout for point #${data.pointId}`;
+                    utils.setStatusWarn(node, errorText);
+                    node.error(errorText);  // Show in debug panel
+                    
+                    // Notify point-reference of timeout
+                    RED.events.emit('pointReference:response', {
+                        sourceNodeId: data.sourceNodeId,
+                        pointId: data.pointId,
+                        value: null,
+                        error: true,
+                        errorMessage: "Read timeout",
+                        requestId: data.requestId
+                    });
+                }
+            }, 10000);
+        };
+        
+        RED.events.on('pointReference:read', readRequestHandler);
+
+        // ====================================================================
+        // Listen for write requests from point-write nodes via event
+        // ====================================================================
+        const writeRequestHandler = function(data) {
+            // Only process requests meant for this bridge
+            if (data.bridgeNodeId !== node.id) {
+                return;
+            }
+
+            // ================================================================
+            // Track if request is during startup phase (for error suppression)
+            // ================================================================
+            let isStartupPhase = false;
+            if (!node.startupComplete) {
+                const elapsedSeconds = (Date.now() - node.startupTime) / 1000;
+                if (elapsedSeconds < node.startupDelay) {
+                    isStartupPhase = true;
+                    const remainingSeconds = Math.ceil(node.startupDelay - elapsedSeconds);
+                    utils.setStatusWarn(node, `Startup delay: ${remainingSeconds}s - allowing retries...`);
+                } else {
+                    node.startupComplete = true;
+                    updateStatus();
+                }
+            }
+            
+            // Track this cross-flow request
+            node.pendingRequests[data.requestId] = {
+                requestId: data.requestId,
+                pointId: data.pointId,
+                timestamp: Date.now(),
+                sourceNodeId: data.sourceNodeId,
+                isWrite: true,
+                isStartupPhase: isStartupPhase  // Mark if during startup (errors suppressed)
+            };
+
+            // Create outbound message for WebSocket
+            const outMsg = {
+                action: "write",
+                pointId: data.pointId,
+                priority: data.priority,
+                value: data.value,
+                requestId: data.requestId,
+                timestamp: Date.now()
+            };
+
+            // Send through WebSocket
+            node.send(outMsg);
+            
+            node.stats.sent++;
+            updateStatus();
+            
+            // Timeout: if no response after 10 seconds, clean up
+            setTimeout(() => {
+                if (node.pendingRequests[data.requestId]) {
+                    const pending = node.pendingRequests[data.requestId];
+                    delete node.pendingRequests[data.requestId];
+                    
+                    // Suppress error notification during startup phase
+                    // (allows network to come online without nuisance errors)
+                    if (pending.isStartupPhase) {
+                        // Silently drop timeout during startup
+                        return;
+                    }
+                    
+                    const errorText = `Write timeout for point #${data.pointId}`;
+                    utils.setStatusWarn(node, errorText);
+                    node.error(errorText);  // Show in debug panel
+                    
+                    // Notify point-write of timeout
+                    RED.events.emit('pointWrite:response', {
+                        sourceNodeId: pending.sourceNodeId,
+                        pointId: data.pointId,
+                        error: "Write timeout",
+                        requestId: data.requestId
+                    });
+                }
+            }, 10000);
+        };
+        
+        RED.events.on('pointWrite:write', writeRequestHandler);
+
+        // ====================================================================
+        // Main message handler - ONLY processes WebSocket responses
+        // Read/write requests come via events, not wired input
+        // ====================================================================
+        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 response from WebSocket (network-read returns data object)
+            // Response has: network.pointId, value (or payload), status.code
+            // Route back to point-reference via event
+            // ================================================================
+            
+            // Check if this looks like a point response (has network.pointId or status.pointId)
+            const responsePointId = msg.network?.pointId ?? msg.status?.pointId ?? msg.pointId;
+            const responseValue = msg.value ?? msg.payload;
+            const statusCode = msg.status?.code;
+            const statusMessage = msg.status?.message || "";
+            const isError = statusCode === "error";
+            
+            // Valid response if we have a pointId (value can be null/undefined on error)
+            const isValidResponse = responsePointId !== undefined;
+            
+            if (isValidResponse) {
+                // Find ALL matching pending requests by pointId
+                // Multiple nodes might be waiting for the same point
+                const matchingRequests = [];
+                
+                for (const [reqId, reqData] of Object.entries(node.pendingRequests)) {
+                    if (reqData.pointId === responsePointId) {
+                        matchingRequests.push({
+                            requestId: reqId,
+                            sourceNodeId: reqData.sourceNodeId,
+                            isWrite: reqData.isWrite,
+                            isStartupPhase: reqData.isStartupPhase  // Preserve startup phase flag
+                        });
+                    }
+                }
+                
+                if (matchingRequests.length > 0) {
+                    // Remove all matched requests from pending BEFORE notifying
+                    // (prevents race conditions if notification triggers new requests)
+                    for (const match of matchingRequests) {
+                        delete node.pendingRequests[match.requestId];
+                    }
+                    
+                    // Now notify all waiting nodes
+                    for (const match of matchingRequests) {
+                        const eventName = match.isWrite ? 'pointWrite:response' : 'pointReference:response';
+                        
+                        if (isError) {
+                            RED.events.emit(eventName, {
+                                sourceNodeId: match.sourceNodeId,
+                                pointId: responsePointId,
+                                value: null,
+                                error: match.isWrite ? statusMessage : true,
+                                errorMessage: statusMessage,
+                                requestId: match.requestId,
+                                timestamp: Date.now(),
+                                isStartupPhase: match.isStartupPhase  // Pass startup phase flag
+                            });
+                        } else {
+                            // Success response
+                            node.stats.received++;
+                            
+                            RED.events.emit(eventName, {
+                                sourceNodeId: match.sourceNodeId,
+                                pointId: responsePointId,
+                                value: responseValue,
+                                message: msg,
+                                error: match.isWrite ? null : false,
+                                requestId: match.requestId,
+                                timestamp: msg.timestamp || Date.now(),
+                                isStartupPhase: match.isStartupPhase  // Pass startup phase flag
+                            });
+                        }
+                    }
+                    
+                    // Update status once after all notifications
+                    if (isError) {
+                        const errorText = `Error for #${responsePointId}: ${statusMessage}`;
+                        utils.setStatusWarn(node, errorText);
+                        node.error(errorText);  // Show in debug panel
+                    } else {
+                        updateStatus();
+                    }
+                } else {
+                    // Response without matching request - could be stale or unsolicited
+                    utils.setStatusWarn(node, `Unmatched response for point #${responsePointId}`);
+                }
+
+                if (done) done();
+                return;
+            }
+
+            // ================================================================
+            // Handle statistics/status queries
+            // ================================================================
+            if (msg.action === "getBridgeStats") {
+                const statsMsg = {
+                    action: "bridgeStats",
+                    stats: node.stats,
+                    pendingCount: Object.keys(node.pendingRequests).length,
+                    pending: Object.keys(node.pendingRequests)
+                };
+                send(statsMsg);
+                if (done) done();
+                return;
+            }
+
+            if (msg.action === "clearPending") {
+                node.pendingRequests = {};
+                utils.setStatusOK(node, "Pending requests cleared");
+                if (done) done();
+                return;
+            }
+
+            if (msg.action === "resetStats") {
+                node.stats = { sent: 0, received: 0 };
+                utils.setStatusOK(node, "Stats reset");
+                if (done) done();
+                return;
+            }
+
+            // Unknown action - pass through anyway (could be for other nodes)
+            if (done) done();
+        });
+
+        // ====================================================================
+        // Node lifecycle
+        // ====================================================================
+        node.on("close", function(done) {
+            // Clear pending requests on close
+            node.pendingRequests = {};
+            // Remove event listeners
+            RED.events.off('pointReference:read', readRequestHandler);
+            RED.events.off('pointWrite:write', writeRequestHandler);
+            done();
+        });
+
+        // ====================================================================
+        // Initialize
+        // ====================================================================
+        updateStatus();
+    }
+
+    RED.nodes.registerType("network-service-bridge", NetworkServiceBridgeNode);
+};

package/nodes/network-service-read.html

@@ -0,0 +1,81 @@
+<script type="text/html" data-template-name="network-service-read">
+    <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-registry"><i class="fa fa-book"></i> Registry</label>
+        <input type="text" id="node-input-registry">
+    </div>
+    
+    <div class="form-tips">
+        <b>Input Payload Format:</b><br>
+        <pre>
+        {
+            "action": "read",
+            "pointId": 101
+        }
+        </pre>
+    </div>
+</script>
+
+<script type="text/javascript">
+    RED.nodes.registerType('network-service-read', {
+        category: 'bldgblocks network',
+        color: '#3090C7',
+        defaults: {
+            name: { value: "" },
+            registry: { value: "", type: "network-service-registry", required: true }
+        },
+        inputs: 1,
+        outputs: 1,
+        icon: "font-awesome/fa-database",
+        label: function() {
+            return "network service read";
+        },
+        paletteLabel: "network service read",
+        oneditprepare: function() {
+            const nodeId = this.id;
+        }
+    });
+</script>
+
+<script type="text/markdown" data-help-name="network-service-read">
+Reads a network point value from the service registry.
+
+Looks up global variable path corresponding to pointId and returns the current value.
+
+### Inputs
+: action (string) : Command - read to retrieve point value.
+: pointId (number) : The integer ID of the point to read.
+: payload (object) : Message object (optional, can include context).
+
+### Outputs
+: payload (object) : Value of the referenced global variable.
+: pointId (number) : Echo of requested point ID.
+: status (string) : ok or error status code.
+: message (string) : Status message describing result.
+
+### Details
+Registry Lookup Process:
+1. Receives pointId in input message
+2. Queries Network Service Registry for point metadata (path, store)
+3. Fetches value from global context using path/store
+4. Returns value in payload
+
+Use With:
+- network-service-registry - Central point registry config
+- network-service-bridge - Remote point access
+
+### 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-read.js → network-service-read.js}

@@ -1,6 +1,7 @@
 module.exports = function(RED) {
     const utils = require('./utils')(RED);
-    function NetworkReadNode(config) {
+    
+    function NetworkServiceReadNode(config) {
         RED.nodes.createNode(this, config);
         const node = this;
         node.registry = RED.nodes.getNode(config.registry);
@@ -10,7 +11,7 @@ module.exports = function(RED) {
             
             try {
                 if (!node.registry) {
-                    node.status({ fill: "red", shape: "ring", text: "Registry missing" });
+                    utils.setStatusError(node, "Registry missing");
                     if (done) done();
                     return;
                 }
@@ -53,5 +54,5 @@ module.exports = function(RED) {
             done();
         });
     }
-    RED.nodes.registerType("network-read", NetworkReadNode);
+    RED.nodes.registerType("network-service-read", NetworkServiceReadNode);
 }

package/nodes/{network-point-registry.html → network-service-registry.html}

@@ -1,4 +1,4 @@
-<script type="text/html" data-template-name="network-point-registry">
+<script type="text/html" data-template-name="network-service-registry">
     <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="Main Registry">
@@ -24,7 +24,7 @@
 </script>
 
 <script type="text/javascript">
-    RED.nodes.registerType('network-point-registry', {
+    RED.nodes.registerType("network-service-registry", {
         category: 'config',
         defaults: {
             name: { value: "" }
@@ -75,12 +75,27 @@
     });
 </script>
 
-<script type="text/markdown" data-help-name="network-point-registry">
-Central database mapping Point IDs to Global Variables.
+<script type="text/markdown" data-help-name="network-service-registry">
+Map Point IDs to global variables.
 
 ### Details
+Maintains the mapping between integer Point IDs and global variable paths. This registry is used by network-read, network-write, and network-register nodes to decouple access by ID from variable path implementation details.
+
+Create a single registry for your network of nodes and reference it from each network-register node.
 
 **API for Developers:**
 * `register(id, meta)`: Claim an ID.
 * `lookup(id)`: Find the path/store for an ID.
+
+### 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-point-registry.js → network-service-registry.js}

@@ -1,8 +1,13 @@
 module.exports = function(RED) {
-    function NetworkPointRegistryNode(config) {
+    
+    function NetworkServiceRegistryNode(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: { 101: { nodeId: "abc.123", writable: true, ... } }
         node.points = new Map();
 
@@ -34,7 +39,7 @@ module.exports = function(RED) {
             return node.points.get(parseInt(pointId));
         };
     }
-    RED.nodes.registerType("network-point-registry", NetworkPointRegistryNode);
+    RED.nodes.registerType("network-service-registry", NetworkServiceRegistryNode);
 
     // --- HTTP Endpoint for Editor Validation ---
     // Route: /network-point-registry/check/<RegistryID>/<PointID>/<CurrentNodeID>

package/nodes/network-service-write.html

@@ -0,0 +1,89 @@
+<script type="text/html" data-template-name="network-service-write">
+    <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-registry"><i class="fa fa-book"></i> Registry</label>
+        <input type="text" id="node-input-registry">
+    </div>
+    
+    <div class="form-tips">
+        <b>Input Payload Format:</b><br>
+        <pre>
+        {
+            "action": "write",
+            "pointId": 101,
+            "priority": 8,
+            "value": 75.5  // or null || "null" to release
+        }
+        </pre>
+    </div>
+</script>
+
+<script type="text/javascript">
+    RED.nodes.registerType('network-service-write', {
+        category: 'bldgblocks network',
+        color: '#3090C7',
+        defaults: {
+            name: { value: "" },
+            registry: { value: "", type: "network-service-registry", required: true }
+        },
+        inputs: 1,
+        outputs: 1,
+        icon: "font-awesome/fa-pencil", 
+        label: function() {
+            return this.name || "network service write";
+        },
+        paletteLabel: "network service write",
+        oneditprepare: function() {
+            
+        }
+    });
+</script>
+
+<script type="text/markdown" data-help-name="network-service-write">
+Writes network commands to global variables using priority array logic.
+
+Acts as inbound gateway, handling priority write arbitration and global state synchronization.
+
+### Inputs
+: payload (object) : Command object with `action`, `pointId`, `priority`, `value`.
+: action (string) : Command type - write for standard priority write.
+: pointId (number) : The integer ID of the point target.
+: priority (number) : Priority level (1-16) to write to, or 0 for release.
+: value (any) : Value to set at priority level, or null to relinquish.
+
+### Outputs
+: payload (object) : Confirmation object with status, pointId, winner value.
+: pointId (number) : Point ID of write target.
+: priority (number) : Priority level that was written.
+: winner (any) : Current highest-priority active value.
+: timestamp (number) : Write timestamp (milliseconds since epoch).
+: status (string) : ok or error status.
+
+### Details
+Priority Write Process:
+1. Looks up pointId in Registry for global variable path
+2. Fetches current state object from global context
+3. Updates specific slot in priority array
+4. Recalculates Present Value (highest priority active)
+5. Saves global variable and emits update event
+6. Triggers reactive getters immediately
+
+Priority Rules:
+- Level 1-16: Explicit priorities, higher wins
+- Level 0: Release (relinquish) this priority
+- null value: Clear the slot
+
+### Status
+- Green (dot): Write successful
+- Blue (dot): State changed
+- Blue (ring): No change
+- 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-write.js → network-service-write.js}

@@ -1,6 +1,6 @@
 module.exports = function(RED) {
     const utils = require('./utils')(RED);
-    function NetworkWriteNode(config) {
+    function NetworkServiceWriteNode(config) {
         RED.nodes.createNode(this, config);
         const node = this;
         node.registry = RED.nodes.getNode(config.registry);
@@ -69,7 +69,7 @@ module.exports = function(RED) {
 
                 msg = { ...state, status: null }; 
                 
-                RED.events.emit("bldgblocks-global-update", { key: path, store: store, data: state });
+                RED.events.emit("bldgblocks:global:value-changed", { key: path, store: store, data: state });
 
                 utils.sendSuccess(node, msg, done, statusMsg, msg.pointId, "ring");
 
@@ -79,5 +79,5 @@ module.exports = function(RED) {
             }
         });
     }
-    RED.nodes.registerType("network-write", NetworkWriteNode);
+    RED.nodes.registerType("network-service-write", NetworkServiceWriteNode);
 }