node-red-contrib-symi-mesh 1.9.42

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 Node.js 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；所有桥接/同步节点共享该参数
  • 反馈确认熔断：智能反馈确认机制，自动检测设备离线状态，避免对不存在/离线设备持续重试
  • 云端同步：从酒店云云平台自动获取设备名称和场景信息
  • 稳定可靠：完善的错误处理和自动重连机制
  • 设备去重保证：所有节点设备列表均采用唯一性保证，确保设备不重复
  • 配置持久化：所有映射关系自动保存，重启后自动恢复，确保配置不丢失
  • 静默重连：网络错误静默处理，自动重连，避免日志刷屏
  • 生产级日志策略：默认仅输出低频关键业务日志（用户操作、控制回执、同步介入），高频诊断需环境变量开启，重复警告自动限流

节点概览

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

节点名称 类型 功能描述
Symi Gateway 配置节点 核心连接中心，支持 TCP/IP (4196端口) 或 串口连接，集成 MQTT 代理配置。
Symi Device 控制节点 Mesh 设备操作核心，支持开关、调光、窗帘、三合一温控等全品类控制与状态反馈。
Symi MQTT 配置节点 共享的 MQTT+网关配置（自动发现 Mesh 设备并发布至 MQTT，支持 Home Assistant 自动发现），供 HA Sync / MQTT Sync 等节点复用。
Symi KNX Bridge 桥接节点 KNX 与 Mesh 互联核心，支持状态自动校准、防死循环逻辑及大规模实体映射。
Symi HA Sync 同步节点 实现 Mesh 设备与 Home Assistant 实体间的双向实时同步，内置窗帘防震荡逻辑。
Symi MQTT Sync 同步节点 第三方 MQTT 品牌（如花语前湾）与 Symi Mesh 设备的双向同步。
Symi MQTT Brand 配置节点 第三方品牌 MQTT 服务器连接配置（如 HYQW 花语前湾协议），供 MQTT Sync 节点选择。
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

npm 登录与发布（维护者）：

本仓库根目录 .npmrc 已指定官方源 https://registry.npmjs.org/。若全局 ~/.npmrc 配置了 registry=https://registry.npmmirror.com/，在本目录执行 npm login 会跳到 npmmirror，无法登录 npm 官方。请在本仓库目录使用：

cd /path/to/node-red-contrib-symi-mesh
npm login --registry https://registry.npmjs.org
# 或依赖 ~/.npmrc 中已有的 //registry.npmjs.org/:_authToken 直接发布
npm publish

客户安装仍可使用任意镜像：npm install node-red-contrib-symi-mesh（镜像会同步 npm 官方包）。

安装后重启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服务器；该节点同时是 HA Sync / MQTT Sync 等节点的设备信息来源。

4. 部署并验证

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

KNX 用户看这里：如果你要用 KNX 桥接（Mesh 设备与 KNX 总线双向同步），请先执行 cd ~/.node-red && npm install node-red-contrib-knx-ultimate 安装 KNX 节点，然后直接阅读下文 「Symi KNX Bridge 桥接节点」 章节的完整配置步骤（含实体导入格式与示例流程 08 的导入方法）。

日志与排障

本插件面向酒店/大规模部署，日志策略为默认只输出低频关键业务日志（用户物理操作、控制回执、同步介入、场景事件），高频诊断信息（状态帧解析、映射匹配等）仅在调试模式可见；可能出现重复的警告（如网络噪音导致的解析失败）做了限流（默认同 key 60 秒一条），避免日志风暴。

默认行为（推荐生产）

  • 不设置任何环境变量：仅输出低频关键业务日志，节点状态（Status）显示连接与映射情况。
  • 网络类未捕获异常（ECONNRESET 等）已被全局兜底，不会刷屏或导致 Node-RED 崩溃。

需要排障时开启诊断日志

通过环境变量开启（重启 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；导入前必须先安装 node-red-contrib-knx-ultimate，否则 knxUltimate 节点会显示为"未知节点"）。已内置 9 条实体模板与 9 条示例映射（执行器1/2 开关、全开/全关场景、双色调光、窗帘、空调、新风、地暖；覆盖 6 类设备实体，场景与 KNX 地址对齐融合网关 0/0/1~2/1/24 实际地址体系；三合一设备 cd:d2:57:93:46:84 预置空调+新风+地暖 3 条子实体映射）。导入后只需：①修改网关串口/TCP 与 KNX 网关 IP；②把映射中的 Mesh 设备 MAC 替换为您现场的设备（在映射下拉框重新选择即可）
  • 09 - KNX ↔ HA 桥接：examples/09-symi-knx-ha-bridge.json（symi-knx-ha-bridge；导入前必须先安装 node-red-contrib-knx-ultimate 与 Home Assistant 相关节点）。已内置 6 类实体模板与 6 条示例映射（HA 实体 ID 为示例如 switch.relay_1，导入后替换为现场实体并选择 HA server 节点）
  • 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) switch 开关+场景功能（1-4路，固定场景个数；HA 实体为 switch，场景触发走按键场景通道）
五色调光灯 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防死循环时间窗口，增强型状态回传过滤逻辑
  • 组地址合法性：本节点将 KNX 组地址（GA）以标准字符串透传，合法性校验由上游 node-red-contrib-knx-ultimate 节点负责（其在接入总线时已过滤非法组地址）。本节点不重复实现地址解析，避免与 knxUltimate 的循环引用保护冲突。

配置步骤：

  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 桥接节点 →「同步设置」内联面板）：

参数 默认值 说明
场景遮蔽 (sceneVeilMs) 2000ms Mesh 场景触发后短时遮蔽，避免互斥场景同帧双发
反馈抑制 (meshFeedbackSuppressMs) 3000ms KNX→Mesh 后 Mesh 中间帧反写 KNX 的抑制窗口；单路开关通常 3 秒内放行用户反馈，不建议超过 5000ms（现场 8000ms 会导致单路控制等待过久）
场景结算 (sceneSettleMs) 3000ms KNX 场景批次展开结束后，0x32 刷新 + KNX Read 纠偏的等待时间
自动同步延迟 3000ms AutoSync / DelayedSync 触发前的延迟

防死循环机制： 系统会自动识别校准产生的回复消息，仅更新内部状态，绝不会再次触发反向控制发送给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. 最多重试1次（避免场景批量控制时重发过多报文挤爆总线；配合乐观回写与熔断窗口保障最终一致）
    • 快速连按最终收敛（Last Write Wins）：在 3 秒 KNX 主控窗口内，若Mesh尾帧/抖动导致最终状态跑偏，会自动纠错补发（限频，最多1次），确保最终一致。
    • 多路开关解析一致性：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) 场景

三合一设备（空调+新风+地暖）必须拆成 3 条映射：

一条 Mesh 三合一设备同时承载空调、新风、地暖三个子系统，在 KNX 桥接节点里必须为它建立 3 条映射，每条映射同一个 Mesh 设备、选择不同的 KNX 子实体：

映射 实体类型 实体名称 命令地址 状态/扩展地址
空调 climate e.g. 温控器 cmdAddr 开关 statusAddr 温度、ext1 模式、ext2 风速、ext3 当前温度
新风 fresh_air e.g. 新风 cmdAddr 开关 statusAddr 风速
地暖 floor_heating e.g. 地暖 cmdAddr 开关 statusAddr 温度、ext1 当前温度

映射一旦建立，Mesh 设备上报时会自动按设备类型分发给 3 条映射分别同步到对应 KNX 地址，互不干扰。设备发现日志会显示 找到3个映射，代表三条子系统均被关联。

三合一 KNX 实体导入示例（Tab 分隔）：

温控器	climate	0/0/11	0/0/12	0/0/13	0/0/14	0/1/14
新风	fresh_air	0/0/15	0/0/16
地暖	floor_heating	0/0/17	0/0/18	0/1/18

触发值与触发动作说明：

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

四键零火开关场景键（CH3/CH4）与 KNX 场景双向同步（v1.9.42）：

适用于米家四键零火开关：CH1/CH2 为负载继电器，CH3/CH4 为点动场景键（按下自动复位，不上报 OFF）。需在 KNX 桥接节点完成以下配置：

  1. KNX 实体库 — 新增 2 条 scene 实体（可共用同一组地址 0/0/20）：

    全开场景    scene    0/0/20            1    1
全关场景    scene    0/0/20            2    1
    • 场景号 (triggerValue)：填 ETS/面板场景号（1=全开、2=全关），配置几发几，系统内部自动换算总线字节，不要手动 +1。
    • Mesh动作 (triggerAction)：点动场景键填 1（按下=触发开/激活）。

  2. 设备映射 — 同一 Mesh 四键开关建 4 行（CH1/CH2 负载 + CH3/CH4 场景）：

    Mesh 设备 通道 场景ID KNX 实体
    四键开关 MAC 1 - 执行器1 (switch)
    四键开关 MAC 2 - 执行器2 (switch)
    四键开关 MAC 3 - 全开场景 (scene)
    四键开关 MAC 4 - 全关场景 (scene)

  3. Flow 接线：

    [knxUltimate-in] → [symi-knx-bridge 输入] → [symi-knx-bridge KNX输出] → [knxUltimate-out]
[symi-gateway] ──(配置引用)──→ [symi-knx-bridge]

  4. 行为说明（与日志关键字对照）：

    • Mesh 按 CH3/CH4 → KNX 收到 DPT18 场景字节（日志 [Mesh->KNX] 场景触发 + scenenumber:1/2）。
    • KNX 触发场景 1/2 → Mesh 仅翻转对应场景键，CH1/CH2 负载状态保持（日志 [KNX->Mesh] 场景触发 ... 精确状态 0x..., 负载通道保持）。
    • 总线回显会被拦截（跳过场景触发(总线回显)），避免死循环。

  5. 可选：导入 examples/08-symi-knx-bridge.json 作为模板（已含 9 实体 / 9 映射及 meshFeedbackSuppressMs=3000）。

注意：四键面板 CH3/CH4 走 KNX scene 实体映射 + 精确状态组包；与下方「按键X场景 / Mesh场景 / 0x34」是不同链路——后者用于 HA/MQTT/RS485 同步节点或映射通道选 mesh_scene 时触发 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 设备参与 A↔B 同步；纯两条 RS485 总线间同步可留空，示例 06 即为无网关的纯总线同步）
    • 选择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. 部署后即可实现场景联动

按键场景触发（Mesh 内置场景 / 0x34）

在 HA / MQTT / RS485 同步节点（以及 KNX 桥接映射通道选 mesh_scene 时）可用「按键X场景」或「Mesh场景」通道。

功能说明：

  • 选择后通过 gateway.sendScene(sceneId) 发送串口协议 0x34 Mesh 内置场景控制帧，替代继电器直控
  • 场景ID 默认 0（不触发）；有效范围 0-31（0=全关、1=全开为内置默认）及 64-95（自定义）
  • 与 KNX DPT18 场景实体相互独立：KNX 四键 CH3/CH4 请按上文「四键零火开关场景键」用 scene 实体 + 精确状态组包，不要与 0x34 混用

使用方式：

  1. 在同步节点的设备选择中，选择 Mesh 开关设备
  2. 通道选择「按键X场景」或「Mesh场景」
  3. 输入场景 ID（0-31 或 64-95，默认 0=不触发）
  4. 配置对应的外部系统实体
  5. 部署后，按键触发时将执行 Mesh 内置场景

更新日志

v1.9.42 场景键双向同步修复：4 键零火开关 CH3/CH4 + KNX→Mesh 精确状态 (2026-08-24)

排查 mesh 4 键零火开关 CH3/CH4 在双向同步中表现异常的两条根因链：

Mesh→KNX 链：CH3/CH4 点动按键时 mesh 上报 0x02 整包状态帧（含 CH1/CH2/CH3/CH4 全部位），且厂商老固件 NODE_STATUS 不携带 msg_type=0x0D 字段；按 v1.9.40 的 isUserControl 严格判定整包都被判为非用户控制 → bridge.js deviceType="scene" 分支 if (!eventData.isUserControl) continue 把整个场景触发判定拦住 → 按 CH3/CH4 KNX 端 0/0/20 永远收不到场景字节。修复：在 scene 分支加 4 键零火开关点动场景键精确放行（isFourKeyMomentary）—— deviceType="scene" 且 meshChannel 为数字 1-4 时直接放行（不依赖 isUserControl），其他场景键仍受 isUserControl 拦截网关回写。

KNX→Mesh 链：CH3/CH4 触发 KNX 场景后，若用 TYPE_ON_OFF 整包模拟按键或 pulse 全关基态，1 字节同时定义按键 1-4 位，会把其它已真实打开的按键位写成关，重复触发全开场景时 CH1/CH2 被"关闭又打开"。修复：KNX 场景触发主路径改用 buildSwitchState 精确状态组包——只翻转目标场景键（CH3/CH4），保留 CH1/CH2 负载通道当前状态，直接发 TYPE_ON_OFF 帧（日志关键字 精确状态）；不再用 pulse 全关基态，也不再对四键场景键走 mesh 内置 0x34。队列中仍保留 type="mesh_scene" 分支供映射表 meshChannel="mesh_scene" 等显式配置场景 ID 时使用。

配套修复：(a) isValidSceneId 场景ID 范围 2-31 → 0-31（mesh 协议 0=全关 1=全开内置默认，2-31/64-95=自定义），与 gateway.sendScene 一致；(b) isSceneChannel=true 路径增加 armSceneLoadSuppressForDevice(macNormalized, ...) 给同 MAC 负载通道打 5s 抑制标记（与 scene 分支 L1482 对齐），避免点动 CH3/CH4 触发的整包副作用误反写 KNX；(c) Mesh→KNX 出站写帧统一带 _internal: true，输入 handler 早返回逻辑与 v1.9.40 设计一致；(d) 默认 meshFeedbackSuppressMs 保持 3000ms（v1.9.31 现场 8000ms 过长，单路开关控制需等 8 秒才放行反馈，3000ms 为合理上限）。验证：本机 Node-RED v1.9.42 重复按 CH3/CH4 场景键各 2 次 + 重复开/重复关各 1 次，KNX 端 0/0/20 收到 DPT18 场景字节（1=全开 / 2=全关），CH1/CH2 无误反写，无重复误触发，symi 节点 0 Error/Warning。

  • scene 分支加 4 键零火开关点动场景键精确放行：symi-knx-bridge.js deviceType="scene" 分支在 switchKey 判定前增加 isFourKeyMomentary 条件——deviceType="scene" 且 meshChannel 为数字 1-4 时直接放行（mesh 物理按键即用户意图），其他场景键仍受 if (!eventData.isUserControl) continue 拦截网关回写/查询响应。现场 v1.9.31 同行为（gateway 内 [按键场景] 检测 lastChangedButtons 直接发场景，不依赖 isUserControl）。

  • KNX→Mesh 场景触发改用精确状态组包（主路径）：KNX 场景字节匹配 deviceType="scene" 映射后，用 protocolHandler.buildSwitchState 构造仅翻转目标 CH3/CH4 的 TYPE_ON_OFF 帧，负载通道 CH1/CH2 保持当前缓存状态；日志 [KNX->Mesh] 场景触发 ... (精确状态 0x..., 负载通道保持)。替代 v1.9.40 的 pulse 全关基态与整包误动方案。映射表 meshChannel="mesh_scene" 且配置了 sceneId 时，队列消费仍可走 gateway.sendScene（0x34）备用路径。

  • isValidSceneId 场景ID 范围扩展：bridge.js 场景ID 校验由 2-31/64-95 → 0-31/64-95（mesh 协议 MESH_SCENE_NO_ALL_OFF=0 / ALL_ON=1 内置默认），与 gateway.sendScene 范围校验一致；gateway.js sendScene 同步扩展。

  • isSceneChannel 路径加 sceneLoadSuppress 整包抑制：bridge.js mapping.deviceType="switch" 且 isSceneChannel=true（meshChannel 以 scene/mesh_scene 开头）分支触发场景后调用 node.armSceneLoadSuppressForDevice(macNormalized, ...)，给同 MAC 负载通道打 5s 抑制标记，与 deviceType="scene" 分支 L1482 对齐；避免点动 CH3/CH4 触发的整包副作用误反写 KNX。

  • Mesh→KNX 出站 _internal 标记补全：Mesh→KNX 写帧（含反馈重试）统一设置 _internal: true，与输入 handler msg._internal === true 早返回配对，避免 flow 回环时误触发 KNX→Mesh 控制逻辑。

  • 默认反馈抑制 3000ms：meshFeedbackSuppressMs 默认 3000ms（500–30000 可调）；示例 examples/08 同步为 3000ms。相对 v1.9.31 现场 8000ms，单路开关控制反馈放行更快，仍保留批次/reconcile 兜底。

  • 不动行为（用户业务约束）：mesh 4 键零火开关只支持开关模式（米家限制，不能用无线开关/场景模式）；CH3/CH4 仍是点动按键，按下自动复位不上报 OFF 帧（symi-gateway.js 点动按键自动复位不上报），与现场 v1.9.31 同行为。设备映射中 CH3/CH4 的 通道填 3/4，KNX 实体类型选 scene（不要与下方 0x34「Mesh场景」通道混用）。

  • 验证：npm test 52 specs passing、npm run lint 0 errors；本机 Node-RED v1.9.42 启动 + 现场控制验证：日志 [Mesh->KNX] 场景触发 / [KNX->Mesh] 场景触发 ... 精确状态 / SceneExecGuard / 场景批次 ... 3000ms 结算 均正常，DPT18 场景字节正确（1=全开 / 2=全关），CH1/CH2 无误反写，symi 节点 0 Error/Warning。

版本说明：npm 无 v1.9.41 包；v1.9.40 中规划的 _internal 补全、四键场景精确状态等 hotfix 已在 v1.9.42 一并交付。

v1.9.40 P0/P1 修复：首次对账 + 场景批次 reconcile + 测试覆盖 (2026-08-22)

v1.9.39 现场审查后三项修复 + 单元测试扩至 52 spec。v1.9.42 在此基础上完成 _internal 出站标记补全与四键场景精确状态组包。

  • 【P0 #1】输入 handler 早返回：由 topic 字符串匹配改为 msg._internal === true（v1.9.42 已补全 Mesh→KNX 写帧设置 _internal）。
  • 【P0 #2】首次状态 KNX 对账：首次 Mesh 状态仅缓存并标记 pendingFirstReconcile，待 KNX 反馈到达后轻量纠偏。
  • 【P1 #3】场景批次 reconcile：结算前不清空反馈缓存，0x32 刷新完成后再比对，避免批次期间误反写。
  • 测试：新增 test/sync-knx-to-mesh_spec.js、test/handle-mesh-state_spec.js 等，共 52 passing。

v1.9.33 反馈组地址透明化：实体面板统一字段 (2026-08-21)

KNX 实体「添加/编辑」面板第二个地址字段统一命名为「反馈组地址」（复杂类型括号内保留功能语义，如位置/温度/风速）。反馈组地址仅在 KNX 实体库录入（v1.9.39 起设备映射表不再展示反馈列，保持列表简洁）。

  • 实体面板：switch/light 等为独立反馈地址；cover/climate 等标签注明「同时承担反馈」。
  • 实体列表「反馈」列：展示各实体 feedback 组地址，便于核对。
  • 导入模板：Tab 分隔字段名统一为「反馈组地址」。

v1.9.32 全节点编辑托盘默认宽度加宽 (2026-08-21)

  • 全部 13 个节点编辑托盘默认约 950px（小屏自动收窄）；修复 symi-knx-bridge jQuery tray[0].getBoundingClientRect() bug。
  • 同步设置单行不换行；表单 flex 填满宽度；默认值与运行时常量一致（场景遮蔽 2000ms、反馈抑制 3000ms、场景结算 3000ms）。

v1.9.31 代码审查 + 编辑器面板优化 (2026-08-20)

  • 同步设置内联展开：自动同步/场景遮蔽/反馈抑制/场景结算收纳到「同步设置」，主面板仅保留网关、实体库、映射。
  • 移除孤儿模块 lib/knx-bridge-guards.js；485 断线不再重放过期队列。
  • 温度钳制：空调 16–30°C、地暖 18–32°C（Mesh 模组规格）。
  • Mesh 内置场景 (0x34) 与 KNX DPT18 场景语义分离；KNX 四键场景键配置见上文「四键零火开关场景键」（v1.9.42 起 KNX→Mesh 主路径为精确状态组包）。

v1.9.29 - v1.9.39 迭代汇总 (2026-08-20 ~ 2026-08-21)

中间版本要点合并如下；v1.9.41 未单独发包，相关 hotfix 已并入 v1.9.42。

  • v1.9.39：设备映射表移除「反馈地址」列；反馈组地址只在 KNX 实体库录入（showEntityPanel）。
  • v1.9.38：回退实体列表中的反馈地址字面量展示；保留 v1.9.37 数据模型与 lib/knx-entity-mapper.js。
  • v1.9.37：statusExt1/2/3 独立反馈地址；translateKnxEntityAddresses + getKnxAddrFunction；9 实体迁移兼容（statusExt 空则回退 statusAddr）。
  • v1.9.36：编辑面板标签按设备类型注明真实用途（如 cover「位置地址(同时承担反馈）」）。
  • v1.9.35：light_cct / cover 的 Mesh→KNX 路径补第 5 层拦截（lastKnxToMeshTime + meshFeedbackSuppressMs 默认 3000ms）。
  • v1.9.34：examples/08 全开/全关同地址 0/0/20、场景号 1/2；与 v1.9.33 UI 命名同步。
  • v1.9.30：场景/同步拦截点增加 isUserControl 前置判断——用户主动操作 5 秒内立刻放行。
  • v1.9.29：新增 lib/knx-scene.js（ETS 1–64 ↔ 总线 byte 0–63）；sceneEchoGuard / sceneExecGuard / sceneLoadSuppress；场景批次 + sceneSettleMs；首批 mocha 测试。注：v1.9.29 的 KNX→Mesh「场景脉冲」路径已被 v1.9.42 精确状态组包取代；Mesh 内置 0x34（mesh_scene 通道）仍保留。

v1.9.20 - v1.9.23 (2026-08-17/18) KNX/Mesh 同步链路迭代汇总

注：以下弱随 v1.9.23 发布。核心要点如下，详细改动见 Git 历史。

  • v1.9.23 (2026-08-18)：
    • KNX 功能地址判定修复：getKnxAddrFunction 判定顺序调整，功能地址（温度/模式/风速等）优先于 status，修复三合一设备温度/风速无法从 KNX 控制的问题。
    • KNX→Mesh 场景触发修复（DPT 18.001）：场景号解析兼容 knxUltimate 三种入站形态（优先 rawValue 原始字节），修复 parseInt 得 NaN 导致场景匹配失效。
    • 日志静默优化：状态事件解析失败、设备列表短帧日志降为 debug（生产无噪声）。
    • 示例预置：examples/08（KNX 桥接 9 实体/9 映射）、examples/09（KNX↔HA 6 实体）预置模板。
  • v1.9.22 (2026-08-17)：三合一设备 KNX 映射拆分为 climate/fresh_air/floor_heating 3 条映射；4 键面板按键 3/4 恢复为场景键；按实测回报时长收窄防回环窗口（实体控制锁 <1 秒）。
  • v1.9.21 (2026-08-17)：移除全局 KNX 活动窗口拦截、命令回环窗口 6s→2s 并引入值语义（0.8s 起反向操作立即生效）、场景遮蔽默认 3000→2000ms、命令队列实时优先（用户实体命令插队）。
  • v1.9.20 (2026-08-17)：修复 KNX 状态地址回报误刷新全局活动窗口导致用户 Mesh 操作被静默拦截；三处防回环拦截点恢复 debug 诊断日志；移除 KNX 桥接运行时统计面板避免覆盖关键状态提示。

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

较早迭代详见 Git 历史。核心方向：KNX/Mesh 双向同步可靠性、单一事件源、防死循环/防回弹、协议兼容、稳定性与合规、安装兼容性修复等。要点如下：

  • v1.9.12 (2026-04-10)：安装兼容性修复（必须升级）——降低 engines 至 node>=18 / npm>=8 / node-red>=3，修复 Node.js 20.x/Node-RED 3.x 下 EBADENGINE 安装失败；修复 symi-rs485-sync 节点 gateway 字段未初始化导致同步永不执行。
  • v1.9.11 (2026-03-30)：关闭 KNX→Mesh 后的 Mesh→KNX 反写回（knxControlTimestamps 窗口内无条件阻止）；MQTT 节点 connack timeout 握手超时非致命化并触发重连兜底。
  • v1.9.10 (2026-03-30)：发布包安装可靠性（必须）——修复 lock 文件中误将自身 .tgz 写为 file: 本地依赖，避免客户侧 tarball corrupted / ENOENT 安装失败。
  • v1.9.9 (2026-03-28)：KNX 桥同步可靠性（推荐 KNX 项目升级）——Mesh 写 KNX 对称主控、KNX 面板优先、状态反馈去重、场景遮蔽（SceneVeil）、默认关闭 LWW；DelayedSync 与 Mesh 查询回包、MQTT connack timeout 防崩、autoSyncEnabled 健壮解析。
  • v1.9.8 (2026-03-23)：稳定性、协议兼容性与合规性增强——引擎升级（Node>=22/NPM>=10/Node-RED>=4）、高并发与抗丢包测试策略、双向防死循环击穿修复、修复依赖 CVE、eslint 通过。
  • v1.9.7 (2026-02-28)：自动状态校准（AutoSync）与状态查询逻辑——自动同步状态、查询不改变总线状态、Read/Response/Write 严格区分、DelayedSync 读响应不误触 HA、误关灯防护、界面布局优化与日志分级。
  • v1.9.0 - v1.9.6：防反向控制与回显保护（3 秒主控窗口、回显检测窗口）、双向批量处理与网关限流、窗帘/调光同步增强、反馈确认闭环、多协议联动映射修复、首次启动状态快照与设备发现增强、虚拟化与场景支持（虚拟场景实体、按键场景触发 0x34）、工程化改进（静默日志与配置/内存泄漏修复）。

Node Info

Version: 1.9.42
Updated 2 weeks, 1 day ago
License: MIT
Rating: not yet rated
View on npm
View on GitHub
View Scorecard 11 1

Categories

Actions

Rate:

Downloads

410 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