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

package/nodes/network-point-write.js

@@ -0,0 +1,222 @@
+// ============================================================================
+// Point Write - Write values to remote points via network bridge
+// ============================================================================
+// Sends write requests to a remote point through the selected network bridge.
+// Supports priority levels (1-16) for BACnet-style priority arrays.
+// Configurable input property to read value from msg.
+// ============================================================================
+
+module.exports = function(RED) {
+    const utils = require('./utils')(RED);
+
+    function NetworkPointWriteNode(config) {
+        RED.nodes.createNode(this, config);
+        const node = this;
+
+        // ====================================================================
+        // Configuration
+        // ====================================================================
+        node.pointId = parseInt(config.pointId) || 0;
+        node.priority = parseInt(config.priority) || 16;  // Default to lowest priority
+        node.inputProperty = config.inputProperty || "payload";
+        node.bridgeNodeId = config.bridgeNodeId || "";
+
+        // ====================================================================
+        // State tracking
+        // ====================================================================
+        let pendingWrite = null;
+        let lastWriteTime = null;
+        let lastWriteValue = null;
+
+        // ====================================================================
+        // Helper: Get status text
+        // ====================================================================
+        function getStatusText() {
+            if (lastWriteValue !== null) {
+                return `#${node.pointId} @${node.priority}: ${lastWriteValue}`;
+            }
+            return `#${node.pointId} @${node.priority}: (no writes)`;
+        }
+
+        // ====================================================================
+        // Response handler - receives write confirmations from bridge
+        // ====================================================================
+        function responseHandler(response) {
+            // Only process responses for this node
+            if (response.sourceNodeId !== node.id) return;
+            if (response.pointId !== node.pointId) return;
+
+            pendingWrite = null;
+
+            if (response.error) {
+                const errorText = `Write failed for point #${node.pointId}: ${response.error}`;
+                utils.setStatusError(node, `#${node.pointId}: ${response.error}`);
+                node.error(errorText);  // Show in debug panel
+                node.send({
+                    payload: lastWriteValue,
+                    pointId: node.pointId,
+                    priority: node.priority,
+                    action: "writeError",
+                    error: response.error,
+                    timestamp: Date.now()
+                });
+            } else {
+                lastWriteTime = Date.now();
+                utils.setStatusChanged(node, getStatusText());
+                node.send({
+                    payload: lastWriteValue,
+                    pointId: node.pointId,
+                    priority: node.priority,
+                    action: "writeConfirmed",
+                    timestamp: lastWriteTime
+                });
+            }
+        }
+
+        // Register response listener
+        RED.events.on("pointWrite:response", responseHandler);
+
+        // Initial status
+        utils.setStatusOK(node, getStatusText());
+
+        // ====================================================================
+        // Input handler
+        // ====================================================================
+        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 configuration commands via msg.context
+            // ================================================================
+            if (msg.hasOwnProperty("context")) {
+                if (!msg.hasOwnProperty("payload")) {
+                    utils.setStatusError(node, `missing payload for ${msg.context}`);
+                    if (done) done();
+                    return;
+                }
+
+                if (msg.context === "pointId") {
+                    const newPointId = parseInt(msg.payload);
+                    if (isNaN(newPointId) || newPointId < 0) {
+                        utils.setStatusError(node, "invalid pointId");
+                        if (done) done();
+                        return;
+                    }
+                    node.pointId = newPointId;
+                    utils.setStatusOK(node, getStatusText());
+                    if (done) done();
+                    return;
+                }
+
+                if (msg.context === "priority") {
+                    const newPriority = parseInt(msg.payload);
+                    if (isNaN(newPriority) || newPriority < 1 || newPriority > 16) {
+                        utils.setStatusError(node, "priority must be 1-16");
+                        if (done) done();
+                        return;
+                    }
+                    node.priority = newPriority;
+                    utils.setStatusOK(node, getStatusText());
+                    if (done) done();
+                    return;
+                }
+
+                if (msg.context === "release") {
+                    // Release priority (write null to clear priority slot)
+                    if (!node.bridgeNodeId) {
+                        utils.setStatusError(node, "no bridge configured");
+                        if (done) done();
+                        return;
+                    }
+
+                    const requestId = `${node.id}-${Date.now()}`;
+                    pendingWrite = requestId;
+                    lastWriteValue = null;
+
+                    utils.setStatusWarn(node, `#${node.pointId} @${node.priority}: releasing...`);
+
+                    RED.events.emit("pointWrite:write", {
+                        sourceNodeId: node.id,
+                        bridgeNodeId: node.bridgeNodeId,
+                        pointId: node.pointId,
+                        priority: node.priority,
+                        value: null,  // null = release
+                        requestId: requestId
+                    });
+
+                    if (done) done();
+                    return;
+                }
+
+                utils.setStatusWarn(node, "unknown context");
+                if (done) done();
+                return;
+            }
+
+            // ================================================================
+            // Normal write - read value from configured input property
+            // ================================================================
+            if (!node.bridgeNodeId) {
+                utils.setStatusError(node, "no bridge configured");
+                if (done) done();
+                return;
+            }
+
+            // Read value from input property
+            let writeValue;
+            try {
+                writeValue = RED.util.getMessageProperty(msg, node.inputProperty);
+            } catch (err) {
+                utils.setStatusError(node, `invalid input property: ${node.inputProperty}`);
+                if (done) done();
+                return;
+            }
+
+            if (writeValue === undefined) {
+                utils.setStatusError(node, `missing ${node.inputProperty}`);
+                if (done) done();
+                return;
+            }
+
+            // Track the value we're writing
+            lastWriteValue = writeValue;
+
+            // Generate unique request ID
+            const requestId = `${node.id}-${Date.now()}`;
+            pendingWrite = requestId;
+
+            // Show pending status
+            utils.setStatusWarn(node, `#${node.pointId} @${node.priority}: writing ${writeValue}...`);
+
+            // Emit write request to bridge
+            RED.events.emit("pointWrite:write", {
+                sourceNodeId: node.id,
+                bridgeNodeId: node.bridgeNodeId,
+                pointId: node.pointId,
+                priority: node.priority,
+                value: writeValue,
+                requestId: requestId
+            });
+
+            if (done) done();
+        });
+
+        // ====================================================================
+        // Cleanup on close
+        // ====================================================================
+        node.on("close", function(done) {
+            RED.events.removeListener("pointWrite:response", responseHandler);
+            pendingWrite = null;
+            done();
+        });
+    }
+
+    RED.nodes.registerType("network-point-write", NetworkPointWriteNode);
+};

package/nodes/network-service-bridge.html

@@ -0,0 +1,131 @@
+<script type="text/html" data-template-name="network-service-bridge">
+    <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="Network Bridge">
+    </div>
+    <hr style="margin: 10px 0;">
+    <div class="form-row">
+        <label for="node-input-startupDelay" title="Delay before processing requests (seconds, allows network to come online)"><i class="fa fa-clock-o"></i> Startup Delay (sec)</label>
+        <input type="number" id="node-input-startupDelay" placeholder="30" min="0" step="1">
+    </div>
+</script>
+
+<script type="text/javascript">
+    RED.nodes.registerType("network-service-bridge", {
+        category: "bldgblocks network",
+        color: "#3090C7",
+        defaults: {
+            name: { value: "Network Bridge" },
+            startupDelay: { value: 30, required: false, validate: function(v) { return !isNaN(parseInt(v)) && parseInt(v) >= 0; } }
+        },
+        inputs: 1,
+        outputs: 1,
+        inputLabels: ["read requests / responses"],
+        outputLabels: ["routed to/from remote"],
+        icon: "font-awesome/fa-exchange",
+        paletteLabel: "network point bridge",
+        label: function() {
+            return this.name || "network point bridge";
+        }
+    });
+</script>
+
+<script type="text/markdown" data-help-name="network-service-bridge">
+Routes point read/write requests through WebSocket to remote devices and correlates responses.
+
+Sits in the network flow between point-reference nodes and WebSocket communication, handling request/response routing and request correlation.
+
+### Inputs
+: action (string) : Command - read, write
+: pointId (number) : Target point ID for read/write operations.
+: requestId (string) : Unique request identifier for correlation.
+: priority (number) : Priority level for write operations.
+: value (any) : Value to write (read operations ignore this).
+: timestamp (number) : Request timestamp (milliseconds since epoch).
+
+### Outputs
+: payload (object) : Response data (value for reads, status for writes).
+: pointId (number) : Echo of request point ID.
+: requestId (string) : Matching request ID for correlation.
+: action (string) : readResponse, writeResponse, or stats.
+: value (any) : Retrieved value (for reads) or winner value (for writes).
+: timestamp (number) : Response timestamp.
+
+### Details
+Request/Response Correlation:
+1. Assigns unique requestId to each request
+2. Tracks pending requests in memory
+3. Matches incoming responses to original requests
+4. Timeout: 10 seconds per request
+
+Management Commands:
+- getBridgeStats: Returns sent/received/pending counts
+- clearPending: Clear all pending request timeouts
+- resetStats: Reset statistics counters
+
+Flow Architecture:
+- Left input: Requests from point-read/point-write nodes
+- Right input: Responses from remote via WebSocket
+- Outputs routed appropriately (back to requester or to WebSocket)
+
+### Status
+- Green (dot): Idle, no pending requests
+- Blue (dot): Requests pending
+- Blue (ring): Active, zero pending
+- Yellow (ring): Some requests failed
+- Red (ring): Configuration error
+
+### References
+5. Cleans up stale requests automatically
+
+Request Flow:
+```
+[point-reference] sends read request
+    ↓
+[point-network-bridge] assigns requestId, forwards to WebSocket
+    ↓
+[WebSocket client] sends to remote
+    ↓
+[Remote receives, gets value]
+    ↓
+[WebSocket client] receives response
+    ↓
+[point-network-bridge] matches by requestId, forwards back
+    ↓
+[point-reference] updates cache
+```
+
+#### Architecture
+
+This node is the **bridge** between:
+- **LOCAL**: point-reference nodes (send read requests)
+- **REMOTE**: WebSocket endpoint (receives/sends over network)
+
+Enables non-blocking polling pattern:
+- Logic flows request cached values from point-reference
+- point-reference triggers reads via this bridge
+- Responses update cache in background
+- Logic flows get instant responses without network latency
+
+#### Statistics
+
+- **sent**: Total read requests sent to remote
+- **received**: Total responses received from remote
+- **errors**: Requests that timed out
+- **pending**: Currently outstanding requests
+
+#### Example Flow
+
+```
+Network Flow:
+[WebSocket client] ←→ [point-network-bridge]
+                              ↑
+                        [point-reference #301]
+                        [point-reference #302]
+                        (send read requests)
+```
+
+#### References
+- [Polling Architecture](../planning/POLLING_ARCHITECTURE.md)
+- [point-reference Node](./point-reference.html)
+</script>