node-red-contrib-symi-mesh 1.9.6

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自动发现功能。

npm version Node-RED License: MIT

功能特性

  • 完整协议支持：TCP/串口双模式，严格遵循蓝牙MESH网关串口协议V1.0
  • 自动设备发现：连接后自动发现所有设备，无需手动配置
    • 增强分包粘包处理：自动处理TCP分包粘包问题，确保设备列表完整接收
    • 完整性验证：自动检测缺失设备，提供详细的发现进度和完整性报告
    • 超时保护：10秒超时机制，防止发现流程卡死
    • 去重机制：按设备index自动去重，避免重复计数
    • 单次发现：53 12 00 41 设备列表查询仅在部署/重启时执行一次，避免重复查询导致丢包
  • MQTT Discovery：自动发布HA Discovery配置，设备即插即用
  • 双向状态同步：支持0x80状态事件，实时反馈设备状态变化
    • 完全依赖主动上报：已移除 53 32 状态查询命令，完全依赖设备主动上报，避免查询导致丢包
    • 三合一设备检测：通过设备主动上报的 0x94 消息或 0x68/0x6B 属性自动识别三合一面板
  • 多设备类型：支持开关、灯光、窗帘、温控器、传感器等12+种设备
  • 三合一面板：完整支持空调+新风+地暖三合一控制面板，自动识别
  • RS485/Modbus集成：支持第三方485设备双向同步，内置协议模板，支持中弘VRF、SYMI面板协议
  • RS485同步增强：symi-rs485-sync 节点已全面重构，采用统一防环路机制，支持多台空调内机批量状态同步和三合一子实体增强映射
  • KNX集成：支持与KNX系统双向同步，新增状态自动校准功能
  • KNX-HA集成：支持KNX与Home Assistant实体直接双向同步
  • 窗帘同步优化：专门针对无限位Mesh窗帘模组优化，支持控制锁定（默认3s，可配置）和即时状态同步，彻底解决状态死循环和丢包问题
    • 可配置锁定时间：针对慢速窗帘电机，支持在网关节点的“显示全局同步设置”中配置调光/窗帘锁时间（500ms-50000ms），默认3000ms；所有桥接/同步节点共享该参数
  • 反馈确认熔断：智能反馈确认机制，自动检测设备离线状态，避免对不存在/离线设备持续重试
  • 云端同步：从酒店云云平台自动获取设备名称和场景信息
  • 稳定可靠：完善的错误处理和自动重连机制
  • 设备去重保证：所有节点设备列表均采用唯一性保证，确保设备不重复
  • 配置持久化：所有映射关系自动保存，重启后自动恢复，确保配置不丢失
  • 静默重连：网络错误静默处理，自动重连，避免日志刷屏
  • 生产级静默日志：默认不刷 Node-RED 侧边栏；需要排障时可通过环境变量开启 debug/trace，并带限流保护

节点概览

本插件包含以下核心节点，旨在提供完整的蓝牙Mesh、KNX、HA及RS485集成方案：

节点名称 类型 功能描述
Symi Gateway 配置节点 核心连接中心，支持 TCP/IP (4196端口) 或 串口连接，集成 MQTT 代理配置。
Symi Device 控制节点 Mesh 设备操作核心，支持开关、调光、窗帘、三合一温控等全品类控制与状态反馈。
Symi MQTT 桥接节点 自动发现 Mesh 设备并发布至 MQTT，支持 Home Assistant 自动发现。
Symi KNX Bridge 桥接节点 KNX 与 Mesh 互联核心，支持状态自动校准、防死循环逻辑及大规模实体映射。
Symi HA Sync 同步节点 实现 Mesh 设备与 Home Assistant 实体间的双向实时同步，内置窗帘防震荡逻辑。
Symi MQTT Sync 同步节点 第三方 MQTT 品牌（如花语前湾）与 Symi Mesh 设备的双向同步。
Symi 485 Bridge 桥接节点 RS485 通信桥接，支持 Modbus 协议透传与自定义指令映射。
Symi 485 Config 配置节点 RS485/TCP 串口服务器连接配置，支持多实例管理。
Symi Cloud Sync 同步节点 云端设备状态同步，支持远程监控与控制。
Symi KNX HA 桥接节点 专门针对 KNX 实体与 HA 实体之间的直连同步（实验性）。
RS485 Debug 调试工具 原始 485 字节流监控，支持十六进制/ASCII 显示，定位通信故障。
Symi RS485 Sync 同步节点 两个独立 RS485 总线之间的数据与状态同步。

快速上手

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 /ABSOLUTE/PATH/node-red-contrib-symi-mesh

建议用绝对路径（macOS 示例：/Volumes/.../node-red-contrib-symi-mesh），这样你在仓库里改代码后，Node-RED 侧会直接使用最新源码。

方式四：发布前打包安装（最后发布时再用）

# 在仓库目录执行
npm pack

# 然后到 ~/.node-red 安装生成的 .tgz
cd ~/.node-red
npm install /ABSOLUTE/PATH/node-red-contrib-symi-mesh-<version>.tgz

安装后重启Node-RED：

node-red-restart

2. 配置网关节点

添加"Symi Gateway"配置节点：

网关连接配置:

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

全局同步设置（已移除状态查询功能）:

  • 状态查询延时: 已移除，不再使用 53 32 命令查询设备状态
    • 系统完全依赖设备主动上报（0x80状态事件）来获取设备状态
    • 这样可以避免查询命令导致的丢包问题，提高系统稳定性

3. 添加MQTT桥接节点

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

节点配置:

  • 网关: 选择已配置的网关节点（必填）
  • MQTT地址: mqtt://localhost:1883（默认，可修改）
  • 用户名: MQTT认证用户名（可选）
  • 密码: MQTT认证密码（可选）
  • HA前缀: homeassistant（默认，可修改）
  • 名称: 可选，用于标识节点

注意: MQTT配置在MQTT节点中完成，每个MQTT节点可以配置不同的MQTT服务器。

4. 部署并验证

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

本插件面向酒店/大规模部署，默认不向 Node-RED 侧边栏刷屏（包括 node.error/node.warn/node.log），并对可选的诊断输出做了限流，避免网络抖动/断线重连时产生日志风暴。

默认行为（推荐生产）

  • 不设置任何环境变量：日志保持静默，仅通过节点状态（Status）显示关键状态（如“未配置网关/同步失败”等）。
  • KNX输入日志：KNX输入日志已调整为 debug 级别，生产环境下默认不显示，仅在开启调试模式时可见。

需要排障时开启诊断日志

通过环境变量开启（重启 Node-RED 生效）：

  • SYMI_LOG_LEVEL：日志级别
    • debug：输出关键流程信息（推荐排障用）
    • trace：输出更详细的信息（仅短时间使用）
  • SYMI_LOG_INTERVAL_MS：相同 key 的日志限流间隔（默认 60000ms）

示例（macOS/Linux）：

export SYMI_LOG_LEVEL=debug
export SYMI_LOG_INTERVAL_MS=60000
node-red

排障结束后建议清除环境变量并重启 Node-RED，恢复生产静默。

5. 示例流程（examples）

所有示例已按 "每个节点一个独立 flow 文件" 拆分，导入即可看到对应节点与配置位置：

  • 01 - MQTT Discovery：examples/01-symi-mqtt-discovery.json（symi-gateway + symi-mqtt）
  • 02 - 设备控制：examples/02-symi-device-control.json（symi-device）
  • 03 - HA 双向同步：examples/03-symi-ha-sync.json（symi-ha-sync，需安装并配置 Home Assistant Server）
  • 04 - 品牌 MQTT 同步：examples/04-symi-mqtt-sync-brand.json（symi-mqtt-sync + symi-mqtt-brand）
  • 05 - RS485 桥接：examples/05-symi-rs485-bridge.json（symi-485-bridge + symi-485-config）
  • 06 - RS485 A↔B 同步：examples/06-symi-rs485-sync.json（symi-rs485-sync + symi-485-config）
  • 07 - RS485 抓包调试：examples/07-rs485-debug.json（rs485-debug + symi-485-config）
  • 08 - KNX 桥接：examples/08-symi-knx-bridge.json（symi-knx-bridge；如需对接 KNX 建议安装 node-red-contrib-knx-ultimate）
  • 09 - KNX ↔ HA 桥接：examples/09-symi-knx-ha-bridge.json（symi-knx-ha-bridge；需安装 HA/KNX 相关节点）
  • 10 - 云端同步：examples/10-symi-cloud-sync.json（symi-cloud-sync）

6. 多网关配置（可选）

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

  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%）
情景面板 0x06 scene 场景触发（仅场景功能）
门磁传感器 0x07 binary_sensor 门窗开关状态
人体感应 0x08 binary_sensor 人体活动检测
插卡取电 0x09 switch + binary_sensor 插卡检测+开关控制
温控器/三合一 0x0A climate 温度/模式/风速控制，当前温度采集；空调+新风+地暖三合一控制面板
温湿度传感器 0x0B sensor 温湿度监测
情景开关 0x0C (12) scene 开关+场景功能（1-4路，固定场景个数）
五色调光灯 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地暖控制器

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

节点详细配置

Symi Device 设备控制节点

用于在Flow中直接控制单个Mesh设备，并接收状态回传。

配置项：

  • 网关: 选择已配置的网关节点（必填）
  • 设备: 从下拉列表选择Mesh设备，或手动输入MAC地址
  • 通道: 对于多路开关，选择要控制的按键（1-6）
  • 子实体: 对于三合一设备，选择要控制的功能（空调/新风/地暖）
  • 输出格式: 选择状态输出的格式（full/simple）

使用示例：

  • 开关控制：payload = "ON" 或 payload = true
  • 调光控制：msg.command = "brightness" + payload = 0-100
  • 窗帘控制：payload = "open"/"close"/"stop" 或 payload = 0-100
  • 温控控制：msg.command = "temperature"/"mode"/"fan"

Symi MQTT 桥接节点

自动发现Mesh设备并发布到MQTT，支持Home Assistant自动发现。

配置项：

  • 网关: 选择已配置的网关节点（必填）
  • MQTT地址: MQTT Broker地址（如 mqtt://localhost:1883）
  • 用户名: MQTT认证用户名（可选）
  • 密码: MQTT认证密码（可选）
  • HA前缀: Home Assistant Discovery前缀（默认：homeassistant）

功能说明：

  • 部署后自动发现所有Mesh设备
  • 自动发布HA Discovery配置
  • 支持设备状态实时同步
  • 支持按键场景触发（自动识别按键绑定的场景）

Symi HA Sync 双向同步节点

实现Symi蓝牙Mesh设备与Home Assistant实体的直接双向同步。

功能特性：

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

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

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

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

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

配置步骤：

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

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

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

配置步骤：

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

状态指示：

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

配置步骤：

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

注意事项：

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

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

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

示例配置：

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

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

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

Symi MQTT Sync 品牌同步节点

用于实现第三方MQTT品牌设备与Symi Mesh设备的双向状态同步。

功能特性：

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

支持的品牌协议：

品牌 设备类型 功能码映射
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)

配置步骤：

  1. 添加品牌MQTT配置节点：

    • 从左侧拖入Symi MQTT Brand配置节点
    • 配置品牌MQTT服务器地址、用户名、密码
    • 选择品牌协议（如HYQW）

  2. 添加MQTT同步节点：

    • 从左侧拖入Symi MQTT Sync节点
    • 选择Mesh MQTT配置（用于获取Mesh设备）
    • 选择品牌MQTT配置（用于获取品牌设备）

  3. 配置实体映射：

    • 点击"添加"按钮
    • 左侧选择Mesh设备（多路开关可选择按键或场景通道）
    • 右侧选择品牌设备
    • 可添加多组映射

  4. 部署：点击部署，开始双向同步

注意事项：

  • 设备类型匹配：建议同步相同类型的设备（灯具对灯具，空调对空调）
  • 离线设备显示：[离线]标记缓存中但当前不在线的设备
  • 防死循环：统一使用800ms防死循环时间窗口，避免状态震荡
  • 自动重连：5秒重连间隔，断线自动恢复

Symi KNX Bridge 桥接节点

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

功能特点：

  • KNX实体库：导入KNX组地址，快速选择实体
  • 一行映射：紧凑表格，适合大量设备映射
  • 多设备类型：开关、调光灯、窗帘、空调、新风、地暖
  • 双向同步：自动处理Mesh↔KNX状态同步
  • 批量处理优化：
    • KNX→Mesh批量处理：当KNX同时触发同一Mesh设备的多个通道时，自动合并为一行码发送，提升效率
    • Mesh→KNX批量处理：当Mesh同时改变同一设备的多个开关通道时，批量发送到不同的KNX地址，按通道顺序排序确保一致性
    • 批量处理时间窗口：100ms内收到的同一设备的开关命令会自动合并
  • 自动状态校准：新增功能，可选全局自动读取状态，解决手动操作后的同步延迟
  • 防死循环：统一使用800ms防死循环时间窗口，增强型状态回传过滤逻辑

配置步骤：

  1. 安装KNX节点
cd ~/.node-red
npm install node-red-contrib-knx-ultimate

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

  2. 导入KNX实体

  • 点击"下载模板"获取导入格式
  • 填写KNX组地址后点击"导入"
  1. 添加映射
  • 点击"添加"按钮
  • 选择Mesh设备和KNX实体
  • 开关设备可选择通道（按键1-6、按键X场景、Mesh场景）
  • 当选择场景通道时，输入场景ID（范围2-95）
  1. 连接KNX节点
[knxUltimate-in] → [symi-knx-bridge] → [knxUltimate-out]

KNX状态自动校准：

这是为了解决"状态不同步导致的二次控制失败"而设计的核心功能。

工作原理：

  1. 触发：当你在米家/Mesh端发起控制，或者KNX总线上出现动作（GroupValue_Write）时，系统会启动一个倒计时。
  2. 延迟读取：默认3000ms（3秒）后，系统会自动向所有已映射的KNX状态地址发送读取请求（GroupValue_Read）。延迟时间可在节点配置中自定义（建议2000-5000ms）。
  3. 状态对齐：收到KNX系统的回复（GroupValue_Response）后，系统会比较KNX状态和Mesh状态：
    • 如果状态一致：记录日志，不执行操作
    • 如果状态不一致：立即发送校准命令到Mesh，强制对齐状态
  4. 效果：即使KNX总线没有主动反馈状态，系统也会在配置的延迟时间后通过主动查询完成同步。这样用户在第二次触发控制时，状态已经对齐，确保控制100%成功。

配置方法：

  • 开启自动状态校准：勾选此项开启全局校准。
  • 校准延迟(ms)：建议设置在 2000ms - 5000ms 之间。设置太短可能在设备还在动作中就读取了旧状态，设置太长则响应不够及时。

防死循环机制： 系统会自动识别校准产生的回复消息，仅更新内部状态，绝不会再次触发反向控制发送给KNX，请放心使用。

KNX状态反馈地址优化：

  • 核心改进：区分控制地址（cmdAddr）和状态反馈地址（statusAddr）的处理逻辑。
  • 状态反馈地址：如果配置了独立的状态反馈地址（statusAddr）且与命令地址（cmdAddr）不同，则：
    • 从状态反馈地址收到的消息：只同步状态到Mesh，不记录控制时间戳，不触发反向控制保护。
    • 从命令地址收到的消息：才是真正的控制命令，需要记录时间戳并触发反向控制保护。
  • AutoSync 配合：当启用自动状态校准（AutoSync）时，从状态反馈地址收到的 GroupValue_Response 也会参与 KNX/Mesh 状态比对；若状态不一致，会向 Mesh 发送一次校准命令（带校准标记，不触发反向 KNX 控制），若状态一致则只更新内部缓存。
  • 优势：避免状态反馈地址触发反向控制，同时又能在需要时依托 AutoSync 精准校准 Mesh 状态，简化状态锁逻辑，提升同步效率和稳定性。

双向反馈确认机制：

  • 核心功能：实现"发-收"闭环确认，确保控制命令执行成功，状态完全同步。
  • KNX控制Mesh：
    • 发送命令后，记录待确认的命令（3秒超时）
    • 收到Mesh状态反馈且与期望值一致时，确认成功并记录日志：[反馈确认] ✓ KNX控制Mesh成功: ...
    • 超时未收到反馈时，自动重试：
      1. 查询Mesh设备实际状态
      2. 如果状态不一致，重发命令确保同步
      3. 如果状态一致，确认成功
      4. 最多重试5次（MAX_RETRY_COUNT），确保“最后一次KNX命令”最终在Mesh侧达成
    • 快速连按最终收敛（Last Write Wins）：在 3 秒 KNX 主控窗口内，若Mesh尾帧/抖动导致最终状态跑偏，会自动纠错补发（限频，最多5次），确保最终一致。
    • 多路开关解析一致性：switchState 采用每路 2-bit 编码解码（decodeSwitchState2Bit），避免状态矛盾触发反向控制或误确认。
  • Mesh控制KNX：
    • 发送命令后，记录待确认的命令（3秒超时）
    • 收到KNX状态反馈（控制地址或状态地址）且与期望值一致时，确认成功并记录日志：[反馈确认] ✓ Mesh控制KNX成功: ...
    • 超时未收到反馈时，自动重试：
      1. 查询KNX设备状态
      2. 如果仍未收到反馈，重发命令确保同步
      3. 最多重试1次，避免死循环
  • 闭环保证：无论谁控制谁，都会确保状态完全同步后才完成闭环，不会造成死循环，因为重试概率很低，只有真正失败时才会介入。
  • 优势：确保控制命令的可靠性，自动处理网络延迟或丢包问题，确保Mesh和KNX状态始终保持一致。

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 开关, 温度, 当前温度 地暖
scene 组地址(cmd), 场景号(triggerValue), Mesh动作(triggerAction) 场景

触发值与触发动作说明：

  • 开关类型（switch）：
    • 只需要填写命令/状态组地址，触发值字段是可选，一般情况下可以留空；
    • 触发值支持 Hex 0x01 或 Dec 1，用于精确匹配某个载荷（rawValue / payload），为空则匹配所有值；
    • 不会显示“触发动作”下拉框，开关类型只根据 KNX 端的具体值同步到 Mesh，不做额外动作映射。
  • 场景类型（scene）：
    • triggerValue 字段表示 场景号（如 1、2），用于和 KNX 侧的场景值对应；
    • triggerAction 表示 Mesh 侧要执行的动作，仅在场景类型下出现下拉框，可选：
      • on：触发场景对应的“开/激活”动作
      • off：触发场景对应的“关/取消”动作
      • toggle：在 Mesh 当前状态基础上反转

Symi RS485 Bridge 桥接节点

RS485通信桥接，支持Modbus协议透传与自定义指令映射。

配置步骤：

  1. 添加RS485配置节点：

    • 从左侧拖入Symi 485 Config配置节点
    • 配置串口服务器地址、端口、串口参数

  2. 添加RS485桥接节点：

    • 从左侧拖入Symi 485 Bridge节点
    • 选择网关节点（用于获取Mesh设备）
    • 选择RS485配置节点

  3. 配置映射：

    • 点击"添加"按钮
    • 选择Mesh设备和RS485设备
    • 配置协议模板（如中弘VRF、SYMI面板）

  4. 部署：点击部署，开始双向同步

Symi RS485 Sync 同步节点

两个独立RS485总线之间的数据与状态同步。

配置步骤：

  1. 添加两个RS485配置节点：

    • 配置节点A：第一个RS485总线
    • 配置节点B：第二个RS485总线

  2. 添加RS485同步节点：

    • 从左侧拖入Symi RS485 Sync节点
    • 选择网关节点（用于获取Mesh设备）
    • 选择RS485配置A和配置B

  3. 配置映射：

    • 点击"添加"按钮
    • 左侧选择Mesh设备或RS485 A设备
    • 右侧选择RS485 B设备
    • 支持多台空调内机批量状态同步

  4. 部署：点击部署，开始双向同步

注意事项：

  • 支持多台空调内机批量状态同步
  • 支持三合一子实体增强映射
  • 采用统一防环路机制

虚拟场景实体

新增永久生效的虚拟场景设备，固定MAC地址：00:00:00:00:00:00。

功能说明：

  • 场景ID默认值为0（不触发），需要设置为2-95时才触发对应场景
  • 支持场景ID范围：2-31 和 64-95
  • 只要配置了Mesh网关，该实体就自动生效，无需物理设备
  • 支持KNX、RS485、HA、MQTT全协议联动，可在所有桥接节点中选择使用
  • 在所有同步节点的设备列表中，会自动显示"Mesh 永久场景 (虚拟设备)"

使用方式：

  1. 在同步节点（KNX、HA、MQTT、RS485）的设备选择下拉框中，选择"Mesh 永久场景 (虚拟设备)"
  2. 选择通道为"Mesh场景"
  3. 输入场景ID（范围2-95，默认0=不触发）
  4. 配置对应的外部系统实体（KNX组地址、HA实体、MQTT设备等）
  5. 部署后即可实现场景联动

按键场景触发

在所有同步节点（KNX、RS485、HA、MQTT）的通道选择中，新增"按键X场景"选项（X为1-6）。

功能说明：

  • 选择"按键X场景"后，系统会自动使用串口协议V1.0的0x34操作码（场景控制）替代原有的继电器控制
  • 场景ID默认值为0（不触发），需要设置为2-95时才触发对应场景
  • 支持场景ID范围：2-31 和 64-95
  • 当Mesh开关按键被触发时，不仅能控制继电器，还能触发本地场景，满足设备上报状态的需求

使用方式：

  1. 在同步节点的设备选择中，选择Mesh开关设备
  2. 在通道选择中，选择"按键X场景"（X为1-6）
  3. 输入场景ID（范围2-95，默认0=不触发）
  4. 配置对应的外部系统实体
  5. 部署后，当按键被触发时，会自动触发对应的场景

更新日志

v1.9.6 (2026-02-07)

修复与优化

  • 修复KNX开关快速反复操作被反向重置的问题：
    • 问题：当用户快速反复操作KNX开关（如快速开-关-开）时，中间状态的Mesh延迟反馈会导致最终状态被错误重置（如最后一次是“开”，但收到中间的“关”反馈导致被反向同步为“关”）。
    • 修复：
      • 在所有控制路径中严格更新 knxControlTimestamps，包括初始发送和所有重试场景。
      • 确保每次KNX控制命令发出时，都会刷新对应设备的时间戳，阻止后续Mesh反馈触发反向同步。
      • 覆盖了所有实体类型：开关、窗帘、调光、空调、新风、地暖、场景，确保全品类保护。
    • 效果：无论操作多快，KNX的最后一次操作永远生效，不会被延迟的Mesh反馈“弹回”。

窗帘/调光同步与首次查询逻辑修复（解决部署后真实窗帘被驱动）

  • 问题：Mesh 窗帘与 HA 同步时，部署后真实 HA 窗帘会动；原则应为「Mesh 同步真实窗帘状态」——不因部署主动驱动真实窗帘，且需区分触发来源避免回显误触发。
  • 网关：
    • 状态查询期间或 0xB2 查询响应触发的状态事件，统一带上 isFromStateQuery 并照常发送 device-state-changed，便于区分主控方。
  • HA Sync：
    • 部署/查询不驱动 HA 窗帘：isFromStateQuery 或非用户主控时，不同步任何窗帘状态到 HA（既不执行 open/close，也不下发 set_cover_position），部署后真实窗帘保持不动。
    • HA 触发时禁止反向控制：只要 coverMoving.direction === "ha"，Symi→HA 方向绝不同步窗帘（位置与动作均不写回 HA），任何人不得在 HA 触发时反向控制 HA 窗帘，避免回弹。
    • handleCurtainChange 先判 HA 主控再判查询/非主控，仅 Mesh 用户主控时才同步到 HA；Symi 下发 cover 前写入 recordCoverSync，抑制 HA 回显。
    • Symi 下发导致的 HA 状态回显：state_changed 收到 opening/closing/位置/停止时，若当前为 Symi 主控（coverMoving.direction === "symi"），不反向下发 HA->Symi，仅释放锁定，避免连锁驱动。
    • 调光：isFromStateQuery 时不同步亮度到 HA；HA 主控期间（brightnessMoving）不向 HA 回写亮度，与窗帘逻辑一致。
  • KNX Bridge：
    • 窗帘：isFromStateQuery 或非 isUserControl 时仅同步位置到 KNX，不发送开/关动作。
    • 开关快速连按最终收敛（Last Write Wins）：
      • switchState 按每路 2-bit 编码解析（统一解码函数 decodeSwitchState2Bit），避免因位解析错误导致 Mesh/KNX 状态互相矛盾、产生回弹。
      • KNX 主控窗口提升为 3 秒：快速操作结束后的尾帧/抖动上报不会反向回写 KNX。
      • 窗口内纠错闭环：以“最后一次 KNX 命令”为准，若 Mesh 状态跑偏则自动补发纠错（限频，最多 5 次），确保最终 Mesh 与 KNX 一致。
      • 反馈确认更严格：确认成功只基于“本次变化(changed)”判断，避免旧缓存/无关帧误判成功导致不再重试。
  • 效果：部署后真实窗帘不动；窗帘/调光带步进忽略过程上报，主控方区分清晰，适合长期稳定运行。

KNX/全节点：部署时仅更新缓存，不下发控制（窗帘、调光、开关）

  • 原则：只有主动发起的控制才发送控制指令；部署/StateQuery 的读取响应（Response）仅更新本地缓存，不向 Mesh 或 KNX 写入。
  • KNX Bridge：
    • 开关：收到 GroupValue_Response 时仅更新 stateCache，不再向 Mesh 发送校准命令。
    • 调光（开关/亮度/色温）：收到 Response 时仅更新缓存并 return，不 queueCommand 到 Mesh。
    • 窗帘：cover 映射的 knxAddrStatus 为空，StateQuery 不读取窗帘，故无 Response 下发。
  • HA Sync：已在上述条款中禁止部署时 set_cover_position。
  • Symi MQTT：为 MQTT→Mesh 的 开关/窗帘 控制加入“反馈确认 + 查询重试”闭环（3 秒超时、最多 5 次），提升 HA 通过 MQTT 快速操作时的可靠性，避免因丢包/延迟上报导致的回弹与不同步，确保 HA/MQTT 实体状态最终与 Mesh 一致。
  • MQTT Sync / RS485 Bridge / RS485 Sync：无 state-query-complete 或首次同步下发逻辑，仅事件驱动，部署不会触发控制。

v1.9.5 (2026-02-05)

启动时重复读取优化

  • 修复启动时重复读取问题：启动时 AutoSync 和 StateQuery 都会触发，导致重复读取（48+48=96个请求），增加 KNX 总线负载
  • 防重复机制：
    • 记录 AutoSync 执行时间戳 lastAutoSyncTime
    • StateQuery 检查：如果 AutoSync 在最近 5 秒内执行过，则跳过 StateQuery 读取，避免重复
    • 效果：启动时只执行一次读取（AutoSync），不再重复，减少 KNX 总线负载和重复日志
  • 影响说明：
    • 不修复的影响：每次启动会发送双倍读取请求（如48个设备会发送96个请求），虽然不会导致功能错误，但会增加 KNX 总线负载，在大型系统中可能影响性能，且会产生重复日志
    • 修复后：启动时只执行一次读取，减少总线负载，日志更清晰，适合生产环境长期运行

工程化与生产日志策略（客户无感）

  • ESLint/打包验证闭环：补齐 .eslintrc.js 与 npm run lint / npm pack 流程，确保发布前可重复校验
  • 日志恢复可观测：保留节点内原有的 node.log/node.warn/node.error 行为，用于长期运行时的关键业务日志；仅在少数高频诊断点使用节流 Logger，避免刷屏
  • 主控识别与步进防抖：针对窗帘/调光等带步进设备，完善 HA/KNX 与 Mesh 之间的“主控识别 + 回显抑制”，确保：
    • HA/KNX 发起控制时，Mesh 只跟随状态，不反向修改 HA/KNX
    • Mesh 发起控制时，HA/KNX 只做一次性状态对齐，不把步进反馈当成新指令

v1.9.4 (2026-02-03)

全局同步默认值与 Symi KNX Bridge 稳定性

  • 统一全局同步默认值：网关配置中的“显示全局同步设置”默认采用队列长度 100、队列间隔 50ms、开关锁时间 800ms、调光/窗帘锁时间 3000ms，范围分别为 100-300 / 50-200ms / 500-3000ms / 500-50000ms，所有桥接节点（KNX、HA、MQTT 等）共享这一组限流与防抖参数，确保在 40~50 个组地址/实体的大规模场景下也能稳定工作。
  • 修复 KNX Bridge 映射保存丢失问题：symi-knx-bridge 编辑器在 oneditsave 中错误引用了仅存在于 oneditprepare 作用域内的 devices 变量，导致部署时抛出前端异常、映射列表无法持久化；现在改为直接从 DOM 下拉选项的 data-* 属性和文本恢复设备名称、类型和通道数，并在缺失时回退到已有映射数据，确保每次编辑后映射都能正确保存和恢复。
  • 增强所有节点映射列表的持久化一致性：对包含映射表的节点（MQTT Sync、HA Sync、RS485 Bridge、RS485 Sync 等）的 oneditsave 逻辑进行审查，统一采用“从 DOM/隐藏字段收集数据 → 写入配置字段(JSON 字符串)”的模式，避免依赖临时内存变量，保证在网关/外部服务离线时依然可以从已保存配置中完整恢复映射列表。
  • AutoSync 校准命令不再触发反馈重试闭环：区分 KNX 用户控制和 AutoSync 状态校准；对带 isCalibration=true 标记的 KNX→Mesh 校准命令，仅发送一次并记录到本地缓存，不创建待确认记录、不触发 5 次重试逻辑，从而避免在 Mesh 设备掉线时周期性输出多轮 [反馈确认] ✗ KNX控制Mesh失败(已重试5次) 告警。
  • 保持用户控制的强一致性反馈确认：普通 KNX→Mesh 控制依然使用 5 次递归重试 + 状态查询 + switchState 位掩码解析的闭环机制，依旧保证“用户在 KNX 侧最后一次操作的目标状态”必须在 Mesh 侧达成，同时将中间的超时/查询失败日志保持在 debug 级别，生产环境只在最终失败时输出一条 warn 级告警。
  • 方向性与回显保护说明：明确 KNX→Mesh 控制周期内 Mesh 只作为执行端与状态上报端——由 KNX 写入产生的状态变化会被标记为“非用户控制”，并在 800ms 全局 KNX 活动窗口内阻止任何 Mesh→KNX 反向写入；同时回显检测仅作用于控制地址，在 500ms 窗口内对“值相同的回包”直接丢弃，状态地址与指示灯反馈永远不会被当作新的控制命令，彻底避免 KNX/Mesh 之间因为回显导致的死循环。

v1.9.3 (2026-02-02)

Symi KNX Bridge 稳定性修复

  • 修复编辑器红三角问题：symi-knx-bridge 节点的 echoWindow 配置在旧 flows.json 中缺失时会导致校验失败，节点虽然工作正常但编辑器一直显示红色错误标记；现在允许 echoWindow 为空/未定义时通过校验，并在内部使用默认值 500ms。
  • 修复 KNX 输入解析异常：修复 parseBoolean 在 KNX 输入处理流程中被提前使用导致的 ReferenceError: Cannot access 'parseBoolean' before initialization，该问题会在 Mesh→KNX 同步反馈时刷大量红色错误日志并影响反馈确认重试逻辑。
  • 反馈确认逻辑稳固：
    • 在不改变 1.9.2 行为的前提下，确保 KNX 侧状态反馈在所有路径中都能被正确解析、确认和清理待确认记录，避免错误重试和“看起来已经同步但日志持续重试”的情况。
    • 快速多次控制仅认最后一次状态（Last Write Wins）：同一设备同一通道/同一 KNX 组地址的待确认记录在新增时会覆盖旧记录，确保在类似你日志中 0/0/1 快速连按、出现多次“反馈确认/重试”时，只追踪“最后一次希望达到的状态”，中间过程状态（含查询重试）不会被再次强制执行或反向触发。
    • 降噪优化，避免生产环境刷屏：反馈确认过程中关于“超时未收到反馈(重试x/x)”“查询后状态不一致/无法获取状态”“Mesh设备不存在/查询失败，重发命令”等内部诊断信息统一下调为 debug 级日志，正常 Info/Warn 级别只会在最终失败（已重试 5 次仍不同步）时输出一条告警，确保长期运行不刷屏。

v1.9.2 (2026-02-02)

回显检测优化

  • 正常情况下不会回显：KNX反馈应该使用状态地址（knxAddrStatus），而我们发送的是控制地址（knxAddrCmd），地址不同，不会造成回显
  • 优化回显检测逻辑：如果收到的是状态地址且与控制地址不同，不当作回显（正常情况下状态地址不会回显）
  • 可配置回显检测时间窗口：支持在节点配置中设置回显检测时间窗口（默认500ms），适用于反馈也使用控制地址的特殊情况
  • 确保大量设备控制时也能正确工作：优化后的逻辑确保在50个KNX开关组地址场景下也能完美解析处理同步Mesh对应的开关状态，不会造成回显反控的情况

修复

  • 【关键修复】KNX->Mesh控制必须确保同步成功：
    • 问题：KNX控制Mesh后，如果Mesh没有及时反馈状态，系统就停止处理，导致同步失败
    • 修复：
      • 增强重试机制：从1次重试增加到5次（MAX_RETRY_COUNT），确保必须同步成功
      • 递归重试逻辑：超时后查询Mesh状态，如果状态不一致则重发命令，继续等待反馈，直到成功或达到最大重试次数
      • 改进反馈确认：支持多种状态格式（switch_${channel}、switch、switchState位掩码），确保能正确识别Mesh状态反馈
      • 重试时复用待确认记录：重试时不会创建新的待确认记录，而是更新现有的记录，避免重复确认
      • 确保双向同步可靠性：谁主动发起的控制，另一方必须达到最终的同步状态效果
  • 【关键修复】场景批量命令导致反向同步问题：
    • 问题：场景触发时，多个KNX设备在短时间内（如500ms内）陆续动作，只有被直接控制的设备会更新单设备时间戳，场景中的其他设备如果没有被直接控制，或者isUserControl判断错误，就会漏掉检查，导致Mesh状态返回时触发反向同步到KNX
    • 修复：
      • 新增全局KNX活动时间戳lastKnxActivityTime，每次收到KNX命令时更新（第1815行）
      • 在Mesh→KNX同步检查时，优先检查全局时间戳（第462-468行通用设备，第549-555行开关设备，第618-623行调光灯设备）
      • 无论哪个设备被KNX控制，只要在800ms活动窗口内，就阻止所有Mesh→KNX同步
      • 与单设备时间戳形成双层保护机制，确保场景批量命令时不会触发反向同步
  • 【关键优化】批量处理逻辑完善：
    • Mesh→KNX方向：
      • 当Mesh设备的所有通道同时变化时（如4键或6键面板同时按下多个按键），handleSwitchState方法会解析一行代码的所有按键状态（lib/device-manager.js第464-617行）
      • 解析后的状态会触发device-state-changed事件，包含所有变化的按键状态（changedState对象）
      • KNX Bridge会遍历所有匹配的映射，收集所有开关命令到batchCommands数组，使用相同的时间戳（nodes/symi-knx-bridge.js第460-591行）
      • 批量加入队列后统一处理，确保所有映射的KNX地址都能正确同步（第845-863行）
      • 不会一个一个按键去列队，而是一行代码给该开关的所有按键去同步真实状态
    • KNX→Mesh方向：
      • 当KNX同时触发同一Mesh设备的多个通道时，会收集所有命令到cmds数组（批量处理逻辑）
      • 使用syncKnxToMeshBatch方法，收集所有通道的目标状态到channelStates对象（第1422-1473行）
      • 使用buildSwitchState按通道顺序应用状态变化，构建最终状态（第1496-1511行）
      • 一行代码发送整个面板状态，不会逐个按键发送（第1528-1562行）
      • KNX会正确解析一行代码一个开关的所有按键的状态，触发KNX的开关组地址正确完成同步
    • 支持4键和6键面板（1-2-3-4-6键），100%正确匹配，单个按键动作或多个按键同时动作都能正确处理

v1.9.1 (2026-01-31)

修复

  • 【关键修复】AutoSync读取地址错误导致状态丢失：
    • 错误：Mesh控制KNX后，AutoSync读取了状态地址（knxAddrStatus）而不是控制地址（knxAddrCmd），导致读取的状态与Mesh发送的地址不一致，出现"Mesh控制KNX后状态丢失"的问题
    • 修复：AutoSync现在优先读取控制地址（knxAddrCmd），如果配置了独立的状态地址且与控制地址不同，才读取状态地址。确保AutoSync读取的地址与Mesh发送的地址一致
  • knxControlTimestamps检查过于严格：
    • 错误：knxControlTimestamps检查在所有情况下都会阻止Mesh→KNX同步，包括状态反馈场景，导致状态反馈被错误阻止
    • 修复：现在只在isUserControl=true时检查，避免状态反馈被错误阻止
  • KNX控制保护期错误阻止KNX→Mesh同步：
    • 错误：knxControlTimestamps被错误地用于阻止KNX→Mesh同步，导致KNX控制一次后无法再次控制Mesh设备
    • 修复：删除了错误的检查逻辑，knxControlTimestamps只用于阻止Mesh→KNX同步，KNX可以随时控制Mesh设备
  • AutoSync防抖机制跳过状态匹配：
    • 错误：AutoSync防抖机制在时间窗口内会跳过状态匹配，导致某些Mesh控制后没有触发状态匹配
    • 修复：改为重置定时器而不是跳过，确保每次Mesh控制后都会触发状态匹配
  • AutoSync状态校准使用缓存导致误判：
    • 错误：状态校准逻辑直接使用Mesh缓存状态，可能导致因缓存不准确而误判状态不一致
    • 修复：当检测到KNX状态与Mesh缓存状态不一致时，先查询Mesh设备的实际状态（发送0x32查询指令），等待500ms让Mesh设备响应后，再次检查状态，确保使用真实状态。只有在查询后确认状态仍不一致时，才发送校准命令到Mesh设备
  • KNX控制后状态反馈被误判为用户控制：
    • 错误：KNX控制Mesh设备后，Mesh返回的状态反馈被误判为用户控制，触发Mesh→KNX反向同步，导致死循环
    • 修复：当收到0xB0控制响应或0xB2查询响应后，500ms内的状态反馈帧（包括开关和窗帘）会被正确识别为控制响应，标记为isUserControl=false，不会触发反向同步
  • 批量发送时间戳记录时机错误：
    • 错误：批量发送时时间戳记录时机不正确，导致回显检测不准确，自己发送的命令被误判为回显
    • 修复：批量发送时时间戳在实际发送时记录，确保时间戳准确，提升回显检测准确性
  • 首次部署查询逻辑优化：
    • 错误：三合一设备检测使用固定2秒等待时间，查询完成后使用固定3秒等待时间，导致查询时间不准确
    • 修复：
      • 三合一设备检测：发送查询请求后立即继续查询完整状态，不再等待固定时间（响应通过事件异步处理）
      • 查询完成等待：根据实际查询的设备数量动态计算等待时间（查询间隔50ms × 设备数量 + 响应时间200ms + 缓冲时间200ms）
      • 确保查询的目的是：根据匹配的同步数据去查询真实映射设备的状态，然后同步给KNX/HA/MQTT等系统
      • 查询完成后正确传递设备列表给同步节点，确保状态校准基于实际查询到的设备
      • 部署后逻辑：
        1. 先获取mesh网关设备列表
        2. 然后根据映射节点的同步设备去同步状态，把真实设备的状态发送给mesh设备去同步状态
        3. 然后就稳定的根据双方的主动发起的控制去同步另外一方的状态，并且不会造成死循环的情况

优化

  • AutoSync触发范围扩展：为所有设备类型（开关、场景、调光灯、窗帘、空调、新风、地暖）的Mesh控制都添加了AutoSync触发，确保每次Mesh同步动作后都能匹配一次状态
  • 批量处理优化（全节点）：
    • KNX Bridge双向批量处理：
      • KNX→Mesh批量处理：当KNX同时触发同一Mesh设备的多个通道时，自动合并为一行码发送
      • Mesh→KNX批量处理：当Mesh同时改变同一设备的多个开关通道时，批量发送到不同的KNX地址，按通道顺序排序确保一致性
      • 批量处理时间窗口：100ms内收到的同一设备的开关命令会自动合并
      • 支持状态组合算法：正确计算多路开关的最终状态值，确保所有通道状态一次性同步
      • 协议格式优化：开关控制消息类型统一为0x02 (TYPE_ON_OFF)，1-4路使用1字节参数，6-8路使用2字节参数（小端序）
    • HA Sync批量处理：当HA同时控制同一Mesh设备的多个通道时，自动合并为一行码发送
    • RS485 Bridge批量处理：当RS485同时控制同一Mesh设备的多个通道时，自动合并为一行码发送
    • 优化网络传输效率：减少Mesh网关的通信压力，提升响应速度，确保高效稳定的双向同步

v1.9.0 (2026-01-29)

修复

  • KNX-HA Bridge映射显示修复：
    • 错误：映射列表左右两侧（KNX实体和HA实体）选择器不显示，映射数据绑定问题导致数据无法正确保存
    • 修复：修复了映射数据绑定问题，确保映射数据正确保存到容器；修复了映射加载逻辑，清空现有映射后再加载；优化了初始化顺序：先加载KNX实体，再加载映射，最后加载HA实体；修复了KNX和HA选项更新时机，在所有相关操作后都会同步更新两个选项列表
  • KNX-HA Bridge代码质量优化：
    • 错误：防死循环跳过日志过多，节点关闭时队列处理可能继续运行导致内存泄漏，命令队列去重逻辑不够完善
    • 修复：优化日志级别为debug级别；添加 isClosed 标志确保节点关闭时队列处理正确停止；完善防死循环保护，验证所有同步路径都有防死循环检查；优化命令队列去重逻辑，检查值是否相同而不仅仅是时间窗口；添加状态缓存检查，同步前检查值是否真的改变
  • 日志刷屏问题修复：
    • 错误：KNX-HA Bridge的 /ha-entities 接口在编辑器重复请求时反复打日志；MQTT重连时重复发布Discovery配置导致日志刷屏
    • 修复：将日志级别降为 debug，并添加30秒缓存；MQTT连接时不再清空已发布设备记录，避免重复生成实体日志
  • 首次部署状态查询（v1.9.1）：
    • 首次启动时：执行一次状态查询，用于：
      • 主动查询三合一设备：通过查询 0x68 新风开关和 0x6B 地暖开关来检测三合一设备
        • 查询结果会自动调用 markAsThreeInOne 持久化保存到文件
        • 确保网关断网断电后不会变回温控器（从文件恢复三合一状态）
        • 去重逻辑：已确认的三合一设备不会重新检测
      • 获取每个同步映射的初始状态（用于KNX-HA Bridge等同步节点进行状态校准）
    • 运行过程中：不再主动使用 53 32 查询命令，完全依赖设备主动上报
    • 原因：运行过程中的查询命令会导致丢包，影响网关正常设备上报和下发
    • 改进：系统在首次启动时查询一次后，完全依赖设备主动上报（0x80状态事件），提高稳定性
    • 三合一检测：
      • 首次启动时：主动查询 0x68/0x6B 检测，结果持久化保存
      • 运行过程中：依赖设备主动上报的 0x94 消息或 0x68/0x6B 属性（也会持久化保存）
    • 持久化保存：三合一设备状态保存在 ~/.node-red/symi-mesh-data/three-in-one-devices-{gatewayId}.json
    • 修复：现在默认值会正确显示为"关闭 (默认)"
  • 设备控制节点场景ID保存和加载问题：
    • 错误：选择虚拟场景时场景ID没有正确保存，场景ID在编辑面板中不显示，场景ID输入框显示逻辑不正确
    • 修复：场景ID会正确保存到配置中；场景ID会正确加载和显示已保存的值；场景ID输入框会根据通道类型（mesh_scene或scene1-6）正确显示/隐藏

优化

  • 首次部署状态查询（v1.9.1）：
    • 首次启动时主动查询三合一设备（0x68/0x6B），结果持久化保存
    • 运行过程中不再使用 53 32 查询命令，完全依赖设备主动上报，避免查询导致丢包问题
    • KNX Bridge的AutoSync状态校准使用独立的查询机制，不会与首次部署查询冲突
  • KNX Bridge双向同步优化：正确处理状态反馈地址（statusAddr），状态反馈不会记录时间戳，不会触发反向控制保护；AutoSync校准命令发送后立即更新控制时间戳，防止反向同步；优化队列处理，确保在大量KNX数据时稳定运行

更新日志（历史版本）

v1.9.0 (2026-01-29)

新增功能

  • 按键场景触发支持：在所有同步节点（KNX、RS485、HA、MQTT）的通道选择中，新增"按键X场景"选项（X为1-6），支持场景ID范围2-95
  • 虚拟场景实体：新增永久生效的虚拟场景设备，固定MAC地址00:00:00:00:00:00，支持全协议联动
  • 设备发现优化：53 12 00 41 设备列表查询仅在部署/重启时执行一次，避免重复查询导致丢包
  • KNX状态反馈地址优化：区分控制地址和状态反馈地址的处理逻辑，避免状态反馈地址触发反向控制
  • 设备发现增强：自动处理TCP分包粘包问题，完整性验证，10秒超时保护，去重机制，进度跟踪

修复

  • 配置持久化问题：修复了"选择场景按键后部署不生效"的问题，恢复Node-RED原生的"确认保存"机制
  • RS485同步节点虚拟设备注册问题：修复了虚拟设备注册问题
  • 连接错误处理：网关连接失败时采用静默重连机制，网络错误不输出错误日志，避免反复提醒

优化

  • 窗帘控制优化：针对RS485窗帘增加1秒的控制锁（防回弹锁定），防止因控制过快导致的丢包或状态死循环
  • UI交互改进：所有同步节点UI适配场景选择逻辑，支持根据通道类型动态显示场景ID输入框
  • 稳定性增强：完善各同步节点的全局状态查询参与机制，设备去重机制，映射关系持久化，确保配置不丢失

Node Info

Version: 1.9.6
Updated 1 day ago
License: MIT
Rating: not yet rated
View on npm
View on GitHub
View Scorecard 11 1

Categories

Actions

Rate:

Downloads

335 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