node-red-contrib-symi-mesh 1.9.7

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状态事件，实时反馈设备状态变化
    • 依赖主动上报与主动校准：移除常规轮询，正常运行完全依赖设备主动上报；仅在 KNX/Mesh 同步校准时使用 0x32 指令进行主动查询，确保状态对齐的准确性
    • 三合一设备检测：通过设备主动上报的 0x94 消息或 0x68/0x6B 属性自动识别三合一面板
  • 多设备类型：支持开关、灯光、窗帘、温控器、传感器等12+种设备
  • 三合一面板：完整支持空调+新风+地暖三合一控制面板，自动识别
  • RS485/Modbus集成：支持第三方485设备双向同步，内置协议模板，支持中弘VRF、SYMI面板协议
  • RS485同步增强：symi-rs485-sync 节点已全面重构，采用统一防环路机制，支持多台空调内机批量状态同步和三合一子实体增强映射
  • 自动状态同步：支持状态自动校准与防死循环，开启后 Mesh 或 KNX 设备动作将触发延迟状态读取，强制对齐两端状态
  • 查询优化：严格区分 KNX 读取请求（GroupValue_Read），查询时直接回复缓存状态，不再触发设备控制，彻底解决“查询即关闭”问题
  • Mesh 主动查询：同步时自动下发 0x32 指令查询 Mesh 实时状态，确保校准依据准确
  • 介入日志：控制台实时输出 [Mesh->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状态事件）
    • 这样可以避免频繁查询导致的无线丢包问题，提高系统稳定性
    • 按需主动查询 (v1.9.7)：仅在执行校准或特定同步逻辑时主动下发查询指令，确保数据对齐

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）时，系统启动可配置的延迟倒计时（默认 3 秒）。
  2. 规定时间内完成查询：延迟结束后，先向所有涉及的 Mesh 设备下发 0x32 状态查询，约 1 秒后再向已映射的 KNX 组地址发送 GroupValue_Read；收到 GroupValue_Response 后与 Mesh 实时状态比对。
  3. 状态对齐：
    • 智能比对：比较 KNX 状态与 Mesh 状态（Mesh 状态来自 0x32 查询后的缓存）。
    • 按需同步：若不一致，仅向 Mesh 下发校准命令（标记为校准，不触发反向 KNX 控制）；若一致，仅更新内部缓存，不下发任何控制。
  4. 查询不改变 KNX 状态：KNX 侧仅发送 GroupValue_Read、接收 GroupValue_Response，绝不向总线发送 Write，因此状态查询不会改变 KNX 开关状态。
  5. 无真实设备/无反馈时的防护：若某 KNX 组地址无真实设备或无法反馈，读回可能为默认/错误值，若直接按读回值同步到 Mesh 会导致误关灯。本节点已做防护：若近期（5 秒内）我们向该地址写过与读回值相反的值（例如刚写过 ON 但读回 OFF），则仅更新缓存、不向 Mesh 下发校准，并打日志「近期已向KNX写入与读回值相反，可能无真实设备/反馈，仅更新缓存不同步到Mesh」。使用真实 KNX 设备时，读回与写入一致则正常同步。
  6. 介入日志：控制台输出 [DelayedSync] / [Mesh->KNX介入] 等日志，便于核对校准过程。
  7. 效果：在规定延迟内完成 Mesh 与 KNX 的状态查询与比对，确保两端对齐，避免二次控制失败。

配置方法：

  • 开启自动状态校准：勾选此项开启全局校准。
  • 校准延迟(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.7 (2026-02-28)

自动状态校准 (AutoSync) 与状态查询逻辑

  • KNX Bridge「自动同步状态」：开启后，Mesh 或 KNX 动作触发可配置延迟（默认 3s）；在规定时间内完成：先对涉及设备发 0x32 查 Mesh 状态，约 1s 后发 KNX GroupValue_Read，收到 GroupValue_Response 后与 Mesh 比对，不一致则仅同步到 Mesh（校准），一致则仅更新缓存不下发；校准命令带 isCalibration，不触发反向 KNX 控制。
  • KNX 状态查询不改变总线状态：仅发送 GroupValue_Read、接收 Response，绝不向 KNX 总线写 Write，查询不会改变 KNX 开关状态。
  • GroupValue_Read 处理：严格区分 Read/Response/Write；对 GroupValue_Read 只回复缓存状态，不触发 Mesh 控制，修复 Read 分支中 mapping/addrFunc 未定义导致的引用错误。
  • DelayedSync 读响应不误触 HA：部分 KNX 库将 GroupValue_Response 标为 Write 输出，导致 KNX-HA Bridge 误执行关灯。通过 global 约定 DelayedSync 读阶段与地址列表，KNX-HA Bridge 在此窗口内忽略这些地址的报文，避免状态查询触发 HA 控制。
  • Mesh 设备查询与 MAC 格式：DelayedSync 与 DeviceManager getDeviceByMac 兼容带冒号/无冒号 MAC，确保能正确触发 0x32 查询并获取 Mesh 状态参与比对（修复「已触发 0 个 Mesh 设备的状态查询」）。
  • DelayedSync 误关灯防护：当 KNX 组地址无真实设备或无反馈时，读回值可能错误（如刚写入 ON 却读回 OFF），若直接同步到 Mesh 会误关灯。已增加防护：5 秒内若我们向该地址写过与读回值相反的值，则仅更新缓存、不同步到 Mesh，并用日志提示，使用真实设备时行为正常。

界面与体验

  • 配置项布局优化：修复「自动同步状态」在某些分辨率下的换行问题。
  • 日志分级：生产环境默认静默，关键介入逻辑使用 node.log 确保可追溯。

v1.9.0 - v1.9.6 历史迭代汇总

核心修复与优化

  • 防反向控制与回显保护：
    • 引入 3秒全局 KNX 主控窗口，确保快速连按时“最后一次操作”生效，阻止延迟反馈导致的状态回弹。
    • 完善 Last Write Wins (最终写入获胜) 逻辑，多路开关采用 2-bit 编码解析，确保状态收敛。
    • 支持可配置的 回显检测时间窗口 (默认 500ms)，严格区分控制地址与状态地址。
  • 批量处理与性能：
    • 实现 双向批量处理：同一设备的多个通道动作合并为单条协议指令（一行代码），大幅降低总线负载。
    • 优化 部署查询逻辑：启动时 AutoSync 与 StateQuery 互斥，避免重复读取；动态计算设备列表查询等待时间。
    • 网关限流机制：统一全局同步参数（队列长度 100，间隔 50ms），保障 50+ 实体大规模场景稳定性。
  • 同步与兼容性：
    • 窗帘/调光同步增强：区分主控来源（isFromStateQuery），部署或后台同步时不驱动真实电机；支持调光/窗帘锁定时间配置。
    • 反馈确认闭环：对用户控制引入 5 次重试 + 状态查询闭环，确保控制指令 100% 送达。
    • 多协议联动：修复 KNX-HA Bridge、MQTT Sync 等映射保存与显示问题，支持空调/新风/地暖三合一面板自动识别。
  • 智能初始化与发现：
    • 首次启动状态快照：仅在部署后执行一次全局状态查询，用于三合一设备检测与持久化缓存（~/.node-red/symi-mesh-data/），运行中完全依赖 0x80 事件上报，彻底解决查询导致的丢包问题。
    • 增强设备发现：自动处理 TCP 分包粘包，提供 10s 超时保护与完整性报告，去重机制按 index 确保唯一。
  • 虚拟化与场景支持：
    • 支持 虚拟场景实体 (MAC: 00:00:00:00:00:00)，支持 KNX、RS485、HA、MQTT 全协议联动触发。
    • 新增 按键场景触发 (0x34)，支持场景 ID 2-95，满足本地场景上报需求。
  • 工程化改进：
    • 生产环境默认 静默日志，关键逻辑使用 debug 级并带 30s 缓存，避免日志刷屏。
    • 修复了大量编辑器红三角校验、变量初始化顺序、内存泄漏及配置持久化保存隐患。

Node Info

Version: 1.9.7
Updated 5 days ago
License: MIT
Rating: not yet rated
View on npm
View on GitHub
View Scorecard 11 1

Categories

Actions

Rate:

Downloads

58 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