node-red-contrib-symi-mesh 1.8.18

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设备双向同步，内置协议模板，支持中弘VRF、SYMI面板协议
RS485同步增强：symi-rs485-sync 节点已全面重构，采用统一防环路机制，支持多台空调内机批量状态同步和三合一子实体增强映射
KNX集成：支持与KNX系统双向同步
KNX-HA集成：支持KNX与Home Assistant实体直接双向同步
窗帘同步优化：专门针对无限位Mesh窗帘模组优化，支持控制锁定（40s）和即时状态同步，彻底解决状态死循环和丢包问题
云端同步：从酒店云云平台自动获取设备名称和场景信息
稳定可靠：完善的错误处理和自动重连机制

快速开始

1. 安装

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

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

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

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

方式三：本地开发安装

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. 部署并验证

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

5. 多网关配置（可选）

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

添加第二个网关节点：
- 拖入新的"Symi Gateway"节点
- 配置不同的IP地址或串口
- 给网关起不同的名称（如"网关-客厅"、"网关-卧室"）
添加对应的MQTT节点：
- 为每个网关添加独立的"Symi MQTT"节点
- 在配置中选择对应的网关
- 使用相同的MQTT broker配置
设备隔离：
- 每个网关的设备独立存储，互不干扰
- 每个网关的设备在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地暖控制器

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

HA双向同步

Symi HA同步节点 (symi-ha-sync) 用于实现Symi蓝牙Mesh设备与Home Assistant实体的直接双向同步。

功能特性

配置复用：
- 复用symi-mqtt配置节点获取Symi设备信息
- 复用server配置节点连接Home Assistant
双向同步：
- Symi -> HA：Mesh设备状态变化 -> 更新HA实体状态（自动工作）
- HA -> Symi：HA实体状态变化 -> 控制Mesh设备（需连接HA事件节点）
防死循环：
- 内置2秒冷却机制（窗帘30秒）
- 区分Symi触发和HA触发，避免信号震荡
便捷配置：
- 自动加载所有Symi设备和HA实体
- 支持按键通道选择（1-4键）
- 支持实体ID搜索和下拉选择

⚠️ 双向同步连接方式（重要）

要实现完整的双向同步，必须连接HA事件节点到symi-ha-sync节点的输入端：

方式1：使用 server-events 节点（推荐）

[events: all] → [symi-ha-sync]
  (事件类型: state_changed)

配置步骤：

添加 events: all 节点（Home Assistant 分类下）
事件类型(Event Type)填写: state_changed
将输出连接到 symi-ha-sync 节点的输入端

方式2：使用 server-state-changed 节点

[events: state] → [symi-ha-sync]

配置步骤：

添加 events: state 节点
实体ID可留空（监听所有实体）或指定特定实体
将输出连接到 symi-ha-sync 节点的输入端

状态指示

蓝色 "Mesh→HA (N组)"：仅 Mesh 到 HA 方向工作（未连接 HA 事件节点）
绿色 "双向同步 (N组)"：双向同步正常工作
红色：配置错误

配置步骤

添加节点：从左侧拖入Symi HA Sync节点
选择MQTT配置：选择已有的symi-mqtt配置节点（共享Symi网关连接）
选择HA服务器：选择已有的server配置节点（共享HA连接）
添加映射：
- 点击"添加"按钮
- Symi设备：下拉选择Mesh设备（显示名称和MAC）
- 按键：选择控制通道（按键1-4）
- HA实体：输入或选择要同步的HA实体ID（如switch.living_room_light）
连接HA事件节点：添加events: all或events: state节点，连接到输入端
部署：点击部署，立即生效

注意事项

MQTT配置：必须选择symi-mqtt配置节点，用于获取设备列表和接收Mesh事件
HA连接：必须确保HA服务器节点连接正常
HA事件节点：必须连接HA事件节点才能实现HA→Symi方向同步
实体类型：建议同步相同类型的实体（如开关对开关，调光灯对灯光）
多通道设备：对于多键开关，请分别为每个按键添加一条映射
event实体过滤：系统自动过滤event.开头的实体（如按键点击事件），不会同步

三合一面板配置

三合一面板（空调+新风+地暖）需要分别配置每个子设备的映射：

选择三合一设备：在Symi设备下拉框中选择三合一面板
选择子设备：在按键选择器中选择要同步的功能：
- 空调：同步开关、温度、模式、风速
- 新风：同步开关、风速
- 地暖：同步开关、温度
选择HA实体：
- 空调 → climate实体
- 新风 → fan实体
- 地暖 → climate实体

示例配置：

三合一面板_xxx [空调] ↔ climate.living_room_ac
三合一面板_xxx [新风] ↔ fan.living_room_fresh_air
三合一面板_xxx [地暖] ↔ climate.living_room_floor_heating

窗帘同步说明

窗帘设备采用特殊的同步机制，避免运动过程中的步进反馈干扰：

30秒防死循环窗口：窗帘运动时间较长，使用30秒防死循环（普通设备2秒）
1.5秒防抖：等待窗帘位置稳定后再同步，避免步进码干扰
运动状态跟踪：记录运动发起方（Symi/HA），忽略对方的中间状态反馈
opening/closing过滤：HA窗帘处于运动状态时，不同步位置变化到Mesh

MQTT品牌同步

Symi MQTT同步节点 (symi-mqtt-sync) 用于实现第三方MQTT品牌设备与Symi Mesh设备的双向状态同步。

功能特性

双MQTT配置：
- Mesh MQTT：连接Symi网关获取设备列表
- 品牌MQTT：连接第三方品牌MQTT服务器
设备自动发现：品牌MQTT连接后自动发现设备
双向同步：品牌设备↔Mesh设备实时状态同步
配置持久化：设备列表和映射配置持久保存，断线后仍可显示

支持的品牌协议

品牌	设备类型	功能码映射
HYQW（花语前湾）	灯具(8)	开关(fn=1)、亮度(fn=2, 0-100)
	空调(12)	开关(fn=1)、温度(fn=2, 18-29°C)、模式(fn=3)、风速(fn=4)
	窗帘(14)	动作(fn=1, 开/关/停)、位置(fn=2, 0-100%)
	地暖(16)	开关(fn=1)、温度(fn=2, 5-35°C)
	新风(36)	开关(fn=1)、风速(fn=3)

配置步骤

添加品牌MQTT配置节点：
- 从左侧拖入Symi MQTT Brand配置节点
- 配置品牌MQTT服务器地址、用户名、密码
- 选择品牌协议（如HYQW）
添加MQTT同步节点：
- 从左侧拖入Symi MQTT Sync节点
- 选择Mesh MQTT配置（用于获取Mesh设备）
- 选择品牌MQTT配置（用于获取品牌设备）
配置实体映射：
- 点击"添加"按钮
- 左侧选择Mesh设备（多路开关可选择按键）
- 右侧选择品牌设备
- 可添加多组映射
部署：点击部署，开始双向同步

注意事项

设备类型匹配：建议同步相同类型的设备（灯具对灯具，空调对空调）
离线设备显示：[离线]标记缓存中但当前不在线的设备
防死循环：内置2秒防抖机制，避免状态震荡
自动重连：5秒重连间隔，断线自动恢复

KNX双向同步

本节点支持与node-red-contrib-knx-ultimate完整双向同步，实现Symi Mesh设备与KNX系统的互联互通。

KNX桥接节点（推荐）

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

功能特点

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

配置步骤

安装KNX节点

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

添加KNX桥接节点 从"Symi Mesh"分类中拖入"KNX桥接"节点
导入KNX实体

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

添加映射

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

连接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节点配置（关键）

输入节点(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

注意事项

10秒初始化延迟：部署后前10秒不同步，等待Mesh设备发现完成
首次状态缓存：启动后第一次状态仅缓存，第二次操作才会同步
防死循环：KNX控制后1秒内，Mesh状态变化不会反向同步

KNX-HA双向同步

本节点支持KNX与Home Assistant实体直接双向同步，实现KNX系统与HA的实时互联互通。

功能特点

直接实体同步：通过HA events-state节点实时接收HA状态变化事件
KNX实体导入：支持Tab分隔格式导入KNX组地址配置
HA实体加载：从HA服务器节点自动加载所有支持的实体
快速输入：支持直接输入实体ID或名称搜索，带autocomplete提示
多设备类型：开关、灯光、窗帘、空调、风扇
双向同步：自动处理KNX↔HA状态同步
智能防抖：调光300ms、窗帘500ms防抖，避免过程中频繁同步
防死循环：内置800ms防抖机制

配置步骤

安装依赖节点

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

配置HA服务器 添加Home Assistant服务器配置节点，输入HA的URL和访问令牌
添加KNX-HA桥接节点 从"Symi Mesh"分类中拖入"KNX-HA桥接"节点
导入KNX实体 按照Tab分隔格式准备KNX组地址数据，点击"导入"按钮
配置映射 选择KNX实体和对应的HA实体
连接节点

[knxUltimate-in] → [KNX-HA桥接] → [knxUltimate-out]
[server-state-changed] → [KNX-HA桥接] ↗

支持的设备类型

KNX设备类型	HA实体类型	同步内容
开关	switch	开/关状态
灯光	light	开关、亮度、色温
窗帘	cover	开关、位置、停止
空调	climate	开关、温度、模式
风扇	fan	开关、风速

RS485/Modbus双向同步

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

功能特点

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

配置步骤

添加RS485桥接节点 从"Symi Mesh"分类中拖入"RS485桥接"节点
配置RS485连接

串口模式：选择USB串口，设置波特率（常用9600）
TCP模式：输入485转TCP网关的IP地址和端口

配置实体映射 选择Mesh设备和RS485设备类型、地址
部署点击"部署"按钮，开始双向同步

内置协议支持

品牌	支持设备
话语前湾	空调、地暖、新风、窗帘、1-8键开关
通用Modbus	各类标准Modbus设备
自定义协议	任意485码匹配（开关/窗帘/场景）

三合一面板配置

三合一面板需要创建3个独立映射：

Mesh设备	RS485设备类型	从机地址
三合一面板_xxx	空调	0
三合一面板_xxx	新风	60
三合一面板_xxx	地暖	62

云端数据同步

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

使用场景

酒店项目：自动同步房间设备的本地化名称
场景管理：获取云端配置的场景列表并本地化调用
批量部署：统一管理多个房间的设备名称

配置步骤

添加云端同步节点
配置云端认证：App ID和App Secret
配置房间信息：酒店ID和房间号
部署并验证

按键场景自动触发

开关按键可以绑定场景，按下时自动触发场景执行：

普通按键：控制本地继电器
场景按键：按下时触发指定场景
双控按键：根据当前状态触发开/关场景
总控按键：全局控制

节点概览

节点	用途
Symi RS485 Sync	RS485多机批量同步
RS485调试	原始485字节流抓取显示
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协议双向同步

协议说明

核心协议格式

[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
4路	0x55	0xAA
8路	0x5555	0xAAAA

常用消息类型

消息类型	代码	数据格式	范围/说明
开关状态	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主题结构

Discovery主题

homeassistant/[platform]/[object_id]/config

状态和命令主题

普通设备：

symi_mesh/[mac_clean]/[entity]/state
symi_mesh/[mac_clean]/[entity]/set

三合一设备：

空调：symi_mesh/[mac_clean]/climate/mode
新风：symi_mesh/[mac_clean]/fresh_air/state
地暖：symi_mesh/[mac_clean]/floor_heating/mode

技术栈兼容性

版本要求

组件	最低版本	推荐版本
Node-RED	≥3.0.0	4.0+
Node.js	≥18.0.0	22.x LTS
MQTT Broker	任意	Mosquitto 2.x

Node.js 18+ 兼容性

本项目已针对Node.js 18+进行优化：

AggregateError处理：全局异常处理器捕获AggregateError，防止崩溃
Happy Eyeballs禁用：通过net.setDefaultAutoSelectFamily(false)禁用
强制IPv4连接：TCP连接使用family: 4参数
网络异常恢复：自动捕获网络错误

代码质量

经2025-12-10代码审查确认：

遵循Node-RED节点开发规范
使用标准日志接口
正确处理节点关闭事件
无未处理的Promise rejection
代码无重复，模块化设计

开发者信息

项目结构

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-knx-bridge.js/html # KNX桥接节点
│   ├── symi-knx-ha-bridge.js/html # KNX-HA桥接节点
│   ├── symi-ha-sync.js/html  # HA同步节点
│   ├── symi-mqtt-sync.js/html # MQTT品牌同步节点
│   └── ...
├── examples/
│   ├── basic-example.json
│   ├── knx-sync-example.json
│   └── rs485-sync-example.json
├── LICENSE
├── README.md
└── package.json

更新日志

v1.8.18 (2026-01-21)

【修复】npm安装失败问题：
- 删除package.json中错误的自引用依赖，修复所有用户无法安装v1.8.17的问题

v1.8.17 (2026-01-20)

【修复】KNX场景批量命令仍有反向发送问题：
- 在syncMeshToKnx执行时再次检查全局KNX活动时间窗口，确保执行时也阻止
- 队列处理间隔从50ms增加到60ms，避免处理太快导致状态同步遗漏
【优化】场景面板事件日志解析：
- 正确识别协议扩展的0x11事件类型（场景面板按键事件）
- 区分不同attrType：0x13(开关1-4路场景)、0x12(开关5-6路场景)、0x40(循环场景)
- 日志从[场景执行]改为[场景面板]，更准确描述事件来源
- 为后续场景联动功能开发预留接口

v1.8.16 (2026-01-20)

【修复】窗帘KNX→Mesh同步失效问题：
- 修复窗帘位置地址与状态地址冲突导致KNX位置控制无法同步到Mesh的bug。
- 窗帘设备清空knxAddrStatus，避免与knxAddrPosition匹配冲突。
- 优化回显检测逻辑：只检查当前地址，避免位置数据被错误跳过。
【修复】KNX场景批量命令干扰问题：
- 新增全局KNX活动时间戳机制，解决场景触发多个设备时Mesh反向干扰KNX的问题。
- 只要KNX总线在活动（600ms内有任何KNX命令），就阻止所有Mesh→KNX同步。
- 回显检测后才更新全局时间戳，确保Mesh控制KNX时不会被自己的回传阻止。

v1.8.15 (2026-01-20)

【关键修复】KNX场景控制反向发送问题：
- 彻底解决KNX场景控制后系统错误地将数据反向发送回KNX的严重问题。
- 新增"KNX控制中"全局标记机制，KNX数据进入时500ms内禁止Mesh→KNX同步。
- 防死循环时间记录移至KNX输入处理阶段（而非队列执行时），确保时序正确。
- 核心原则：当数据来源是KNX时，只响应更新Mesh设备状态，绝不反向发送指令到KNX。

v1.8.14 (2026-01-19)

配置界面拖动排序：
- 为所有映射配置表格添加了拖动排序功能，支持通过拖动手柄调整条目顺序。
- 支持的节点：KNX桥接（KNX实体库 + 设备映射）、MQTT同步、RS485桥接、RS485同步。
- 部署后顺序持久化保存，重启不丢失。
配置窗口响应式布局：
- 统一所有节点配置窗口的列表高度为响应式布局（calc(100vh - 380px)）。
- 窗口越大显示内容越多，操作更便捷。

v1.8.13 (2026-01-18)

KNX 并发控制逻辑修复（关键更新）：
- 禁止状态地址反向触发：彻底修复了 KNX 总线在场景执行或多设备并发响应时，Mesh 设备出现“相反操作”或错误控制的问题。现在系统严格区分控制地址（Cmd）和状态地址（Status），严禁状态反馈报文触发对 Mesh 设备的控制指令。
- Buffer 类型数据解析增强：修复了当 KNX 节点传递 Buffer 类型数据（如 <Buffer 01>）时，系统错误解析为 false (关) 导致的操作反转问题。现在能正确识别 Buffer 格式的开关量。
- 并发稳定性：优化了输入处理逻辑，在高并发场景下（如 KNX 场景同时触发几十个设备）能稳定运行，消除了因状态反馈震荡导致的逻辑错误。

v1.8.10+ (2026-01-18)

KNX 并发控制逻辑修复（关键更新）：

禁止状态地址反向触发：彻底修复了 KNX 总线在场景执行或多设备并发响应时，Mesh 设备出现“相反操作”或错误控制的问题。现在系统严格区分控制地址（Cmd）和状态地址（Status），严禁状态反馈报文触发对 Mesh 设备的控制指令。
Buffer 类型数据解析增强：修复了当 KNX 节点传递 Buffer 类型数据（如 <Buffer 01>）时，系统错误解析为 false (关) 导致的操作反转问题。现在能正确识别 Buffer 格式的开关量。
并发稳定性：优化了输入处理逻辑，在高并发场景下（如 KNX 场景同时触发几十个设备）能稳定运行，消除了因状态反馈震荡导致的逻辑错误。
日志优化：优化了 TCP 客户端和网关初始化逻辑，对连接超时和离线错误进行节流处理，避免在断网情况下日志刷屏。

新增功能：

KNX 场景联动支持：新增“场景”设备类型，支持 Mesh 开关按键与 KNX 场景的双向联动。
- 双向同步：
  - KNX 触发场景 -> 自动控制 Mesh 开关 (ON/OFF)
  - Mesh 按键操作 -> 自动触发 KNX 场景 (发送场景号)
- 防死循环：针对场景触发的单向特性，特别优化了防环路机制，确保 Mesh 状态变化后不会再次触发场景发送。
- 配置方式：在 KNX 桥接节点中添加 KNX 实体时选择“场景”类型，需要配置以下三个参数：
  1. KNX组地址：场景控制的组地址（如 1/1/1）。
  2. 场景号(1-64)：KNX 标准场景编号（对应 DPT 17.001 0-63 值）。
  3. 绑定Mesh开关状态：必填项。设置当触发该 KNX 场景时，关联的 Mesh 开关应变为“开”还是“关”。
    - 为什么必须指定状态？ 场景通常是确定的状态（如“离家”=全关），而不是翻转（Toggle）。如果使用翻转，当灯已经是关闭状态时，再次触发“离家”会导致灯打开，这违背了场景的初衷。
    - 逻辑说明：
      - KNX -> Mesh：收到 KNX 场景号 -> Mesh 开关执行指定状态（如设为 0，则执行关）。
      - Mesh -> KNX：Mesh 开关变为指定状态（如变为关） -> 发送 KNX 场景号。

历史版本功能合并 (v1.8.4 - v1.8.10)：

三合一面板深度集成：
- 完整支持空调、新风、地暖的全功能双向同步。
- 持久化存储设备类型，重启后自动恢复，无需重复探测。
- 优化了状态缓存机制，只同步真正变化的属性，减少资源消耗。
稳定性增强：
- 错误日志节流：在网关连接和 RS485 配置中引入节流机制，彻底解决离线时的日志刷屏问题。
- 通用同步工具类：重构了所有同步节点（HA、MQTT、KNX、RS485），统一使用 SyncUtils 类进行防环路和状态缓存管理。
- 窗帘同步修复：实现了"谁发起控制就只听谁的命令"逻辑，彻底解决窗帘双向同步死循环问题。
- 协议鲁棒性：增强了分包与粘包处理，修复了 Buffer 类型数据解析问题。

常见问题排查

MQTT连接失败

检查MQTT Broker地址配置
确认MQTT Broker运行状态
检查防火墙/网络

网关连接失败

确认网关IP地址和端口（默认4196）
使用ping测试网络连通性
检查网关是否开启TCP服务模式

设备状态不同步

检查网关节点是否显示"已连接"
检查MQTT节点是否显示"已连接"
在Node-RED调试面板查看是否收到设备状态事件

技术支持

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

环境信息: Node-RED版本、Node.js版本、操作系统
网关信息: 网关型号、固件版本、连接方式
问题描述: 完整错误日志、设备类型和数量、复现步骤

许可证

MIT License

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

Node Info

Version: 1.8.18

Updated 23 hours ago

License: MIT

Rating: not yet rated

View on npm

View on GitHub

View Scorecard 10 2

Actions

Downloads

733 in the last week

Nodes

symi-gateway
symi-device
symi-mqtt
symi-cloud-sync
symi-485-config
symi-rs485-bridge
rs485-debug
symi-knx-bridge
symi-knx-ha-bridge
symi-ha-sync
symi-rs485-sync
symi-mqtt-sync
symi-mqtt-brand

Keywords

node-red
symi
mesh
bluetooth
mqtt
smart-home
home-assistant
iot
亖米
智能家居
蓝牙网关

Maintainers

symi-daguo

node-red-contrib-symi-mesh 1.8.18

node-red-contrib-symi-mesh

功能特性

快速开始

1. 安装

2. 配置网关节点

3. 添加MQTT桥接节点

4. 部署并验证

5. 多网关配置（可选）

支持的设备类型

三合一设备说明

实体说明

使用方式

HA双向同步

功能特性

⚠️ 双向同步连接方式（重要）

状态指示

配置步骤

注意事项

三合一面板配置

窗帘同步说明

MQTT品牌同步

功能特性

支持的品牌协议

配置步骤

注意事项

KNX双向同步

KNX桥接节点（推荐）

功能特点

配置步骤

KNX实体导入格式

knxUltimate节点配置（关键）

注意事项

KNX-HA双向同步

功能特点

配置步骤

支持的设备类型

RS485/Modbus双向同步

功能特点

配置步骤

内置协议支持

三合一面板配置

云端数据同步

使用场景

配置步骤

按键场景自动触发

节点概览

协议说明

核心协议格式

关键操作码

开关状态编码

常用消息类型

MQTT主题结构

Discovery主题

状态和命令主题

技术栈兼容性

版本要求

Node.js 18+ 兼容性

代码质量

开发者信息

项目结构

更新日志

v1.8.18 (2026-01-21)

v1.8.17 (2026-01-20)

v1.8.16 (2026-01-20)

v1.8.15 (2026-01-20)

v1.8.14 (2026-01-19)

v1.8.13 (2026-01-18)

v1.8.10+ (2026-01-18)

常见问题排查

MQTT连接失败

网关连接失败

设备状态不同步

技术支持

许可证

Node Info

Categories

Actions

Downloads

Nodes