node-red-contrib-openbeken-subflow 1.1.0 → 1.3.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,69 @@ 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.
+    
+
+Anti-Chatter & Hybrid Sync (3-Way Switching)
+--------------------------------------------
+
+This subflow uses a **State-Locking** mechanism to prevent "Relay Chattering" (rapid oscillations) often caused by the race condition between OpenBeken UDP Groups and MQTT feedback loops.
+
+### How it Works:
+
+1.  **Physical Trigger:** When a physical switch is flipped, the hardware sends a 1/get message.
+    
+2.  **Lockout Window:** Upon receiving a hardware state change, the subflow "locks" the Sync Group for **400ms**.
+    
+3.  **Loop Prevention:** The subflow tags the outgoing synchronization message with source: "from\_hw".
+    
+4.  **Logic Gate:** Any node receiving a message tagged from\_hw will update its local relay but **will not** echo that change back out to the network. This breaks the infinite loop.
+    
+
+### Recommended Wiring for UDP Backup:
+
+If you want MQTT to act as a fail-safe for dropped UDP packets:
+
+*   Wire **Output 1** of Node A to **Input 1** of Node B.
+    
+*   Wire **Output 1** of Node B to **Input 1** of Node A.
+    
+*   Connect your Dashboard UI switch to the inputs of both nodes.
     
 
 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.json

@@ -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.3.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// Helper to reset UI to default\nconst uiReset = { \"offcolor\": \"\", \"officon\": \"\", \"onicon\": \"\" };\n// Helper for Offline UI state\nconst uiOffline = { \"offcolor\": \"red\", \"officon\": \"wifi-strength-off-outline\", \"onicon\": \"wifi-strength-off-outline\" };\n\n// --- 1. WATCHDOG TIMEOUT ---\nif (msg.topic === \"watchdog\") {\n    const s = { fill: \"red\", shape: \"ring\", text: \"Offline (Timeout)\" };\n    node.status(s);\n    // Output 1: Force UI Switch Off + Set Offline Icon\n    return [{ payload: false, ui_update: uiOffline }, null, { payload: s }];\n}\n\n// --- 2. INCOMING MQTT (Device -> Node-RED) ---\nif (msg.topic && msg.topic !== \"\") {\n\n    // Handle Connection Status\n    if (msg.topic.endsWith('connected')) {\n        const isOnline = (msg.payload === \"online\" || msg.payload === \"1\" || msg.payload === 1);\n        const s = {\n            fill: isOnline ? \"yellow\" : \"red\",\n            shape: isOnline ? \"dot\" : \"ring\",\n            text: isOnline ? \"Online\" : \"Offline\"\n        };\n        node.status(s);\n\n        if (!isOnline) {\n            // Force Switch off and show offline icon\n            return [{ payload: false, ui_update: uiOffline }, null, { payload: s }];\n        } else {\n            // Restore default icons/colors when back online\n            return [{ ui_update: uiReset }, null, { payload: s }];\n        }\n    }\n\n    // Handle Relay State\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        // We include uiReset here just in case it's the first message after a reconnect\n        return [{ payload: isOn, ui_update: uiReset }, null, { payload: s }];\n    }\n}\n\n// --- 3. UI COMMAND (Dashboard/Inject -> Device) ---\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\n// --- 1. WATCHDOG ---\nif (msg.topic === \"watchdog\") {\n    node.status({ fill: \"red\", shape: \"ring\", text: \"Offline\" });\n    return [null, null, null];\n}\n\n// --- 2. INCOMING MQTT (From Hardware) ---\n// Matches exactly {topicBase}/1/get\nif (msg.topic === `${topicBase}/1/get`) {\n    const isOn = (msg.payload == 1 || msg.payload === \"on\" || msg.payload === true);\n    const contextKey = \"sync_\" + syncGroup;\n    const lockKey = \"lock_\" + syncGroup;\n    \n    const lastKnown = global.get(contextKey);\n    const isLocked = global.get(lockKey) || false;\n\n    node.status({ fill: isOn ? \"green\" : \"grey\", shape: \"dot\", text: isOn ? \"On\" : \"Off\" });\n\n    // Propagate if state changed and we aren't currently in a 400ms lockout\n    if (syncGroup && isOn !== lastKnown && !isLocked) {\n        global.set(contextKey, isOn);\n        global.set(lockKey, true);\n        \n        // Lockout prevents circular triggers from busy networks or UDP echoes\n        setTimeout(() => { global.set(lockKey, false); }, 400);\n\n        return [{ payload: isOn, source: \"from_hw\" }, null, null];\n    }\n    return [null, null, null];\n}\n\n// --- 3. COMMAND LOGIC (From UI 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 mqttMsg = { topic: `${topicBase}/1/set`, payload: isTrue ? 1 : 0 };\n\n    if (msg.source === \"from_hw\") {\n        // This is a sync command from another node: update hardware only\n        return [null, mqttMsg, null];\n    } \n    \n    // This is a UI command: update hardware (the 1/get will handle sync)\n    return [null, mqttMsg, null];\n}\n\nreturn null;",
         "outputs": 3,
         "timeout": "",
         "noerr": 0,
@@ -264,4 +269,4 @@
             ]
         ]
     }
-]
+]

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "node-red-contrib-openbeken-subflow",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Optimized OpenBeken support for Node-RED with Dashboard 2.0 dynamic UI updates",
-  "main": "index.js",
+  "main": "openbeken.js",
   "node-red": {
     "nodes": {
       "openbeken": "openbeken.js"