node-red-contrib-symi-mesh 1.6.8 → 1.7.0

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中任意实体同步
+- 配置灵活，易于调整
+
 ## 协议说明
 
 ### 核心协议格式
@@ -400,7 +603,7 @@ Tab分隔，每行一个实体：
 
 #### 注意事项
 
-1. **20秒初始化延迟**：部署后前20秒不同步，等待Mesh设备发现完成
+1. **10秒初始化延迟**：部署后前10秒不同步，等待Mesh设备发现完成
 2. **首次状态缓存**：启动后第一次状态仅缓存，第二次操作才会同步
 3. **防死循环**：KNX控制后1秒内，Mesh状态变化不会反向同步
 
@@ -539,34 +742,67 @@ Mesh 四键开关 第2路 ↔ RS485 六键开关 第5路  地址:2   ✓ 支持
 | 通用Modbus | 各类标准Modbus设备 |
 | 自定义协议 | 任意485码匹配（开关/窗帘/场景） |
 
-### 自定义协议模式
+### 自定义协议模式（v1.7.0增强）
+
+当内置协议无法满足需求时，可使用"自定义协议"模式，手动录入RS485十六进制码进行双向匹配。
+
+#### 自定义开关（4组码）
+
+- **发开码**：Mesh开关打开时，发送此码到RS485总线
+- **发关码**：Mesh开关关闭时，发送此码到RS485总线
+- **收开码**：RS485总线收到此码时，触发Mesh开关打开
+- **收关码**：RS485总线收到此码时，触发Mesh开关关闭
+
+**翻转模式**：当收开码=收关码时，收到后自动翻转开关状态
+
+#### 自定义窗帘（6组码）
 
-当内置协议无法满足需求时，可使用"自定义协议"模式，手动录入RS485十六进制码进行双向匹配：
+- **发开码**、**发关码**、**发停码**：Mesh→RS485
+- **收开码**、**收关码**、**收停码**：RS485→Mesh
 
-#### 自定义开关
-- **打开码**：当Mesh开关打开时发送此码，收到此码时触发Mesh开关打开
-- **关闭码**：当Mesh开关关闭时发送此码，收到此码时触发Mesh开关关闭
+#### 自定义空调（完整收发码）
 
-#### 自定义窗帘
-- **打开码**：Mesh窗帘打开 ↔ RS485打开命令
-- **关闭码**：Mesh窗帘关闭 ↔ RS485关闭命令
-- **停止码**：Mesh窗帘停止 ↔ RS485停止命令
+- **开关**：发开码、发关码、收开码、收关码
+- **风速**：发高风、发中风、发低风、收高风、收中风、收低风
+- **模式**：发制冷、发制热、发除湿、发送风、收制冷、收制热、收除湿、收送风
+- **温度**：发温度码、收温度码（支持16-30度，使用{TEMP}占位符）
 
 #### 配置示例
+
+**自定义开关（花语前湾大屏）**：
+```
+品牌: 自定义协议
+类型: 自定义开关
+发开码: 01 20 10 14 00 01 00 7F 82 B6
+发关码: 01 20 10 14 00 01 00 FF 83 16
+收开码: 01 20
+收关码: 01 20
+```
+说明：收开码=收关码，收到后翻转开关状态
+
+**自定义窗帘**：
 ```
 品牌: 自定义协议
 类型: 自定义窗帘
-打开码: 55 02 02 03 01 49 44
-关闭码: 55 02 02 03 02 09 45
-停止码: 55 02 02 03 03 C8 85
+发开码: 55 02 02 03 01 49 44
+发关码: 55 02 02 03 02 09 45
+发停码: 55 02 02 03 03 C8 85
+收开码: 55 02 02 03 01
+收关码: 55 02 02 03 02
+收停码: 55 02 02 03 03
 ```
 
 #### 工作原理
-1. **Mesh→RS485**：Mesh设备状态变化时，发送对应的自定义码
-2. **RS485→Mesh**：收到的RS485帧与自定义码匹配，触发对应Mesh设备
-3. **防死循环**：500ms内不重复触发，避免Mesh→RS485→Mesh循环
+1. **Mesh→RS485**：Mesh设备状态变化时，发送对应的发码
+2. **RS485→Mesh**：收到的RS485帧与收码匹配，触发对应Mesh设备
+3. **翻转逻辑**：开关的收开码=收关码时，收到后翻转当前状态
+4. **防死循环**：500ms内不重复触发，避免Mesh→RS485→Mesh循环
 
-> 自定义码支持任意长度的十六进制字符串，支持空格分隔（如 `55 01 01` 或 `550101`）
+#### 注意事项
+- 支持最多24字节（72个十六进制字符）数据录入
+- 支持空格分隔（如 `55 01 01` 或 `550101`）
+- 自定义模式不需要填写地址字段（自动隐藏）
+- 配置持久化保存，重启后保持
 
 ### 注意事项
 
@@ -853,6 +1089,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 +1254,47 @@ node-red-contrib-symi-mesh/
 
 ## 更新日志
 
+### v1.7.0 (2025-12-21)
+- **自定义协议增强**：RS485桥接节点自定义协议功能全面升级
+  - 自定义开关：添加发开、发关、收开、收关4组码
+  - 翻转模式：收开码=收关码时，收到后自动翻转开关状态
+  - 自定义窗帘：添加发开、发关、发停、收开、收关、收停6组码
+  - 自定义空调：新增完整收发码支持（开关、风速、模式、温度）
+  - 支持最多24字节（72个十六进制字符）数据录入
+  - 自定义模式自动隐藏地址字段
+  - 配置持久化保存，重启后保持
+  - 防死循环机制优化
+  - 内存优化，防止日志溢出
+
+### 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`
@@ -1036,18 +1314,6 @@ node-red-contrib-symi-mesh/
   - 多设备类型：开关、调光灯、窗帘、空调、新风、地暖
   - 智能通道选择：根据Mesh设备实际路数显示可选通道
 
-### 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.6 (2025-12-09)
 - **三合一面板完整双向同步**：支持空调+新风+地暖独立RS485映射
   - 三合一0x94协议完整解析：空调(开关/模式/风速/温度)、地暖(开关/温度)、新风(开关/风速)
@@ -1076,23 +1342,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
@@ -1104,8 +1353,8 @@ Copyright (c) 2025 SYMI 亖米
 ## 关于
 
 **作者**: SYMI 亖米
-**版本**: 1.6.8
+**版本**: 1.7.0
 **协议**: 蓝牙MESH网关（初级版）串口协议V1.0
-**最后更新**: 2025-12-15
+**最后更新**: 2025-12-21
 **仓库**: https://github.com/symi-daguo/node-red-contrib-symi-mesh
 **npm包**: https://www.npmjs.com/package/node-red-contrib-symi-mesh