node-red-contrib-symi-mesh 1.7.5

Node-RED节点集合，用于通过TCP/串口连接Symi蓝牙Mesh网关，支持Home Assistant MQTT Discovery自动发现和云端数据同步

npm install node-red-contrib-symi-mesh

node-red-contrib-symi-mesh

一个为Node-RED设计的Symi蓝牙Mesh网关集成包，提供完整的设备控制和Home Assistant MQTT Discovery自动发现功能。

功能特性

• 完整协议支持：TCP/串口双模式，严格遵循蓝牙MESH网关串口协议V1.0
• 自动设备发现：连接后自动发现所有设备，无需手动配置
• MQTT Discovery：自动发布HA Discovery配置，设备即插即用
• 双向状态同步：支持0x80状态事件，实时反馈设备状态变化
• 多设备类型：支持开关、灯光、窗帘、温控器、传感器等12+种设备
• 三合一面板：完整支持空调+新风+地暖三合一控制面板，自动识别
• RS485/Modbus集成：支持第三方485设备双向同步，内置协议模板
• KNX集成：支持与KNX系统双向同步
• KNX-HA集成：支持KNX与Home Assistant实体直接双向同步
• 云端同步：从酒店云云平台自动获取设备名称和场景信息
• 稳定可靠：完善的错误处理和自动重连机制

快速开始

1. 安装

方式一：通过npm安装（推荐）

cd ~/.node-red
npm install node-red-contrib-symi-mesh

方式二：通过Node-RED界面安装

1. 打开Node-RED界面
2. 点击右上角菜单 → 节点管理
3. 搜索 node-red-contrib-symi-mesh
4. 点击安装

方式三：本地开发安装

cd ~/.node-red
npm install /path/to/node-red-contrib-symi-mesh

安装后重启Node-RED：

node-red-restart

2. 配置网关节点

添加"Symi Gateway"配置节点：

网关连接配置:

• 连接方式: TCP/IP 或 串口
• TCP模式（推荐）:
  • 主机地址: 网关IP（如 192.168.2.110）
  • 端口: 4196（默认）
• 串口模式:
  • 串口路径: /dev/ttyUSB0
  • 波特率: 115200

MQTT配置（用于Home Assistant集成）:

• MQTT地址: mqtt://localhost:1883（默认，可修改）
• 用户名: MQTT认证用户名（可选）
• 密码: MQTT认证密码（可选）
• HA前缀: homeassistant（默认，可修改）

提示: MQTT配置已集成到网关节点中，所有使用该网关的MQTT节点会自动使用这些配置。

3. 添加MQTT桥接节点

添加"Symi MQTT"节点到流程中：

• 网关: 选择已配置的网关节点
• 名称: 可选，用于标识节点

注意: MQTT连接参数从网关节点获取，无需重复配置。

4. 部署并验证

1. 点击右上角"部署"按钮
2. 检查调试面板确认连接状态：
   • Gateway connected - 网关连接成功
   • Device discovery complete - 设备发现完成
   • MQTT已连接 - MQTT连接成功
   • 发布设备 XXX - 设备发布到MQTT
3. 在Home Assistant中查看自动发现的设备
4. 测试设备控制和状态反馈

5. 多网关配置（可选）

对于大户型或多区域部署，可以配置多个网关节点：

1. 添加第二个网关节点：

   • 拖入新的"Symi Gateway"节点
   • 配置不同的IP地址或串口
   • 给网关起不同的名称（如"网关-客厅"、"网关-卧室"）

2. 添加对应的MQTT节点：

   • 为每个网关添加独立的"Symi MQTT"节点
   • 在配置中选择对应的网关
   • 使用相同的MQTT broker配置

3. 设备隔离：

   • 每个网关的设备独立存储，互不干扰
   • 每个网关的设备在HA中独立显示
   • 可以为不同网关配置不同的MQTT主题前缀

示例配置：

网关1（客厅）: 192.168.2.110:4196 → MQTT主题: symi_mesh/living_room/
网关2（卧室）: 192.168.2.111:4196 → MQTT主题: symi_mesh/bedroom/

支持的设备类型

设备类型	类型码	HA实体	功能说明
零火开关	0x01	switch	1-6路独立控制，状态反馈
单火开关	0x02	switch	1-6路独立控制，状态反馈
智能插座	0x03	switch	单路开关控制
双色调光灯	0x04	light	亮度+色温调节
智能窗帘	0x05	cover	开关+位置控制（0-100%）
门磁传感器	0x07	binary_sensor	门窗开关状态
人体感应	0x08	binary_sensor	人体活动检测
插卡取电	0x09	switch + binary_sensor	插卡检测+开关控制
温控器/三合一	0x0A	climate	温度/模式/风速控制，当前温度采集
温湿度传感器	0x0B	sensor	温湿度监测
五色调光灯	0x18	light	RGB+亮度+色温调节
四输入八输出	0x27 (39)	switch	8路独立控制，支持场景绑定

三合一设备说明

三合一设备集成了空调、新风和地暖控制，在Home Assistant中自动创建3个独立实体：

实体说明

1. 空调（climate实体）

• 温度调节：16-30°C
• 工作模式：制冷/制热/送风/除湿/关闭
• 风速控制：高/中/低/自动

2. 新风（fan实体）

• 开关控制：ON/OFF
• 风速档位：高/中/低/自动
• 送风/排风：支持送风和排风方向控制

3. 地暖（climate实体）

• 温度调节：18-32°C
• 工作模式：制热/关闭

使用方式

自动识别机制：

• 空调温控器和三合一面板属于同一设备品类（deviceType=10）
• 系统通过主动查询新风(0x68)和地暖(0x6B)状态来区分
• 有响应的识别为三合一面板，无响应的识别为普通温控器
• 无需手动配置，部署后自动完成识别

识别日志示例：

[三合一检测] 发现温控器类型设备: 温控器_xxx，将通过查询新风/地暖确认类型
[三合一检测] 开始检测设备 xxx (0xABCD)
[三合一检测] 收到 xxx 的新风响应 (0x68)，确认为三合一面板
[三合一检测] 确认为三合一面板（收到新风/地暖响应）

控制方式：

• HA中直接控制：设置温度/模式自动开启设备
• 面板物理操作：状态自动同步到HA
• MQTT直接控制：支持完整的MQTT命令

KNX同步： 在Symi Device节点中选择三合一设备，通过"子实体"下拉选项选择与KNX同步的功能：

• 空调 ↔ KNX空调控制器
• 新风 ↔ KNX新风控制器
• 地暖 ↔ KNX地暖控制器

每个功能独立同步，互不干扰。

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. 安装依赖节点

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中任意实体同步
• 配置灵活，易于调整

协议说明

核心协议格式

[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桥接节点（推荐）

v1.6.7新增：使用symi-knx-bridge节点实现一站式配置，支持KNX实体导入和批量映射。

功能特点

• KNX实体库：导入KNX组地址，快速选择实体
• 一行映射：紧凑表格，适合大量设备映射
• 多设备类型：开关、调光灯、窗帘、空调、新风、地暖
• 双向同步：自动处理Mesh↔KNX状态同步
• 防死循环：内置1.5秒防抖机制

配置步骤

1. 安装KNX节点

cd ~/.node-red
npm install node-red-contrib-knx-ultimate

2. 添加KNX桥接节点 从"Symi Mesh"分类中拖入"KNX桥接"节点

3. 导入KNX实体

• 点击"下载模板"获取导入格式
• 填写KNX组地址后点击"导入"

4. 添加映射

• 点击"添加"按钮
• 选择Mesh设备和KNX实体
• 开关设备可选择通道

5. 连接KNX节点

[knxUltimate-in] → [symi-knx-bridge] → [knxUltimate-out]

KNX实体导入格式

Tab分隔，每行一个实体：

名称	类型	命令地址	状态地址	扩展1	扩展2	扩展3

支持的类型和地址字段：

类型	字段	说明
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. 10秒初始化延迟：部署后前10秒不同步，等待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双向同步

本节点支持与第三方RS485/Modbus设备进行双向状态同步，适用于对接各品牌空调、新风、地暖等设备。

功能特点

• 双模式连接：支持串口(RS485)和TCP/IP两种连接方式
• 协议模板：内置常用协议模板，支持自定义寄存器映射
• 双向同步：Mesh设备和485设备状态实时同步
• 多设备支持：单个485连接可管理多达105个设备

配置步骤

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   ✓ 支持

4. 部署

点击"部署"按钮，所有映射自动开始双向同步

RS485调试节点

新增 RS485调试 节点用于抓取并显示原始485字节流：

功能：

• 实时显示RS485总线所有通信数据（TX发送/RX接收）
• 自动解析Modbus RTU帧结构（从机地址、功能码）
• 支持手动发送测试帧（输入十六进制字符串）
• 十六进制/ASCII显示模式
• 调试窗口高度自适应

输出示例：

[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 写单寄存器

实体映射规则

Mesh实体类型	RS485实体类型	同步内容
开关-按键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），请分别创建映射。

内置协议支持

品牌	支持设备
话语前湾	空调（客厅/主卧/次卧1/次卧2）、地暖、新风、窗帘、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节点发送查询命令：

{
  "payload": {
    "action": "query"
  }
}

这将向A侧所有中弘VRF设备发送状态查询命令。

故障排查

A→B不工作：

1. 检查日志是否有[A侧收到]输出
2. 确认A侧协议参数（从机/外机/内机地址）正确
3. 检查RS485连接A是否已连接

B→A不工作：

1. 检查日志是否有[B侧收到]输出
2. 确认B侧协议参数正确
3. 检查RS485连接B是否已连接

状态不同步：

1. 检查节点状态是否显示"同步中"
2. 确认两个RS485连接都已连接（绿色状态）
3. 查看日志中的同步消息

云端数据同步

本节点支持从酒店云云平台自动获取设备名称和场景信息，实现本地化配置的自动同步。

使用场景

• 酒店项目：自动同步房间设备的本地化名称（如"客厅窗帘"、"床头灯"等）
• 场景管理：获取云端配置的场景列表（如"全关"、"睡眠模式"等）并本地化调用
• 批量部署：统一管理多个房间的设备名称，无需手动配置

配置步骤

1. 添加云端同步节点

在Node-RED中添加"Symi Cloud Sync"节点：

基础配置：

• 网关：选择已配置的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中查看设备名称是否已更新

3. 手动触发同步

如需手动触发同步，可以使用inject节点：

[inject] --> [cloud-sync]
payload: "sync"

4. 调用场景

云端同步后，可以通过inject节点调用场景：

[inject] --> [cloud-sync]
payload: { scene_id: 4 }  // 执行场景ID为4的场景（如"全关"）

按键场景自动触发

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

配置示例

云端配置（酒店云云平台）：

{
  "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
    }
  ]
}

日志示例

启动时显示场景绑定：

[场景绑定] 床头三键: 按键1(明亮)→场景4, 按键2(温馨)→场景6, 按键3(睡眠)→场景5
[场景绑定] 入户二键: 按键1(廊灯)→开:场景22/关:场景21, 按键2(卫浴灯)→开:场景24/关:场景23

按键按下时触发场景：

[按键场景] 检测到按键1(明亮)状态变化: 关 → 开, 触发场景4
[按键场景] ✓ 场景4(明亮)控制命令已发送
[场景控制] 场景控制命令已被网关接受
[场景执行] 收到场景执行通知事件: 场景ID=4

注意事项

1. 云端配置必需：需要先配置云端同步节点并成功获取设备配置
2. 完全本地化：场景触发完全在本地进行，不依赖云端
3. 避免循环：场景执行期间不会再次触发按键场景，防止循环
4. 状态同步：场景执行后的设备状态变化会自动同步到HA

工作原理

数据获取流程

启动/部署
  ↓
调用云端API（房间信息接口）
  ↓
解析设备列表和场景列表
  ↓
根据MAC地址匹配本地设备
  ↓
更新设备名称（device.name）
  ↓
保存场景列表到本地
  ↓
重新发布MQTT Discovery配置
  ↓
持久化存储（缓存）
  ↓
完成（不再调用）

MAC地址匹配规则

云端返回的设备MAC地址会自动反转后与本地设备MAC地址匹配：

// 云端设备（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（使用新名称）

场景本地化调用

云端场景信息会保存到本地，可以通过网关直接调用：

// 云端场景
{
  "scene_name": "全关",
  "scene_id": 4
}

// 本地调用
通过inject节点发送: { scene_id: 4 }
节点会查找场景名称并输出到下游节点
可以连接到其他节点进行进一步处理

数据持久化

云端同步节点会将获取的数据持久化存储到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. 查看调试日志中的详细错误信息

症状: 设备名称未更新

解决方法:

1. 检查云端设备MAC地址是否与本地设备一致
2. 查看调试日志中的"设备匹配完成"信息
3. 确认MQTT节点已正确配置
4. 手动触发同步（发送 msg.payload = "sync"）

症状: 场景无法调用

解决方法:

1. 检查云端是否返回了场景列表
2. 查看调试日志中的"场景列表已保存"信息
3. 确认场景ID是否正确
4. 检查网关连接是否正常

节点概览

节点	用途	详见章节
Symi Gateway	网关连接（TCP/串口）	快速开始
Symi MQTT	MQTT桥接，设备发布到HA	快速开始
Symi Device	Flow中单设备控制/监听	可用于KNX/自定义同步
Symi Cloud Sync	云端同步设备名称和场景	云端数据同步
Symi RS485 Bridge	RS485设备双向同步	RS485/Modbus双向同步
Symi KNX Bridge	KNX系统双向同步	KNX双向同步
Symi KNX-HA Bridge	KNX与HA实体双向同步	KNX-HA双向同步
Symi MQTT Sync	第三方MQTT品牌设备同步	v1.7.3新增
Symi MQTT Brand	品牌MQTT配置节点	v1.7.3新增
RS485 Debug	RS485总线数据抓包调试	RS485调试节点
Symi RS485 Sync	两种RS485协议双向同步	RS485协议同步

开发者信息

项目结构

node-red-contrib-symi-mesh/
├── lib/
│   ├── device-manager.js     # 设备管理和状态缓存
│   ├── mqtt-helper.js        # MQTT Discovery配置生成
│   ├── protocol.js           # 协议构建和解析
│   ├── tcp-client.js         # TCP连接客户端
│   └── serial-client.js      # 串口连接客户端
├── nodes/
│   ├── symi-gateway.js/html  # 网关配置节点
│   ├── symi-mqtt.js/html     # MQTT节点
│   ├── 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-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协议同步示例
├── 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标记
• 代码无重复，模块化设计

技术支持

如遇问题，请提供以下信息：

1. 环境信息:

   • Node-RED版本
   • Node.js版本
   • 操作系统

2. 网关信息:

   • 网关型号
   • 固件版本
   • 连接方式（TCP/串口）

3. 问题描述:

   • 完整错误日志
   • 设备类型和数量
   • 复现步骤

4. 调试日志:

   • Node-RED调试日志
   • MQTT日志（如相关）
   • 网关串口日志（如可用）

常见问题排查

MQTT连接失败

问题：节点状态显示"Broker不可用"或"连接失败"

排查步骤：

1. 检查MQTT Broker地址配置

   # Docker部署时使用容器名
   mqttBroker: mqtt://mosquitto:1883
   
   # 本地安装时使用localhost
   mqttBroker: mqtt://localhost:1883
   

2. 确认MQTT Broker运行状态

   # 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.7.5 (2025-12-24)

• API路径兼容性修复：修复HassOS环境下节点配置界面无法加载设备列表的问题
  • 根本原因：HassOS Node-RED使用nginx反向代理，绝对路径/api会被拦截，需使用相对路径api
  • 修复范围：所有节点HTML中的$.getJSON()调用统一使用相对路径
  • 开发规范：后续开发节点时，所有前端API调用必须使用相对路径，不带前导斜杠
• KNX Bridge双向同步修复：修复Mesh控制KNX开关不工作的问题
  • 根本原因：knxUltimate节点当setTopicType: "str"时使用msg.topic作为目标地址，而非msg.destination
  • 修复方案：发送消息同时包含topic和destination字段，确保兼容所有knxUltimate配置
  • 消息格式：{ topic, destination, payload, dpt, event }
  • 防死循环：不包含knx对象，避免触发knxUltimate的循环引用保护机制
• 用户体验优化：
  • 设备列表加载时显示"加载中..."提示
  • API调用失败时显示"加载失败，请重试"提示

v1.7.4 (2025-12-24)

• 串口配置完善：完整的串口参数配置，解决HassOS环境串口锁定问题
  • 完整参数：波特率、数据位(7/8)、停止位(1/2)、校验位(None/Even/Odd)
  • 串口解锁：添加lock: false参数，避免HassOS环境下"Cannot lock port"错误
  • 配置持久化：所有串口参数自动保存，重启后保持
  • 统一界面：symi-gateway和symi-485-config使用相同的串口配置界面
• 串口兼容性修复：兼容serialport v9和v10+，确保HassOS环境正常使用串口
  • serial-client.js：动态检测serialport版本
  • symi-485-config.js：兼容v9/v10+ API
  • symi-485-bridge.js：兼容v9/v10+ API
• KNX Bridge窗帘/调光同步优化：重新设计步进设备同步逻辑，解决双向控制时乱动问题
  • 控制锁定机制：谁先发起控制谁锁定，3秒内忽略另一方的反馈
  • 窗帘设备：Mesh控制→锁定→忽略KNX反馈；KNX控制→锁定→忽略Mesh反馈
  • 调光设备：同样应用控制锁定机制，避免亮度调节过程中的反馈干扰
  • 停止解锁：窗帘stopped动作会解除锁定，允许下一次控制
  • 位置/亮度同步：只同步最终值，不同步过程中的步进状态

v1.7.3 (2025-12-24)

• MQTT同步节点：新增symi-mqtt-sync节点实现第三方MQTT品牌设备与Mesh设备双向同步
  • 双MQTT配置节点架构：
    • Mesh MQTT：选择symi-mqtt配置节点，获取Mesh设备列表
    • 品牌MQTT：选择symi-mqtt-brand配置节点（支持下拉选择+编辑+添加）
  • 品牌MQTT配置节点：新增symi-mqtt-brand配置节点
    • 支持配置MQTT服务器地址、用户名、密码
    • 支持HYQW协议（项目代码、设备SN）
    • 自动发现品牌MQTT设备实体
    • 可扩展支持更多品牌协议
  • 实体映射：
    • 左边选择Mesh设备+通道
    • 右边选择品牌设备+通道（灯具支持多路）
    • 相同类型实体一对一映射
  • 设备类型：灯具(8)、空调(12)、窗帘(14)、地暖(16)、新风(36)
  • 双向同步：MQTT↔Mesh实时状态同步，2秒防抖防死循环
  • 输入输出端口：支持连接debug节点调试同步数据
  • 错误日志限流：网络故障时每60秒最多记录一次错误
  • 断线自动重连：5秒重连间隔
• 串口支持优化：
  • 所有串口节点支持手动输入+搜索选择
  • 兼容serialport v9/v10+，兼容HassOS环境
  • 串口错误日志限流，避免长时间故障时日志爆炸
• 稳定性优化：
  • 错误日志频率限制，长时间网络故障不影响系统性能
  • 静默处理非关键错误，生产级稳定性
  • 内存安全，无调试日志，断电断网恢复后正常工作
  • 缓存队列处理，符合MQTT协议要求

v1.7.2 (2025-12-22)

• RS485双向同步节点：新增symi-rs485-sync独立节点实现两种不同RS485协议之间的双向同步
  • 支持中弘VRF网关协议（功能码0x31-0x34控制，0x50查询）
  • 支持SYMI空调面板Modbus协议
  • 支持自定义码协议
  • 双向状态同步，2秒防抖防止死循环
  • 多组映射配置，持久化保存
  • 反馈选项：新增"反馈"复选框，控制RS485收码后是否发送反馈码
  • Mesh→RS485方向：
    • 修复开关控制：只同步配置的通道，避免其他通道变化误触发
    • 修复空调风速：fanMode变化正确发送fanSendHigh/Mid/Low/Auto码
    • 修复空调中速(fanMode=2)事件触发
    • 修复空调开关：去重处理，避免switch和acSwitch重复发送
    • 添加自动风速(fanSendAuto/fanRecvAuto)配置支持
  • RS485→Mesh方向：
    • 修复收码匹配触发Mesh实体状态变化
    • 自定义开关recvOn/recvOff正确触发开关动作
    • 自定义空调acRecvOn/acRecvOff/fanRecvHigh等正确触发空调控制
  • 事件系统优化：
    • DeviceManager事件添加完整字段（isUserControl、isSceneExecution等）
    • 用户控制事件允许绕过首次状态缓存
    • 修复单路温控器开关事件丢失问题
    • fanMode事件同时发送acFanSpeed别名字段
  • 防死循环优化：
    • 使用映射特定时间戳，避免不同设备同步互相影响
    • Mesh→RS485和RS485→Mesh双向都记录同步时间
    • 500ms冷却时间防止状态回环
    • 空调命令去重（同类命令只发送一次）
  • 生产稳定性：
    • 初始化延迟从10秒缩短为5秒
    • 详细日志改为debug级别，减少生产环境日志量
    • 保留关键同步日志便于问题排查
  • UI优化：
    • 自定义码折叠按钮移到同一行，减少占用空间
    • 修复MAC地址大小写匹配问题
    • 添加自动风速配置框（发自动/收自动）
• RS485-to-RS485空调桥接：SYMI空调面板与中弘VRF系统双向同步
  • 支持SYMI 485空调面板协议（7E...7D帧格式，CRC8校验）
  • 支持中弘VRF空调协议（求和校验，功能码0x31-0x34控制，0x50查询）
  • 双向状态同步：SYMI面板操作→中弘VRF执行，中弘状态→SYMI面板显示

v1.7.1 (2025-12-21)

• 自定义协议全面修复：完善自定义开关/窗帘/空调双向同步
  • 空调风速控制：修复风速变化事件触发机制
    • 添加fanMode字段支持（mesh空调实际使用的字段）
    • 修复DeviceInfo事件触发，正确发送device-state-changed事件
    • 支持风速值1-4（1=高, 2=中, 3=低, 4=自动）
    • 自动识别温控器0x02消息中的风速控制
  • 空调开关控制：修复开关状态变化事件触发
    • 温控器0x02开关消息正确触发device-state-changed事件
    • 自定义空调开关码（acSendOn/acSendOff）正确发送到RS485总线
  • RS485收码匹配：修复hexStr格式处理
    • hexStr完全去掉空格，确保标准格式（如030610330001BD27）
    • 用户录入支持带空格格式（如01 06 10 34 00 01 0D 04）
    • 自动匹配并触发mesh实体动作
  • 事件系统优化：
    • DeviceInfo添加manager引用，正确触发事件
    • 修复事件名称不匹配问题（stateChange -> device-state-changed）
    • 确保所有自定义码双向同步正常
  • 队列处理：
    • 命令队列顺序处理，防止并发冲突
    • 500ms防死循环机制
    • 队列限制100条，防止内存溢出
  • 调试日志：添加详细调试日志，方便排查问题

v1.7.0 (2025-12-21)

• 自定义协议增强：RS485桥接节点自定义协议功能全面升级
  • 自定义开关：添加发开、发关、收开、收关4组码
  • 翻转模式：收开码=收关码时，收到后自动翻转开关状态
  • 自定义窗帘：添加发开、发关、发停、收开、收关、收停6组码
  • 自定义空调：新增完整收发码支持（开关、风速、模式、温度）
  • 支持最多24字节（72个十六进制字符）数据录入
  • 自定义模式自动隐藏地址字段
  • 配置持久化保存，重启后保持
  • 防死循环机制优化
  • 内存优化，防止日志溢出

许可证

MIT License

Copyright (c) 2025 SYMI 亖米

---

关于

作者: SYMI 亖米 版本: 1.7.5 协议: 蓝牙MESH网关（初级版）串口协议V1.0 最后更新: 2025-12-24 仓库: https://github.com/symi-daguo/node-red-contrib-symi-mesh npm包: https://www.npmjs.com/package/node-red-contrib-symi-mesh