node-red-contrib-symi-mesh 1.8.3 → 1.8.5

package/README.md

@@ -14,9 +14,11 @@
 - **双向状态同步**：支持0x80状态事件，实时反馈设备状态变化
 - **多设备类型**：支持开关、灯光、窗帘、温控器、传感器等12+种设备
 - **三合一面板**：完整支持空调+新风+地暖三合一控制面板，自动识别
-- **RS485/Modbus集成**：支持第三方485设备双向同步，内置协议模板
+- **RS485/Modbus集成**：支持第三方485设备双向同步，内置协议模板，支持中弘VRF、SYMI面板协议
+- **RS485同步增强**：`symi-rs485-sync` 节点已全面重构，采用统一防环路机制，支持多台空调内机批量状态同步和三合一子实体增强映射
 - **KNX集成**：支持与KNX系统双向同步
 - **KNX-HA集成**：支持KNX与Home Assistant实体直接双向同步
+- **窗帘同步优化**：专门针对无限位Mesh窗帘模组优化，支持控制锁定（40s）和即时状态同步，彻底解决状态死循环和丢包问题
 - **云端同步**：从酒店云云平台自动获取设备名称和场景信息
 - **稳定可靠**：完善的错误处理和自动重连机制
 
@@ -180,214 +182,11 @@ 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中任意实体同步
-- 配置灵活，易于调整
-
-
-### HA双向同步
+## HA双向同步
 
 Symi HA同步节点 (`symi-ha-sync`) 用于实现Symi蓝牙Mesh设备与Home Assistant实体的直接双向同步。
 
-#### 功能特性
+### 功能特性
 
 1. **配置复用**：
    - 复用`symi-mqtt`配置节点获取Symi设备信息
@@ -403,7 +202,7 @@ Symi HA同步节点 (`symi-ha-sync`) 用于实现Symi蓝牙Mesh设备与Home Ass
    - 支持按键通道选择（1-4键）
    - 支持实体ID搜索和下拉选择
 
-#### ⚠️ 双向同步连接方式（重要）
+### ⚠️ 双向同步连接方式（重要）
 
 要实现完整的双向同步，必须连接HA事件节点到`symi-ha-sync`节点的输入端：
 
@@ -428,13 +227,13 @@ Symi HA同步节点 (`symi-ha-sync`) 用于实现Symi蓝牙Mesh设备与Home Ass
 2. 实体ID可留空（监听所有实体）或指定特定实体
 3. 将输出连接到 symi-ha-sync 节点的输入端
 
-#### 状态指示
+### 状态指示
 
 - **蓝色 "Mesh→HA (N组)"**：仅 Mesh 到 HA 方向工作（未连接 HA 事件节点）
 - **绿色 "双向同步 (N组)"**：双向同步正常工作
 - **红色**：配置错误
 
-#### 配置步骤
+### 配置步骤
 
 1. **添加节点**：从左侧拖入`Symi HA Sync`节点
 2. **选择MQTT配置**：选择已有的`symi-mqtt`配置节点（共享Symi网关连接）
@@ -447,7 +246,7 @@ Symi HA同步节点 (`symi-ha-sync`) 用于实现Symi蓝牙Mesh设备与Home Ass
 5. **连接HA事件节点**：添加`events: all`或`events: state`节点，连接到输入端
 6. **部署**：点击部署，立即生效
 
-#### 注意事项
+### 注意事项
 
 - **MQTT配置**：必须选择`symi-mqtt`配置节点，用于获取设备列表和接收Mesh事件
 - **HA连接**：必须确保HA服务器节点连接正常
@@ -456,7 +255,7 @@ Symi HA同步节点 (`symi-ha-sync`) 用于实现Symi蓝牙Mesh设备与Home Ass
 - **多通道设备**：对于多键开关，请分别为每个按键添加一条映射
 - **event实体过滤**：系统自动过滤`event.`开头的实体（如按键点击事件），不会同步
 
-#### 三合一面板配置
+### 三合一面板配置
 
 三合一面板（空调+新风+地暖）需要分别配置每个子设备的映射：
 
@@ -477,7 +276,7 @@ Symi HA同步节点 (`symi-ha-sync`) 用于实现Symi蓝牙Mesh设备与Home Ass
 三合一面板_xxx [地暖] ↔ climate.living_room_floor_heating
 ```
 
-#### 窗帘同步说明
+### 窗帘同步说明
 
 窗帘设备采用特殊的同步机制，避免运动过程中的步进反馈干扰：
 
@@ -486,12 +285,11 @@ Symi HA同步节点 (`symi-ha-sync`) 用于实现Symi蓝牙Mesh设备与Home Ass
 - **运动状态跟踪**：记录运动发起方（Symi/HA），忽略对方的中间状态反馈
 - **opening/closing过滤**：HA窗帘处于运动状态时，不同步位置变化到Mesh
 
-
-### MQTT品牌同步
+## MQTT品牌同步
 
 Symi MQTT同步节点 (`symi-mqtt-sync`) 用于实现第三方MQTT品牌设备与Symi Mesh设备的双向状态同步。
 
-#### 功能特性
+### 功能特性
 
 1. **双MQTT配置**：
    - Mesh MQTT：连接Symi网关获取设备列表
@@ -500,7 +298,7 @@ Symi MQTT同步节点 (`symi-mqtt-sync`) 用于实现第三方MQTT品牌设备
 3. **双向同步**：品牌设备↔Mesh设备实时状态同步
 4. **配置持久化**：设备列表和映射配置持久保存，断线后仍可显示
 
-#### 支持的品牌协议
+### 支持的品牌协议
 
 | 品牌 | 设备类型 | 功能码映射 |
 |------|---------|-----------|
@@ -510,7 +308,7 @@ Symi MQTT同步节点 (`symi-mqtt-sync`) 用于实现第三方MQTT品牌设备
 | | 地暖(16) | 开关(fn=1)、温度(fn=2, 5-35°C) |
 | | 新风(36) | 开关(fn=1)、风速(fn=3) |
 
-#### 配置步骤
+### 配置步骤
 
 1. **添加品牌MQTT配置节点**：
    - 从左侧拖入`Symi MQTT Brand`配置节点
@@ -530,143 +328,20 @@ Symi MQTT同步节点 (`symi-mqtt-sync`) 用于实现第三方MQTT品牌设备
 
 4. **部署**：点击部署，开始双向同步
 
-#### 注意事项
+### 注意事项
 
 - **设备类型匹配**：建议同步相同类型的设备（灯具对灯具，空调对空调）
 - **离线设备显示**：[离线]标记缓存中但当前不在线的设备
 - **防死循环**：内置2秒防抖机制，避免状态震荡
 - **自动重连**：5秒重连间隔，断线自动恢复
 
-
-## 协议说明
-
-### 核心协议格式
-
-```
-[Header(0x53)] [Opcode] [Status] [Length] [Data] [Checksum]
-```
-
-### 关键操作码
-
-| 操作码 | 名称 | 方向 | 说明 |
-|-------|------|------|------|
-| 0x12 | 设备列表查询 | 主机→网关 | 查询所有设备 |
-| 0x92 | 设备列表响应 | 网关→主机 | 返回设备信息 |
-| 0x30 | 设备控制 | 主机→网关 | 控制指定设备 |
-| 0xB0 | 控制响应 | 网关→主机 | 控制结果 |
-| 0x34 | 场景控制 | 主机→网关 | 执行场景（群控） |
-| 0xB4 | 场景控制响应 | 网关→主机 | 场景控制结果 |
-| 0x80 | 状态事件 | 网关→主机 | 设备状态主动上报 |
-| 0x32 | 状态查询 | 主机→网关 | 查询设备状态 |
-
-### 开关状态编码（重要）
-
-**协议规则**: 每2位表示1路，`01`=关，`10`=开，从最低位开始
-
-| 路数 | 全关 | 全开 | 示例 |
-|-----|------|------|------|
-| 1路 | 0x01 | 0x02 | 直接值 |
-| 2路 | 0x05 | 0x0A | 0x06=第1路开、第2路关 |
-| 3路 | 0x15 | 0x2A | 从低位开始 |
-| 4路 | 0x55 | 0xAA | 每2位1路 |
-| 6路 | 0x5555 | 0xAAAA | 2字节小端序 |
-| 8路 | 0x5555 | 0xAAAA | 2字节小端序 |
-
-#### 8路开关状态详解
-
-8路开关使用2字节（16位）表示状态，小端序传输。实测帧示例：
-
-```
-帧格式: 53 80 [Status] [Length] [网络地址LE] [AttrType] [状态LE] [Checksum]
-示例帧: 53 80 05 05 E4 01 45 56 55 70
-        │  │  │  │  └─────┘ │  └───┘ └─ 校验和
-        │  │  │  │     │    │    └─ 状态值 0x5556 (第1路开)
-        │  │  │  │     │    └─ AttrType=0x45 (8路开关)
-        │  │  │  │     └─ 网络地址 0x01E4
-        │  │  │  └─ 数据长度=5字节
-        │  │  └─ 状态码
-        │  └─ Opcode=0x80 (事件上报)
-        └─ 帧头
-```
-
-**状态值对照表**（小端序）:
-| 状态数据 | 16位值 | 二进制 | 含义 |
-|---------|--------|--------|------|
-| 55 55 | 0x5555 | 01010101 01010101 | 全关 |
-| 56 55 | 0x5556 | 01010101 01010110 | 第1路开 |
-| 59 55 | 0x5559 | 01010101 01011001 | 第2路开 |
-| 65 55 | 0x5565 | 01010101 01100101 | 第3路开 |
-| 95 55 | 0x5595 | 01010101 10010101 | 第4路开 |
-| 55 56 | 0x5655 | 01010110 01010101 | 第5路开 |
-| 55 59 | 0x5955 | 01011001 01010101 | 第6路开 |
-| 55 65 | 0x6555 | 01100101 01010101 | 第7路开 |
-| 55 95 | 0x9555 | 10010101 01010101 | 第8路开 |
-| AA AA | 0xAAAA | 10101010 10101010 | 全开 |
-
-### 常用消息类型
-
-| 消息类型 | 代码 | 数据格式 | 范围/说明 |
-|---------|------|---------|----------|
-| 开关状态 | 0x02 | 1字节 | 1-4路开关，见上表 |
-| 亮度 | 0x03 | 1字节 | 0-100% |
-| 色温 | 0x04 | 1字节 | 0%=暖白, 100%=冷白 |
-| 窗帘动作 | 0x05 | 1字节 | 1=开/2=关/3=停 |
-| 窗帘位置 | 0x06 | 1字节 | 0-100% |
-| 人体感应 | 0x0C | 1字节 | 0=无活动/1=检测到 |
-| 插卡状态 | 0x0E | 1字节 | 0=无卡/1=有卡 |
-| 湿度 | 0x17 | 1字节 | 0-100% |
-| 当前温度 | 0x16 | 2字节LE | 温度*100（如2500=25.00°C）|
-| 目标温度 | 0x1B | 1字节 | 16-30°C（直接温度值）|
-| 风速 | 0x1C | 1字节 | 1=高/2=中/3=低/4=自动 |
-| 模式 | 0x1D | 1字节 | 1=制冷/2=制热/3=送风/4=除湿 |
-| 6-8路开关 | 0x45 | 2字节LE | 多路开关状态，见上表 |
-| 五色RGB | 0x4C | 5字节 | R/G/B/WW/CW (各0-255) |
-
-## MQTT主题结构
-
-### Discovery主题
-
-```
-homeassistant/[platform]/[object_id]/config
-```
-
-例如：
-- 开关：`homeassistant/switch/9361c820dacc_switch/config`
-- 温控器：`homeassistant/climate/142e68468cac_climate/config`
-- 三合一空调：`homeassistant/climate/894ab820dacc_climate/config`
-- 三合一新风：`homeassistant/fan/894ab820dacc_fresh_air/config`
-- 三合一地暖：`homeassistant/climate/894ab820dacc_floor_heating/config`
-
-### 状态和命令主题
-
-**普通设备**：
-```
-symi_mesh/[mac_clean]/[entity]/state
-symi_mesh/[mac_clean]/[entity]/set
-```
-
-**三合一设备**（关键：空调使用climate主题）：
-```
-空调：symi_mesh/[mac_clean]/climate/mode
-新风：symi_mesh/[mac_clean]/fresh_air/state
-地暖：symi_mesh/[mac_clean]/floor_heating/mode
-```
-
-例如（三合一设备 894ab820dacc）：
-- 空调状态: `symi_mesh/894ab820dacc/climate/target_temp`
-- 空调命令: `symi_mesh/894ab820dacc/climate/target_temp/set`
-- 新风状态: `symi_mesh/894ab820dacc/fresh_air/state`
-- 新风命令: `symi_mesh/894ab820dacc/fresh_air/set`
-- 地暖状态: `symi_mesh/894ab820dacc/floor_heating/mode`
-- 地暖命令: `symi_mesh/894ab820dacc/floor_heating/mode/set`
-
 ## KNX双向同步
 
 本节点支持与`node-red-contrib-knx-ultimate`完整双向同步，实现Symi Mesh设备与KNX系统的互联互通。
 
-### 方式一：KNX桥接节点（推荐）
+### KNX桥接节点（推荐）
 
-**v1.6.7新增**：使用`symi-knx-bridge`节点实现一站式配置，支持KNX实体导入和批量映射。
+使用`symi-knx-bridge`节点实现一站式配置，支持KNX实体导入和批量映射。
 
 #### 功能特点
 
@@ -729,12 +404,6 @@ Tab分隔，每行一个实体：
 主卧空调	climate	3/1/1	3/2/1	3/3/1	3/4/1	3/5/1
 ```
 
-#### 输入/输出
-
-- **输入**：接收来自`knxUltimate-in`节点的KNX消息
-- **输出1**：发送到`knxUltimate-out`节点的KNX命令
-- **输出2**：调试信息（连接Debug节点查看同步过程）
-
 #### knxUltimate节点配置（关键）
 
 **输入节点(knxUltimate-in)**：
@@ -763,410 +432,101 @@ Tab分隔，每行一个实体：
 2. **首次状态缓存**：启动后第一次状态仅缓存，第二次操作才会同步
 3. **防死循环**：KNX控制后1秒内，Mesh状态变化不会反向同步
 
-#### 故障排查
-
-**Mesh->KNX不工作**：
-1. 检查日志是否有`[Mesh->KNX]`输出
-2. 确认映射中的MAC地址与设备列表中的MAC一致
-3. 等待20秒初始化完成
-4. 手动操作Mesh设备，观察日志
-
-**KNX->Mesh不工作**：
-1. 检查knxUltimate-in节点是否收到KNX消息
-2. 确认KNX组地址与映射中的命令地址一致
-3. 查看日志是否有`[KNX输入]`输出
-4. 如果显示`未找到映射`，检查配置的组地址
-
-## RS485/Modbus双向同步
+## KNX-HA双向同步
 
-本节点支持与第三方RS485/Modbus设备进行双向状态同步，适用于对接各品牌空调、新风、地暖等设备。
+本节点支持KNX与Home Assistant实体直接双向同步，实现KNX系统与HA的实时互联互通。
 
 ### 功能特点
 
-- **双模式连接**：支持串口(RS485)和TCP/IP两种连接方式
-- **协议模板**：内置常用协议模板，支持自定义寄存器映射
-- **双向同步**：Mesh设备和485设备状态实时同步
-- **多设备支持**：单个485连接可管理多达105个设备
+- **直接实体同步**：通过HA events-state节点实时接收HA状态变化事件
+- **KNX实体导入**：支持Tab分隔格式导入KNX组地址配置
+- **HA实体加载**：从HA服务器节点自动加载所有支持的实体
+- **快速输入**：支持直接输入实体ID或名称搜索，带autocomplete提示
+- **多设备类型**：开关、灯光、窗帘、空调、风扇
+- **双向同步**：自动处理KNX↔HA状态同步
+- **智能防抖**：调光300ms、窗帘500ms防抖，避免过程中频繁同步
+- **防死循环**：内置800ms防抖机制
 
 ### 配置步骤
 
-#### 1. 添加RS485桥接节点
-
-从"Symi Mesh"分类中拖入"RS485桥接"节点，双击打开配置：
-
-**基本配置**：
-- **Mesh网关**：选择已配置的Symi Gateway（点击+号可新建）
-- **RS485连接**：点击+号新建连接配置
-
-#### 2. 配置RS485连接
-
-点击RS485连接旁边的+号，创建新连接：
-
-**串口模式**：
-- **连接方式**：选择 串口(RS485)
-- **串口**：从下拉框选择USB串口（点击刷新按钮可重新扫描）
-- **波特率**：根据设备设置（常用9600）
-- **校验位**：无/偶校验/奇校验
-
-**TCP模式**：
-- **连接方式**：选择 TCP/IP
-- **主机地址**：485转TCP网关的IP地址
-- **端口**：Modbus TCP端口（默认502）
-
-#### 3. 配置实体映射
-
-点击"添加映射"按钮，每行配置一组对应关系：
-
-| 列 | 说明 |
-|----|------|
-| Mesh实体/按键 | 选择Mesh设备，开关设备会显示按键选择（第1路、第2路...） |
-| 品牌 | 选择RS485协议品牌（如 话语前湾） |
-| 类型/按键 | 选择设备类型，开关类型会显示按键选择 |
-| 地址 | Modbus从机地址（1-255） |
-
-**开关设备命名**：按按键数命名，方便识别：
-- Mesh端：一键开关、二键开关、三键开关、四键开关、六键开关、八键开关
-- RS485端：一键开关、二键开关、三键开关、四键开关、六键开关、八键开关
-
-**按键独立配置**：Mesh和RS485的按键可以自由对应，不必一一匹配：
-```
-Mesh 六键开关 第3路 ↔ RS485 四键开关 第1路  地址:1   ✓ 支持
-Mesh 四键开关 第2路 ↔ RS485 六键开关 第5路  地址:2   ✓ 支持
+1. **安装依赖节点**
+```bash
+cd ~/.node-red
+npm install node-red-contrib-knx-ultimate
+npm install node-red-contrib-home-assistant-websocket
 ```
 
-#### 4. 部署
-
-点击"部署"按钮，所有映射自动开始双向同步
+2. **配置HA服务器**
+添加Home Assistant服务器配置节点，输入HA的URL和访问令牌
 
-### RS485调试节点
+3. **添加KNX-HA桥接节点**
+从"Symi Mesh"分类中拖入"KNX-HA桥接"节点
 
-新增 `RS485调试` 节点用于抓取并显示原始485字节流：
+4. **导入KNX实体**
+按照Tab分隔格式准备KNX组地址数据，点击"导入"按钮
 
-**功能**：
-- 实时显示RS485总线所有通信数据（TX发送/RX接收）
-- 自动解析Modbus RTU帧结构（从机地址、功能码）
-- 支持手动发送测试帧（输入十六进制字符串）
-- 十六进制/ASCII显示模式
-- 调试窗口高度自适应
+5. **配置映射**
+选择KNX实体和对应的HA实体
 
-**输出示例**：
+6. **连接节点**
 ```
-[15:07:55.123] → TX: 01 06 10 31 00 01 6A 35 | 从机:1 写单寄存器
-[15:07:55.180] ← RX: 01 06 10 31 00 01 6A 35 | 从机:1 写单寄存器
+[knxUltimate-in] → [KNX-HA桥接] → [knxUltimate-out]
+[server-state-changed] → [KNX-HA桥接] ↗
 ```
 
-### 实体映射规则
+### 支持的设备类型
 
-| Mesh实体类型 | RS485实体类型 | 同步内容 |
-|-------------|--------------|---------|
-| 开关-按键N | 开关 | 开/关状态 |
-| 温控器 | 空调 | 开关、温度、模式、风速 |
-| 三合一面板 | 空调+新风+地暖 | 分别配置，独立同步 |
-| 调光灯 | 调光器 | 开关、亮度 |
+| KNX设备类型 | HA实体类型 | 同步内容 |
+|------------|-----------|----------|
+| 开关 | switch | 开/关状态 |
+| 灯光 | light | 开关、亮度、色温 |
+| 窗帘 | cover | 开关、位置、停止 |
+| 空调 | climate | 开关、温度、模式 |
+| 风扇 | fan | 开关、风速 |
 
-**部分同步**：如果RS485协议不提供某些功能点，只同步双方都支持的内容
+## RS485/Modbus双向同步
 
-### 三合一面板配置
+本节点支持与第三方RS485/Modbus设备进行双向状态同步，适用于对接各品牌空调、新风、地暖等设备。
 
-三合一面板（温控器类型）可同时控制空调、新风、地暖，需要创建3个独立映射：
+### 功能特点
 
-#### 配置示例（话语前湾协议）
+- **双模式连接**：支持串口(RS485)和TCP/IP两种连接方式
+- **协议模板**：内置常用协议模板，支持自定义寄存器映射
+- **双向同步**：Mesh设备和485设备状态实时同步
+- **多设备支持**：单个485连接可管理多达105个设备
 
-| Mesh设备 | RS485设备类型 | 从机地址 | 说明 |
-|---------|--------------|---------|------|
-| 三合一面板_xxx | 次卧1空调 | 0 | 空调寄存器0x0FA4-0x0FA7 |
-| 三合一面板_xxx | 新风 | 60 | 开关0x0039，风速0x004B |
-| 三合一面板_xxx | 次卧1地暖 | 62 | 开关0x0039，温度0x0043 |
+### 配置步骤
 
-#### 话语前湾地暖/新风从机地址
+1. **添加RS485桥接节点**
+从"Symi Mesh"分类中拖入"RS485桥接"节点
 
-| 设备 | 从机地址 | 十六进制 |
-|------|---------|---------|
-| 客餐厅地暖 | 60 | 0x3C |
-| 新风 | 60 | 0x3C |
-| 主卧地暖 | 61 | 0x3D |
-| 次卧1地暖 | 62 | 0x3E |
-| 次卧2地暖 | 63 | 0x3F |
+2. **配置RS485连接**
+- **串口模式**：选择USB串口，设置波特率（常用9600）
+- **TCP模式**：输入485转TCP网关的IP地址和端口
 
-> **注意**：新风和客餐厅地暖共用从机地址60，但开关值不同（新风开=1，地暖开=2），请分别创建映射。
+3. **配置实体映射**
+选择Mesh设备和RS485设备类型、地址
+
+4. **部署**
+点击"部署"按钮，开始双向同步
 
 ### 内置协议支持
 
 | 品牌 | 支持设备 |
 |-----|---------|
-| 话语前湾 | 空调（客厅/主卧/次卧1/次卧2）、地暖、新风、窗帘、1-8键开关 |
+| 话语前湾 | 空调、地暖、新风、窗帘、1-8键开关 |
 | 通用Modbus | 各类标准Modbus设备 |
 | 自定义协议 | 任意485码匹配（开关/窗帘/场景） |
 
-### 自定义协议模式（v1.7.0增强）
-
-当内置协议无法满足需求时，可使用"自定义协议"模式，手动录入RS485十六进制码进行双向匹配。
-
-#### 反馈选项
-
-每个映射可设置"反馈"复选框：
-- **勾选反馈**（默认）：RS485收码触发Mesh动作后，Mesh状态变化会再发送发码到RS485总线
-- **不勾选反馈**：RS485收码触发Mesh动作后，不再发送反馈码，避免总线重复数据
-
-适用场景：当第三方设备已经知道自己的状态，不需要收到确认反馈时，取消勾选可减少总线流量。
-
-#### 自定义开关（4组码）
-
-- **发开码**：Mesh开关打开时，发送此码到RS485总线
-- **发关码**：Mesh开关关闭时，发送此码到RS485总线
-- **收开码**：RS485总线收到此码时，触发Mesh开关打开
-- **收关码**：RS485总线收到此码时，触发Mesh开关关闭
-
-**翻转模式**：当收开码=收关码时，收到后自动翻转开关状态
-
-#### 自定义窗帘（6组码）
-
-- **发开码**、**发关码**、**发停码**：Mesh→RS485
-- **收开码**、**收关码**、**收停码**：RS485→Mesh
-
-#### 自定义空调（完整收发码）
-
-- **开关**：发开码、发关码、收开码、收关码
-- **风速**：发高风、发中风、发低风、收高风、收中风、收低风
-- **模式**：发制冷、发制热、发除湿、发送风、收制冷、收制热、收除湿、收送风
-- **温度**：发温度码、收温度码（支持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
-收关码: 55 02 02 03 02
-收停码: 55 02 02 03 03
-```
-
-#### 工作原理
-1. **Mesh→RS485**：Mesh设备状态变化时，发送对应的发码
-2. **RS485→Mesh**：收到的RS485帧与收码匹配，触发对应Mesh设备
-3. **翻转逻辑**：开关的收开码=收关码时，收到后翻转当前状态
-4. **防死循环**：500ms内不重复触发，避免Mesh→RS485→Mesh循环
-
-#### 注意事项
-- 支持最多24字节（72个十六进制字符）数据录入
-- 支持空格分隔（如 `55 01 01` 或 `550101`）
-- 自定义模式不需要填写地址字段（自动隐藏）
-- 配置持久化保存，重启后保持
-
-### 注意事项
-
-1. **Modbus地址**：同一485总线上设备地址不能重复（1-255）
-2. **自动重连**：网络断开后5秒自动重连，无需人工干预
-3. **事件驱动**：非轮询模式，设备状态变化时才同步
-4. **防循环保护**：内置同步锁机制，避免状态死循环
-5. **485转TCP网关**：Node-RED只能收到自己发送请求后的设备回应，其他TCP客户端的数据不会转发（网关机制）
-
-## RS485协议同步
-
-本节点支持两种不同RS485协议之间的双向数据同步，适用于对接中弘VRF网关与SYMI空调面板等场景。
-
-### 功能特点
-
-- **协议互转**：中弘VRF ↔ SYMI空调面板 ↔ 自定义码
-- **双向同步**：A侧状态变化自动同步到B侧，反之亦然
-- **自动轮询**：内置定时轮询中弘VRF设备状态（默认1秒）
-- **多组映射**：单节点支持多组设备映射
-- **防死循环**：2秒防抖机制，避免状态回环
-- **持久化配置**：重启后保持所有映射设置
-
-### 支持的协议
-
-| 协议类型 | 说明 | 帧格式 |
-|---------|------|--------|
-| 中弘VRF | 中弘品牌VRF空调网关（需轮询） | `[从机] [功能码] [控制值] [数量] [外机] [内机] [校验和]` |
-| SYMI空调面板 | SYMI Mesh空调面板RS485接口（主动上报） | `[地址] [0x60] [开关] [温度] [模式] [风速] [...] [校验和]` |
-| 自定义码 | 任意十六进制码匹配 | 用户自定义 |
-
-### 中弘VRF协议详解（需轮询）
-
-| 功能码 | 用途 | 控制值 |
-|--------|------|--------|
-| 0x31 | 开关控制 | 0x00=关, 0x01=开 |
-| 0x32 | 温度控制 | 16-30（直接温度值） |
-| 0x33 | 模式控制 | 0x01=制冷, 0x02=除湿, 0x04=送风, 0x08=制热 |
-| 0x34 | 风速控制 | 0x01=高, 0x02=中, 0x04=低 |
-| 0x50 | 状态查询 | - |
-
-> **注意**：中弘VRF是被动响应式协议，需要主动轮询才能获取设备状态。启用轮询后会定时发送0x50查询命令。
-
-### SYMI空调面板协议详解（主动上报）
-
-SYMI空调面板会主动上报状态变化，无需轮询。
-
-**帧格式**：`[地址] [0x60] [开关] [温度] [模式] [风速] [x] [x] [x] [校验和]`
-
-| 字节 | 说明 | 值域 |
-|------|------|------|
-| 0 | 设备地址 | 1-255 |
-| 1 | 功能码 | 0x60 |
-| 2 | 开关状态 | 0x00=关, 0x01=开 |
-| 3 | 目标温度 | 16-30 (0x10-0x1E) |
-| 4 | 运行模式 | 0x01=制冷, 0x02=除湿, 0x04=送风, 0x08=制热 |
-| 5 | 风速 | 0x01=低, 0x02=中, 0x04=高 |
-| 6-8 | 保留 | - |
-| 9 | 校验和 | 前9字节累加和的低8位 |
-
-**示例帧**：`01 60 01 18 08 02 01 01 00 86`
-- 地址1, 开机, 24°C, 制热, 中风
-
-**帧示例**（开机）：
-```
-01 31 01 01 01 01 36
-│  │  │  │  │  │  └─ 校验和
-│  │  │  │  │  └─ 内机地址
-│  │  │  │  └─ 外机地址
-│  │  │  └─ 空调数量
-│  │  └─ 控制值（开）
-│  └─ 功能码（开关）
-└─ 从机地址
-```
-
-### 配置步骤
-
-#### 1. 添加RS485同步节点
-
-从"Symi Mesh"分类中拖入"RS485同步"节点
-
-#### 2. 配置RS485连接
-
-**RS485连接A**：选择第一种协议的RS485配置（如中弘VRF网关）
-**RS485连接B**：选择第二种协议的RS485配置（如SYMI空调面板）
-
-> **注意**：A和B必须是两个不同的RS485配置节点
-
-#### 3. 添加协议映射
-
-点击"添加映射"按钮，配置每组对应关系：
-
-| 配置项 | 说明 |
-|--------|------|
-| A侧协议 | 选择A侧使用的协议（中弘VRF/SYMI空调面板/自定义码） |
-| B侧协议 | 选择B侧使用的协议 |
-| 详细参数 | 点击齿轮按钮展开，配置地址等参数 |
-
-#### 4. 轮询设置
-
-| 参数 | 说明 | 默认值 |
-|------|------|--------|
-| 启用轮询 | 开启后自动轮询中弘VRF设备状态 | 启用 |
-| 轮询间隔 | 轮询周期（毫秒） | 1000ms |
-
-> **说明**：中弘VRF是被动响应式协议，需要主动查询才能获取设备状态。启用轮询后会逐个查询所有配置的中弘VRF设备。
-
-#### 5. 中弘VRF参数配置
-
-| 参数 | 说明 | 范围 |
-|------|------|------|
-| 外机地址 | VRF外机地址 | 0-255 |
-| 内机地址 | VRF内机地址 | 0-255 |
-
-#### 6. SYMI空调面板参数配置
-
-| 参数 | 说明 | 范围 |
-|------|------|------|
-| 设备地址 | SYMI面板Modbus地址 | 1-255 |
-
-#### 7. 自定义码参数配置
-
-| 参数 | 说明 |
-|------|------|
-| 开机发码 | 检测到开机时发送的十六进制码 |
-| 关机发码 | 检测到关机时发送的十六进制码 |
-| 开机收码 | 收到此码时认为设备开机 |
-| 关机收码 | 收到此码时认为设备关机 |
-
-#### 8. 部署
-
-点击"部署"按钮，节点自动开始双向同步
-
-### 配置示例
-
-**中弘VRF ↔ SYMI空调面板**：
-```
-RS485连接A: 192.168.2.100:502 (中弘VRF网关)
-RS485连接B: 192.168.2.110:1031 (SYMI面板总线)
-
-映射1:
-  A侧: 中弘VRF (从机1, 外机1, 内机1)
-  B侧: SYMI空调面板 (地址1)
-
-映射2:
-  A侧: 中弘VRF (从机1, 外机1, 内机2)
-  B侧: SYMI空调面板 (地址2)
-```
-
-### 工作原理
-
-#### A→B同步流程
-
-1. A侧RS485收到状态帧
-2. 解析协议，提取状态（开关/温度/模式/风速）
-3. 根据B侧协议生成控制命令
-4. 发送到B侧RS485
-
-#### B→A同步流程
-
-1. B侧RS485收到状态帧
-2. 解析协议，提取状态
-3. 根据A侧协议生成控制命令
-4. 发送到A侧RS485
-
-#### 防死循环机制
-
-- 同步后2秒内忽略反向状态变化
-- 每组映射独立防抖，互不影响
-- 状态缓存避免重复同步
-
-### 手动触发查询
-
-可以使用inject节点发送查询命令：
-
-```json
-{
-  "payload": {
-    "action": "query"
-  }
-}
-```
-
-这将向A侧所有中弘VRF设备发送状态查询命令。
-
-### 故障排查
-
-**A→B不工作**：
-1. 检查日志是否有`[A侧收到]`输出
-2. 确认A侧协议参数（从机/外机/内机地址）正确
-3. 检查RS485连接A是否已连接
+### 三合一面板配置
 
-**B→A不工作**：
-1. 检查日志是否有`[B侧收到]`输出
-2. 确认B侧协议参数正确
-3. 检查RS485连接B是否已连接
+三合一面板需要创建3个独立映射：
 
-**状态不同步**：
-1. 检查节点状态是否显示"同步中"
-2. 确认两个RS485连接都已连接（绿色状态）
-3. 查看日志中的同步消息
+| Mesh设备 | RS485设备类型 | 从机地址 |
+|---------|--------------|---------|
+| 三合一面板_xxx | 空调 | 0 |
+| 三合一面板_xxx | 新风 | 60 |
+| 三合一面板_xxx | 地暖 | 62 |
 
 ## 云端数据同步
 
@@ -1174,283 +534,139 @@ RS485连接B: 192.168.2.110:1031 (SYMI面板总线)
 
 ### 使用场景
 
-- **酒店项目**：自动同步房间设备的本地化名称（如"客厅窗帘"、"床头灯"等）
-- **场景管理**：获取云端配置的场景列表（如"全关"、"睡眠模式"等）并本地化调用
-- **批量部署**：统一管理多个房间的设备名称，无需手动配置
+- **酒店项目**：自动同步房间设备的本地化名称
+- **场景管理**：获取云端配置的场景列表并本地化调用
+- **批量部署**：统一管理多个房间的设备名称
 
 ### 配置步骤
 
-#### 1. 添加云端同步节点
-
-在Node-RED中添加"Symi Cloud Sync"节点：
+1. **添加云端同步节点**
+2. **配置云端认证**：App ID和App Secret
+3. **配置房间信息**：酒店ID和房间号
+4. **部署并验证**
 
-**基础配置**：
-- **网关**：选择已配置的Symi Gateway节点
-- **MQTT节点**：选择Symi MQTT节点（用于更新Discovery配置）
-
-**云端认证**：
-- **App ID**：请联系Symi技术支持获取
-- **App Secret**：请联系Symi技术支持获取
-- 点击"测试连接"按钮验证认证信息
+### 按键场景自动触发
 
-**房间配置**：
-- **酒店ID**：输入酒店ID或点击"加载酒店列表"自动获取
-- **房间号**：输入房间号（如：1001）
-- **房间UUID**：可选，如果有UUID可直接填写
+开关按键可以绑定场景，按下时自动触发场景执行：
 
-**同步选项**：
-- **自动同步**：勾选后，启动时自动从云端获取数据（推荐）
+- **普通按键**：控制本地继电器
+- **场景按键**：按下时触发指定场景
+- **双控按键**：根据当前状态触发开/关场景
+- **总控按键**：全局控制
 
-#### 2. 部署并验证
+## 节点概览
 
-1. 点击右上角"部署"按钮
-2. 检查调试面板确认同步状态：
-   - `开始从云端获取数据` - 开始同步
-   - `云端数据获取成功: X个设备, Y个场景` - 同步成功
-   - `设备名称已更新: 旧名称 -> 新名称` - 名称更新
-   - `重新发布MQTT Discovery配置` - 更新HA配置
-3. 在Home Assistant中查看设备名称是否已更新
+| 节点 | 用途 |
+|-----|------|
+| **Symi Gateway** | 网关连接（TCP/串口） |
+| **Symi MQTT** | MQTT桥接，设备发布到HA |
+| **Symi Device** | Flow中单设备控制/监听 |
+| **Symi Cloud Sync** | 云端同步设备名称和场景 |
+| **Symi RS485 Bridge** | RS485设备双向同步 |
+| **Symi KNX Bridge** | KNX系统双向同步 |
+| **Symi KNX-HA Bridge** | KNX与HA实体双向同步 |
+| **Symi HA Sync** | HA实体双向同步 |
+| **Symi MQTT Sync** | 第三方MQTT品牌设备同步 |
+| **Symi MQTT Brand** | 品牌MQTT配置节点 |
+| **RS485 Debug** | RS485总线数据抓包调试 |
+| **Symi RS485 Sync** | 两种RS485协议双向同步 |
 
-#### 3. 手动触发同步
+## 协议说明
 
-如需手动触发同步，可以使用inject节点：
+### 核心协议格式
 
 ```
-[inject] --> [cloud-sync]
-payload: "sync"
+[Header(0x53)] [Opcode] [Status] [Length] [Data] [Checksum]
 ```
 
-#### 4. 调用场景
-
-云端同步后，可以通过inject节点调用场景：
+### 关键操作码
 
-```
-[inject] --> [cloud-sync]
-payload: { scene_id: 4 }  // 执行场景ID为4的场景（如"全关"）
-```
+| 操作码 | 名称 | 方向 | 说明 |
+|-------|------|------|------|
+| 0x12 | 设备列表查询 | 主机→网关 | 查询所有设备 |
+| 0x92 | 设备列表响应 | 网关→主机 | 返回设备信息 |
+| 0x30 | 设备控制 | 主机→网关 | 控制指定设备 |
+| 0xB0 | 控制响应 | 网关→主机 | 控制结果 |
+| 0x34 | 场景控制 | 主机→网关 | 执行场景（群控） |
+| 0xB4 | 场景控制响应 | 网关→主机 | 场景控制结果 |
+| 0x80 | 状态事件 | 网关→主机 | 设备状态主动上报 |
+| 0x32 | 状态查询 | 主机→网关 | 查询设备状态 |
 
-### 按键场景自动触发
+### 开关状态编码
 
-**v1.4.0新功能**：开关按键可以绑定场景，按下时自动触发场景执行，实现本地化场景联动。
-
-#### 工作原理
-
-1. **云端配置获取**：从云端获取每个按键的配置信息（sub_device）
-2. **按键类型识别**：
-   - **普通按键**（sub_type="普通"）：控制本地继电器，不触发场景
-   - **场景按键**（sub_type="场景"）：按下时触发指定场景（scene_id）
-   - **双控按键**（sub_type="双控"）：根据当前状态触发开场景（on_scene_id）或关场景（off_scene_id）
-   - **总控按键**（sub_type="总控"）：同双控，用于全局控制
-3. **本地化触发**：按键按下时，系统自动检测并发送0x34场景控制命令到总线
-4. **状态同步**：场景执行后，所有相关设备状态自动同步到Home Assistant
-
-#### 配置示例
-
-云端配置（酒店云云平台）：
-```json
-{
-  "device_name": "床头三键",
-  "sub_device": [
-    {
-      "sub_name": "明亮",
-      "sub_type": "场景",
-      "scene_id": 4
-    },
-    {
-      "sub_name": "温馨",
-      "sub_type": "场景",
-      "scene_id": 6
-    },
-    {
-      "sub_name": "睡眠",
-      "sub_type": "场景",
-      "scene_id": 5
-    }
-  ]
-}
-```
+**协议规则**: 每2位表示1路，`01`=关，`10`=开，从最低位开始
 
-#### 日志示例
+| 路数 | 全关 | 全开 |
+|-----|------|------|
+| 1路 | 0x01 | 0x02 |
+| 2路 | 0x05 | 0x0A |
+| 4路 | 0x55 | 0xAA |
+| 8路 | 0x5555 | 0xAAAA |
 
-启动时显示场景绑定：
-```
-[场景绑定] 床头三键: 按键1(明亮)→场景4, 按键2(温馨)→场景6, 按键3(睡眠)→场景5
-[场景绑定] 入户二键: 按键1(廊灯)→开:场景22/关:场景21, 按键2(卫浴灯)→开:场景24/关:场景23
-```
+### 常用消息类型
 
-按键按下时触发场景：
-```
-[按键场景] 检测到按键1(明亮)状态变化: 关 → 开, 触发场景4
-[按键场景] ✓ 场景4(明亮)控制命令已发送
-[场景控制] 场景控制命令已被网关接受
-[场景执行] 收到场景执行通知事件: 场景ID=4
-```
+| 消息类型 | 代码 | 数据格式 | 范围/说明 |
+|---------|------|---------|----------|
+| 开关状态 | 0x02 | 1字节 | 1-4路开关 |
+| 亮度 | 0x03 | 1字节 | 0-100% |
+| 色温 | 0x04 | 1字节 | 0%=暖白, 100%=冷白 |
+| 窗帘动作 | 0x05 | 1字节 | 1=开/2=关/3=停 |
+| 窗帘位置 | 0x06 | 1字节 | 0-100% |
+| 当前温度 | 0x16 | 2字节LE | 温度*100 |
+| 目标温度 | 0x1B | 1字节 | 16-30°C |
+| 风速 | 0x1C | 1字节 | 1=高/2=中/3=低/4=自动 |
+| 模式 | 0x1D | 1字节 | 1=制冷/2=制热/3=送风/4=除湿 |
 
-#### 注意事项
+## MQTT主题结构
 
-1. **云端配置必需**：需要先配置云端同步节点并成功获取设备配置
-2. **完全本地化**：场景触发完全在本地进行，不依赖云端
-3. **避免循环**：场景执行期间不会再次触发按键场景，防止循环
-4. **状态同步**：场景执行后的设备状态变化会自动同步到HA
+### Discovery主题
 
-### 工作原理
+```
+homeassistant/[platform]/[object_id]/config
+```
 
-#### 数据获取流程
+### 状态和命令主题
 
+**普通设备**：
 ```
-启动/部署
-  ↓
-调用云端API（房间信息接口）
-  ↓
-解析设备列表和场景列表
-  ↓
-根据MAC地址匹配本地设备
-  ↓
-更新设备名称（device.name）
-  ↓
-保存场景列表到本地
-  ↓
-重新发布MQTT Discovery配置
-  ↓
-持久化存储（缓存）
-  ↓
-完成（不再调用）
+symi_mesh/[mac_clean]/[entity]/state
+symi_mesh/[mac_clean]/[entity]/set
 ```
 
-#### MAC地址匹配规则
-
-云端返回的设备MAC地址会自动反转后与本地设备MAC地址匹配：
-
-```javascript
-// 云端设备（MAC地址为反序存储）
-{
-  "device_name": "窗帘",
-  "nick_name": "客厅窗帘",
-  "mac": "14d881c086d4",  // 云端反序存储
-  "naddr": 256
-}
-
-// 本地设备匹配
-1. 将云端MAC转换为小写并去除分隔符: "14d881c086d4"
-2. 反转MAC地址（每2位反转）: "d486c081d814"
-3. 与本地设备MAC进行精确匹配
-4. 匹配成功后更新 device.name = "客厅窗帘"
-5. 如果云端名称为"未命名"或空，则保留设备类型标准名称（如"智能窗帘"）
-6. 重新发布MQTT Discovery（使用新名称）
+**三合一设备**：
 ```
-
-#### 场景本地化调用
-
-云端场景信息会保存到本地，可以通过网关直接调用：
-
-```javascript
-// 云端场景
-{
-  "scene_name": "全关",
-  "scene_id": 4
-}
-
-// 本地调用
-通过inject节点发送: { scene_id: 4 }
-节点会查找场景名称并输出到下游节点
-可以连接到其他节点进行进一步处理
+空调：symi_mesh/[mac_clean]/climate/mode
+新风：symi_mesh/[mac_clean]/fresh_air/state
+地暖：symi_mesh/[mac_clean]/floor_heating/mode
 ```
 
-### 数据持久化
-
-云端同步节点会将获取的数据持久化存储到Node-RED的context中：
-
-- **存储内容**：设备列表、场景列表、最后同步时间
-- **存储位置**：节点的context存储（重启后保留）
-- **使用场景**：
-  - 云端API调用失败时，自动使用缓存数据
-  - 禁用自动同步后，仍可使用上次获取的数据
-  - 网络故障时，不影响已同步的设备名称
-
-### 常见问题
-
-#### Q: 云端同步会影响性能吗？
-
-A: 不会。云端同步仅在启动/部署时执行一次，不会持续轮询。同步完成后，节点处于空闲状态，不占用资源。
-
-#### Q: 如果云端API调用失败怎么办？
-
-A: 节点会自动使用上次成功获取的缓存数据。如果从未成功获取过，设备将保持原有名称。
-
-#### Q: 可以禁用云端同步节点吗？
-
-A: 可以。禁用节点不会影响其他功能（网关、MQTT、设备控制）的正常运行。已同步的设备名称会保留。
-
-#### Q: 云端名称和本地设备如何匹配？
-
-A: 通过MAC地址精确匹配。云端返回的设备MAC地址会自动反转后与本地设备MAC匹配（因为云端存储为反序）。如果云端名称为"未命名"或空，则自动保留设备类型标准名称（如"智能窗帘"、"零火开关"等）。
-
-#### Q: 场景如何调用？
-
-A: 云端同步后，场景会自动发布为Home Assistant按钮实体。在HA中点击场景按钮即可触发本地场景执行（使用0x34协议，不经过云端）。场景执行后，所有相关设备的状态会自动同步到HA，确保状态一致性。也可以通过inject节点发送 `{ scene_id: X }` 来调用场景。
-
-#### Q: 设备列表中的勾选框是做什么用的？
-
-A: 勾选的设备会同步云端名称到本地，未勾选的设备保持原有名称不变。如果不勾选任何设备，则默认同步所有设备。场景勾选同理，勾选的场景会发布到Home Assistant。支持一键全选功能。
-
-#### Q: 开关设备的按键名称如何显示？
-
-A: 对于多键开关（1-6键），云端同步节点会显示每个按键的名称（如"床头灯"、"睡眠"等），这些名称来自云端的sub_device配置，并会同步到MQTT实体名称中。
-
-#### Q: MQTT配置在哪里？
-
-A: MQTT配置统一在**网关节点**中配置。所有使用该网关的节点（包括云端同步节点）都会自动使用网关中配置的MQTT客户端，无需重复配置。
-
-#### Q: HA中的实体名称格式是什么？
-
-A: HA实体名称为纯名称，不带MAC地址和ID。例如"客厅灯 床头灯"而不是"客厅灯_14d881c086d4_1"。MAC地址仅用作unique_id确保实体唯一性。
-
-#### Q: 多个房间如何管理？
-
-A: 每个房间部署一个云端同步节点，配置对应的酒店ID和房间号即可。
-
-### 故障排除
-
-**症状**: 云端同步失败
+## 技术栈兼容性
 
-**解决方法**:
-1. 检查App ID和App Secret是否正确
-2. 点击"测试连接"按钮验证认证信息
-3. 检查网络连接是否正常
-4. 查看调试日志中的详细错误信息
+### 版本要求
 
-**症状**: 设备名称未更新
+| 组件 | 最低版本 | 推荐版本 |
+|------|---------|---------|
+| Node-RED | ≥3.0.0 | 4.0+ |
+| Node.js | ≥18.0.0 | 22.x LTS |
+| MQTT Broker | 任意 | Mosquitto 2.x |
 
-**解决方法**:
-1. 检查云端设备MAC地址是否与本地设备一致
-2. 查看调试日志中的"设备匹配完成"信息
-3. 确认MQTT节点已正确配置
-4. 手动触发同步（发送 `msg.payload = "sync"`）
+### Node.js 18+ 兼容性
 
-**症状**: 场景无法调用
+本项目已针对Node.js 18+进行优化：
 
-**解决方法**:
-1. 检查云端是否返回了场景列表
-2. 查看调试日志中的"场景列表已保存"信息
-3. 确认场景ID是否正确
-4. 检查网关连接是否正常
+- **AggregateError处理**：全局异常处理器捕获`AggregateError`，防止崩溃
+- **Happy Eyeballs禁用**：通过`net.setDefaultAutoSelectFamily(false)`禁用
+- **强制IPv4连接**：TCP连接使用`family: 4`参数
+- **网络异常恢复**：自动捕获网络错误
 
-## 节点概览
+### 代码质量
 
-| 节点 | 用途 | 详见章节 |
-|-----|------|---------|
-| **Symi Gateway** | 网关连接（TCP/串口） | [快速开始](#快速开始) |
-| **Symi MQTT** | MQTT桥接，设备发布到HA | [快速开始](#快速开始) |
-| **Symi Device** | Flow中单设备控制/监听 | 可用于KNX/自定义同步 |
-| **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双向同步) |
-| **Symi HA Sync** | HA实体双向同步 | [HA双向同步](#ha双向同步) |
-| **Symi MQTT Sync** | 第三方MQTT品牌设备同步 | [MQTT品牌同步](#mqtt品牌同步) |
-| **Symi MQTT Brand** | 品牌MQTT配置节点 | [MQTT品牌同步](#mqtt品牌同步) |
-| **RS485 Debug** | RS485总线数据抓包调试 | [RS485调试节点](#rs485调试节点) |
-| **Symi RS485 Sync** | 两种RS485协议双向同步 | [RS485协议同步](#rs485协议同步) |
+经2025-12-10代码审查确认：
+- 遵循Node-RED节点开发规范
+- 使用标准日志接口
+- 正确处理节点关闭事件
+- 无未处理的Promise rejection
+- 代码无重复，模块化设计
 
 ## 开发者信息
 
@@ -1470,232 +686,113 @@ node-red-contrib-symi-mesh/
 │   ├── symi-device.js/html   # 设备控制节点
 │   ├── symi-cloud-sync.js/html # 云端同步节点
 │   ├── symi-485-bridge.js/html # RS485桥接节点
-│   ├── symi-485-config.js/html # RS485配置节点
 │   ├── symi-knx-bridge.js/html # KNX桥接节点
 │   ├── symi-knx-ha-bridge.js/html # KNX-HA桥接节点
-│   ├── symi-rs485-sync.js/html # RS485协议同步节点
+│   ├── symi-ha-sync.js/html  # HA同步节点
 │   ├── symi-mqtt-sync.js/html # MQTT品牌同步节点
-│   ├── symi-mqtt-brand.js/html # 品牌MQTT配置节点
-│   └── rs485-debug.js/html   # RS485调试节点
+│   └── ...
 ├── examples/
-│   ├── basic-example.json    # 基础示例
-│   ├── knx-sync-example.json # KNX桥接节点示例
-│   └── rs485-sync-example.json # RS485协议同步示例
+│   ├── basic-example.json
+│   ├── knx-sync-example.json
+│   └── rs485-sync-example.json
 ├── LICENSE
 ├── README.md
 └── package.json
 ```
 
-### 协议参考
-
-本项目严格遵循"蓝牙MESH网关（初级版）串口协议V1.0"文档实现。
-
-### 贡献指南
-
-欢迎提交Issue和Pull Request：
-
-1. Fork本仓库
-2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
-3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
-4. 推送到分支 (`git push origin feature/AmazingFeature`)
-5. 提交Pull Request
-
-**开发要求**：
-- 遵循现有代码风格
-- 添加必要的注释和文档
-- 测试所有更改
-- 更新README（如需要）
-
-## 技术栈兼容性
-
-### 版本要求
-
-| 组件 | 最低版本 | 推荐版本 | 说明 |
-|------|---------|---------|------|
-| Node-RED | ≥3.0.0 | 4.0+ | 支持最新API |
-| Node.js | ≥18.0.0 | 22.x LTS | 官方推荐LTS版本 |
-| MQTT Broker | 任意 | Mosquitto 2.x | 支持MQTT 3.1.1+ |
-
-### Node.js 18+ 兼容性
-
-本项目已针对Node.js 18+进行优化：
-
-- **AggregateError处理**：全局异常处理器捕获`AggregateError`，防止崩溃
-- **Happy Eyeballs禁用**：通过`net.setDefaultAutoSelectFamily(false)`禁用
-- **强制IPv4连接**：TCP连接使用`family: 4`参数，避免IPv6连接超时
-- **网络异常恢复**：自动捕获`ECONNREFUSED`、`ETIMEDOUT`等网络错误
-
-### 代码质量
-
-经2025-12-10代码审查确认：
-- 遵循Node-RED节点开发规范
-- 使用标准日志接口（`node.log()`、`node.error()`等）
-- 正确处理节点关闭事件，清理事件监听器防止内存泄漏
-- 无未处理的Promise rejection
-- 无TODO/FIXME/HACK标记
-- 代码无重复，模块化设计
-
 ## 更新日志
 
-### v1.8.3 (2026-01-05)
-
-**HA同步节点重大修复**：
-- 修复HA→Symi方向不工作的问题（input监听器未正确注册）
-- 支持多种HA节点消息格式（server-events、server-state-changed、trigger:state等）
-- 自动过滤event类型实体（如按键点击事件），避免无效同步
-- 优化状态显示：蓝色"Mesh→HA"表示单向，绿色"双向同步"表示双向正常
-- 精简日志输出，只记录映射中的实体状态变化
-- 更新HTML帮助文档，详细说明双向同步连接方式
-- 更新README文档，添加完整的HA同步配置指南
-
-**连接方式说明**：
-- Symi→HA：自动工作，无需额外配置
-- HA→Symi：需连接`events: all`或`events: state`节点到symi-ha-sync输入端
-
-### v1.8.2 (2025-12-xx)
-
-- 窗帘和调光灯智能防抖，只同步最终状态
-- 三合一面板完整双向同步支持
-
-## 技术支持
-
-如遇问题，请提供以下信息：
-
-1. **环境信息**:
-   - Node-RED版本
-   - Node.js版本
-   - 操作系统
-
-2. **网关信息**:
-   - 网关型号
-   - 固件版本
-   - 连接方式（TCP/串口）
-
-3. **问题描述**:
-   - 完整错误日志
-   - 设备类型和数量
-   - 复现步骤
-
-4. **调试日志**:
-   - Node-RED调试日志
-   - MQTT日志（如相关）
-   - 网关串口日志（如可用）
+### v1.8.5 (2026-01-06)
+
+**通用同步工具类重构**：
+- 新增 `lib/sync-utils.js` 通用同步工具模块
+- 统一 SyncUtils 类：提供防环路逻辑，支持不同设备类型的超时配置
+- 统一 StateCache 类：状态缓存对比，避免重复同步
+- 统一 SyncQueue 类：同步命令队列管理，支持高负载场景
+
+**所有同步节点统一使用 SyncUtils**：
+- HA同步节点 (`symi-ha-sync.js`) 使用 SyncUtils 替代原有防环路实现
+- MQTT同步节点 (`symi-mqtt-sync.js`) 使用 SyncUtils 替代原有防环路实现
+- KNX桥接节点 (`symi-knx-bridge.js`) 重构使用 SyncUtils，移除独立的 LOOP_PREVENTION_MS
+- RS485桥接节点 (`symi-485-bridge.js`) 重构使用 SyncUtils，统一防环路逻辑
+- 统一超时配置：普通设备2秒、窗帘30秒、亮度800ms
+
+**MQTT品牌同步三合一子实体支持**：
+- 新增 `meshSubEntity` 映射字段，支持三合一面板子实体映射
+- 空调子实体 → HYQW type 12 (开关/温度/模式/风速)
+- 新风子实体 → HYQW type 36 (开关/风速)
+- 地暖子实体 → HYQW type 16 (开关/温度)
+- 双向同步：HYQW设备状态变化自动同步到Mesh三合一面板
+
+**代码质量优化**：
+- 消除重复的防环路代码，所有同步节点共用 SyncUtils
+- 节点关闭时正确调用 SyncUtils.destroy() 清理资源
+- 减少内存泄漏风险，统一时间戳清理机制
+
+**三合一状态缓存细粒度优化**：
+- HA同步节点使用 StateCache 实现细粒度状态对比
+- 缓存key格式优化为 `{mac}_{subEntity}_{property}`
+- 只同步真正变化的属性，减少冗余HA API调用
+- 支持空调、新风、地暖各属性独立变化检测
+
+### v1.8.4 (2026-01-06)
+
+**HA同步节点窗帘双向同步重大修复**：
+- 实现"谁发起控制就只听谁的命令"逻辑，彻底解决窗帘双向同步死循环问题
+- Mesh控制时：只同步位置到HA，不发送动作命令
+- HA控制时：发送动作/位置到Mesh，运动过程中忽略Mesh的所有反馈
+- 停止后延迟5秒释放控制权，确保延迟反馈也被正确过滤
+- 只处理HA的`opening`/`closing`状态，忽略`open`/`closed`状态反馈
+
+**其他优化**：
+- 修复HA state_changed事件解析，支持更多消息格式变体
+- 优化空调同步逻辑：只在开关状态真正变化时同步
+- 优化调光同步逻辑：HA发起调光时忽略Mesh步进反馈
+- 增加状态变化检测：无变化时跳过处理
+- 过滤sensor类型实体，避免不必要的处理
+
+**MQTT品牌同步协议修复**：
+- 窗帘设备协议修复：修复窗帘fn=1功能码的正确解析
+- 设备类型独立处理：重构syncToMesh和syncToMqtt函数
+- 完整功能码支持：灯具、空调、窗帘、地暖、新风
+
+**三合一面板深度集成**：
+- 子设备选择：HA同步节点新增三合一子设备选择功能
+- 完整属性同步：支持空调、新风、地暖的全功能双向同步
+
+**稳定性修复**：
+- 修复Mesh控制窗帘时HA反向发送命令导致窗帘停止的问题
+- 修复HA控制窗帘时Mesh反馈导致循环控制的问题
+- 修复窗帘打开命令被防死循环机制阻止的问题
+- 修复空调off->off重复日志的问题
 
 ## 常见问题排查
 
 ### MQTT连接失败
 
-**问题**：节点状态显示"Broker不可用"或"连接失败"
-
-**排查步骤**：
-
-1. **检查MQTT Broker地址配置**
-   ```
-   # Docker部署时使用容器名
-   mqttBroker: mqtt://mosquitto:1883
-   
-   # 本地安装时使用localhost
-   mqttBroker: mqtt://localhost:1883
-   ```
-
-2. **确认MQTT Broker运行状态**
-   ```bash
-   # Docker方式
-   docker ps | grep mosquitto
-   docker start mosquitto  # 如未运行
-   
-   # Homebrew方式（macOS）
-   brew services list | grep mosquitto
-   brew services start mosquitto
-   
-   # 测试连接
-   nc -zv localhost 1883
-   ```
-
-3. **检查防火墙/网络**
-   - 确保1883端口未被占用或阻断
-   - 如使用Docker，确保网络配置正确
+1. 检查MQTT Broker地址配置
+2. 确认MQTT Broker运行状态
+3. 检查防火墙/网络
 
 ### 网关连接失败
 
-**问题**：节点状态显示"连接失败"或频繁重连
-
-**排查步骤**：
-
 1. 确认网关IP地址和端口（默认4196）
 2. 使用`ping`测试网络连通性
 3. 检查网关是否开启TCP服务模式
-4. 查看Node-RED日志中的详细错误信息
 
 ### 设备状态不同步
 
-**问题**：HA中设备状态与实际不一致
-
-**排查步骤**：
-
 1. 检查网关节点是否显示"已连接"
 2. 检查MQTT节点是否显示"已连接"
 3. 在Node-RED调试面板查看是否收到设备状态事件
-4. 确认MQTT Broker中的topic消息是否正确
 
-## 更新日志
+## 技术支持
 
-### v1.8.3 (2026-01-05)
-
-**HA同步节点重大修复**：
-- 修复HA→Symi方向不工作的问题（input监听器未正确注册）
-- 支持多种HA节点消息格式（server-events、server-state-changed、trigger:state等）
-- 自动过滤event类型实体（如按键点击事件），避免无效同步
-- 优化状态显示：蓝色"Mesh→HA"表示单向，绿色"双向同步"表示双向正常
-- 精简日志输出，只记录映射中的实体状态变化
-- 更新HTML帮助文档，详细说明双向同步连接方式
-- 更新README文档，添加完整的HA同步配置指南
-
-**连接方式说明**：
-- Symi→HA：自动工作，无需额外配置
-- HA→Symi：需连接`events: all`或`events: state`节点到symi-ha-sync输入端
-
-### v1.8.2 (2026-01-05)
-- **MQTT品牌同步协议修复**：
-  - **窗帘设备协议修复**：修复窗帘fn=1功能码的正确解析（0=关闭, 1=打开, 2=停止），之前错误地当作开关处理
-  - **设备类型独立处理**：重构syncToMesh和syncToMqtt函数，按设备类型(8/12/14/16/36)独立处理功能码映射
-  - **完整功能码支持**：
-    - 灯具(8): fn=1开关, fn=2亮度
-    - 空调(12): fn=1开关, fn=2温度, fn=3模式, fn=4风速
-    - 窗帘(14): fn=1动作(开/关/停), fn=2位置
-    - 地暖(16): fn=1开关, fn=2温度
-    - 新风(36): fn=1开关, fn=3风速
-  - **错误日志增强**：同步失败时输出详细错误信息，便于调试
-
-### v1.8.1 (2026-01-05)
-- **三合一面板深度集成**：
-  - **子设备选择**：HA同步节点新增三合一子设备选择功能，可分别选择“空调”、“新风”、“地暖”进行独立映射。
-  - **完整属性同步**：支持空调（开关/模式/温度/风速）、新风（开关/风速）、地暖（开关/温度）的全功能双向同步。
-- **配置与文档优化**：
-  - **纯配置同步**：明确HA同步节点为纯配置模式，无需额外连线即可实现双向同步。
-  - **文档更新**：全面更新README，增加三合一配置示例和Config-Only说明。
-- **稳定性修复**：
-  - 修复 Symi→HA 同步时的调试日志重复输出问题。
-  - 增强 HA 事件监听的健壮性，支持多种输入格式。
-- **窗帘双向同步修复**：
-  - **运动状态跟踪**：新增 `coverMoving` 状态跟踪机制，记录窗帘运动的发起方（Symi/HA）和开始时间
-  - **步进反馈过滤**：当 HA 发起窗帘控制时，自动忽略 Mesh 窗帘运动过程中的步进位置反馈，避免干扰
-  - **运动中状态过滤**：当 HA 窗帘处于 `opening`/`closing` 状态时，不同步位置变化到 Mesh，只同步最终位置
-  - **专用防死循环时间**：窗帘使用 30 秒防死循环窗口（普通设备 2 秒），适应窗帘较长的运动时间
-  - **防抖时间优化**：窗帘防抖时间从 500ms 增加到 1500ms，确保位置稳定后再同步
-  - **自动清理机制**：运动状态超时（30秒）自动清理，防止内存泄漏
-
-### v1.8.0 (2026-01-05)
-- **HA同步节点重大增强**：
-  - **同步模式选择**：新增“双向同步”、“仅Symi→HA”、“仅HA→Symi”三种模式，配置更加灵活。
-  - **持久化修复**：修复了 `syncMode` 和 `symiEntityType` 在节点保存时丢失的问题，确保配置 100% 永久保存。
-  - **UI 体验优化**：重新设计了映射列表布局，增加了“同步模式”列，并优化了窄屏下的显示效果。
-  - **容错能力增强**：修复了设备离线时无法正确显示按键选择器的问题，现在会自动回退到保存的配置。
-- **发布包质量保证**：
-  - 重新核对并优化了 `package.json` 的 `files` 字段，确保所有必要的 `lib` 和 `nodes` 文件在发布包中完整无缺，解决部分客户反馈的安装不完整问题。
-- **性能与稳定性**：
-  - 优化了双向同步的防死循环逻辑，减少了在高频触发场景下的 CPU 占用。
-  - 修复了 MQTT 配置下拉框在节点编辑面板打开时偶尔出现的加载卡顿问题。
+如遇问题，请提供以下信息：
+
+1. **环境信息**: Node-RED版本、Node.js版本、操作系统
+2. **网关信息**: 网关型号、固件版本、连接方式
+3. **问题描述**: 完整错误日志、设备类型和数量、复现步骤
 
 ## 许可证
 
@@ -1705,11 +802,9 @@ Copyright (c) 2025 SYMI 亖米
 
 ---
 
-## 关于
-
 **作者**: SYMI 亖米
-**版本**: 1.8.3
+**版本**: 1.8.5
 **协议**: 蓝牙MESH网关（初级版）串口协议V1.0
-**最后更新**: 2026-01-05
+**最后更新**: 2026-01-06
 **仓库**: https://github.com/symi-daguo/node-red-contrib-symi-mesh
 **npm包**: https://www.npmjs.com/package/node-red-contrib-symi-mesh