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

package/README.md

@@ -202,7 +202,7 @@ node-red-restart
 
 ### 开关状态编码（重要）
 
-**协议规则**: 每2位表示1路，b01=关，b10=开
+**协议规则**: 每2位表示1路，`01`=关，`10`=开，从最低位开始
 
 | 路数 | 全关 | 全开 | 示例 |
 |-----|------|------|------|
@@ -211,24 +211,57 @@ node-red-restart
 | 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-2字节 | 见上表 |
+| 开关状态 | 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=有卡 |
-| RGB颜色 | 0x11 | 5字节 | R(0-255)/G/B/WW(0-100)/CW |
-| 当前温度 | 0x16 | 2字节LE | 温度*100 |
-| 目标温度 | 0x1B | 2字节LE | 16-30°C, *100 |
+| 湿度 | 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键开关状态 | 0x45 | 2字节LE | 场景执行后状态上报 |
+| 6-8路开关 | 0x45 | 2字节LE | 多路开关状态，见上表 |
+| 五色RGB | 0x4C | 5字节 | R/G/B/WW/CW (各0-255) |
 
 ## MQTT主题结构
 
@@ -272,180 +305,118 @@ symi_mesh/[mac_clean]/[entity]/set
 
 本节点支持与`node-red-contrib-knx-ultimate`完整双向同步，实现Symi Mesh设备与KNX系统的互联互通。
 
-### 配置步骤
+### 方式一：KNX桥接节点（推荐）
 
-#### 1. 安装KNX节点
+**v1.6.7新增**：使用`symi-knx-bridge`节点实现一站式配置，支持KNX实体导入和批量映射。
+
+#### 功能特点
+
+- **KNX实体库**：导入KNX组地址，快速选择实体
+- **一行映射**：紧凑表格，适合大量设备映射
+- **多设备类型**：开关、调光灯、窗帘、空调、新风、地暖
+- **双向同步**：自动处理Mesh↔KNX状态同步
+- **防死循环**：内置1.5秒防抖机制
+
+#### 配置步骤
+
+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过滤 | 禁用 | 确保所有消息通过 |
 
-1. **组地址配置**：根据您的KNX系统修改组地址
-2. **DPT类型**：确保DPT类型与KNX设备匹配
-3. **MAC地址**：使用小写无冒号格式（如：`1427c920dacc`）
-4. **双向同步**：避免循环控制，使用`outputRBE: true`防抖
-5. **测试验证**：先测试单向同步，确认正常后再启用双向
+**输出节点(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设备，观察日志
+
+**KNX->Mesh不工作**：
+1. 检查knxUltimate-in节点是否收到KNX消息
+2. 确认KNX组地址与映射中的命令地址一致
+3. 查看日志是否有`[KNX输入]`输出
+4. 如果显示`未找到映射`，检查配置的组地址
 
 ## RS485/Modbus双向同步
 
@@ -531,10 +502,35 @@ Mesh 四键开关 第2路 ↔ RS485 六键开关 第5路  地址:2   ✓ 支持
 |-------------|--------------|---------|
 | 开关-按键N | 开关 | 开/关状态 |
 | 温控器 | 空调 | 开关、温度、模式、风速 |
+| 三合一面板 | 空调+新风+地暖 | 分别配置，独立同步 |
 | 调光灯 | 调光器 | 开关、亮度 |
 
 **部分同步**：如果RS485协议不提供某些功能点，只同步双方都支持的内容
 
+### 三合一面板配置
+
+三合一面板（温控器类型）可同时控制空调、新风、地暖，需要创建3个独立映射：
+
+#### 配置示例（话语前湾协议）
+
+| Mesh设备 | RS485设备类型 | 从机地址 | 说明 |
+|---------|--------------|---------|------|
+| 三合一面板_xxx | 次卧1空调 | 0 | 空调寄存器0x0FA4-0x0FA7 |
+| 三合一面板_xxx | 新风 | 60 | 开关0x0039，风速0x004B |
+| 三合一面板_xxx | 次卧1地暖 | 62 | 开关0x0039，温度0x0043 |
+
+#### 话语前湾地暖/新风从机地址
+
+| 设备 | 从机地址 | 十六进制 |
+|------|---------|---------|
+| 客餐厅地暖 | 60 | 0x3C |
+| 新风 | 60 | 0x3C |
+| 主卧地暖 | 61 | 0x3D |
+| 次卧1地暖 | 62 | 0x3E |
+| 次卧2地暖 | 63 | 0x3F |
+
+> **注意**：新风和客餐厅地暖共用从机地址60，但开关值不同（新风开=1，地暖开=2），请分别创建映射。
+
 ### 内置协议支持
 
 | 品牌 | 支持设备 |
@@ -847,150 +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
-- 获取失败时自动使用上次缓存的数据
-- 可以禁用节点，不影响其他功能正常运行
+| 节点 | 用途 | 详见章节 |
+|-----|------|---------|
+| **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调试节点) |
 
 ## 开发者信息
 
@@ -1007,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
@@ -1035,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标记
+- 代码无重复，模块化设计
+
 ## 技术支持
 
 如遇问题，请提供以下信息：
@@ -1059,8 +958,112 @@ 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.6 (2025-12-09)
+- **三合一面板完整双向同步**：支持空调+新风+地暖独立RS485映射
+  - 三合一0x94协议完整解析：空调(开关/模式/风速/温度)、地暖(开关/温度)、新风(开关/风速)
+  - Mesh→RS485：三合一状态变化自动发送对应RS485帧
+  - RS485→Mesh：RS485帧自动同步到三合一面板对应功能
+  - 支持climateSwitch/climateMode/fanMode/floorHeatingSwitch/freshAirSwitch等字段
+- **开关双向同步修复**：修复米家App全开/全关只触发部分按键的问题
+  - 命令队列防抖逻辑修复：只有完全相同映射才合并，不同映射独立处理
+  - 支持同一Mesh设备多通道分别绑定不同RS485设备
+- **RS485多映射匹配**：修复同一从机地址多个映射时只匹配第一个的问题
+  - findAllRS485Mappings返回所有匹配的映射
+  - rs485Channel精确匹配：根据寄存器地址确定通道
+- **网络异常处理增强**：彻底修复Node.js 18+ AggregateError导致崩溃的问题
+  - 全局uncaughtException/unhandledRejection处理器
+  - TCP连接过程同步错误捕获
+  - 只捕获网络相关错误，不影响其他异常
+- **三合一面板自动识别**：设备列表API返回isThreeInOne标志
+- **窗帘双协议兼容**：同时支持米家和小程序两种控制协议
+  - 米家协议: `subOpcode=0x06, status: 0=打开中, 1=关闭中, 2=停止`
+  - 小程序协议: `subOpcode=0x05, status: 1=打开, 2=关闭, 3=停止`
+- **话语前湾协议完善**：
+  - 空调：客厅/主卧/次卧1/次卧2，寄存器0x0FA0-0x0FAF
+  - 地暖：客餐厅(60)/主卧(61)/次卧1(62)/次卧2(63)，寄存器0x0039/0x0043
+  - 新风：从机60，开关0x0039(开=1)，风速0x004B(高=2,低=0)
+- **地址输入修复**：允许从机地址为0（话语前湾空调地址是0）
+- **内存安全**：命令队列限制100条，节点关闭时清理所有缓存
+- **文档更新**：添加三合一面板RS485配置说明和协议对照表
+
 ### v1.6.5 (2025-12-06)
 - **杜亚窗帘协议**：原生支持杜亚窗帘协议(A6B6)，2字节地址，自动CRC16计算
   - 帧格式：55 [地址高] [地址低] 03 [动作/位置] [CRC16低] [CRC16高]
@@ -1078,25 +1081,6 @@ node-red-contrib-symi-mesh/
 - **RS485调试增强**：新增协议测试发送功能
 - **初始化延迟**：20秒，避免部署时误发命令
 
-### v1.6.4 (2025-12-05)
-- **代码优化**：移除未使用的 `three-in-one-detected` 事件监听器（死代码清理）
-- **TCP连接优化**：移除可能导致连接问题的keep-alive设置
-- **多从机支持修复**：修复只能配置从机ID1的问题，现在支持任意从机地址(1-255)
-- **映射数值类型修复**：确保address/meshChannel/rs485Channel字段为正确的数字类型
-
-### v1.6.3 (2025-12-05)
-- **自定义协议模式**：支持任意RS485十六进制码双向匹配
-- **按键寄存器优化**：只处理按键寄存器(0x1031-0x1036)，移除指示灯寄存器处理
-- **CRC校验正确**：发送帧与协议文档完全匹配
-
-### v1.6.2 (2025-12-05)
-- **MQTT订阅修复**：修复闭包问题导致的设备MAC映射错误，确保HA实体可控
-- **内存泄漏修复**：节点关闭时正确移除gateway事件监听器，防止内存累积
-- **三合一面板完善**：空调/新风/地暖控制和状态反馈全面优化
-- **RS485双向同步**：支持Mesh与第三方485设备双向状态同步
-- **代码优化**：中文注释规范化，移除冗余代码，提升可维护性
-
-
 ## 许可证
 
 MIT License
@@ -1108,8 +1092,8 @@ Copyright (c) 2025 SYMI 亖米
 ## 关于
 
 **作者**: SYMI 亖米
-**版本**: 1.6.5
+**版本**: 1.6.7
 **协议**: 蓝牙MESH网关（初级版）串口协议V1.0
-**最后更新**: 2025-12-06
+**最后更新**: 2025-12-10
 **仓库**: https://github.com/symi-daguo/node-red-contrib-symi-mesh
 **npm包**: https://www.npmjs.com/package/node-red-contrib-symi-mesh