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

package/README.md

@@ -305,180 +305,118 @@ symi_mesh/[mac_clean]/[entity]/set
 
 本节点支持与`node-red-contrib-knx-ultimate`完整双向同步，实现Symi Mesh设备与KNX系统的互联互通。
 
-### 配置步骤
+### 方式一：KNX桥接节点（推荐）
+
+**v1.6.7新增**：使用`symi-knx-bridge`节点实现一站式配置，支持KNX实体导入和批量映射。
+
+#### 功能特点
+
+- **KNX实体库**：导入KNX组地址，快速选择实体
+- **一行映射**：紧凑表格，适合大量设备映射
+- **多设备类型**：开关、调光灯、窗帘、空调、新风、地暖
+- **双向同步**：自动处理Mesh↔KNX状态同步
+- **防死循环**：内置1.5秒防抖机制
 
-#### 1. 安装KNX节点
+#### 配置步骤
+
+1. **安装KNX节点**
 ```bash
 cd ~/.node-red
 npm install node-red-contrib-knx-ultimate
 ```
 
-#### 2. 导入示例Flow
-在Node-RED中：
-- 菜单 → 导入 → 选择文件
-- 导入 `examples/knx-sync-example.json`
-- 修改网关IP地址和设备MAC地址
-- 修改KNX组地址匹配您的系统
-
-#### 3. 设备类型映射
-
-| Symi设备 | KNX类型 | DPT | 说明 |
-|---------|--------|-----|------|
-| 开关 | 开关执行器 | 1.001 | 布尔开关 |
-| 双色调光 | 调光执行器 | 1.001 + 5.001 | 开关+亮度(0-255) |
-| 五色调光 | RGB调光器 | 1.001 + 5.001 + 232.600 | 开关+亮度+RGB |
-| 窗帘 | 窗帘执行器 | 1.008 + 5.001 | 上下+位置(0-255) |
-| 温控器 | 空调控制器 | 1.001 + 9.001 + 20.102 | 开关+温度+模式 |
-| 人体感应 | 移动传感器 | 1.002 | 布尔值 |
-| 插卡取电 | 开关+传感器 | 1.001 + 1.002 | 开关+插卡检测 |
-| 三合一-空调 | 空调控制器 | 1.001 + 9.001 + 20.102 | 开关+温度+模式 |
-| 三合一-新风 | 风机控制器 | 1.001 + 5.001 | 开关+风速 |
-| 三合一-地暖 | 地暖控制器 | 1.001 + 9.001 | 开关+温度 |
-
-### 同步逻辑
-
-#### Symi → KNX（状态反馈）
-1. Symi设备状态变化
-2. symi-device节点输出状态
-3. function节点转换格式
-4. knxUltimate-out发送到KNX总线
-
-#### KNX → Symi（远程控制）
-1. KNX总线命令
-2. knxUltimate-in接收命令
-3. function节点转换为MQTT格式
-4. mqtt-out发送到symi_mesh topic
-5. symi-mqtt节点处理并控制设备
-
-### 转换函数示例
-
-#### 开关转换
-```javascript
-// Symi→KNX
-const value = msg.payload ? 1 : 0;
-msg.destination = '1/1/1';
-return msg;
-
-// KNX→Symi
-const mac = 'device_mac_clean';
-return {
-    topic: `symi_mesh/${mac}/switch/set`,
-    payload: msg.payload === 1 ? 'ON' : 'OFF'
-};
-```
+2. **添加KNX桥接节点**
+从"Symi Mesh"分类中拖入"KNX桥接"节点
 
-#### 调光灯转换
-```javascript
-// Symi→KNX (亮度)
-const brightness = Math.round(msg.payload.brightness * 255 / 100);
-msg.destination = '2/1/2';
-msg.dpt = '5.001';
-return msg;
-
-// KNX→Symi
-return {
-    topic: `symi_mesh/${mac}/light/set`,
-    payload: JSON.stringify({
-        brightness: msg.payload  // 0-255
-    })
-};
-```
+3. **导入KNX实体**
+- 点击"下载模板"获取导入格式
+- 填写KNX组地址后点击"导入"
 
-#### 窗帘转换
-```javascript
-// Symi→KNX (位置)
-const position = Math.round(msg.payload.curtainPosition * 255 / 100);
-msg.destination = '3/1/2';
-msg.dpt = '5.001';
-return msg;
-
-// KNX→Symi
-return {
-    topic: `symi_mesh/${mac}/cover/position/set`,
-    payload: Math.round(msg.payload * 100 / 255).toString()
-};
+4. **添加映射**
+- 点击"添加"按钮
+- 选择Mesh设备和KNX实体
+- 开关设备可选择通道
+
+5. **连接KNX节点**
+```
+[knxUltimate-in] → [symi-knx-bridge] → [knxUltimate-out]
 ```
 
-#### 三合一设备转换
+#### KNX实体导入格式
 
-##### 空调转换（使用climate主题）
-```javascript
-// Symi→KNX (温度)
-msg.destination = '4/1/1';
-msg.dpt = '9.001';
-msg.payload = parseFloat(msg.payload.temp);
-return msg;
-
-// KNX→Symi (温度)
-return {
-    topic: `symi_mesh/${mac}/climate/target_temp/set`,
-    payload: msg.payload.toString()
-};
-
-// Symi→KNX (模式)
-const modeMap = { 'cool': 1, 'heat': 2, 'fan_only': 3, 'dry': 4 };
-msg.destination = '4/1/2';
-msg.dpt = '20.102';
-msg.payload = modeMap[msg.payload.mode] || 0;
-return msg;
-
-// KNX→Symi (模式)
-const modes = ['off', 'cool', 'heat', 'fan_only', 'dry'];
-return {
-    topic: `symi_mesh/${mac}/climate/mode/set`,
-    payload: modes[msg.payload] || 'off'
-};
+Tab分隔，每行一个实体：
 ```
-
-##### 新风转换
-```javascript
-// Symi→KNX (开关)
-msg.destination = '4/2/1';
-msg.dpt = '1.001';
-msg.payload = msg.payload.switch ? 1 : 0;
-return msg;
-
-// KNX→Symi (开关)
-return {
-    topic: `symi_mesh/${mac}/fresh_air/set`,
-    payload: msg.payload === 1 ? 'ON' : 'OFF'
-};
-
-// Symi→KNX (风速)
-msg.destination = '4/2/2';
-msg.dpt = '5.001';
-msg.payload = Math.round(msg.payload.speed * 2.55);
-return msg;
-
-// KNX→Symi (风速)
-return {
-    topic: `symi_mesh/${mac}/fresh_air/speed/set`,
-    payload: Math.round(msg.payload / 2.55).toString()
-};
+名称	类型	命令地址	状态地址	扩展1	扩展2	扩展3
 ```
 
-##### 地暖转换
-```javascript
-// Symi→KNX (温度)
-msg.destination = '4/3/1';
-msg.dpt = '9.001';
-msg.payload = parseFloat(msg.payload.temp);
-return msg;
-
-// KNX→Symi (温度)
-return {
-    topic: `symi_mesh/${mac}/floor_heating/target_temp/set`,
-    payload: msg.payload.toString()
-};
+支持的类型和地址字段：
+| 类型 | 字段 | 说明 |
+|------|------|------|
+| switch | 命令, 状态 | 开关 DPT1.001 |
+| light_mono | 命令, 状态, 亮度 | 单色调光 |
+| light_cct | 命令, 状态, 亮度, 色温 | 双色调光 |
+| light_rgb | 命令, 状态, 亮度, RGB | RGB调光 |
+| light_rgbcw | 命令, 状态, 亮度, 色温, RGB | RGBCW |
+| cover | 上下, 位置, 停止 | 窗帘 |
+| climate | 开关, 温度, 模式, 风速, 当前温度 | 空调 |
+| fresh_air | 开关, 风速 | 新风 |
+| floor_heating | 开关, 温度, 当前温度 | 地暖 |
+
+示例：
+```
+玄关射灯	switch	1/1/28	1/2/28
+客厅吊灯	light_cct	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
 ```
 
-### 注意事项
+#### 输入/输出
+
+- **输入**：接收来自`knxUltimate-in`节点的KNX消息
+- **输出1**：发送到`knxUltimate-out`节点的KNX命令
+- **输出2**：调试信息（连接Debug节点查看同步过程）
+
+#### knxUltimate节点配置（关键）
+
+**输入节点(knxUltimate-in)**：
+| 配置项 | 值 | 说明 |
+|-------|-----|------|
+| Listen to all GA | 勾选 | 必须，否则收不到消息 |
+| Telegram type | 写入 | 接收写入命令 |
+| Notify on write | 勾选 | 接收写入事件 |
+| Notify on response | 勾选 | 接收响应事件 |
+| RBE过滤 | 禁用 | 确保所有消息通过 |
+
+**输出节点(knxUltimate-out)**：
+| 配置项 | 值 | 说明 |
+|-------|-----|------|
+| Listen to all GA | 勾选 | **必须**，Universal Mode |
+| topic | 留空 | 桥接节点动态设置 |
+| 数据类型 | 0 (自动) | 桥接节点动态设置 |
+| Output type | Write | 写入模式 |
+| RBE过滤 | 禁用 | 确保每次都发送 |
+
+> 示例配置见`examples/knx-sync-example.json`
+
+#### 注意事项
+
+1. **20秒初始化延迟**：部署后前20秒不同步，等待Mesh设备发现完成
+2. **首次状态缓存**：启动后第一次状态仅缓存，第二次操作才会同步
+3. **防死循环**：KNX控制后1秒内，Mesh状态变化不会反向同步
+
+#### 故障排查
+
+**Mesh->KNX不工作**：
+1. 检查日志是否有`[Mesh->KNX]`输出
+2. 确认映射中的MAC地址与设备列表中的MAC一致
+3. 等待20秒初始化完成
+4. 手动操作Mesh设备，观察日志
 
-1. **组地址配置**：根据您的KNX系统修改组地址
-2. **DPT类型**：确保DPT类型与KNX设备匹配
-3. **MAC地址**：使用小写无冒号格式（如：`1427c920dacc`）
-4. **双向同步**：避免循环控制，使用`outputRBE: true`防抖
-5. **测试验证**：先测试单向同步，确认正常后再启用双向
+**KNX->Mesh不工作**：
+1. 检查knxUltimate-in节点是否收到KNX消息
+2. 确认KNX组地址与映射中的命令地址一致
+3. 查看日志是否有`[KNX输入]`输出
+4. 如果显示`未找到映射`，检查配置的组地址
 
 ## RS485/Modbus双向同步
 
@@ -905,275 +843,17 @@ A: 每个房间部署一个云端同步节点，配置对应的酒店ID和房间
 3. 确认场景ID是否正确
 4. 检查网关连接是否正常
 
-## 故障排除
+## 节点概览
 
-### 网关连接失败
-
-**症状**: 日志显示连接错误
-
-**解决方法**:
-1. 检查网关IP和端口（默认4196）
-2. 确认网关电源和网络正常
-3. 尝试ping网关IP
-4. 检查防火墙设置
-
-### 设备不显示
-
-**症状**: MQTT连接正常但HA中无设备
-
-**解决方法**:
-1. 确认HA的MQTT集成已启用
-2. 检查Discovery前缀是否正确（默认homeassistant）
-3. 查看MQTT日志：`symi_mesh/#`
-4. 重启Node-RED重新发布Discovery
-
-### 状态不同步
-
-**症状**: 控制正常但状态不更新
-
-**解决方法**:
-1. 检查日志中是否有`[状态事件]`
-2. 确认0x80事件正常接收
-3. 验证设备MAC地址和网络地址映射
-4. 重启网关和Node-RED
-
-### 控制无响应
-
-**症状**: HA发送命令但设备不动作
-
-**解决方法**:
-1. 检查MQTT命令是否发送（查看Node-RED日志）
-2. 确认网络地址正确
-3. 查看是否有`[控制响应] 0xB0`
-4. 尝试手动发送控制命令测试
-
-### 常见日志说明
-
-```
-[INFO] Gateway connected - 网关连接成功
-[INFO] Device discovery complete - 设备发现完成
-[INFO] [TCP Frame] 接收: 53 80 ... - 状态事件接收
-[INFO] [状态事件] 地址=0x... - 设备状态解析成功
-[INFO] MQTT已连接 - MQTT连接成功
-[INFO] 发布设备 XXX - 设备发布到MQTT
-[WARN] 未找到topic订阅 - MQTT订阅问题
-[ERROR] Connection refused - 连接被拒绝
-```
-
-## 节点说明
-
-### Symi Gateway（网关配置节点）
-
-配置节点，管理与Symi蓝牙Mesh网关的连接。
-
-**配置项**：
-- MQTT配置：选择MQTT配置节点（用于Home Assistant Discovery）
-- 连接类型：TCP或串口
-- TCP模式：IP地址和端口（默认4196）
-- 串口模式：串口路径和波特率（默认115200）
-
-**功能**：
-- 自动设备发现
-- 状态事件处理
-- 自动重连机制
-
-### Symi MQTT（MQTT桥接节点）
-
-将Symi设备桥接到MQTT broker，实现Home Assistant Discovery。
-
-**配置项**：
-- MQTT Broker地址
-- 用户名/密码（可选）
-- Discovery前缀（默认homeassistant）
-
-**功能**：
-- 自动发布Discovery配置
-- 双向MQTT消息处理
-- 设备状态同步
-
-### Symi Device（设备控制节点）
-
-用于Flow中直接控制和监听Symi设备状态。
-
-**配置项**：
-- 设备MAC地址
-- 通道选择（多路开关）
-- 子实体（三合一设备）
-
-**功能**：
-- 接收设备状态变化
-- 发送控制命令
-- 支持KNX双向同步
-
-### Symi Cloud Sync（云端同步节点）
-
-从酒店云云平台同步设备名称和场景信息到本地。
-
-**配置项**：
-- 网关：选择已配置的网关节点（自动使用网关中配置的MQTT）
-- App ID / App Secret：云端API认证信息（已预填）
-- 酒店ID / 房间号：指定要同步的房间（支持下拉选择或手动输入）
-- 设备列表：显示云端设备列表（含按键名称），支持一键全选
-- 场景列表：显示云端场景列表，支持一键全选
-- 自动同步：启动时自动从云端获取数据
-
-**功能**：
-- 启动时自动从云端获取设备名称和场景列表
-- 根据MAC地址精确匹配本地设备并更新名称（云端MAC地址自动反转匹配）
-- 支持开关设备的按键名称同步（1-6键的sub_device名称）
-- 云端"未命名"设备自动保留设备类型标准名称（如"智能窗帘"、"零火开关"等）
-- 酒店和房间选择自动持久化保存，重新打开配置无需重新选择
-- 自动重新发布MQTT Discovery配置（使用云端名称）
-- HA实体名称为纯名称，不带MAC地址和ID
-- 将选中的场景发布为Home Assistant按钮实体
-- 在HA中点击场景按钮即可触发本地场景执行（使用0x31协议）
-- 场景触发通过事件机制路由，确保可靠执行
-- 数据持久化存储，获取失败时使用缓存
-- 支持手动触发同步（发送 `msg.payload = "sync"`）
-- 支持场景调用（发送 `msg.payload = { scene_id: 4 }`）
-
-**使用场景**：
-- 酒店项目：自动同步房间设备的本地化名称
-- 场景管理：将云端场景发布到Home Assistant进行控制
-- 批量部署：统一管理多个房间的设备名称和场景
-
-**注意事项**：
-- 仅在启动/部署时获取一次，不会持续轮询
-- 云端MAC地址自动反转匹配本地设备（云端存储为反序）
-- 云端"未命名"设备自动保留设备类型标准名称
-- 酒店和房间选择自动持久化保存，重新打开配置无需重新选择
-- 勾选的设备和场景才会同步，未勾选则同步全部（支持一键全选）
-- 场景按钮发布到HA后，点击即可触发本地场景执行（0x34协议）
-- 场景执行是本地化控制，不经过云端
-- 场景执行后，所有相关设备状态自动同步到HA（队列处理，确保可靠）
-- 按键名称会同步到MQTT实体名称，MAC地址仍作为唯一ID
-- 获取失败时自动使用上次缓存的数据
-- 可以禁用节点，不影响其他功能正常运行
-
-## RS485网桥节点
-
-### 功能概述
-
-RS485网桥节点实现Mesh网关与第三方RS485设备的**双向同步**：
-
-- **事件驱动**：状态变化时立即同步，无轮询
-- **多协议支持**：标准Modbus RTU、杜亚窗帘、自定义十六进制码
-- **按键对按键**：Mesh开关的每一路可独立映射到RS485的任意按键
-- **防循环保护**：智能防抖机制，避免无限循环
-- **内存安全**：命令队列限制100条，缓存自动清理
-
-### 配置说明
-
-#### 1. 添加RS485配置节点
-
-首先配置RS485连接（串口或TCP）：
-
-- **连接方式**: 串口 或 TCP
-- **串口模式**: 选择串口路径，波特率默认9600
-- **TCP模式**: 输入IP地址和端口
-
-#### 2. 添加RS485桥接节点
-
-配置实体映射：
-
-| 配置项 | 说明 |
-|-------|------|
-| **Mesh实体** | 选择要同步的Mesh设备 |
-| **Mesh按键** | 选择具体哪一路（多路开关） |
-| **品牌** | 选择协议品牌（话语前湾、杜亚、自定义等） |
-| **设备类型** | 选择设备类型（决定寄存器配置） |
-| **RS485按键** | 选择RS485端的哪一路 |
-| **从机地址** | Modbus从机地址（0-255，空调填0） |
-
-### 话语前湾协议配置
-
-话语前湾项目使用以下协议：
-
-#### 开关设备 (A4B3)
-
-| 设备 | 从机地址 | 配置方式 |
-|-----|---------|---------|
-| 客厅主灯 | 3 | 选择"话语前湾" → "一键开关"，地址填3 |
-| 餐厅主灯 | 3 | 选择"话语前湾" → "三键开关"，按键3，地址填3 |
-| 玄关灯带 | 1 | 选择"话语前湾" → "四键开关"，按键4，地址填1 |
-
-**寄存器映射**：
-- 按键1: 0x1031
-- 按键2: 0x1032
-- 按键3: 0x1033
-- 按键4: 0x1034
-- 按键5: 0x1035
-- 按键6: 0x1036
-
-#### 空调设备 (A5B5)
-
-**所有空调从机地址都是0**，通过设备类型区分房间：
-
-| 房间 | 设备类型 | 寄存器范围 |
-|-----|---------|-----------|
-| 客厅空调 | ac_living | 0x0FA0-0x0FA3 |
-| 次卧1空调 | ac_bedroom2_1 | 0x0FA4-0x0FA7 |
-| 次卧2空调 | ac_bedroom2_2 | 0x0FA8-0x0FAB |
-| 主卧空调 | ac_master | 0x0FAC-0x0FAF |
-
-**配置示例**：选择"话语前湾" → "主卧空调"，地址填**0**
-
-#### 地暖设备 (A3B3)
-
-| 房间 | 从机地址 | 说明 |
-|-----|---------|------|
-| 客餐厅 | 60 (0x3C) | 开关:0x0039, 温度:0x0043 |
-| 主卧 | 61 (0x3D) | 开关:0x0039, 温度:0x0043 |
-| 次卧1 | 62 (0x3E) | 开关:0x0039, 温度:0x0043 |
-| 次卧2 | 63 (0x3F) | 开关:0x0039, 温度:0x0043 |
-
-**配置示例**：选择"话语前湾" → "地暖"，地址填60/61/62/63
-
-#### 新风设备 (A3B3)
-
-| 参数 | 从机地址 | 说明 |
-|-----|---------|------|
-| 新风 | 60 (0x3C) | 开关:0x0039(值01), 风速:0x004B |
-
-**配置示例**：选择"话语前湾" → "新风"，地址填60
-
-#### 杜亚窗帘 (A6B6)
-
-| 窗帘 | 地址高 | 地址低 |
-|-----|-------|-------|
-| 主卧窗帘 | 2 | 2 |
-| 主卧窗纱 | 1 | 1 |
-
-**配置示例**：选择"杜亚窗帘" → "窗帘"，地址高填2，地址低填2
-
-### 双向同步流程
-
-```
-Mesh面板按键 → 网关 → device-state-changed事件
-                            ↓
-                    RS485桥接节点检测状态变化
-                            ↓
-                    匹配映射配置 + 检查isUserControl
-                            ↓
-                    生成RS485帧 → 发送到485总线
-                            ↓
-                    485设备执行动作
-
-485面板/遥控器 → 485总线 → RS485桥接节点接收帧
-                            ↓
-                    解析帧 + 匹配映射配置
-                            ↓
-                    调用gateway.sendControl()
-                            ↓
-                    Mesh设备执行动作 → HA状态更新
-```
-
-### 注意事项
-
-1. **HA只对接Mesh设备**：485设备不会发布到HA，避免重复实体
-2. **窗帘防抖**：窗帘操作有1-2秒防抖，防止电机反馈误触发
-3. **初始化延迟**：启动后20秒才开始同步，等待Mesh设备发现完成
-4. **场景执行**：场景触发时多设备状态会排队同步，每命令间隔50ms
+| 节点 | 用途 | 详见章节 |
+|-----|------|---------|
+| **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双向同步) |
+| **RS485 Debug** | RS485总线数据抓包调试 | [RS485调试节点](#rs485调试节点) |
 
 ## 开发者信息
 
@@ -1190,9 +870,16 @@ node-red-contrib-symi-mesh/
 ├── nodes/
 │   ├── symi-gateway.js/html  # 网关配置节点
 │   ├── symi-mqtt.js/html     # MQTT节点
-│   └── symi-device.js/html   # 设备控制节点
+│   ├── 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桥接节点
+│   └── rs485-debug.js/html   # RS485调试节点
 ├── examples/
-│   └── knx-sync-example.json # KNX双向同步示例
+│   ├── basic-example.json    # 基础示例
+│   ├── knx-sync-example.json # KNX Function节点示例
+│   └── knx-bridge-example.json # KNX桥接节点示例
 ├── LICENSE
 ├── README.md
 └── package.json
@@ -1218,6 +905,35 @@ node-red-contrib-symi-mesh/
 - 测试所有更改
 - 更新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标记
+- 代码无重复，模块化设计
+
 ## 技术支持
 
 如遇问题，请提供以下信息：
@@ -1242,8 +958,96 @@ node-red-contrib-symi-mesh/
    - MQTT日志（如相关）
    - 网关串口日志（如可用）
 
+## 常见问题排查
+
+### 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. 确认网关IP地址和端口（默认4196）
+2. 使用`ping`测试网络连通性
+3. 检查网关是否开启TCP服务模式
+4. 查看Node-RED日志中的详细错误信息
+
+### 设备状态不同步
+
+**问题**：HA中设备状态与实际不一致
+
+**排查步骤**：
+
+1. 检查网关节点是否显示"已连接"
+2. 检查MQTT节点是否显示"已连接"
+3. 在Node-RED调试面板查看是否收到设备状态事件
+4. 确认MQTT Broker中的topic消息是否正确
+
 ## 更新日志
 
+### v1.6.7 (2025-12-10)
+- **KNX双向同步完善**：`symi-knx-bridge`节点全面升级
+  - **knxUltimate消息格式**：符合官方规范，使用`destination`+`payload`+`dpt`+`event`
+  - **Universal Mode支持**：输出节点需启用"Listen to all GA"，动态设置组地址
+  - **消息事件**：添加`event: "GroupValue_Write"`，确保写入操作正确执行
+  - **payload类型修复**：DPT 1.001使用boolean类型(true/false)，不是number
+  - **地址映射修复**：根据设备类型正确映射扩展地址到具体功能
+  - **KNX输入匹配增强**：支持所有配置地址的匹配，通过地址函数确定功能类型
+  - **DPT格式兼容**：支持"DPT1.001"和"1.001"两种格式
+  - **新增处理器**：色温(light_color_temp)、空调风速(climate_fan)
+  - **防死循环**：1秒防抖机制，智能防止状态回环
+  - **命令队列**：最大100条，100ms防抖，50ms间隔
+  - **内存安全**：节点关闭时清理所有缓存和事件监听器
+- **KNX桥接节点功能**：
+  - KNX实体库：支持从模板导入KNX组地址
+  - 一行映射：紧凑表格显示，适合大量设备配置
+  - 多设备类型：开关、调光灯、窗帘、空调、新风、地暖
+  - 智能通道选择：根据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协议完整解析：空调(开关/模式/风速/温度)、地暖(开关/温度)、新风(开关/风速)
@@ -1300,8 +1104,8 @@ Copyright (c) 2025 SYMI 亖米
 ## 关于
 
 **作者**: SYMI 亖米
-**版本**: 1.6.6
+**版本**: 1.6.8
 **协议**: 蓝牙MESH网关（初级版）串口协议V1.0
-**最后更新**: 2025-12-09
+**最后更新**: 2025-12-15
 **仓库**: https://github.com/symi-daguo/node-red-contrib-symi-mesh
 **npm包**: https://www.npmjs.com/package/node-red-contrib-symi-mesh