node-red-contrib-openbeken-subflow 1.0.0 → 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gparduino
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,7 +1,7 @@
 node-red-contrib-openbeken-subflow
 ==================================
 
-A high-performance Node-RED node designed specifically for **OpenBeken** flashed hardware. This node simplifies the integration of devices using **Flag 10** (immediate MQTT state feedback) and includes a built-in watchdog timer to monitor device health.
+A high-performance Node-RED subflow designed specifically for **OpenBeken** flashed hardware. This node simplifies the integration of devices using **Flag 10 and Flag 2** (immediate MQTT state feedback), provides built-in watchdog monitoring, and supports **Cross-Device Synchronization** for 3-way switch configurations.
 
 Features
 --------
@@ -10,36 +10,54 @@ Features
     
 *   **Watchdog Timer:** Monitors device activity and updates the node status to "Offline" if no heartbeat is detected within 5 minutes.
     
-*   **Smart Sanitization:** Accepts Booleans (true/false), Strings ("on"/off"), or Numbers (1/0) and converts them to the correct format for OpenBeken.
+*   **State-Sync Groups:** Support for multi-way (3-way/4-way) switching. Link multiple devices via a Global context to ensure states match even if UDP packets are dropped or firewalled.
     
-*   **Zero-Config UI:** Designed to work out of the box with Node-RED Dashboard 2.0.
+*   **Smart Sanitization:** Accepts Booleans (true/false), Strings ("on"/"off"), or Numbers (1/0) and converts them to the correct format for OpenBeken.
+    
+*   **Dashboard 2.0 Ready:** Native support for UI updates including icon/color changes based on device connectivity.
     
 
 Hardware Requirements
 ---------------------
 
-For the best experience, ensure your OpenBeken device has **Flag 10** enabled. Open your device's web console and run:Backlog Flag 10 1; restart
+For the best experience, ensure your OpenBeken device has **Flag 10 and Flag 2** enabled. Open your device's web console and run:Backlog Flag 10 1; Flag 2 1; restart
 
 Configuration
 -------------
 
 1.  **Broker:** Select your MQTT Broker configuration node.
     
-2.  **Topic Base:** Enter the base MQTT topic of your device (e.g., BedroomFan). **Do not** include trailing slashes.
+2.  **Topic Base:** Enter the base MQTT topic of your device (e.g., KitchenLights). **Do not** include trailing slashes.
+    
+3.  **Sync Group (Optional):** Enter a unique string (e.g., Kitchen3Way) to link multiple nodes together. Nodes sharing the same group name will stay synchronized automatically.
+    
+
+3-Way Switching Setup (Cross-Sync)
+----------------------------------
+
+To use this node as a backup for OpenBeken Device Groups (or when UDP is blocked):
+
+1.  Give both nodes the same **Sync Group** name.
+    
+2.  Cross-connect the nodes in your flow: Wire **Output 1** of Node A to **Input 1** of Node B, and vice versa.
+    
+3.  The nodes use a source: "from\_hw" tag to prevent infinite relay loops.
     
 
 Input/Output
 ------------
 
-*   **Input:** Send a boolean true/false or string "on"/off" to toggle the device.
+*   **Input:** Send a boolean true/false or string "on"/"off" to toggle the device.
+    
+*   **Output 1:** Returns a clean boolean true/false based on the hardware's actual state. Perfect for updating Dashboard switches.
     
-*   **Output 1:** Returns a clean boolean true/false based on the hardware's actual state.
+*   **Output 2:** MQTT output (Internal use, wire to MQTT Out node).
     
-*   **Output 2:** (Optional) Provides detailed status objects for logging or advanced logic.
+*   **Output 3:** Status output for custom logging or dashboard indicators.
     
 
 ### Tips for Success
 
-*   **Dashboard 2.0:** Simply wire a Dashboard "Switch" node to the input and back from the output for a perfectly synchronized UI.
+*   **Dashboard 2.0:** Wire a Dashboard "Switch" node to the input of any node in a Sync Group. To ensure the UI reflects changes from all physical switches, wire **Output 1** of _all_ grouped nodes back to the Dashboard Switch input.
     
-*   **LWT:** This node relies on the device being "connected" to show online status. Ensure your MQTT Broker is configured to handle the device's Last Will and Testament (LWT).
+*   **LWT:** This node relies on the device being "connected" to show online status. Ensure your MQTT Broker is configured to handle the device's Last Will and Testament (LWT).

package/openbeken.js

@@ -1,11 +1,10 @@
+const fs = require('fs');
+const path = require('path');
+
 module.exports = function(RED) {
-    const fs = require("fs");
-    const path = require("path");
+    const subflowFile = path.join(__dirname, 'openbeken.json');
+    const subflowContents = fs.readFileSync(subflowFile, 'utf8');
+    const subflowJSON = JSON.parse(subflowContents);
     
-    // Load the subflow JSON file
-    const subflowPath = path.join(__dirname, "openbeken.json");
-    const subflowData = JSON.parse(fs.readFileSync(subflowPath, "utf8"));
-    
-    // Register the subflow with Node-RED
-    RED.nodes.registerSubflow(subflowData[0]); 
+    RED.nodes.registerSubflow(subflowJSON);
 };

package/openbeken.json

@@ -3,7 +3,7 @@
         "id": "287344f336f70f21",
         "type": "subflow",
         "name": "OpenBeken Optimized",
-        "info": "Improved handling for Flag 10 devices with watchdog timer.",
+        "info": "Improved handling for Flag 10 + Flag 2 devices with watchdog timer and support for groups.",
         "category": "",
         "in": [
             {
@@ -44,12 +44,17 @@
                     },
                     "type": "conf-types"
                 }
+            },
+            {
+                "name": "SYNC_GROUP",
+                "type": "str",
+                "value": ""
             }
         ],
         "meta": {
             "module": "node-red-contrib-openbeken-subflow",
             "type": "openbeken",
-            "version": "1.0.0",
+            "version": "1.2.0",
             "author": "gparduino",
             "desc": "OpenBeken flashed module support",
             "keywords": "openbeken",
@@ -73,7 +78,7 @@
         "type": "function",
         "z": "287344f336f70f21",
         "name": "Process MQTT & UI",
-        "func": "const topicBase = env.get(\"TOPIC_BASE\");\n\n// --- 1. WATCHDOG TIMEOUT ---\nif (msg.topic === \"watchdog\") {\n    const s = { fill: \"red\", shape: \"ring\", text: \"Offline (Timeout)\" };\n    node.status(s);\n    return [null, null, { payload: s }];\n}\n\n// --- 2. INCOMING MQTT (Device -> Node-RED) ---\nif (msg.topic && msg.topic !== \"\") {\n    if (msg.topic.endsWith('connected')) {\n        const isOnline = (msg.payload === \"online\" || msg.payload === \"1\" || msg.payload === 1);\n        const s = { fill: isOnline ? \"yellow\" : \"red\", shape: isOnline ? \"dot\" : \"ring\", text: isOnline ? \"Online\" : \"Offline\" };\n        node.status(s);\n        return [null, null, { payload: s }];\n    }\n\n    if (msg.topic.endsWith('1/get')) {\n        const isOn = (msg.payload == 1 || msg.payload === \"on\" || msg.payload === true);\n        const s = { fill: isOn ? \"green\" : \"grey\", shape: \"dot\", text: isOn ? \"On\" : \"Off\" };\n        node.status(s);\n        return [{ payload: isOn }, null, { payload: s }];\n    }\n}\n\n// --- 3. UI COMMAND (Dashboard/Inject -> Device) ---\n// We handle booleans OR the strings \"on\"/\"off\"\nconst p = msg.payload;\nif (typeof p === \"boolean\" || p === \"on\" || p === \"off\" || p === \"1\" || p === \"0\") {\n    const isTrue = (p === true || p === \"on\" || p === \"1\" || p === 1);\n    const outTopic = `${topicBase}/1/set`;\n    return [null, { topic: outTopic, payload: isTrue ? 1 : 0 }, null];\n}\n\nreturn null;",
+        "func": "const topicBase = env.get(\"TOPIC_BASE\");\nconst syncGroup = env.get(\"SYNC_GROUP\");\n\nconst uiReset = { \"offcolor\": \"\", \"officon\": \"\", \"onicon\": \"\" };\nconst uiOffline = { \"offcolor\": \"red\", \"officon\": \"wifi-strength-off-outline\", \"onicon\": \"wifi-strength-off-outline\" };\n\n// --- 1. WATCHDOG ---\nif (msg.topic === \"watchdog\") {\n    const s = { fill: \"red\", shape: \"ring\", text: \"Offline\" };\n    node.status(s);\n    return [{ payload: false, ui_update: uiOffline }, null, { payload: s }];\n}\n\n// --- 2. INCOMING MQTT (Status confirmation from Device) ---\nif (msg.topic && msg.topic !== \"\") {\n    \n    // Connection Status\n    if (msg.topic.endsWith('connected')) {\n        const isOnline = (msg.payload === \"online\" || msg.payload === \"1\" || msg.payload === 1);\n        const s = { fill: isOnline ? \"yellow\" : \"red\", shape: isOnline ? \"dot\" : \"ring\", text: isOnline ? \"Online\" : \"Offline\" };\n        node.status(s);\n        return [isOnline ? { ui_update: uiReset } : { payload: false, ui_update: uiOffline }, null, { payload: s }];\n    }\n\n    // Relay State Confirmation (1/get)\n    if (msg.topic.endsWith('1/get')) {\n        const isOn = (msg.payload == 1 || msg.payload === \"on\" || msg.payload === true);\n        const s = { fill: isOn ? \"green\" : \"grey\", shape: \"dot\", text: isOn ? \"On\" : \"Off\" };\n        node.status(s);\n\n        if (syncGroup) {\n            const contextKey = \"sync_\" + syncGroup;\n            \n            // USE GLOBAL CONTEXT - Works in all Node-RED configs\n            const lastKnown = global.get(contextKey);\n            \n            // If the state is already recorded, stop the loop\n            if (isOn === lastKnown) {\n                return [null, null, { payload: s }];\n            }\n\n            // Update the global record\n            global.set(contextKey, isOn);\n\n            // Output 1: Sync partner + update UI\n            return [{ payload: isOn, ui_update: uiReset, source: \"from_hw\" }, null, { payload: s }];\n        }\n        return [{ payload: isOn, ui_update: uiReset }, null, { payload: s }];\n    }\n}\n\n// --- 3. COMMAND LOGIC (UI Switch or Sync Input) ---\nconst p = msg.payload;\nif (typeof p === \"boolean\" || p === \"on\" || p === \"off\" || p === \"1\" || p === \"0\") {\n    const isTrue = (p === true || p === \"on\" || p === \"1\" || p === 1);\n    const outTopic = `${topicBase}/1/set`;\n\n    // THE FAIL-SAFE COMMAND: Always send the MQTT command to the device\n    const mqttMsg = { topic: outTopic, payload: isTrue ? 1 : 0 };\n\n    if (msg.source === \"from_hw\") {\n        // Just command the hardware\n        return [null, mqttMsg, null];\n    } else {\n        // UI Interaction: Command hardware, don't update context yet (wait for 1/get)\n        return [null, mqttMsg, null];\n    }\n}\n\nreturn null;",
         "outputs": 3,
         "timeout": "",
         "noerr": 0,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "node-red-contrib-openbeken-subflow",
-  "version": "1.0.0",
-  "description": "OpenBeken support for Node-RED",
+  "version": "1.2.0",
+  "description": "Optimized OpenBeken support for Node-RED with Dashboard 2.0 dynamic UI updates",
   "main": "openbeken.js",
   "node-red": {
     "nodes": {
@@ -11,8 +11,16 @@
   "keywords": [
     "node-red",
     "openbeken",
-    "tuya"
+    "tuya",
+    "dashboard-2.0",
+    "mqtt"
   ],
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "peerDependencies": {
+    "node-red": ">=3.0.0"
+  },
   "author": "gparduino",
   "license": "MIT"
 }