node-red-contrib-symi-mesh 1.6.7 → 1.6.9

package/README.md

@@ -16,6 +16,7 @@
 - **三合一面板**：完整支持空调+新风+地暖三合一控制面板，自动识别
 - **RS485/Modbus集成**：支持第三方485设备双向同步，内置协议模板
 - **KNX集成**：支持与KNX系统双向同步
+- **KNX-HA集成**：支持KNX与Home Assistant实体直接双向同步
 - **云端同步**：从酒店云云平台自动获取设备名称和场景信息
 - **稳定可靠**：完善的错误处理和自动重连机制
 
@@ -179,6 +180,208 @@ node-red-restart
 
 每个功能独立同步，互不干扰。
 
+## KNX-HA双向同步
+
+本节点支持KNX与Home Assistant实体直接双向同步，实现KNX系统与HA的实时互联互通。
+
+### 功能特点
+
+- **直接实体同步**：通过HA events-state节点实时接收HA状态变化事件
+- **KNX实体导入**：支持Tab分隔格式导入KNX组地址配置，与KNX桥接节点100%一致
+- **HA实体加载**：从HA服务器节点自动加载所有支持的实体
+- **快速输入**：支持直接输入实体ID或名称搜索，带autocomplete提示，支持806+实体
+- **多设备类型**：开关、灯光、窗帘、空调、风扇
+- **双向同步**：自动处理KNX↔HA状态同步
+- **智能防抖**：调光300ms、窗帘500ms防抖，避免过程中频繁同步
+- **防死循环**：内置800ms防抖机制
+- **持久化保存**：映射配置自动保存，重启后保持
+- **宽屏界面**：对话框最小900px宽度，适配大屏幕
+
+### 配置步骤
+
+#### 1. 安装依赖节点
+
+```bash
+cd ~/.node-red
+npm install node-red-contrib-knx-ultimate
+npm install node-red-contrib-home-assistant-websocket
+```
+
+#### 2. 配置HA服务器
+
+1. 添加Home Assistant服务器配置节点（如果还没有）
+2. 输入HA的URL和访问令牌
+3. 测试连接确保成功
+
+#### 3. 添加KNX-HA桥接节点
+
+从"Symi Mesh"分类中拖入"KNX-HA桥接"节点
+
+#### 4. 选择HA服务器
+
+在节点配置中选择已配置的Home Assistant服务器节点
+
+#### 5. 导入KNX实体
+
+1. 点击"下载模板"获取导入格式示例
+2. 按照Tab分隔格式准备KNX组地址数据
+3. 点击"导入"按钮，粘贴数据
+4. 确认导入
+
+**导入格式示例**：
+```
+玄关射灯	switch	1/1/28	1/2/28
+客厅吊灯	light	1/1/10	1/2/10	1/3/10	1/4/10
+客厅布帘	cover	2/1/5	2/2/5	2/3/5
+主卧空调	climate	3/1/1	3/2/1	3/3/1	3/4/1	3/5/1
+```
+
+#### 6. 加载HA实体
+
+1. 选择HA服务器后，系统会自动加载实体（约2秒延迟）
+2. 如果未成功加载，点击"刷新"按钮重新加载
+3. 系统使用HA REST API直接获取实体列表
+
+#### 7. 配置映射
+
+1. 点击"添加"按钮
+2. 选择KNX实体
+3. 输入或选择HA实体（支持直接输入实体ID或输入名称快速搜索）
+4. 可以配置多个映射关系
+
+#### 8. 连接KNX节点
+
+```
+[knxUltimate-in] → [KNX-HA桥接] → [knxUltimate-out]
+```
+
+**knxUltimate-in配置**：
+- Listen to all GA：勾选
+- Telegram type：写入
+- Notify on write：勾选
+- Notify on response：勾选
+
+**knxUltimate-out配置**：
+- Listen to all GA：勾选（Universal Mode）
+- Output type：Write
+
+#### 9. 连接HA节点（实现HA→KNX同步）
+
+```
+[HA server-state-changed] → [KNX-HA桥接]
+```
+
+**HA server-state-changed配置**：
+- 节点类型：events: state changed
+- 实体ID：选择映射中的HA实体（或留空监听所有）
+- 输出属性：data（包含entity_id、new_state、old_state）
+
+**重要**：server-state-changed节点必须直接连接到KNX-HA桥接节点的输入，不要通过knxUltimate-in
+
+#### 10. 部署
+
+点击"部署"按钮，开始双向同步
+
+### 支持的设备类型
+
+| KNX设备类型 | HA实体类型 | 同步内容 | KNX地址字段 |
+|------------|-----------|----------|-------------|
+| 开关 | switch | 开/关状态 | 命令, 状态 |
+| 灯光 | light | 开关、亮度、色温 | 开关, 状态, 亮度, 色温 |
+| 窗帘 | cover | 开关、位置、停止 | 上下, 位置, 停止 |
+| 空调 | climate | 开关、温度、模式 | 开关, 温度, 模式, 风速, 当前温度 |
+| 风扇 | fan | 开关、风速 | 开关, 风速 |
+
+### 连接方式
+
+```
+[knxUltimate-in] → [KNX-HA桥接] → [knxUltimate-out]
+[server-state-changed] → [KNX-HA桥接] ↗
+```
+
+**说明**：
+- KNX→HA：knxUltimate-in → KNX-HA桥接，自动调用HA服务
+- HA→KNX：server-state-changed → KNX-HA桥接，桥接节点发送KNX命令到knxUltimate-out
+
+### 工作原理
+
+#### KNX → HA 同步
+
+1. KNX设备状态变化（如开关按下）
+2. knxUltimate-in节点接收GroupValue_Write
+3. KNX-HA桥接节点检测到变化
+4. 调用HA REST API服务（如switch.turn_on）
+5. HA实体状态更新
+
+#### HA → KNX 同步
+
+1. HA实体状态变化（如在HA界面操作）
+2. server-state-changed节点实时推送state_changed事件
+3. KNX-HA桥接节点接收HA事件
+4. 桥接节点发送KNX GroupValue_Write命令到knxUltimate-out
+5. KNX设备执行动作
+
+**防抖机制**：
+- 调光灯亮度：300ms防抖，只同步最终值
+- 窗帘位置：500ms防抖，避免移动过程中频繁同步
+- 开关控制：立即同步，无延迟
+
+### 注意事项
+
+1. **5秒初始化延迟**：部署后前5秒不同步，等待系统初始化
+2. **事件驱动**：HA→KNX通过events-state节点实时推送，无轮询开销
+3. **防死循环**：KNX/HA控制后800ms内，反向状态变化不会同步
+4. **智能防抖**：调光300ms、窗帘500ms防抖，只同步最终值
+5. **持久化配置**：所有映射配置自动保存，重启后保持
+6. **内存优化**：命令队列限制100条，自动清理过期缓存
+7. **宽屏界面**：对话框最小1000px，映射列表高度400px
+8. **快速输入**：支持直接输入实体ID或输入名称快速定位
+9. **断线恢复**：支持断电断网后自动重连
+
+### 故障排查
+
+**KNX→HA不工作**：
+1. 检查日志是否有`[KNX输入]`输出
+2. 确认knxUltimate-in节点已启用"Listen to all GA"
+3. 确认KNX组地址与映射中的地址一致
+4. 检查HA URL和Token是否正确
+5. 手动操作KNX设备，观察日志
+6. 查看调试输出端口的消息
+
+**HA→KNX不工作**：
+1. 检查日志是否有`[HA->KNX]`输出
+2. 确认HA实体ID与映射中的实体ID一致
+3. 确认HA服务器节点已连接并启用WebSocket
+4. 在HA中操作实体，观察日志
+5. 检查knxUltimate-out节点配置
+6. 确认knxUltimate-out已启用"Listen to all GA"（Universal Mode）
+
+**加载HA实体失败**：
+1. 检查HA服务器节点是否正确配置
+2. 确认HA服务器节点已连接
+3. 点击"刷新"按钮重新加载
+4. 检查是否安装了node-red-contrib-home-assistant-websocket
+5. 查看Node-RED日志中的详细错误信息
+
+### 使用场景
+
+**适合使用KNX-HA桥接的场景**：
+- HA中已有KNX集成，希望与其他系统整合
+- 需要KNX设备与HA中的Zigbee、WiFi等设备联动
+- 希望在HA中统一管理所有设备
+- 需要利用HA的自动化和场景功能
+- 已安装node-red-contrib-home-assistant-websocket，共享HA配置
+
+**与KNX直接集成的区别**：
+- KNX直接集成：HA作为KNX系统的一部分
+- KNX-HA桥接：KNX与HA作为两个独立系统，通过桥接互通
+
+**优势**：
+- 无需修改现有KNX配置
+- 可以选择性同步部分设备
+- 支持与HA中任意实体同步
+- 配置灵活，易于调整
+
 ## 协议说明
 
 ### 核心协议格式
@@ -853,6 +1056,7 @@ A: 每个房间部署一个云端同步节点，配置对应的酒店ID和房间
 | **Symi Cloud Sync** | 云端同步设备名称和场景 | [云端数据同步](#云端数据同步) |
 | **Symi RS485 Bridge** | RS485设备双向同步 | [RS485/Modbus双向同步](#rs485modbus双向同步) |
 | **Symi KNX Bridge** | KNX系统双向同步 | [KNX双向同步](#knx双向同步) |
+| **Symi KNX-HA Bridge** | KNX与HA实体双向同步 | [KNX-HA双向同步](#knx-ha双向同步) |
 | **RS485 Debug** | RS485总线数据抓包调试 | [RS485调试节点](#rs485调试节点) |
 
 ## 开发者信息
@@ -1017,6 +1221,35 @@ node-red-contrib-symi-mesh/
 
 ## 更新日志
 
+### v1.6.9 (2025-12-20)
+- **KNX-HA双向同步**：新增`symi-knx-ha-bridge`节点
+  - 直接连接KNX与HA实体，实现双向同步
+  - 支持Tab分隔格式导入KNX组地址配置（与KNX桥接节点100%一致）
+  - 使用共享HA服务器节点，通过REST API自动加载HA实体列表
+  - 支持开关、灯光、窗帘、空调、风扇等设备类型
+  - 完整双向同步：KNX↔HA实时状态同步
+  - 事件驱动架构，通过HA events-state节点实时接收事件
+  - 智能防抖：调光300ms、窗帘500ms，只同步最终值
+  - 内置防死循环机制（800ms防抖）
+  - 快速输入框：支持输入实体ID或名称搜索，自动提示806+实体
+  - 手动刷新按钮，随时重新加载HA实体
+  - 宽屏界面：对话框最小1000px宽度
+  - 持久化配置保存，内存优化
+  - 连接knxUltimate节点，无缝集成
+  - 适用于已有KNX系统与HA整合的场景
+
+### v1.6.8 (2025-12-15)
+- **KNX双向同步修复**：彻底修复米家/面板操作KNX不同步的问题
+  - 修复0x45消息类型处理：米家/面板操作发送msgType=0x45，不再限制channels>=6
+  - 支持1-4路开关2字节参数解析（米家/面板场景触发格式）
+  - 场景执行通知(0x11)后自动查询设备状态
+- **syncLock阻塞修复**：移除handleMeshStateChange中syncLock检查
+  - 避免队列处理期间丢失状态变化事件
+  - 改用per-device时间戳防回环机制
+- **processQueue健壮性**：添加try/finally确保processing标志正确重置
+- **防死循环参数调整**：LOOP_PREVENTION_MS调整为800ms
+- **同时修复RS485桥接**：应用相同syncLock修复
+
 ### v1.6.7 (2025-12-10)
 - **KNX双向同步完善**：`symi-knx-bridge`节点全面升级
   - **knxUltimate消息格式**：符合官方规范，使用`destination`+`payload`+`dpt`+`event`
@@ -1064,23 +1297,6 @@ node-red-contrib-symi-mesh/
 - **内存安全**：命令队列限制100条，节点关闭时清理所有缓存
 - **文档更新**：添加三合一面板RS485配置说明和协议对照表
 
-### v1.6.5 (2025-12-06)
-- **杜亚窗帘协议**：原生支持杜亚窗帘协议(A6B6)，2字节地址，自动CRC16计算
-  - 帧格式：55 [地址高] [地址低] 03 [动作/位置] [CRC16低] [CRC16高]
-  - 支持打开(01)、关闭(02)、暂停(03)、百分比(04+位置)
-- **窗帘控制智能判断**：根据当前位置判断方向
-  - 位置>=50% + curtainStatus变化 → 发关闭码
-  - 位置<50% + curtainStatus变化 → 发打开码
-  - 暂停(curtainStatus=3)最高优先级
-- **窗帘百分比模式修复**：修复百分比控制后开/关命令失效的问题
-  - 百分比控制时进入百分比模式（inPosMode）
-  - 窗帘到位（curtainStatus=0）后自动退出百分比模式
-  - 退出后开/关命令可正常发送
-- **发码防抖**：500ms内不重复发相同码，避免Mesh状态混乱
-- **设备类型过滤**：映射只响应对应类型的状态变化
-- **RS485调试增强**：新增协议测试发送功能
-- **初始化延迟**：20秒，避免部署时误发命令
-
 ## 许可证
 
 MIT License
@@ -1092,8 +1308,8 @@ Copyright (c) 2025 SYMI 亖米
 ## 关于
 
 **作者**: SYMI 亖米
-**版本**: 1.6.7
+**版本**: 1.6.9
 **协议**: 蓝牙MESH网关（初级版）串口协议V1.0
-**最后更新**: 2025-12-10
+**最后更新**: 2025-12-20
 **仓库**: https://github.com/symi-daguo/node-red-contrib-symi-mesh
 **npm包**: https://www.npmjs.com/package/node-red-contrib-symi-mesh

package/lib/device-manager.js

@@ -85,7 +85,9 @@ class DeviceInfo {
             case 0x45:
                 // 6-8路开关状态上报（2字节，小端序）
                 // 用于场景执行后的状态同步
-                if (this.channels >= 6) {
+                // 注意：米家/面板操作会发送0x45类型，不管实际路数
+                // 窗帘(type=5)不使用0x45
+                if (this.deviceType !== 5) {
                     this.handleSwitchState(parameters);
                 }
                 break;
@@ -385,8 +387,14 @@ class DeviceInfo {
             const value = parameters[0];
             this.state.switch = value === 0x02;
         } else if (this.channels <= 4) {
-            // 1-4路开关：1字节，每2位表示1路
-            const value = parameters[0];
+            // 1-4路开关：通常1字节，但米家/面板操作可能发送2字节(0x45类型)
+            let value;
+            if (parameters.length >= 2) {
+                // 2字节：小端序（米家/面板场景触发）
+                value = parameters[0] | (parameters[1] << 8);
+            } else {
+                value = parameters[0];
+            }
             // 保存原始状态值供控制时使用
             this.state.switchState = value;
             for (let i = 0; i < this.channels; i++) {

package/nodes/symi-485-bridge.js

@@ -530,7 +530,7 @@ module.exports = function(RED) {
 
         // Mesh设备状态变化处理(事件驱动)
         const handleMeshStateChange = (eventData) => {
-            if (node.syncLock) return;
+            // 只检查initializing，不检查syncLock以避免丢失事件
             if (node.initializing) return;
             
             const mac = eventData.device.macAddress;
@@ -972,7 +972,7 @@ module.exports = function(RED) {
 
         // RS485 device state change handler (event-driven)
         const handleModbusStateChange = (data) => {
-            if (node.syncLock) return;
+            // 不检查syncLock以避免丢失事件，使用时间戳防回环
             
             const mapping = node.findRS485Mapping(data.device.modbusAddress);
             if (!mapping) return;
@@ -1025,36 +1025,36 @@ module.exports = function(RED) {
             if (node.processing || node.commandQueue.length === 0) return;
 
             node.processing = true;
-            node.syncLock = true;
             let multiChange = node.commandQueue.length > 1;
 
-            while (node.commandQueue.length > 0) {
-                const cmd = node.commandQueue.shift();
-                try {
-                    if (cmd.direction === 'mesh-to-modbus') {
-                        await node.syncMeshToModbus(cmd);
-                    } else if (cmd.direction === 'modbus-to-mesh') {
-                        await node.syncModbusToMesh(cmd);
+            try {
+                while (node.commandQueue.length > 0) {
+                    const cmd = node.commandQueue.shift();
+                    try {
+                        if (cmd.direction === 'mesh-to-modbus') {
+                            await node.syncMeshToModbus(cmd);
+                        } else if (cmd.direction === 'modbus-to-mesh') {
+                            await node.syncModbusToMesh(cmd);
+                        }
+                        // 命令之间延迟50ms
+                        await node.sleep(50);
+                    } catch (err) {
+                        node.error(`同步失败: ${err.message}`);
                     }
-                    // 命令之间延迟50ms
-                    await node.sleep(50);
-                } catch (err) {
-                    node.error(`同步失败: ${err.message}`);
                 }
-            }
 
-            // 如果发生多次变化，安排验证
-            if (multiChange && !node.pendingVerify) {
-                node.pendingVerify = true;
-                setTimeout(() => {
-                    node.verifySync();
-                    node.pendingVerify = false;
-                }, 200);
+                // 如果发生多次变化，安排验证
+                if (multiChange && !node.pendingVerify) {
+                    node.pendingVerify = true;
+                    setTimeout(() => {
+                        node.verifySync();
+                        node.pendingVerify = false;
+                    }, 200);
+                }
+            } finally {
+                node.processing = false;
+                node.lastSyncTime = Date.now();
             }
-
-            node.syncLock = false;
-            node.processing = false;
-            node.lastSyncTime = Date.now();
         };
 
         // 多实体变化后验证同步状态
@@ -2098,7 +2098,6 @@ module.exports = function(RED) {
             node.curtainCache = {};
             node.lastSentTime = {};
             node.processing = false;
-            node.syncLock = false;
             
             node.log('[RS485 Bridge] 节点已清理');
             done();

package/nodes/symi-gateway.js

@@ -217,6 +217,13 @@ module.exports = function(RED) {
                         Buffer.from([frame.checksum])
                     ]).toString('hex').toUpperCase();
                     this.log(`[场景执行] 收到场景执行通知事件: 场景ID=${sceneId}, 设备地址=0x${event.networkAddress.toString(16).toUpperCase()}, 原始帧=${frameHex}`);
+                    
+                    // 发出场景执行事件，让桥接节点知道需要查询设备状态
+                    this.emit('scene-executed', {
+                        sceneId: sceneId,
+                        triggerAddress: event.networkAddress,
+                        timestamp: Date.now()
+                    });
                     continue;
                 }
 

package/nodes/symi-knx-bridge.js

@@ -3,7 +3,7 @@
  * 支持开关、窗帘等设备的双向状态同步
  * 事件驱动架构，命令队列顺序处理，防死循环机制
  * 
- * 版本: 1.6.7
+ * 版本: 1.6.8
  */
 
 module.exports = function(RED) {
@@ -151,7 +151,7 @@ module.exports = function(RED) {
         node.lastKnxToMesh = {};        // 记录KNX->Mesh发送时间，防止回环
         
         // 防死循环参数
-        const LOOP_PREVENTION_MS = 1000;  // 500ms内不处理反向同步
+        const LOOP_PREVENTION_MS = 800;   // 800ms内不处理反向同步，防止回环
         const DEBOUNCE_MS = 100;          // 100ms防抖
         const MAX_QUEUE_SIZE = 100;       // 最大队列大小
         
@@ -249,7 +249,9 @@ module.exports = function(RED) {
 
         // ========== Mesh设备状态变化处理 ==========
         const handleMeshStateChange = (eventData) => {
-            if (node.syncLock || node.initializing) return;
+            // 只检查initializing，不检查syncLock
+            // syncLock会导致队列处理期间丢失事件，改用per-device时间戳防回环
+            if (node.initializing) return;
             
             const mac = eventData.device.macAddress;
             const state = eventData.state || {};
@@ -489,25 +491,25 @@ module.exports = function(RED) {
             if (node.processing || node.commandQueue.length === 0) return;
             
             node.processing = true;
-            node.syncLock = true;
             
-            while (node.commandQueue.length > 0) {
-                const cmd = node.commandQueue.shift();
-                try {
-                    if (cmd.direction === 'mesh-to-knx') {
-                        await node.syncMeshToKnx(cmd);
-                    } else if (cmd.direction === 'knx-to-mesh') {
-                        await node.syncKnxToMesh(cmd);
+            try {
+                while (node.commandQueue.length > 0) {
+                    const cmd = node.commandQueue.shift();
+                    try {
+                        if (cmd.direction === 'mesh-to-knx') {
+                            await node.syncMeshToKnx(cmd);
+                        } else if (cmd.direction === 'knx-to-mesh') {
+                            await node.syncKnxToMesh(cmd);
+                        }
+                        await node.sleep(50);  // 命令间隔50ms
+                    } catch (err) {
+                        node.error(`同步失败: ${err.message}`);
                     }
-                    await node.sleep(50);  // 命令间隔50ms
-                } catch (err) {
-                    node.error(`同步失败: ${err.message}`);
                 }
+            } finally {
+                node.processing = false;
+                node.lastSyncTime = Date.now();
             }
-            
-            node.syncLock = false;
-            node.processing = false;
-            node.lastSyncTime = Date.now();
         };
 
         // ========== Mesh -> KNX 同步 ==========
@@ -1018,6 +1020,48 @@ module.exports = function(RED) {
         // 监听Mesh设备状态变化
         node.gateway.on('device-state-changed', handleMeshStateChange);
         
+        // ========== 场景执行事件处理 ==========
+        // 当收到场景执行通知时，查询所有已映射设备的状态
+        const handleSceneExecuted = (eventData) => {
+            if (node.initializing) return;
+            
+            node.log(`[场景执行] 检测到场景${eventData.sceneId}执行，延迟查询设备状态`);
+            
+            // 延迟300ms后查询设备状态，给设备执行时间
+            setTimeout(async () => {
+                // 收集所有已映射的唯一设备地址
+                const mappedAddresses = new Set();
+                for (const mapping of node.mappings) {
+                    const mac = node.normalizeMac(mapping.meshMac);
+                    const device = node.gateway.deviceManager.getDeviceByMac(mac);
+                    if (device && device.networkAddress) {
+                        mappedAddresses.add(device.networkAddress);
+                    }
+                }
+                
+                if (mappedAddresses.size === 0) {
+                    node.debug(`[场景执行] 没有已映射的设备需要查询`);
+                    return;
+                }
+                
+                node.log(`[场景执行] 查询${mappedAddresses.size}个设备的状态`);
+                
+                // 逐个查询设备状态
+                for (const addr of mappedAddresses) {
+                    try {
+                        // 查询开关状态 (0x02)
+                        const queryFrame = node.gateway.protocolHandler.buildDeviceStatusQueryFrame(addr, 0x02);
+                        await node.gateway.client.sendFrame(queryFrame, 2);
+                        await node.sleep(100);
+                    } catch (err) {
+                        node.debug(`[场景执行] 查询设备0x${addr.toString(16)}状态失败: ${err.message}`);
+                    }
+                }
+            }, 300);
+        };
+        
+        node.gateway.on('scene-executed', handleSceneExecuted);
+        
         // ========== 清理 ==========
         node.on('close', function(done) {
             // 清除初始化定时器
@@ -1028,6 +1072,7 @@ module.exports = function(RED) {
             // 移除事件监听
             if (node.gateway) {
                 node.gateway.removeListener('device-state-changed', handleMeshStateChange);
+                node.gateway.removeListener('scene-executed', handleSceneExecuted);
             }
             
             // 清空队列和缓存