node-red-contrib-symi-modbus 2.10.7 → 2.10.8

package/README.md

@@ -1,1061 +1,1077 @@
-# node-red-contrib-symi-modbus
-
-Node-RED的Modbus继电器控制节点，支持TCP/串口通信和MQTT集成，专为智能家居场景设计。
-
-[![npm version](https://badge.fury.io/js/node-red-contrib-symi-modbus.svg)](https://www.npmjs.com/package/node-red-contrib-symi-modbus)
-[![Node-RED](https://img.shields.io/badge/Node--RED-%3E%3D2.0.0-red)](https://nodered.org)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-## 核心特性
-
-- **双模式运行**：
-  - **本地模式**：纯串口/TCP通信，断网也能稳定运行，无需MQTT
-  - **MQTT模式**：可选接入Home Assistant等第三方平台
-- **工业级稳定性**：
-  - **多主站隔离**：采用实例级隔离机制，支持无限个主站和从站节点共存，配置互不干扰
-  - **智能分包/粘包处理**：内置1KB环形缓冲区和协议分析器，完美处理RS-485总线的分包、粘包问题
-  - **内存安全**：严格的内存管理策略，长时间运行内存不泄露，自动清理过期缓存
-  - **死锁防护**：多级看门狗机制，自动检测并恢复控制死循环，确保生产环境不卡顿
-- **Symi/Clowire生态集成**：
-  - **多协议支持**：完美支持Symi和Clowire（克伦威尔）双品牌协议，全面兼容 `0x03 SET`、`0x04 REPORT`、`0x05 STATUS` 等多种帧类型
-  - **全按键覆盖**：协议解析逻辑通用化，完美支持 1-8 号所有物理按键，不再局限于特定编号
-  - **蓝牙Mesh深度集成**：支持Symi蓝牙Mesh网关V1.3.1协议，实现无线开关秒级响应
-  - **设备持久化**：Mesh设备列表自动保存到磁盘，断电/重启/断网后配置不丢失
-- **反馈同步优化**：
-  - **轮询暂停机制**：上报数据时自动暂停主站轮询，防止状态回跳
-  - **REPORT协议强制化**：指示灯反馈强制使用REPORT (0x04)协议，不触发继电器动作，避免闪烁
-  - **指示灯状态强同步**：无论当前状态如何，物理按键操作都会强制下发指示灯同步指令，确保面板 LED 与系统状态严格一致，彻底解决状态错位导致的按键失灵
-  - **物理按键强制同步**：物理按键触发时强制同步 LED 反馈（忽略重复检查），纠正面板可能存在的状态不一致
-  - **协议解析安全化**：严格过滤 REPORT (0x04) 反馈回显数据，从源头上切断“反馈触发控制”的无限死循环，确保继电器不乱跳
-  - **精准反馈锁**：内置 **100ms** 毫秒级反馈锁，完美过滤 RS485 总线物理回显，同时确保高频连点操作不丢失状态
-- **高级控制功能**：
-  - **门禁联动过滤**：继电器节点支持门禁ID过滤，实现精确的门禁联动控制
-  - **HomeKit网桥**：一键接入Apple HomeKit，支持Siri语音控制，状态实时同步
-  - **智能写入队列**：所有写入操作串行执行，支持优先级管理，确保指示灯反馈在群控场景下秒级响应
-  - **多主站精准隔离**：支持多主站并行运行，通过 `masterId` 实现指令精准定向，严格过滤跨主站事件，彻底解决多主站环境下的控制冲突与误触发
-  - **智能反馈路由**：从站开关节点自动识别所属主站，仅响应目标主站的状态变化，防止多系统并存时的信号串扰
-  - **真·状态翻转逻辑**：继电器输出节点内置状态感知能力，基于物理设备真实反馈执行翻转操作，解决传统盲发指令导致的开关失灵
-- **可视化运维**：
-  - **控制看板**：实时显示所有继电器状态，支持手动控制
-  - **调试模式**：详细的通信日志，支持十六进制报文监控
-
-### 1. 安装
-
-**通过npm安装（推荐）**
-```bash
-cd ~/.node-red
-npm install node-red-contrib-symi-modbus
-node-red-restart
-```
-
-**通过Node-RED界面安装**
-1. 点击右上角菜单 → 设置 → 节点管理
-2. 搜索 `node-red-contrib-symi-modbus`
-3. 点击安装
-
-### 2. 选择运行模式
-
-本节点支持两种运行模式，根据需求选择：
-
-#### 模式1：本地模式（推荐用于纯串口控制）
-
-**适用场景**：
-- 无需对接第三方平台
-- 断网环境下稳定运行
-- 纯本地化控制，不受网络影响
-
-**配置方法**：
-1. 主站节点：不启用MQTT或不配置MQTT服务器
-2. 从站开关节点：不配置MQTT服务器
-3. **无需连线**：主站和从站通过内部事件自动通信
-
-**优势**：
-- 断网也能稳定运行
-- 不依赖外部服务
-- 响应速度更快
-- 配置更简单
-- 无需手动连线（免连线通信）
-
-#### 模式2：MQTT模式（推荐用于Home Assistant集成）
-
-**适用场景**：
-- 需要对接Home Assistant等平台
-- 需要远程控制
-- 需要状态持久化
-
-**配置方法**：
-1. 拖拽任意节点到流程画布
-2. 双击节点，找到"MQTT服务器"字段
-3. 点击编辑按钮，填写MQTT服务器信息：
-   - MQTT Broker: `mqtt://localhost:1883` (或你的MQTT服务器地址)
-   - 用户名/密码: 按需填写
-   - 基础主题: `modbus/relay` (默认)
-
-**优势**：
-- Home Assistant自动发现
-- 支持远程控制
-- 状态持久化存储
-
-### 3. 配置主站节点
-
-1. 拖拽 **Modbus主站** 节点到流程画布
-2. 配置连接参数：
-   - **串口模式**（直连RS485设备）：
-     - 连接类型: `串口`
-     - 串口路径: `/dev/ttyUSB0` (Linux/Mac) 或 `COM1` (Windows)
-     - 波特率: `9600`（默认）
-     - 数据位: `8`
-     - 停止位: `1`
-     - 校验位: `无`
-   - **TCP模式**（通过TCP转RS485网关）：
-     - 连接类型: `TCP/IP`
-     - TCP模式: `Telnet ASCII`（推荐，适用于大多数TCP转RS485网关）
-     - TCP主机: `192.168.2.110`
-     - TCP端口: `1031`
-     - 其他模式：
-       - `RTU over TCP`：适用于支持Modbus RTU over TCP的网关
-       - `Modbus TCP`：适用于标准Modbus TCP设备
-3. 配置从站设备：
-   - 从站地址: `10` (默认，可添加多个，如10、11、12、13)
-   - 线圈范围: `0-31`
-   - 轮询间隔: `200ms` (默认，支持100-10000ms)
-4. MQTT配置（可选）：
-   - 本地模式：不启用MQTT或留空
-   - MQTT模式：启用MQTT并选择MQTT服务器配置
-5. 部署流程
-
-### 4. 配置RS-485连接配置节点（用于从站开关）
-
-如果需要物理开关面板控制，首先创建RS-485连接配置：
-
-1. 点击右上角菜单 → 配置节点
-2. 添加新的 **serial-port-config** 配置节点
-3. 选择连接类型：
-   - **串口模式**（本地RS-485总线）：
-     - 连接类型: `串口`
-     - 串口路径: `/dev/ttyUSB0` (可点击"搜索"按钮自动发现)
-     - 波特率: `9600`
-     - 数据位: `8`
-     - 停止位: `1`
-     - 校验位: `无 (N)`
-   - **TCP模式**（通过TCP转RS485网关）：
-     - 连接类型: `TCP网关`
-     - TCP主机: `192.168.2.110`
-     - TCP端口: `1031`
-4. 保存配置
-
-### 5. 配置从站开关节点（可选）
-
-使用物理开关面板控制继电器，支持三种模式：
-
-#### 模式1：RS-485开关模式（传统有线开关）
-
-1. 拖拽 **从站开关** 节点到流程画布
-2. 选择刚创建的RS-485连接配置
-3. 配置开关面板信息：
-   - 面板品牌: `亖米` (默认)
-   - 按钮类型: `开关按钮（RS-485）`
-   - 开关ID: 物理面板地址 (0-255)
-   - 按钮编号: 按键编号 (1-8)
-4. 配置映射到的继电器：
-   - 目标从站地址: `10`
-   - 目标线圈编号: `1`（用户输入1-32）
-5. **无需连线**：主站和从站通过内部事件自动通信
-6. 部署流程
-
-#### 模式2：RS-485场景模式（场景触发）
-
-1. 配置步骤同上，但按钮类型选择 `场景按钮（RS-485）`
-2. 每次按键触发状态翻转（ON→OFF或OFF→ON）
-3. 适用于场景联动、一键控制等场景
-
-#### 模式3：Mesh开关模式（蓝牙Mesh无线开关）
-
-**适用场景**：使用Symi蓝牙Mesh网关和Mesh开关面板
-
-**配置步骤**：
-
-1. **准备工作**
-   - 确保Mesh网关已通过TCP或串口连接到Node-RED
-   - 确保Mesh开关已配网到网关
-
-2. **添加节点**
-   - 拖拽 **从站开关** 节点到流程画布
-   - 选择Mesh网关的连接配置（TCP或串口）
-
-3. **扫描Mesh设备**
-   - 按钮类型: 选择 `Mesh开关（蓝牙Mesh）`
-   - 点击 **扫描设备** 按钮
-   - 系统发送 `53 12 00 41` 协议帧到网关
-   - 网关立即返回所有Mesh开关列表（通常5秒内完成）
-   - 设备列表自动持久化保存到 `~/.node-red/mesh-devices-persist/`
-   - 重启Node-RED无需重新扫描，直接从持久化存储加载
-
-4. **选择设备和按键**
-   - Mesh设备: 从下拉框选择开关（显示格式：`MAC地址 (X路开关)`）
-   - 按钮编号: 选择要使用的按键（1-6路）
-   - **无线模式**（可选）: 勾选此选项后，该按键不响应LED反馈
-     - 适用场景：按键用于触发场景（如全开/全关），继电器状态变化不应点亮该按键LED
-     - 例如：按键3控制线圈16（全开触发），勾选无线模式后，线圈0-15状态变化不会点亮按键3的LED
-   - 多个节点可共享同一设备列表，无需重复扫描
-
-5. **配置目标继电器**
-   - 目标从站地址: `10`
-   - 目标线圈编号: `1`（用户输入1-32）
-
-6. **部署流程**
-   - 点击"完成"并部署
-   - Mesh开关按键会自动控制对应继电器
-   - 继电器状态变化会自动反馈到Mesh开关LED（无线模式按键除外）
-
-**Mesh模式特点**：
-- 无线控制，无需布线
-- 支持1-6路开关
-- 双向同步（按键→继电器，继电器→LED）
-- 支持无线模式（场景触发按键不响应LED反馈）
-- 设备列表持久化保存
-- 短地址自动更新（如果网关重新配网）
-- 与RS-485开关使用方式完全一致
-
-### 6. 配置HomeKit网桥节点（可选）
-
-将Modbus继电器桥接到Apple HomeKit，实现Siri语音控制：
-
-**配置步骤**：
-
-1. **添加网桥节点**
-   - 拖拽 **HomeKit网桥** 节点到流程画布
-   - 双击节点打开配置界面
-
-2. **基础配置**
-   - 网桥名称: `Modbus继电器网桥`（在HomeKit中显示）
-   - 选择主站节点: 从下拉框选择已配置的主站
-   - 配对码: `031-45-154`（添加到HomeKit时使用）
-   - 端口: `51828`（保持默认）
-
-3. **配置继电器名称**（推荐）
-   - 选择主站后，下方会自动显示所有继电器
-   - 为每个继电器输入友好的中文名称
-   - 例如：`客厅灯`、`卧室灯`、`空调插座`等
-   - 配置后在HomeKit中直接显示，无需再修改
-
-4. **部署并添加到HomeKit**
-   - 点击"完成"并部署流程
-   - 打开iPhone/iPad的"家庭"App
-   - 点击右上角"+" → "添加配件"
-   - 选择"更多选项"
-   - 找到"Modbus继电器网桥"
-   - 输入配对码：`031-45-154`
-   - 完成配对
-
-**使用说明**：
-- 线圈0-15显示为开关，线圈16-31显示为插座
-- 支持Siri语音控制："嘿Siri，打开客厅灯"
-- 支持HomeKit自动化和场景
-- 配置会自动保存，重启后无需重新配对
-- **群控性能**：支持同时控制多个继电器（如创建编组），智能队列机制确保流畅无卡顿
-
-**群控说明**（客户友好模式）：
-
-本节点专为智能家居群控场景优化，支持以下高性能操作：
-
-1. **HomeKit编组群控**：
-   - 在HomeKit中创建房间或编组，可同时控制多个继电器
-   - 例如：创建"客厅"编组，包含10个灯光开关，一键全开/全关
-   - 智能优先队列机制确保触发源面板最快响应，其他继电器按序执行
-   - 10个继电器同时动作仅需约 500ms（50ms间隔×10），触发源面板优先反馈
-
-2. **场景联动**：
-   - 支持HomeKit场景（如"回家模式"、"离家模式"）
-   - 场景可包含多个继电器动作，自动串行执行
-   - 前16个线圈（继电器）可同时动作，后16个线圈（场景）按需触发
-
-3. **性能保证**：
-   - 最大支持10台继电器（每台32路），共320个线圈
-   - 前160个线圈（10台×16路）可用于继电器控制，支持群控
-   - 后160个线圈（10台×16路）可用于场景触发，一般不会全部同时动作
-   - 智能写入队列确保所有操作串行执行，避免总线冲突
-   - 长期稳定运行，反复控制不会造成内存增加、卡顿或死机
-
-4. **技术细节**：
-   - 写入队列间隔：50ms（确保总线稳定，优化指示灯反馈）
-   - 写入锁机制：写入操作优先级高于轮询，自动抢占总线资源
-   - 轮询恢复时间：50ms（写入完成后快速恢复轮询）
-   - 锁等待超时：500ms（适配高延迟网络，确保指令不丢失）
-   - 智能优先队列：触发源面板优先处理（500ms优先窗口）
-   - 触发源追踪：全链路追踪控制指令来源（triggerSource），日志清晰记录是物理按键、HomeKit还是自动化触发
-   - 队列自动处理，无需手动干预
-
-## 核心特性说明
-
-### Symi开关自动识别
-
-主站节点自动支持两种控制方式，无需额外配置：
-
-#### 方式1：Modbus RTU轮询（标准）
-- 主站定期轮询从站线圈状态
-- 通过MQTT或Node-RED流程控制继电器
-- 适用于所有Modbus RTU设备
-
-#### 方式2：Symi私有协议（自动）
-- 自动识别Symi开关按键事件（协议格式：`7E [地址] 03 0F ...`）
-- 自动应答并控制对应继电器（协议格式：`7E [地址] 04 0F ...`）
-- 映射规则：
-  - 设备地址1 → 从站10
-  - 设备地址2 → 从站11
-  - 设备地址3 → 从站12
-  - 设备地址4 → 从站13
-  - 通道号1-8 → 线圈0-7
-
-**按钮类型说明**：
-
-**1. 开关按钮（推荐）**
-- **控制方式**：按键有独立的开/关状态
-- **LED反馈**：面板LED指示灯精确同步开关状态
-- **适用场景**：
-  - 灯光开关（客厅灯、卧室灯等）
-  - 插座开关（电器控制）
-  - 窗帘开关（电动窗帘）
-  - 任何需要明确开/关状态的场景
-- **技术特点**：
-  - 使用REPORT协议（0x04）发送LED反馈
-  - 使用原始设备地址确保LED精确反馈
-  - 支持物理按键和Home Assistant远程控制
-  - 面板LED完美同步，响应速度快
-
-**2. 场景按钮**
-- **控制方式**：每次按下toggle切换状态（开→关→开）
-- **LED反馈**：根据当前状态显示LED（开=亮，关=灭）
-- **协议特征**：操作信息为0x11、0x12、0x13等（高4位=1表示场景模式）
-- **适用场景**：
-  - 场景触发（回家模式、离家模式等）
-  - 一键全开/全关
-  - 需要状态指示的场景按钮
-- **技术特点**：
-  - 使用REPORT协议（0x04）发送LED反馈
-  - 使用原始设备地址确保LED精确反馈
-  - 支持物理按键和Home Assistant远程控制
-  - 200ms防抖，避免重复触发
-  - 自动识别场景模式（根据操作信息高4位判断）
-
-**两种模式对比**：
-
-| 特性 | 开关按钮 | 场景按钮 |
-|------|---------|---------|
-| 控制方式 | 开/关独立 | Toggle切换 |
-| 操作信息 | 0x00/0x01 | 0x11/0x12/0x13等 |
-| LED反馈协议 | REPORT (0x04) | REPORT (0x04) |
-| 按键事件 | 独立开/关码 | 统一触发码 |
-| LED同步 | ✓ 完美同步 | ✓ 完美同步 |
-| HA远程控制 | ✓ 支持 | ✓ 支持 |
-| 推荐场景 | 灯光/插座 | 场景触发 |
-| 自动识别 | ✓ 支持 | ✓ 支持 |
-
-**配置说明**：
-
-1. **RS-485连接**：选择串口配置节点（波特率9600，8N1）
-2. **MQTT服务器**（可选）：
-   - 本地模式：不启用MQTT，主站和从站通过内部事件自动通信（免连线）
-   - MQTT模式：启用MQTT并选择MQTT配置节点
-3. **面板配置**：
-   - 面板品牌：选择亖米（Symi）
-   - 按钮类型：开关按钮或场景按钮（也可自动识别）
-   - 开关ID：物理面板的RS-485地址（0-255）
-   - 按钮编号：面板上的按键序号（1-8）
-4. **继电器映射**：
-   - 从站地址：Modbus继电器地址（10-247）
-   - 继电器路数：继电器通道（1-32路）
-
-**使用示例**：
-
-**示例1：客厅灯光开关（本地模式）**
-- 面板：开关ID=2，按键1（开关按钮）
-- 继电器：从站10，1路
-- 配置：不启用MQTT，主站和从站自动通信（免连线）
-- 效果：按下面板按键，客厅灯开/关，面板LED同步状态，断网也能正常工作
-
-**示例2：全开场景（MQTT模式）**
-- 面板：开关ID=2，按键8（场景按钮）
-- 继电器：从站10，32路
-- 配置：启用MQTT，连接到Home Assistant
-- 效果：按下面板按键，触发全开场景，HA中可远程控制，面板LED同步状态
-
-**示例3：三键场景开关（本地模式）**
-- 面板：开关ID=1，按键1/2/3（场景按钮，自动识别）
-- 继电器：从站10，1/2/3路
-- 配置：不启用MQTT，主站和从站自动通信（免连线）
-- 效果：按下按键1/2/3，分别控制对应继电器，LED指示灯同步状态
-
-### 智能轮询机制
-
-主站轮询时，从站开关可以同时使用。当从站开关上报数据到服务器后：
-1. **自动暂停轮询**：主站检测到写入操作，立即暂停轮询
-2. **优先处理数据**：处理从站上报的数据（写入Modbus继电器）
-3. **继续轮询**：数据处理完成后（100ms延迟），自动恢复轮询
-4. **日志记录**：记录轮询暂停时长和跳过的轮询次数
-
-这种机制确保：
-- 主站轮询不会与从站写入冲突
-- 从站上报的数据得到优先处理
-- 系统响应迅速，状态同步及时
-
-### 总线数据过滤与稳定性
-
-本节点具备完善的总线数据过滤机制，确保长期稳定运行：
-
-**数据过滤机制**：
-- **CRC校验**：所有Symi协议帧都经过CRC8校验，无效数据自动丢弃
-- **静默忽略**：总线上的非相关数据（其他设备、其他协议）静默忽略，不影响正常通信
-- **精确匹配**：只处理本节点配置的从站地址和线圈范围内的数据
-- **TCP粘包处理**：TCP模式下自动处理粘包和分包问题，确保数据完整性
-
-**稳定性保障**：
-- **写入队列**：多个节点同时写入时自动排队，避免并发冲突
-- **断线重连**：TCP和串口断线后自动重连，指数退避策略（最大60秒）
-- **内存管理**：定时清理缓存，防止内存泄漏
-- **错误日志限流**：避免日志刷屏影响性能
-- **MQTT独立性**：MQTT开启或关闭都不影响主站和从站的本地通信
-
-**网络适应性**：
-- **离线通信**：串口模式完全脱离网络依赖，断网也能正常工作
-- **TCP稳定性**：TCP模式支持局域网通信，网络恢复后自动重连
-- **MQTT可选**：MQTT仅用于对接第三方平台，不影响本地控制
-
-## 调试节点（modbus-debug）
-
-用于抓取并显示原始RS485字节流数据（HEX），帮助定位串口或TCP网关下的Modbus通信问题。
-
-- 数据来源：
-  - 共享连接：`serial-port-config`（推荐，复用主站/从站的同一连接）
-  - 独立连接：`modbus-server-config`（直接连接TCP或串口）
-- 输出内容：
-  - `msg.payload`：格式化的HEX字符串（可选大写）
-  - `msg.buffer`：原始Buffer数据
-  - `msg.meta`：来源信息与连接参数（串口或TCP详情）
-  - `msg.timestamp`：时间戳（可选）
-- 显示控制：
-  - `maxBytes`：限制显示字节数，超过会截断并在`meta.truncated`标记
-
-使用步骤：
-1. 将 `modbus-debug` 节点拖入画布。
-2. 选择“数据来源”：
-   - 选“共享串口配置（serial-port-config）”以复用主站/从站连接；或
-   - 选“Modbus服务器（modbus-server-config）”进行独立直连。
-3. 可选：勾选“大写HEX”、勾选“时间戳”、设置“最大字节数”。
-4. 部署后，节点自动输出捕获到的原始数据。
-
-典型用法：
-- 联调TCP转RS485网关时，观察上行/下行原始数据帧是否完整。
-- 排查波特率/数据位/校验位配置是否正确（串口模式）。
-- 与 `modbus-master` 或 `modbus-slave-switch` 同时使用，定位现场设备通信异常。
-
-### MQTT自动发现
-
-启用MQTT后，自动生成Home Assistant兼容的Discovery配置：
-- **唯一性保证**：每个实体使用稳定的`unique_id`，避免重复生成
-- **设备分组**：同一从站的所有继电器自动分组到一个设备下
-- **状态持久化**：使用`retain=true`确保状态持久化
-- **在线状态**：自动发布设备可用性状态
-
-### 配置持久化
-
-所有节点配置自动保存到Node-RED的flows文件中：
-- 从站地址、线圈范围、轮询间隔
-- MQTT服务器配置
-- 开关面板映射关系
-
-部署后配置永久生效，重启Node-RED后自动恢复。
-
-### 长期稳定运行
-
-针对工控机24/7长期运行优化：
-- **内存管理**：自动清理缓存，释放无用对象
-- **事件监听器清理**：关闭时移除所有监听器，防止内存泄漏
-- **智能日志限流**：错误日志10分钟输出一次，避免日志刷屏
-- **智能重连机制**：
-  - Modbus连接断开自动重连（指数退避：5秒→10秒→20秒...最大60秒）
-  - MQTT连接断开自动重连（支持多地址fallback）
-  - 串口拔插自动检测并重连
-  - TCP网络故障自动恢复
-  - 连接前彻底清理旧实例，避免资源泄漏
-- **互斥锁机制**：防止读写冲突导致的数据异常
-- **TCP永久连接**：
-    - 禁用TCP超时（永久连接），避免无数据时超时断开
-    - Keep-Alive心跳10秒间隔，确保连接活跃
-  - 适应客户长期不在家、总线无数据的场景
-  - 网络故障自动重连，恢复后立即恢复通信
-
-## 技术规格
-
-### Modbus协议
-
-- **协议类型**：Modbus TCP / Modbus RTU
-- **底层库**：modbus-serial ^8.0.23（内部封装serialport，支持TCP和串口）
-- **功能码支持**：0x01（读线圈）、0x05（写单个线圈）、0x0F（写多个线圈）
-- **从站地址范围**：1-247（建议从10开始）
-- **线圈数量**：每台设备32个（0-31）
-- **最大设备数**：10台同时轮询
-- **轮询间隔**：默认200ms（建议300-500ms，支持100-10000ms）
-- **串口配置**：9600 8-N-1（波特率9600，8数据位，无校验，1停止位）
-- **超时设置**：5000ms（TCP和串口通用）
-
-### 兼容性
-
-- **Node.js**: >= 14.0.0
-- **Node-RED**: >= 2.0.0
-- **MQTT Broker**: Mosquitto / EMQX / Any MQTT 3.1.1/5.0
-- **Home Assistant**: 2024.x+（MQTT Discovery标准）
-- **操作系统**: Windows / Linux / macOS / HassOS
-
-## Home Assistant集成
-
-### 自动发现
-
-启用MQTT后，设备自动出现在Home Assistant中：
-- 实体ID: `switch.relay_{从站地址}_{线圈编号}`
-- 设备名称: `Modbus继电器-{从站地址}`
-- 自动分组: 同一从站的所有继电器分组到一个设备
-
-### MQTT主题结构
-
-```
-状态主题: modbus/relay/{从站}/{线圈}/state
-命令主题: modbus/relay/{从站}/{线圈}/set
-可用性主题: modbus/relay/{从站}/availability
-发现主题: homeassistant/switch/modbus_relay_{从站}_{线圈}/config
-```
-
-## 故障排除
-
-### 串口连接失败
-
-**Linux**:
-```bash
-# 查看串口设备
-ls -l /dev/ttyUSB* /dev/ttyS*
-
-# 添加用户到dialout组（需要重新登录）
-sudo usermod -a -G dialout $USER
-```
-
-**macOS**:
-```bash
-# 查看串口设备（注意macOS使用cu.*而不是tty.*）
-ls -l /dev/cu.*
-```
-
-**Docker/HassOS**:
-```yaml
-# 在docker-compose.yml或HassOS插件配置中添加设备映射
-devices:
-  - /dev/ttyUSB0:/dev/ttyUSB0
-```
-
-### MQTT连接失败
-
-1. 确认MQTT broker正在运行：
-   ```bash
-   # Linux
-   sudo systemctl status mosquitto
-   
-   # macOS
-   brew services list | grep mosquitto
-   ```
-
-2. 测试MQTT连接：
-   ```bash
-   mosquitto_sub -h localhost -t test
-   ```
-
-3. 检查Node-RED日志中的MQTT连接信息
-
-### 主站轮询不工作
-
-1. **检查从站配置**：确认已添加所有从站设备（如10、11、12、13）
-2. **检查轮询间隔**：默认200ms，建议300-500ms（多台从站时避免总线拥堵）
-3. **查看Node-RED调试日志**：部署后查看日志中的轮询信息
-4. **检查串口波特率**：确认波特率为9600（与从站设备一致）
-5. **检查从站地址**：确认从站地址正确（1-247）
-
-### 轮询超时或频繁报错
-
-1. **轮询永不停止原则**：
-   - 即使从站不响应，轮询也会持续运行
-   - 不会因超时而跳过任何从站
-   - 只记录错误日志，不影响总线轮询机制
-2. **正常超时**：偶尔超时是正常的，系统会自动重试
-   - 超时设置：2-3秒（串口/TCP）
-   - 只记录日志，不停止轮询
-   - 轮询会持续运行，不受超时影响
-3. **频繁超时**：
-   - 检查Modbus连接是否稳定
-   - 调整轮询间隔（默认200ms，可增加到500ms）
-   - 检查从站设备是否在线
-   - 查看总线是否有其他设备干扰
-4. **总线干扰**：
-   - 总线上的其他数据（如Symi网关通信、其他Modbus设备）可能导致偶尔超时或CRC错误
-   - 系统已优化容错机制，会自动忽略异常数据并继续轮询
-   - 非超时错误（如CRC错误）不累积计数，只记录日志
-5. **长期稳定性保障**：
-   - 轮询循环采用try-catch包裹，确保异常不会中断轮询
-   - 每1000轮输出一次调试日志，证明轮询持续运行
-   - 定时清理机制（每小时）防止内存泄漏
-   - 所有定时器在节点关闭时正确清除
-
-### 总线上出现未知数据
-
-1. **识别数据来源**：
-   - 使用`modbus-debug`节点监听总线数据（必须使用共享的serial-port-config，避免串口冲突）
-   - 查看Node-RED日志中的"写入线圈"日志，确认是否是本节点发送的
-   - 检查是否有其他Modbus设备或Symi网关在总线上通信
-2. **常见数据格式**：
-   - `01 05 00 01 FF 00 ...`：写单个线圈（功能码0x05）
-   - `01 0F 00 00 00 20 ...`：写多个线圈（功能码0x0F）
-   - `7E 01 03 ...`：Symi轻量级协议数据
-3. **影响**：
-   - 总线上的其他数据不会影响轮询稳定性
-   - 可能导致偶尔的CRC错误或超时，但系统会自动忽略并继续轮询
-
-### 串口冲突错误
-
-**错误信息**：
-```
-串口监听错误: Port is not open
-串口监听错误: Error Resource temporarily unavailable Cannot lock port
-```
-
-**原因**：
-- 多个节点试图独立打开同一个串口
-- 串口只能被一个进程同时打开
-
-**解决方案**：
-1. **modbus-debug节点**：必须使用"serial"源类型，选择共享的`serial-port-config`配置节点
-2. **不要使用独立连接**：不要让多个节点独立打开同一个串口
-3. **共享连接配置**：所有节点（主站、从站开关、modbus-debug）都应该使用同一个`serial-port-config`配置节点
-
-### 批量更换连接配置
-
-**问题**：如何批量更换所有节点的RS-485连接配置？
-
-**Node-RED原生方法**（推荐）：
-1. 创建新的`serial-port-config`配置节点
-2. 点击右上角菜单 → 配置节点
-3. 找到旧的`serial-port-config`配置节点
-4. 点击删除按钮
-5. Node-RED会提示"此配置节点被X个节点使用，是否替换为其他配置？"
-6. 选择新创建的配置节点
-7. 点击确认，所有使用旧配置的节点会自动更换为新配置
-
-**注意**：
-- 这是Node-RED的原生功能，安全可靠
-- 删除配置节点前必须先创建新配置
-- 替换后需要部署才能生效
-6. **确认从站设备在线**：使用Modbus调试工具测试从站是否响应
-7. **检查MQTT连接**：确保MQTT broker地址正确，轮询不依赖MQTT但状态发布需要MQTT
-8. **测试连接**：
-   - TCP连接问题：先用 `modbus-serial` 单独测试TCP连接
-   - 串口问题：先用 `serialport` 单独测试串口通信
-
-### 从站开关无响应
-
-1. **检查免连线通信**（v2.6.7+推荐）：
-   - **无需连线**：主站和从站通过内部事件自动通信，无需手动连线
-   - 查看Node-RED日志，确认是否有"内部事件模式：发送命令到从站X 线圈Y"的日志
-   - 查看主站节点日志，确认是否有"收到内部事件：从站X 线圈Y"的日志
-   - 查看主站节点日志，确认是否有"内部事件写入成功，已广播状态变化"的日志
-   - 查看从站开关节点日志，确认是否有"收到状态变化事件"和"LED反馈已发送"的日志
-2. **检查RS-485连接**：
-   - 确认RS-485连接配置正确（串口路径、波特率等）
-   - 查看节点状态显示是否为"MQTT未启用 - 使用内部事件模式"
-   - 物理面板连接：确认物理面板连接到正确的RS-485总线（TCP或串口）
-3. **检查开关面板配置**：
-   - 确认开关面板地址和按钮编号正确
-   - 场景模式开关：操作信息为0x11、0x12、0x13等（高4位=1）
-   - 开关模式开关：操作信息为0x00（关）或0x01（开）
-4. **检查继电器映射**：
-   - 确认目标从站地址和线圈编号正确
-   - 线圈编号范围：0-31（对应用户输入的1-32路）
-5. **查看调试日志**：
-   - 使用modbus-debug节点抓取原始总线数据
-   - 查看Node-RED日志中的协议解析信息
-   - 确认按键事件是否被正确识别
-   - 确认LED反馈协议帧是否正确发送（查看日志中的HEX字符串）
-
-## 输入消息格式
-
-### 主站节点
-
-```javascript
-// 启动轮询
-msg.payload = {cmd: "start"};
-
-// 停止轮询
-msg.payload = {cmd: "stop"};
-
-// 写单个线圈
-msg.payload = {
-    cmd: "writeCoil",
-    slave: 10,      // 从站地址
-    coil: 0,        // 线圈编号
-    value: true     // true=开, false=关
-};
-
-// 批量写多个线圈
-msg.payload = {
-    cmd: "writeCoils",
-    slave: 10,      // 从站地址
-    startCoil: 0,   // 起始线圈
-    values: [true, false, true, false]  // 线圈值数组
-};
-```
-
-### 从站开关节点
-
-```javascript
-// 发送开关命令
-msg.payload = true;   // 或 false
-msg.payload = "ON";   // 或 "OFF"
-msg.payload = 1;      // 或 0
-```
-
-### HomeKit网桥节点
-
-HomeKit网桥节点无需输入消息，自动同步主站配置和状态。
-
-**配置参数**：
-- **主站节点**：选择要桥接的Modbus主站节点（必填）
-- **网桥名称**：在HomeKit中显示的网桥名称（默认：Modbus继电器网桥）
-- **MAC地址**：HomeKit网桥的唯一标识符（自动生成，无需修改）
-- **配对码**：HomeKit配对时使用的PIN码（格式：XXX-XX-XXX，默认：031-45-154）
-- **端口**：HomeKit网桥监听端口（默认：51828）
-- **继电器名称配置**：为每个继电器配置友好的中文名称（可选）
-
-**自动同步规则**：
-- 自动读取主站节点配置的所有从站和线圈
-- 线圈0-15（1-16路）：创建为开关（Switch）配件
-- 线圈16-31（17-32路）：创建为插座（Outlet）配件
-- 监听主站的状态变化事件，实时同步到HomeKit
-- 接收HomeKit控制命令，发送到主站执行
-
-**使用示例**：
-1. 在Node-RED中配置好主站节点和从站
-2. 添加HomeKit网桥节点，选择主站节点
-3. 为每个继电器配置友好的名称（例如：客厅灯、卧室灯）
-4. 部署流程
-5. 在iPhone的"家庭"App中添加配件，输入配对码
-6. 完成配对后，即可在HomeKit中控制继电器，支持Siri语音控制
-
-**注意事项**：
-- 确保主站节点已正确配置并运行
-- 配对码格式必须为XXX-XX-XXX（8位数字）
-- 端口不能与其他服务冲突（默认51828）
-- 配置信息持久化存储在~/.node-red/homekit-persist目录
-- 重启Node-RED后自动恢复配对状态，无需重新配对
-
-### 控制看板节点（客户友好模式）
-
-控制看板节点提供可视化界面，实时显示和控制所有从站的继电器状态，适合现场调试和日常监控。
-
-**配置参数**：
-- **节点名称**：控制看板的显示名称（默认：Modbus控制看板）
-- **主站节点**：选择要监控的Modbus主站节点（必填）
-
-**功能特性**：
-- **实时状态显示**：在配置界面中显示所有从站和线圈的实时状态
-- **一键控制**：点击按钮即可控制继电器开关，无需部署流程
-- **美观布局**：网格布局，按从站分组显示，一目了然
-- **名称同步**：自动同步HomeKit网桥配置的继电器名称
-- **快速响应**：状态实时更新（500ms轮询），响应迅速
-- **零开销**：不参与实际Modbus通信，不影响主站性能
-
-**使用步骤**：
-1. 在Node-RED中添加控制看板节点
-2. 选择已配置的Modbus主站节点
-3. 双击节点打开配置界面，即可看到所有继电器状态
-4. 点击按钮即可控制继电器开关（绿色=ON，红色=OFF）
-5. 部署流程后，节点会显示"监控中"状态
-
-**使用场景**：
-- **现场调试**：快速测试继电器是否正常工作
-- **日常监控**：实时查看所有继电器状态
-- **批量控制**：快速控制多个继电器
-- **客户演示**：美观的界面，适合向客户展示系统功能
-
-**技术细节**：
-- 使用HTTP API与主站通信，通过内部事件发送控制命令
-- 状态缓存机制，减少网络请求
-- 仅在配置界面打开时才轮询状态，关闭后自动停止
-- 与HomeKit网桥共享继电器名称配置，保持一致性
-
-**注意事项**：
-- 确保主站节点已正确配置并运行
-- 控制看板只在配置界面打开时才轮询状态
-- 继电器名称需在HomeKit网桥节点中配置
-- 本节点不参与实际Modbus通信，不会增加主站负担
-
-### 自定义协议节点
-
-用于控制非标准Modbus协议的485设备（如窗帘、特殊开关等）。
-
-**配置步骤**：
-1. 添加自定义协议节点到流程画布
-2. 选择设备类型（开关/窗帘/其他）
-3. 选择串口配置节点
-4. 输入16进制指令（空格分隔，自动格式化为大写）
-   - 打开指令：例如 `01 05 00 00 FF 00 8C 3A`
-   - 关闭指令：例如 `01 05 00 00 00 00 CD CA`
-   - 暂停指令：仅窗帘模式需要，例如 `01 05 00 01 FF 00 DD FA`
-5. 点击"测试"按钮验证指令是否正确发送
-6. 连线：从站开关 → 自定义协议节点
-7. 部署流程
-
-**设备类型说明**：
-- **开关模式**：收到`true`发送打开指令，收到`false`发送关闭指令
-- **窗帘模式**：每次触发循环发送下一个指令（打开 → 暂停 → 关闭 → 暂停 → 打开...）
-- **其他模式**：与开关模式相同
-
-**使用场景**：
-- 窗帘控制：支持打开/暂停/关闭循环控制
-- 特殊开关：非标准Modbus协议的485设备
-- 自定义设备：任何需要发送固定16进制指令的设备
-
-**注意事项**：
-- 每个指令最多48字节
-- 窗帘模式需配置三个指令（打开、关闭、暂停）
-- 测试功能需先选择串口配置
-- 无需连线到debug节点，直接通过串口配置节点发送数据
-
-### 继电器输出节点（relay-output）
-
-用于控制Modbus继电器，支持**绑定从站开关触发源**或接收外部输入，**无需连线到主站**。
-
-**核心特性**：
-- 从站开关、继电器输出、主站之间**完全无需连线**
-- 共享RS-485连接配置，支持多个节点共用
-- 支持绑定从站开关作为触发源（内部事件通信）
-- 支持外部设备触发（如海康门禁）
-- 支持延时执行（0-60000毫秒），实现级联开灯效果
-- 配置持久化保存，断电断网恢复后正常工作
-
-**配置参数**：
-
-*RS-485连接配置*：
-- **连接配置**：选择已配置的RS-485连接（支持TCP网关或串口），多个节点共享
-
-*按键触发配置*：
-- **面板品牌**：开关面板品牌，目前支持亖米（Symi）
-- **按钮类型**：开关按钮/场景按钮/输入端触发（外部设备）
-- **开关ID**：物理面板地址（0-255）
-- **按钮编号**：按键编号(1-8，15=背光灯)
-- **门禁ID**：可选，0=不过滤，>0=只响应指定门禁编号
-
-*目标继电器配置*：
-- **从站地址**：要控制的Modbus从站地址(1-247)
-- **继电器路数**：要控制的继电器通道(1-32)
-
-*动作配置*：
-- **动作**：打开/关闭/跟随输入/翻转状态
-- **延时**：执行延时（0-60000毫秒），用于实现级联开灯效果
-- **忽略释放信号**：只响应按下信号
-
-**使用示例**：
-
-**示例1：按键触发继电器（无需任何连线）**
-```
-配置：开关ID=1，按钮编号=3，从站地址=10，继电器路数=1，动作=打开
-效果：当开关1的按钮3被按下时，自动控制从站10的1路继电器打开
-```
-
-**示例2：一个按键控制多路继电器（级联开灯）**
-```
-继电器输出1: 开关ID=1, 按钮=3, 继电器=1路, 延时=0ms, 动作=打开
-继电器输出2: 开关ID=1, 按钮=3, 继电器=2路, 延时=500ms, 动作=打开
-继电器输出3: 开关ID=1, 按钮=3, 继电器=3路, 延时=1000ms, 动作=打开
-```
-
-**示例3：海康门禁触发（使用输入端）**
-```
-海康门禁事件 → 继电器输出(按钮类型=输入端触发, 从站地址=10, 继电器=1路, 门禁ID=4)
-```
-
-**工作原理**：
-- 节点监听 `modbus:buttonPressed` 事件（按键触发）
-- 通过 `modbus:writeCoil` 事件发送控制命令到主站
-- 实现按键 → 继电器输出 → 主站之间的无连线通信
-
-**稳定性保障**：
-- 长期运行不卡顿、不死机、内存不溢出
-- 无调试数据输出，具备生产条件长期运行
-- 断电断网恢复后正常工作
-- 内置防抖和状态检测机制，不会出现设备反复开关进入死循环
-
-## 输出消息格式
-
-### 主站节点
-
-```javascript
-{
-    payload: {
-        slave: 10,                // 从站地址
-        coils: [true, false, ...], // 线圈状态数组
-        timestamp: 1234567890     // 时间戳
-    }
-}
-```
-
-### 从站开关节点
-
-```javascript
-{
-    payload: true,                    // 开关状态
-    topic: "switch_0_btn1",          // 主题
-    switchId: 0,                     // 开关面板ID
-    button: 1,                       // 按钮编号
-    targetSlave: 10,                 // 目标从站地址
-    targetCoil: 0                    // 目标线圈编号
-}
-```
-
-## 性能指标
-
-- **内存占用**：< 50MB（单个主站节点，轮询10个设备）
-- **CPU占用**：< 5%（正常轮询状态）
-- **连接延迟**：Modbus响应 < 100ms，MQTT发布 < 50ms
-- **稳定运行**：经过工控机7x24小时长期运行验证
-- **容错能力**：Modbus从站离线不影响其他从站，MQTT断线自动重连
-
-## 示例Flow
-
-```json
-[
-    {
-        "id": "modbus-master-1",
-        "type": "modbus-master",
-        "name": "主站",
-        "connectionType": "serial",
-        "serialPort": "/dev/ttyUSB0",
-        "serialBaudRate": 9600,
-        "slaves": [
-            {"address": 10, "coilStart": 0, "coilEnd": 31, "pollInterval": 200},
-            {"address": 11, "coilStart": 0, "coilEnd": 31, "pollInterval": 200},
-            {"address": 12, "coilStart": 0, "coilEnd": 31, "pollInterval": 200},
-            {"address": 13, "coilStart": 0, "coilEnd": 31, "pollInterval": 200}
-        ],
-        "enableMqtt": true,
-        "mqttServer": "mqtt-config-1"
-    }
-]
-```
-
-完整示例请参考项目中的 `examples/basic-flow.json` 文件。
-
-## 技术栈
-
-- Node.js: >=14.0.0
-- Node-RED: >=2.0.0
-- modbus-serial: ^8.0.23
-- serialport: ^12.0.0
-- mqtt: ^5.14.1（可选）
-- hap-nodejs: ^1.2.0
-- node-persist: ^4.0.4
-
-## 版本更新说明
-
-### v2.10.7 (2026-01-22)
-- **协议模式严格匹配**: 全面适配 Symi 智能面板协议 V1.06。
-  - **开关模式 (Switch Mode)**: 严格解析 `0x00` (OFF) 和 `0x01` (ON) 状态码，指示灯状态强制同步（Force Sync），确保面板物理状态与系统状态一致。
-  - **场景模式 (Scene Mode)**: 采用 Toggle 逻辑，忽略触发码的具体值（兼容 `0x01` 或 `0x1X`），依靠系统侧的 LED 反馈指令 (`REPORT 0x04`) 来驱动面板指示灯变化。
-  - **无猜测逻辑**: 移除了代码中基于操作码的模糊推断，完全遵循用户配置 (`buttonType`) 决定处理逻辑，消除混淆。
-- **Clowire协议回退**: 禁用了 v2.10.6 引入的 Clowire 协议“全关”优化（0x1020=0x0002）。经测试，部分面板在接收全关指令后无法正确同步指示灯状态（LED 不熄灭），因此回退为逐个发送关闭指令的逻辑，确保指示灯状态与继电器状态严格一致。
-
-### v2.10.6 (2026-01-17)
-- **多节点LED状态聚合**: 支持多个 `从站开关` 节点配置为同一物理按键（相同 Switch ID 和 Button ID）但控制不同继电器。系统会自动聚合所有关联继电器的状态（OR逻辑），实现“任意开则灯亮，全关则灯灭”的智能反馈，完美支持“一键多控”场景。
-- **Clowire协议深度优化**: 新增支持 Clowire 协议的“全关”指令（0x1020=0x0002）。当检测到某面板下的所有按键状态均为 OFF 时，系统会自动合并发送一条全关指令，替代逐个发送的关闭指令，大幅降低 RS-485 总线通信压力，提升批量关灯时的响应速度。
-- **Symi协议深度优化**: 新增支持 Symi 协议的“全关”指令（0x05 MULTI）。逻辑同上，当检测到 Symi 面板所有按键全关时，自动发送一条多灯控制指令（状态位全0），实现高效的“一键全关”反馈。
-- **网络错误日志优化**: 对 Modbus 主站的 TCP/串口底层连接错误进行严格限流（每分钟仅记录一次），避免在网络不稳定或断网情况下产生大量垃圾日志，保护磁盘空间。
-- **稳定性增强**: 优化了全局状态管理的内存回收机制，确保节点删除或重部署时无内存残留。
-
-### v2.10.5 (2026-01-15)
-- **多主站精准隔离架构**：引入 `masterId` 指令定向机制。`relay-output` 节点现在可以精准锁定目标主站，彻底解决了多主站环境下（如多台 Modbus 网关）指令错发或“一控多”的冲突问题。
-- **真·状态翻转 (Toggle) 逻辑**：继电器输出节点新增状态感知能力。通过实时监听总线状态回传（Coil State Sync），翻转动作不再是盲目的逻辑取反，而是基于物理设备真实状态的精准操作，解决了高频连点或多端控制下的状态不同步顽疾。
-- **指示灯反馈机制重构**：优化了 `modbus-slave-switch` 的反馈锁与初始化逻辑。移除了过度的初始化过滤，确保面板指示灯在系统重启或状态突变时能秒级同步（包括 OFF 状态），解决了指示灯反馈“只开不关”的问题。
-- **生产级日志分级**：对全局日志进行了分级处理。将底层的 Modbus 通信报文转入 Debug 级别，控制台仅保留关键的业务联动日志（如 `[免连线联动]`），极大提升了高并发场景下的运行效率并降低了 IO 损耗。
-- **资源管理与稳定性**：规范化了所有节点的 `close` 生命周期管理。完善了事件监听器的移除机制，确保在频繁部署或节点增删时内存无泄露，系统长期运行更加稳健。
-
-### v2.10.4 (2026-01-14)
-- **Modbus超时优化**：将默认Modbus通信超时时间（Timeout）统一调整为 **3000ms**（原TCP 1000ms/串口 2000ms），彻底解决网络波动或从站响应慢导致的“轮询超时”和“写入失败”问题，这是生产环境稳定的关键参数。
-- **锁等待恢复合理值**：将写入锁等待超时恢复为 **3000ms**，配合更长的底层通信超时，确保在总线繁忙时依然能有序排队，不再出现死锁或虚假超时。
-- **断连彻底静默**：移除写入队列在断连时的错误日志提醒，断线期间不报错、不刷屏，确保生产环境日志整洁。
-- **缓存策略优化**：连接断开时立即清空所有待处理的写入任务（`writeQueue = []`），重连后不处理断连期间的旧指令，只响应重连后的新操作。
-- **连接恢复优化**：移除重连后的自动任务恢复逻辑，实现真正的“断连不处理缓存，重连只理新数”。
-
-### v2.10.3 (2026-01-14)
-- **协议兼容性**: 完善 Symi 协议解析逻辑，全面支持 `0x03 SET`、`0x04 REPORT` 和 `0x05 STATUS` 帧类型，解决某些面板状态错位导致的按键不响应问题。
-- **稳定性修复**: 紧急修复物理回显导致的“继电器无限跳动”死循环问题，通过严格过滤 `0x04` 反馈帧并延长反馈锁至 **100ms**，确保系统在复杂干扰环境下依然稳定。
-- **并发优化**: 优化主站写入锁等待机制，将最大等待时间延长至 **500ms**，适配 TCP 网关或低速串口的高延迟场景。
-- **指示灯同步**: 引入物理按键“强制同步”机制，无论系统状态是否变化，物理按键按下时都会强制纠正面板 LED，确保面板与继电器状态 100% 对齐。
-- **多主站联动**: 优化 `relay-output` 和 `modbus-slave-switch` 的事件路由，确保多台主站独立轮询、互不干扰，支持复杂的跨网关控制场景。
-- **架构解耦**: 明确指示灯同步职责，实现多主站环境下的闭环同步，同时保持 50ms 队列间隔与轮询暂停机制。
-
-### v2.10.2 (2026-01-14)
-- **轮询优化**: 引入轮询暂停机制，上报数据时自动暂停主站轮询，解决状态回跳问题。
-- **反馈增强**: 强制使用 REPORT (0x04) 协议进行指示灯同步，实现状态显示与物理继电器控制的彻底隔离。
-- **并发管理**: 优化写入队列机制。串口写入增加 50ms 厂家推荐间隔，支持高并发下的顺序发送，确保指示灯反馈稳定。
-- **Mesh深度支持**: 完善 Mesh 模式下的 LED 反馈。通过 `OP_DEVICE_REPORT (0x31)` 操作码同步状态，不干扰物理开关动作。
-- **稳定性提升**: 优化主站轮询逻辑，支持 7x24 小时高可靠性运行，具备自动重连与异常恢复能力。
-- **隔离机制**: 引入多串口/多网关作用域隔离，支持在同一 Node-RED 实例中运行多个物理隔离的 Modbus 网络。
-
-### v2.10.1 (2026-01-13)
-- **名称校准**: HA 实体名称校准，从 0-31 线圈索引校准为 1-32 路。
-- **防抖优化**: 引入全局按键事件去重防抖，解决信号抖动问题。
-- **组网支持**: 改进 LED 反馈机制，支持 Symi/Clowire/Mesh 多品牌混合组网下的状态同步。
-
-**核心特性**：
-- **指示灯同步逻辑优化**：
-  - **485面板**：使用 `REPORT (0x04)` 协议进行反馈，并将主机地址固定为 `0x00`，确保同步状态时不触发继电器动作。
-  - **Mesh面板**：引入 `OP_DEVICE_REPORT (0x31)` 专用指令，并支持 `0x00 (保持不变)` 状态位，解决全控场景下的状态覆盖问题。
-  - **批量同步**：支持同一面板多按键状态变更的合并排队发送，确保所有指示灯同步无遗漏。
-- **串口队列优先级**：
-  - **触发源优先**：手动触发按键的面板反馈指令进入最高优先级队列，响应时间 < 100ms。
-  - **智能限速**：严格执行 50ms 发送间隔，确保 RS-485 总线和 TCP 网络在高并发场景下的稳定性。
-- **兼容性优化**：
-  - 优化 macOS 环境下多串口/TCP 连接稳定性。
-  - 保持 `v2.10.2` 版本号，采用非沙盒模式打包，确保 Node-RED 长期运行的兼容性与稳定性。
-
-**LED 反馈与同步机制**：
-- **触发源优先**：手动按下的开关面板享有 50ms 稳定反馈优先级，优先进入发送队列。
-- **批量同步**：支持全开/全关等大批量操作，所有受影响面板按 50ms 间隔有序同步，无丢失。
-- **Mesh 合并**：Mesh 面板采用按面板合并策略，一帧同步所有按键状态，节省总线带宽。
-- **RS-485 独立同步**：Symi/Clowire 采用按键独立防抖，确保每个按键的状态变化都能准确反馈。
-- **状态锁定**：LED 发送后自动开启 50ms 状态锁定，防止主站旧状态回刷导致的指示灯闪烁。
-
-**稳定性保障**：
-- **轮询暂停**：优化轮询暂停逻辑，在上报数据时自动暂停主站轮询 50ms，解决状态回跳问题。
-- **多连接支持**：支持 Mac/Linux 多串口与 TCP 同时运行，各主站实例完全隔离，互不干扰。
-- **断电恢复**：所有状态和配置自动持久化，设备上电后 1 秒内自动同步最新状态。
-- **日志防护**：错误日志限流与磁盘溢出保护，确保工控机环境下的系统安全。
-- **日志分级**：生产环境下仅输出关键业务日志，详细通信日志转入 Debug 级别
-- **智能优先队列**：触发源面板优先处理（500ms优先窗口）
-  - **队列自动处理**：指令自动串行化，避免 RS485 总线冲突
-  - **断连自动恢复**：主站/从站连接断开后支持毫秒级自动重连
-  - **多实例运行**：支持同时运行多个 `Modbus主站` 节点，配置完全隔离
-  - **状态持久化**：Mesh 设备列表和继电器状态在重启后自动恢复
-  - **日志分级**：生产环境下仅输出关键业务日志，详细通信日志转入 Debug 级别
-
-**实际使用场景**：
-- 主站轮询：200ms/台，支持5-10台从站设备
-- 开关面板：支持50个以内Mesh面板，约200个按钮
-- LED同步：部署/重启后1秒内完成所有LED状态同步
-- 批量控制：支持全开/全关等批量操作，LED反馈流畅无卡顿
-- 多面板支持：100个面板同时LED反馈仅需 5 秒（50ms间隔×100）
-- 场景触发：支持无线模式按键，不受LED反馈影响
-
-## 许可证
-
-MIT License
-
-## 支持与反馈
-
-- GitHub: https://github.com/symi-daguo/node-red-contrib-symi-modbus
-- Issues: https://github.com/symi-daguo/node-red-contrib-symi-modbus/issues
-- NPM: https://www.npmjs.com/package/node-red-contrib-symi-modbus
+# node-red-contrib-symi-modbus
+
+Node-RED的Modbus继电器控制节点，支持TCP/串口通信和MQTT集成，专为智能家居场景设计。
+
+[![npm version](https://badge.fury.io/js/node-red-contrib-symi-modbus.svg)](https://www.npmjs.com/package/node-red-contrib-symi-modbus)
+[![Node-RED](https://img.shields.io/badge/Node--RED-%3E%3D2.0.0-red)](https://nodered.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## 核心特性
+
+- **双模式运行**：
+  - **本地模式**：纯串口/TCP通信，断网也能稳定运行，无需MQTT
+  - **MQTT模式**：可选接入Home Assistant等第三方平台
+- **工业级稳定性**：
+  - **多主站隔离**：采用实例级隔离机制，支持无限个主站和从站节点共存，配置互不干扰
+  - **智能分包/粘包处理**：内置1KB环形缓冲区和协议分析器，完美处理RS-485总线的分包、粘包问题
+  - **内存安全**：严格的内存管理策略，长时间运行内存不泄露，自动清理过期缓存
+  - **死锁防护**：多级看门狗机制，自动检测并恢复控制死循环，确保生产环境不卡顿
+- **Symi/Clowire生态集成**：
+  - **多协议支持**：完美支持Symi和Clowire（克伦威尔）双品牌协议，全面兼容 `0x03 SET`、`0x04 REPORT`、`0x05 STATUS` 等多种帧类型
+  - **全按键覆盖**：协议解析逻辑通用化，完美支持 1-8 号所有物理按键，不再局限于特定编号
+  - **蓝牙Mesh深度集成**：支持Symi蓝牙Mesh网关V1.3.1协议，实现无线开关秒级响应
+  - **设备持久化**：Mesh设备列表自动保存到磁盘，断电/重启/断网后配置不丢失
+- **反馈同步优化**：
+  - **轮询暂停机制**：上报数据时自动暂停主站轮询，防止状态回跳
+  - **REPORT协议强制化**：指示灯反馈强制使用REPORT (0x04)协议，不触发继电器动作，避免闪烁
+  - **指示灯状态强同步**：无论当前状态如何，物理按键操作都会强制下发指示灯同步指令，确保面板 LED 与系统状态严格一致，彻底解决状态错位导致的按键失灵
+  - **物理按键强制同步**：物理按键触发时强制同步 LED 反馈（忽略重复检查），纠正面板可能存在的状态不一致
+  - **协议解析安全化**：严格过滤 REPORT (0x04) 反馈回显数据，从源头上切断“反馈触发控制”的无限死循环，确保继电器不乱跳
+  - **精准反馈锁**：内置 **100ms** 毫秒级反馈锁，完美过滤 RS485 总线物理回显，同时确保高频连点操作不丢失状态
+- **高级控制功能**：
+  - **门禁联动过滤**：继电器节点支持门禁ID过滤，实现精确的门禁联动控制
+  - **HomeKit网桥**：一键接入Apple HomeKit，支持Siri语音控制，状态实时同步
+  - **智能写入队列**：所有写入操作串行执行，支持优先级管理，确保指示灯反馈在群控场景下秒级响应
+  - **多主站精准隔离**：支持多主站并行运行，通过 `masterId` 实现指令精准定向，严格过滤跨主站事件，彻底解决多主站环境下的控制冲突与误触发
+  - **智能反馈路由**：从站开关节点自动识别所属主站，仅响应目标主站的状态变化，防止多系统并存时的信号串扰
+  - **真·状态翻转逻辑**：继电器输出节点内置状态感知能力，基于物理设备真实反馈执行翻转操作，解决传统盲发指令导致的开关失灵
+- **可视化运维**：
+  - **控制看板**：实时显示所有继电器状态，支持手动控制
+  - **调试模式**：详细的通信日志，支持十六进制报文监控
+
+### 1. 安装
+
+**通过npm安装（推荐）**
+```bash
+cd ~/.node-red
+npm install node-red-contrib-symi-modbus
+node-red-restart
+```
+
+**通过Node-RED界面安装**
+1. 点击右上角菜单 → 设置 → 节点管理
+2. 搜索 `node-red-contrib-symi-modbus`
+3. 点击安装
+
+### 2. 选择运行模式
+
+本节点支持两种运行模式，根据需求选择：
+
+#### 模式1：本地模式（推荐用于纯串口控制）
+
+**适用场景**：
+- 无需对接第三方平台
+- 断网环境下稳定运行
+- 纯本地化控制，不受网络影响
+
+**配置方法**：
+1. 主站节点：不启用MQTT或不配置MQTT服务器
+2. 从站开关节点：不配置MQTT服务器
+3. **无需连线**：主站和从站通过内部事件自动通信
+
+**优势**：
+- 断网也能稳定运行
+- 不依赖外部服务
+- 响应速度更快
+- 配置更简单
+- 无需手动连线（免连线通信）
+
+#### 模式2：MQTT模式（推荐用于Home Assistant集成）
+
+**适用场景**：
+- 需要对接Home Assistant等平台
+- 需要远程控制
+- 需要状态持久化
+
+**配置方法**：
+1. 拖拽任意节点到流程画布
+2. 双击节点，找到"MQTT服务器"字段
+3. 点击编辑按钮，填写MQTT服务器信息：
+   - MQTT Broker: `mqtt://localhost:1883` (或你的MQTT服务器地址)
+   - 用户名/密码: 按需填写
+   - 基础主题: `modbus/relay` (默认)
+
+**优势**：
+- Home Assistant自动发现
+- 支持远程控制
+- 状态持久化存储
+
+### 3. 配置主站节点
+
+1. 拖拽 **Modbus主站** 节点到流程画布
+2. 配置连接参数：
+   - **串口模式**（直连RS485设备）：
+     - 连接类型: `串口`
+     - 串口路径: `/dev/ttyUSB0` (Linux/Mac) 或 `COM1` (Windows)
+     - 波特率: `9600`（默认）
+     - 数据位: `8`
+     - 停止位: `1`
+     - 校验位: `无`
+   - **TCP模式**（通过TCP转RS485网关）：
+     - 连接类型: `TCP/IP`
+     - TCP模式: `Telnet ASCII`（推荐，适用于大多数TCP转RS485网关）
+     - TCP主机: `192.168.2.110`
+     - TCP端口: `1031`
+     - 其他模式：
+       - `RTU over TCP`：适用于支持Modbus RTU over TCP的网关
+       - `Modbus TCP`：适用于标准Modbus TCP设备
+3. 配置从站设备：
+   - 从站地址: `10` (默认，可添加多个，如10、11、12、13)
+   - 线圈范围: `0-31`
+   - 轮询间隔: `200ms` (默认，支持100-10000ms)
+4. MQTT配置（可选）：
+   - 本地模式：不启用MQTT或留空
+   - MQTT模式：启用MQTT并选择MQTT服务器配置
+5. 部署流程
+
+### 4. 配置RS-485连接配置节点（用于从站开关）
+
+如果需要物理开关面板控制，首先创建RS-485连接配置：
+
+1. 点击右上角菜单 → 配置节点
+2. 添加新的 **serial-port-config** 配置节点
+3. 选择连接类型：
+   - **串口模式**（本地RS-485总线）：
+     - 连接类型: `串口`
+     - 串口路径: `/dev/ttyUSB0` (可点击"搜索"按钮自动发现)
+     - 波特率: `9600`
+     - 数据位: `8`
+     - 停止位: `1`
+     - 校验位: `无 (N)`
+   - **TCP模式**（通过TCP转RS485网关）：
+     - 连接类型: `TCP网关`
+     - TCP主机: `192.168.2.110`
+     - TCP端口: `1031`
+4. 保存配置
+
+### 5. 配置从站开关节点（可选）
+
+使用物理开关面板控制继电器，支持三种模式：
+
+#### 模式1：RS-485开关模式（传统有线开关）
+
+1. 拖拽 **从站开关** 节点到流程画布
+2. 选择刚创建的RS-485连接配置
+3. 配置开关面板信息：
+   - 面板品牌: `亖米` (默认)
+   - 按钮类型: `开关按钮（RS-485）`
+   - 开关ID: 物理面板地址 (0-255)
+   - 按钮编号: 按键编号 (1-8)
+4. 配置映射到的继电器：
+   - 目标从站地址: `10`
+   - 目标线圈编号: `1`（用户输入1-32）
+5. **无需连线**：主站和从站通过内部事件自动通信
+6. 部署流程
+
+#### 模式2：RS-485场景模式（场景触发）
+
+1. 配置步骤同上，但按钮类型选择 `场景按钮（RS-485）`
+2. 每次按键触发状态翻转（ON→OFF或OFF→ON）
+3. 适用于场景联动、一键控制等场景
+
+#### 模式3：Mesh开关模式（蓝牙Mesh无线开关）
+
+**适用场景**：使用Symi蓝牙Mesh网关和Mesh开关面板
+
+**配置步骤**：
+
+1. **准备工作**
+   - 确保Mesh网关已通过TCP或串口连接到Node-RED
+   - 确保Mesh开关已配网到网关
+
+2. **添加节点**
+   - 拖拽 **从站开关** 节点到流程画布
+   - 选择Mesh网关的连接配置（TCP或串口）
+
+3. **扫描Mesh设备**
+   - 按钮类型: 选择 `Mesh开关（蓝牙Mesh）`
+   - 点击 **扫描设备** 按钮
+   - 系统发送 `53 12 00 41` 协议帧到网关
+   - 网关立即返回所有Mesh开关列表（通常5秒内完成）
+   - 设备列表自动持久化保存到 `~/.node-red/mesh-devices-persist/`
+   - 重启Node-RED无需重新扫描，直接从持久化存储加载
+
+4. **选择设备和按键**
+   - Mesh设备: 从下拉框选择开关（显示格式：`MAC地址 (X路开关)`）
+   - 按钮编号: 选择要使用的按键（1-6路）
+   - **无线模式**（可选）: 勾选此选项后，该按键不响应LED反馈
+     - 适用场景：按键用于触发场景（如全开/全关），继电器状态变化不应点亮该按键LED
+     - 例如：按键3控制线圈16（全开触发），勾选无线模式后，线圈0-15状态变化不会点亮按键3的LED
+   - 多个节点可共享同一设备列表，无需重复扫描
+
+5. **配置目标继电器**
+   - 目标从站地址: `10`
+   - 目标线圈编号: `1`（用户输入1-32）
+
+6. **部署流程**
+   - 点击"完成"并部署
+   - Mesh开关按键会自动控制对应继电器
+   - 继电器状态变化会自动反馈到Mesh开关LED（无线模式按键除外）
+
+**Mesh模式特点**：
+- 无线控制，无需布线
+- 支持1-6路开关
+- 双向同步（按键→继电器，继电器→LED）
+- 支持无线模式（场景触发按键不响应LED反馈）
+- 设备列表持久化保存
+- 短地址自动更新（如果网关重新配网）
+- 与RS-485开关使用方式完全一致
+
+### 6. 配置HomeKit网桥节点（可选）
+
+将Modbus继电器桥接到Apple HomeKit，实现Siri语音控制：
+
+**配置步骤**：
+
+1. **添加网桥节点**
+   - 拖拽 **HomeKit网桥** 节点到流程画布
+   - 双击节点打开配置界面
+
+2. **基础配置**
+   - 网桥名称: `Modbus继电器网桥`（在HomeKit中显示）
+   - 选择主站节点: 从下拉框选择已配置的主站
+   - 配对码: `031-45-154`（添加到HomeKit时使用）
+   - 端口: `51828`（保持默认）
+
+3. **配置继电器名称**（推荐）
+   - 选择主站后，下方会自动显示所有继电器
+   - 为每个继电器输入友好的中文名称
+   - 例如：`客厅灯`、`卧室灯`、`空调插座`等
+   - 配置后在HomeKit中直接显示，无需再修改
+
+4. **部署并添加到HomeKit**
+   - 点击"完成"并部署流程
+   - 打开iPhone/iPad的"家庭"App
+   - 点击右上角"+" → "添加配件"
+   - 选择"更多选项"
+   - 找到"Modbus继电器网桥"
+   - 输入配对码：`031-45-154`
+   - 完成配对
+
+**使用说明**：
+- 线圈0-15显示为开关，线圈16-31显示为插座
+- 支持Siri语音控制："嘿Siri，打开客厅灯"
+- 支持HomeKit自动化和场景
+- 配置会自动保存，重启后无需重新配对
+- **群控性能**：支持同时控制多个继电器（如创建编组），智能队列机制确保流畅无卡顿
+
+**群控说明**（客户友好模式）：
+
+本节点专为智能家居群控场景优化，支持以下高性能操作：
+
+1. **HomeKit编组群控**：
+   - 在HomeKit中创建房间或编组，可同时控制多个继电器
+   - 例如：创建"客厅"编组，包含10个灯光开关，一键全开/全关
+   - 智能优先队列机制确保触发源面板最快响应，其他继电器按序执行
+   - 10个继电器同时动作仅需约 500ms（50ms间隔×10），触发源面板优先反馈
+
+2. **场景联动**：
+   - 支持HomeKit场景（如"回家模式"、"离家模式"）
+   - 场景可包含多个继电器动作，自动串行执行
+   - 前16个线圈（继电器）可同时动作，后16个线圈（场景）按需触发
+
+3. **性能保证**：
+   - 最大支持10台继电器（每台32路），共320个线圈
+   - 前160个线圈（10台×16路）可用于继电器控制，支持群控
+   - 后160个线圈（10台×16路）可用于场景触发，一般不会全部同时动作
+   - 智能写入队列确保所有操作串行执行，避免总线冲突
+   - 长期稳定运行，反复控制不会造成内存增加、卡顿或死机
+
+4. **技术细节**：
+   - 写入队列间隔：50ms（确保总线稳定，优化指示灯反馈）
+   - 写入锁机制：写入操作优先级高于轮询，自动抢占总线资源
+   - 轮询恢复时间：50ms（写入完成后快速恢复轮询）
+   - 锁等待超时：500ms（适配高延迟网络，确保指令不丢失）
+   - 智能优先队列：触发源面板优先处理（500ms优先窗口）
+   - 触发源追踪：全链路追踪控制指令来源（triggerSource），日志清晰记录是物理按键、HomeKit还是自动化触发
+   - 队列自动处理，无需手动干预
+
+## 核心特性说明
+
+### Symi开关自动识别
+
+主站节点自动支持两种控制方式，无需额外配置：
+
+#### 方式1：Modbus RTU轮询（标准）
+- 主站定期轮询从站线圈状态
+- 通过MQTT或Node-RED流程控制继电器
+- 适用于所有Modbus RTU设备
+
+#### 方式2：Symi私有协议（自动）
+- 自动识别Symi开关按键事件（协议格式：`7E [地址] 03 0F ...`）
+- 自动应答并控制对应继电器（协议格式：`7E [地址] 04 0F ...`）
+- 映射规则：
+  - 设备地址1 → 从站10
+  - 设备地址2 → 从站11
+  - 设备地址3 → 从站12
+  - 设备地址4 → 从站13
+  - 通道号1-8 → 线圈0-7
+
+**按钮类型说明**：
+
+**1. 开关按钮（推荐）**
+- **控制方式**：按键有独立的开/关状态
+- **LED反馈**：面板LED指示灯精确同步开关状态
+- **适用场景**：
+  - 灯光开关（客厅灯、卧室灯等）
+  - 插座开关（电器控制）
+  - 窗帘开关（电动窗帘）
+  - 任何需要明确开/关状态的场景
+- **技术特点**：
+  - 使用REPORT协议（0x04）发送LED反馈
+  - 使用原始设备地址确保LED精确反馈
+  - 支持物理按键和Home Assistant远程控制
+  - 面板LED完美同步，响应速度快
+
+**2. 场景按钮**
+- **控制方式**：每次按下toggle切换状态（开→关→开）
+- **LED反馈**：根据当前状态显示LED（开=亮，关=灭）
+- **协议特征**：操作信息为0x11、0x12、0x13等（高4位=1表示场景模式）
+- **适用场景**：
+  - 场景触发（回家模式、离家模式等）
+  - 一键全开/全关
+  - 需要状态指示的场景按钮
+- **技术特点**：
+  - 使用REPORT协议（0x04）发送LED反馈
+  - 使用原始设备地址确保LED精确反馈
+  - 支持物理按键和Home Assistant远程控制
+  - 200ms防抖，避免重复触发
+  - 自动识别场景模式（根据操作信息高4位判断）
+
+**两种模式对比**：
+
+| 特性 | 开关按钮 | 场景按钮 |
+|------|---------|---------|
+| 控制方式 | 开/关独立 | Toggle切换 |
+| 操作信息 | 0x00/0x01 | 0x11/0x12/0x13等 |
+| LED反馈协议 | REPORT (0x04) | REPORT (0x04) |
+| 按键事件 | 独立开/关码 | 统一触发码 |
+| LED同步 | ✓ 完美同步 | ✓ 完美同步 |
+| HA远程控制 | ✓ 支持 | ✓ 支持 |
+| 推荐场景 | 灯光/插座 | 场景触发 |
+| 自动识别 | ✓ 支持 | ✓ 支持 |
+
+**配置说明**：
+
+1. **RS-485连接**：选择串口配置节点（波特率9600，8N1）
+2. **MQTT服务器**（可选）：
+   - 本地模式：不启用MQTT，主站和从站通过内部事件自动通信（免连线）
+   - MQTT模式：启用MQTT并选择MQTT配置节点
+3. **面板配置**：
+   - 面板品牌：选择亖米（Symi）
+   - 按钮类型：开关按钮或场景按钮（也可自动识别）
+   - 开关ID：物理面板的RS-485地址（0-255）
+   - 按钮编号：面板上的按键序号（1-8）
+4. **继电器映射**：
+   - 从站地址：Modbus继电器地址（10-247）
+   - 继电器路数：继电器通道（1-32路）
+
+**使用示例**：
+
+**示例1：客厅灯光开关（本地模式）**
+- 面板：开关ID=2，按键1（开关按钮）
+- 继电器：从站10，1路
+- 配置：不启用MQTT，主站和从站自动通信（免连线）
+- 效果：按下面板按键，客厅灯开/关，面板LED同步状态，断网也能正常工作
+
+**示例2：全开场景（MQTT模式）**
+- 面板：开关ID=2，按键8（场景按钮）
+- 继电器：从站10，32路
+- 配置：启用MQTT，连接到Home Assistant
+- 效果：按下面板按键，触发全开场景，HA中可远程控制，面板LED同步状态
+
+**示例3：三键场景开关（本地模式）**
+- 面板：开关ID=1，按键1/2/3（场景按钮，自动识别）
+- 继电器：从站10，1/2/3路
+- 配置：不启用MQTT，主站和从站自动通信（免连线）
+- 效果：按下按键1/2/3，分别控制对应继电器，LED指示灯同步状态
+
+### 智能轮询机制
+
+主站轮询时，从站开关可以同时使用。当从站开关上报数据到服务器后：
+1. **自动暂停轮询**：主站检测到写入操作，立即暂停轮询
+2. **优先处理数据**：处理从站上报的数据（写入Modbus继电器）
+3. **继续轮询**：数据处理完成后（100ms延迟），自动恢复轮询
+4. **日志记录**：记录轮询暂停时长和跳过的轮询次数
+
+这种机制确保：
+- 主站轮询不会与从站写入冲突
+- 从站上报的数据得到优先处理
+- 系统响应迅速，状态同步及时
+
+### 总线数据过滤与稳定性
+
+本节点具备完善的总线数据过滤机制，确保长期稳定运行：
+
+**数据过滤机制**：
+- **CRC校验**：所有Symi协议帧都经过CRC8校验，无效数据自动丢弃
+- **静默忽略**：总线上的非相关数据（其他设备、其他协议）静默忽略，不影响正常通信
+- **精确匹配**：只处理本节点配置的从站地址和线圈范围内的数据
+- **TCP粘包处理**：TCP模式下自动处理粘包和分包问题，确保数据完整性
+
+**稳定性保障**：
+- **写入队列**：多个节点同时写入时自动排队，避免并发冲突
+- **断线重连**：TCP和串口断线后自动重连，指数退避策略（最大60秒）
+- **内存管理**：定时清理缓存，防止内存泄漏
+- **错误日志限流**：避免日志刷屏影响性能
+- **MQTT独立性**：MQTT开启或关闭都不影响主站和从站的本地通信
+
+**网络适应性**：
+- **离线通信**：串口模式完全脱离网络依赖，断网也能正常工作
+- **TCP稳定性**：TCP模式支持局域网通信，网络恢复后自动重连
+- **MQTT可选**：MQTT仅用于对接第三方平台，不影响本地控制
+
+## 调试节点（modbus-debug）
+
+用于抓取并显示原始RS485字节流数据（HEX），帮助定位串口或TCP网关下的Modbus通信问题。
+
+- 数据来源：
+  - 共享连接：`serial-port-config`（推荐，复用主站/从站的同一连接）
+  - 独立连接：`modbus-server-config`（直接连接TCP或串口）
+- 输出内容：
+  - `msg.payload`：格式化的HEX字符串（可选大写）
+  - `msg.buffer`：原始Buffer数据
+  - `msg.meta`：来源信息与连接参数（串口或TCP详情）
+  - `msg.timestamp`：时间戳（可选）
+- 显示控制：
+  - `maxBytes`：限制显示字节数，超过会截断并在`meta.truncated`标记
+
+使用步骤：
+1. 将 `modbus-debug` 节点拖入画布。
+2. 选择“数据来源”：
+   - 选“共享串口配置（serial-port-config）”以复用主站/从站连接；或
+   - 选“Modbus服务器（modbus-server-config）”进行独立直连。
+3. 可选：勾选“大写HEX”、勾选“时间戳”、设置“最大字节数”。
+4. 部署后，节点自动输出捕获到的原始数据。
+
+典型用法：
+- 联调TCP转RS485网关时，观察上行/下行原始数据帧是否完整。
+- 排查波特率/数据位/校验位配置是否正确（串口模式）。
+- 与 `modbus-master` 或 `modbus-slave-switch` 同时使用，定位现场设备通信异常。
+
+### MQTT自动发现
+
+启用MQTT后，自动生成Home Assistant兼容的Discovery配置：
+- **唯一性保证**：每个实体使用稳定的`unique_id`，避免重复生成
+- **设备分组**：同一从站的所有继电器自动分组到一个设备下
+- **状态持久化**：使用`retain=true`确保状态持久化
+- **在线状态**：自动发布设备可用性状态
+
+### 配置持久化
+
+所有节点配置自动保存到Node-RED的flows文件中：
+- 从站地址、线圈范围、轮询间隔
+- MQTT服务器配置
+- 开关面板映射关系
+
+部署后配置永久生效，重启Node-RED后自动恢复。
+
+### 长期稳定运行
+
+针对工控机24/7长期运行优化：
+- **内存管理**：自动清理缓存，释放无用对象
+- **事件监听器清理**：关闭时移除所有监听器，防止内存泄漏
+- **智能日志限流**：错误日志10分钟输出一次，避免日志刷屏
+- **智能重连机制**：
+  - Modbus连接断开自动重连（指数退避：5秒→10秒→20秒...最大60秒）
+  - MQTT连接断开自动重连（支持多地址fallback）
+  - 串口拔插自动检测并重连
+  - TCP网络故障自动恢复
+  - 连接前彻底清理旧实例，避免资源泄漏
+- **互斥锁机制**：防止读写冲突导致的数据异常
+- **TCP永久连接**：
+    - 禁用TCP超时（永久连接），避免无数据时超时断开
+    - Keep-Alive心跳10秒间隔，确保连接活跃
+  - 适应客户长期不在家、总线无数据的场景
+  - 网络故障自动重连，恢复后立即恢复通信
+
+## 技术规格
+
+### Modbus协议
+
+- **协议类型**：Modbus TCP / Modbus RTU
+- **底层库**：modbus-serial ^8.0.23（内部封装serialport，支持TCP和串口）
+- **功能码支持**：0x01（读线圈）、0x05（写单个线圈）、0x0F（写多个线圈）
+- **从站地址范围**：1-247（建议从10开始）
+- **线圈数量**：每台设备32个（0-31）
+- **最大设备数**：10台同时轮询
+- **轮询间隔**：默认200ms（建议300-500ms，支持100-10000ms）
+- **串口配置**：9600 8-N-1（波特率9600，8数据位，无校验，1停止位）
+- **超时设置**：5000ms（TCP和串口通用）
+
+### 兼容性
+
+- **Node.js**: >= 14.0.0
+- **Node-RED**: >= 2.0.0
+- **MQTT Broker**: Mosquitto / EMQX / Any MQTT 3.1.1/5.0
+- **Home Assistant**: 2024.x+（MQTT Discovery标准）
+- **操作系统**: Windows / Linux / macOS / HassOS
+
+## Home Assistant集成
+
+### 自动发现
+
+启用MQTT后，设备自动出现在Home Assistant中：
+- 实体ID: `switch.relay_{从站地址}_{线圈编号}`
+- 设备名称: `Modbus继电器-{从站地址}`
+- 自动分组: 同一从站的所有继电器分组到一个设备
+
+### MQTT主题结构
+
+```
+状态主题: modbus/relay/{从站}/{线圈}/state
+命令主题: modbus/relay/{从站}/{线圈}/set
+可用性主题: modbus/relay/{从站}/availability
+发现主题: homeassistant/switch/modbus_relay_{从站}_{线圈}/config
+```
+
+## 故障排除
+
+### 串口连接失败
+
+**Linux**:
+```bash
+# 查看串口设备
+ls -l /dev/ttyUSB* /dev/ttyS*
+
+# 添加用户到dialout组（需要重新登录）
+sudo usermod -a -G dialout $USER
+```
+
+**macOS**:
+```bash
+# 查看串口设备（注意macOS使用cu.*而不是tty.*）
+ls -l /dev/cu.*
+```
+
+**Docker/HassOS**:
+```yaml
+# 在docker-compose.yml或HassOS插件配置中添加设备映射
+devices:
+  - /dev/ttyUSB0:/dev/ttyUSB0
+```
+
+### MQTT连接失败
+
+1. 确认MQTT broker正在运行：
+   ```bash
+   # Linux
+   sudo systemctl status mosquitto
+   
+   # macOS
+   brew services list | grep mosquitto
+   ```
+
+2. 测试MQTT连接：
+   ```bash
+   mosquitto_sub -h localhost -t test
+   ```
+
+3. 检查Node-RED日志中的MQTT连接信息
+
+### 主站轮询不工作
+
+1. **检查从站配置**：确认已添加所有从站设备（如10、11、12、13）
+2. **检查轮询间隔**：默认200ms，建议300-500ms（多台从站时避免总线拥堵）
+3. **查看Node-RED调试日志**：部署后查看日志中的轮询信息
+4. **检查串口波特率**：确认波特率为9600（与从站设备一致）
+5. **检查从站地址**：确认从站地址正确（1-247）
+
+### 轮询超时或频繁报错
+
+1. **轮询永不停止原则**：
+   - 即使从站不响应，轮询也会持续运行
+   - 不会因超时而跳过任何从站
+   - 只记录错误日志，不影响总线轮询机制
+2. **正常超时**：偶尔超时是正常的，系统会自动重试
+   - 超时设置：2-3秒（串口/TCP）
+   - 只记录日志，不停止轮询
+   - 轮询会持续运行，不受超时影响
+3. **频繁超时**：
+   - 检查Modbus连接是否稳定
+   - 调整轮询间隔（默认200ms，可增加到500ms）
+   - 检查从站设备是否在线
+   - 查看总线是否有其他设备干扰
+4. **总线干扰**：
+   - 总线上的其他数据（如Symi网关通信、其他Modbus设备）可能导致偶尔超时或CRC错误
+   - 系统已优化容错机制，会自动忽略异常数据并继续轮询
+   - 非超时错误（如CRC错误）不累积计数，只记录日志
+5. **长期稳定性保障**：
+   - 轮询循环采用try-catch包裹，确保异常不会中断轮询
+   - 每1000轮输出一次调试日志，证明轮询持续运行
+   - 定时清理机制（每小时）防止内存泄漏
+   - 所有定时器在节点关闭时正确清除
+
+### 总线上出现未知数据
+
+1. **识别数据来源**：
+   - 使用`modbus-debug`节点监听总线数据（必须使用共享的serial-port-config，避免串口冲突）
+   - 查看Node-RED日志中的"写入线圈"日志，确认是否是本节点发送的
+   - 检查是否有其他Modbus设备或Symi网关在总线上通信
+2. **常见数据格式**：
+   - `01 05 00 01 FF 00 ...`：写单个线圈（功能码0x05）
+   - `01 0F 00 00 00 20 ...`：写多个线圈（功能码0x0F）
+   - `7E 01 03 ...`：Symi轻量级协议数据
+3. **影响**：
+   - 总线上的其他数据不会影响轮询稳定性
+   - 可能导致偶尔的CRC错误或超时，但系统会自动忽略并继续轮询
+
+### 串口冲突错误
+
+**错误信息**：
+```
+串口监听错误: Port is not open
+串口监听错误: Error Resource temporarily unavailable Cannot lock port
+```
+
+**原因**：
+- 多个节点试图独立打开同一个串口
+- 串口只能被一个进程同时打开
+
+**解决方案**：
+1. **modbus-debug节点**：必须使用"serial"源类型，选择共享的`serial-port-config`配置节点
+2. **不要使用独立连接**：不要让多个节点独立打开同一个串口
+3. **共享连接配置**：所有节点（主站、从站开关、modbus-debug）都应该使用同一个`serial-port-config`配置节点
+
+### 批量更换连接配置
+
+**问题**：如何批量更换所有节点的RS-485连接配置？
+
+**Node-RED原生方法**（推荐）：
+1. 创建新的`serial-port-config`配置节点
+2. 点击右上角菜单 → 配置节点
+3. 找到旧的`serial-port-config`配置节点
+4. 点击删除按钮
+5. Node-RED会提示"此配置节点被X个节点使用，是否替换为其他配置？"
+6. 选择新创建的配置节点
+7. 点击确认，所有使用旧配置的节点会自动更换为新配置
+
+**注意**：
+- 这是Node-RED的原生功能，安全可靠
+- 删除配置节点前必须先创建新配置
+- 替换后需要部署才能生效
+6. **确认从站设备在线**：使用Modbus调试工具测试从站是否响应
+7. **检查MQTT连接**：确保MQTT broker地址正确，轮询不依赖MQTT但状态发布需要MQTT
+8. **测试连接**：
+   - TCP连接问题：先用 `modbus-serial` 单独测试TCP连接
+   - 串口问题：先用 `serialport` 单独测试串口通信
+
+### 从站开关无响应
+
+1. **检查免连线通信**（v2.6.7+推荐）：
+   - **无需连线**：主站和从站通过内部事件自动通信，无需手动连线
+   - 查看Node-RED日志，确认是否有"内部事件模式：发送命令到从站X 线圈Y"的日志
+   - 查看主站节点日志，确认是否有"收到内部事件：从站X 线圈Y"的日志
+   - 查看主站节点日志，确认是否有"内部事件写入成功，已广播状态变化"的日志
+   - 查看从站开关节点日志，确认是否有"收到状态变化事件"和"LED反馈已发送"的日志
+2. **检查RS-485连接**：
+   - 确认RS-485连接配置正确（串口路径、波特率等）
+   - 查看节点状态显示是否为"MQTT未启用 - 使用内部事件模式"
+   - 物理面板连接：确认物理面板连接到正确的RS-485总线（TCP或串口）
+3. **检查开关面板配置**：
+   - 确认开关面板地址和按钮编号正确
+   - 场景模式开关：操作信息为0x11、0x12、0x13等（高4位=1）
+   - 开关模式开关：操作信息为0x00（关）或0x01（开）
+4. **检查继电器映射**：
+   - 确认目标从站地址和线圈编号正确
+   - 线圈编号范围：0-31（对应用户输入的1-32路）
+5. **查看调试日志**：
+   - 使用modbus-debug节点抓取原始总线数据
+   - 查看Node-RED日志中的协议解析信息
+   - 确认按键事件是否被正确识别
+   - 确认LED反馈协议帧是否正确发送（查看日志中的HEX字符串）
+
+## 输入消息格式
+
+### 主站节点
+
+```javascript
+// 启动轮询
+msg.payload = {cmd: "start"};
+
+// 停止轮询
+msg.payload = {cmd: "stop"};
+
+// 写单个线圈
+msg.payload = {
+    cmd: "writeCoil",
+    slave: 10,      // 从站地址
+    coil: 0,        // 线圈编号
+    value: true     // true=开, false=关
+};
+
+// 批量写多个线圈
+msg.payload = {
+    cmd: "writeCoils",
+    slave: 10,      // 从站地址
+    startCoil: 0,   // 起始线圈
+    values: [true, false, true, false]  // 线圈值数组
+};
+```
+
+### 从站开关节点
+
+```javascript
+// 发送开关命令
+msg.payload = true;   // 或 false
+msg.payload = "ON";   // 或 "OFF"
+msg.payload = 1;      // 或 0
+```
+
+### HomeKit网桥节点
+
+HomeKit网桥节点无需输入消息，自动同步主站配置和状态。
+
+**配置参数**：
+- **主站节点**：选择要桥接的Modbus主站节点（必填）
+- **网桥名称**：在HomeKit中显示的网桥名称（默认：Modbus继电器网桥）
+- **MAC地址**：HomeKit网桥的唯一标识符（自动生成，无需修改）
+- **配对码**：HomeKit配对时使用的PIN码（格式：XXX-XX-XXX，默认：031-45-154）
+- **端口**：HomeKit网桥监听端口（默认：51828）
+- **继电器名称配置**：为每个继电器配置友好的中文名称（可选）
+
+**自动同步规则**：
+- 自动读取主站节点配置的所有从站和线圈
+- 线圈0-15（1-16路）：创建为开关（Switch）配件
+- 线圈16-31（17-32路）：创建为插座（Outlet）配件
+- 监听主站的状态变化事件，实时同步到HomeKit
+- 接收HomeKit控制命令，发送到主站执行
+
+**使用示例**：
+1. 在Node-RED中配置好主站节点和从站
+2. 添加HomeKit网桥节点，选择主站节点
+3. 为每个继电器配置友好的名称（例如：客厅灯、卧室灯）
+4. 部署流程
+5. 在iPhone的"家庭"App中添加配件，输入配对码
+6. 完成配对后，即可在HomeKit中控制继电器，支持Siri语音控制
+
+**注意事项**：
+- 确保主站节点已正确配置并运行
+- 配对码格式必须为XXX-XX-XXX（8位数字）
+- 端口不能与其他服务冲突（默认51828）
+- 配置信息持久化存储在~/.node-red/homekit-persist目录
+- 重启Node-RED后自动恢复配对状态，无需重新配对
+
+### 7. 配置Mesh透传控制节点
+
+**Mesh透传控制**节点允许在没有Mesh网关的情况下，直接通过现有的RS-485或TCP连接与Mesh实体进行通信。
+
+**功能特点**：
+- **自动发现**：只要总线上有匹配的Mesh实体协议（如窗帘、调光、开关、空调、新风、地暖），节点会自动捕捉并生成实体。
+- **持久化存储**：实体信息根据MAC地址去重并永久保存到磁盘（`.node-red/symi-mesh-entities`），确保设备离线或Node-RED重启后实体列表依然有效。
+- **灵活绑定**：支持绑定到物理从站继电器输出或物理从站开关面板按键。
+- **多类型支持**：
+  - **窗帘**：实现“打开 -> 停止 -> 关闭 -> 停止”循环控制。
+  - **开关/调光/空调/新风/地暖**：实现标准的开/关/翻转控制。
+- **状态同步**：实时监听总线上的Mesh状态更新，并在节点上直观显示当前状态（如 ON/OFF 或窗帘动作）。
+
+**配置步骤**：
+
+1. **添加节点**
+   - 拖拽 **Mesh透传控制** 节点到流程画布。
+   - 选择现有的 **serial-port-config** 连接配置（串口 9600 或 TCP 网关）。
+
+2. **选择Mesh实体**
+   - 在“Mesh实体”下拉框中选择已发现的设备。
+   - 如果是新设备，请先在物理端操作一次设备，总线采集到数据后会自动出现在列表中。
+   - 列表显示格式：`[类型] MAC地址 (短地址)`。
+
+3. **配置触发源（可选）**
+   - **绑定从站继电器**：输入目标从站地址和线圈编号。当对应的从站继电器状态变化时，会触发此Mesh实体的控制。
+   - **绑定面板按键**：输入面板开关ID和按键编号。当按下物理面板按键时，会触发此Mesh实体的控制。
+
+4. **控制逻辑**
+   - 节点会自动根据实体类型选择最佳控制逻辑（窗帘循环或普通开关）。
+   - 手动点击节点左侧按钮也可直接触发控制。
+
+---
+
+### 8. 控制看板节点（客户友好模式）
+
+控制看板节点提供可视化界面，实时显示和控制所有从站的继电器状态，适合现场调试和日常监控。
+
+**配置参数**：
+- **节点名称**：控制看板的显示名称（默认：Modbus控制看板）
+- **主站节点**：选择要监控的Modbus主站节点（必填）
+
+**功能特性**：
+- **实时状态显示**：在配置界面中显示所有从站和线圈的实时状态
+- **一键控制**：点击按钮即可控制继电器开关，无需部署流程
+- **美观布局**：网格布局，按从站分组显示，一目了然
+- **名称同步**：自动同步HomeKit网桥配置的继电器名称
+- **快速响应**：状态实时更新（500ms轮询），响应迅速
+- **零开销**：不参与实际Modbus通信，不影响主站性能
+
+**使用步骤**：
+1. 在Node-RED中添加控制看板节点
+2. 选择已配置的Modbus主站节点
+3. 双击节点打开配置界面，即可看到所有继电器状态
+4. 点击按钮即可控制继电器开关（绿色=ON，红色=OFF）
+5. 部署流程后，节点会显示"监控中"状态
+
+**使用场景**：
+- **现场调试**：快速测试继电器是否正常工作
+- **日常监控**：实时查看所有继电器状态
+- **批量控制**：快速控制多个继电器
+- **客户演示**：美观的界面，适合向客户展示系统功能
+
+**技术细节**：
+- 使用HTTP API与主站通信，通过内部事件发送控制命令
+- 状态缓存机制，减少网络请求
+- 仅在配置界面打开时才轮询状态，关闭后自动停止
+- 与HomeKit网桥共享继电器名称配置，保持一致性
+
+**注意事项**：
+- 确保主站节点已正确配置并运行
+- 控制看板只在配置界面打开时才轮询状态
+- 继电器名称需在HomeKit网桥节点中配置
+- 本节点不参与实际Modbus通信，不会增加主站负担
+
+### 自定义协议节点
+
+用于控制非标准Modbus协议的485设备（如窗帘、特殊开关等）。
+
+**配置步骤**：
+1. 添加自定义协议节点到流程画布
+2. 选择设备类型（开关/窗帘/其他）
+3. 选择串口配置节点
+4. 输入16进制指令（空格分隔，自动格式化为大写）
+   - 打开指令：例如 `01 05 00 00 FF 00 8C 3A`
+   - 关闭指令：例如 `01 05 00 00 00 00 CD CA`
+   - 暂停指令：仅窗帘模式需要，例如 `01 05 00 01 FF 00 DD FA`
+5. 点击"测试"按钮验证指令是否正确发送
+6. 连线：从站开关 → 自定义协议节点
+7. 部署流程
+
+**设备类型说明**：
+- **开关模式**：收到`true`发送打开指令，收到`false`发送关闭指令
+- **窗帘模式**：每次触发循环发送下一个指令（打开 → 暂停 → 关闭 → 暂停 → 打开...）
+- **其他模式**：与开关模式相同
+
+**使用场景**：
+- 窗帘控制：支持打开/暂停/关闭循环控制
+- 特殊开关：非标准Modbus协议的485设备
+- 自定义设备：任何需要发送固定16进制指令的设备
+
+**注意事项**：
+- 每个指令最多48字节
+- 窗帘模式需配置三个指令（打开、关闭、暂停）
+- 测试功能需先选择串口配置
+- 无需连线到debug节点，直接通过串口配置节点发送数据
+
+### 继电器输出节点（relay-output）
+
+用于控制Modbus继电器，支持**绑定从站开关触发源**或接收外部输入，**无需连线到主站**。
+
+**核心特性**：
+- 从站开关、继电器输出、主站之间**完全无需连线**
+- 共享RS-485连接配置，支持多个节点共用
+- 支持绑定从站开关作为触发源（内部事件通信）
+- 支持外部设备触发（如海康门禁）
+- 支持延时执行（0-60000毫秒），实现级联开灯效果
+- 配置持久化保存，断电断网恢复后正常工作
+
+**配置参数**：
+
+*RS-485连接配置*：
+- **连接配置**：选择已配置的RS-485连接（支持TCP网关或串口），多个节点共享
+
+*按键触发配置*：
+- **面板品牌**：开关面板品牌，目前支持亖米（Symi）
+- **按钮类型**：开关按钮/场景按钮/输入端触发（外部设备）
+- **开关ID**：物理面板地址（0-255）
+- **按钮编号**：按键编号(1-8，15=背光灯)
+- **门禁ID**：可选，0=不过滤，>0=只响应指定门禁编号
+
+*目标继电器配置*：
+- **从站地址**：要控制的Modbus从站地址(1-247)
+- **继电器路数**：要控制的继电器通道(1-32)
+
+*动作配置*：
+- **动作**：打开/关闭/跟随输入/翻转状态
+- **延时**：执行延时（0-60000毫秒），用于实现级联开灯效果
+- **忽略释放信号**：只响应按下信号
+
+**使用示例**：
+
+**示例1：按键触发继电器（无需任何连线）**
+```
+配置：开关ID=1，按钮编号=3，从站地址=10，继电器路数=1，动作=打开
+效果：当开关1的按钮3被按下时，自动控制从站10的1路继电器打开
+```
+
+**示例2：一个按键控制多路继电器（级联开灯）**
+```
+继电器输出1: 开关ID=1, 按钮=3, 继电器=1路, 延时=0ms, 动作=打开
+继电器输出2: 开关ID=1, 按钮=3, 继电器=2路, 延时=500ms, 动作=打开
+继电器输出3: 开关ID=1, 按钮=3, 继电器=3路, 延时=1000ms, 动作=打开
+```
+
+**示例3：海康门禁触发（使用输入端）**
+```
+海康门禁事件 → 继电器输出(按钮类型=输入端触发, 从站地址=10, 继电器=1路, 门禁ID=4)
+```
+
+**工作原理**：
+- 节点监听 `modbus:buttonPressed` 事件（按键触发）
+- 通过 `modbus:writeCoil` 事件发送控制命令到主站
+- 实现按键 → 继电器输出 → 主站之间的无连线通信
+
+**稳定性保障**：
+- 长期运行不卡顿、不死机、内存不溢出
+- 无调试数据输出，具备生产条件长期运行
+- 断电断网恢复后正常工作
+- 内置防抖和状态检测机制，不会出现设备反复开关进入死循环
+
+## 输出消息格式
+
+### 主站节点
+
+```javascript
+{
+    payload: {
+        slave: 10,                // 从站地址
+        coils: [true, false, ...], // 线圈状态数组
+        timestamp: 1234567890     // 时间戳
+    }
+}
+```
+
+### 从站开关节点
+
+```javascript
+{
+    payload: true,                    // 开关状态
+    topic: "switch_0_btn1",          // 主题
+    switchId: 0,                     // 开关面板ID
+    button: 1,                       // 按钮编号
+    targetSlave: 10,                 // 目标从站地址
+    targetCoil: 0                    // 目标线圈编号
+}
+```
+
+## 性能指标
+
+- **内存占用**：< 50MB（单个主站节点，轮询10个设备）
+- **CPU占用**：< 5%（正常轮询状态）
+- **连接延迟**：Modbus响应 < 100ms，MQTT发布 < 50ms
+- **稳定运行**：经过工控机7x24小时长期运行验证
+- **容错能力**：Modbus从站离线不影响其他从站，MQTT断线自动重连
+
+## 示例Flow
+
+```json
+[
+    {
+        "id": "modbus-master-1",
+        "type": "modbus-master",
+        "name": "主站",
+        "connectionType": "serial",
+        "serialPort": "/dev/ttyUSB0",
+        "serialBaudRate": 9600,
+        "slaves": [
+            {"address": 10, "coilStart": 0, "coilEnd": 31, "pollInterval": 200},
+            {"address": 11, "coilStart": 0, "coilEnd": 31, "pollInterval": 200},
+            {"address": 12, "coilStart": 0, "coilEnd": 31, "pollInterval": 200},
+            {"address": 13, "coilStart": 0, "coilEnd": 31, "pollInterval": 200}
+        ],
+        "enableMqtt": true,
+        "mqttServer": "mqtt-config-1"
+    }
+]
+```
+
+完整示例请参考项目中的 `examples/basic-flow.json` 文件。
+
+## 技术栈
+
+- Node.js: >=14.0.0
+- Node-RED: >=2.0.0
+- modbus-serial: ^8.0.23
+- serialport: ^12.0.0
+- mqtt: ^5.14.1（可选）
+- hap-nodejs: ^1.2.0
+- node-persist: ^4.0.4
+
+## 版本更新说明
+
+### v2.10.8 (2026-01-24)
+- **指示灯反馈核心修复**: 彻底修复指示灯反馈地址错误及失效问题。
+  - **寻址逻辑修正**: 修正反馈帧的地址映射逻辑。`localAddr` 修正为面板 ID（发送方），`deviceAddr` 修正为子设备地址（1），`channel` 修正为按键 ID，确保反馈报文准确送达目标按键。
+  - **协议帧结构重构**: 严格对齐 V0.13 协议框架图，修正 `REPORT` 帧结构为 15 字节，修正 CRC8 计算范围（前13字节），移除了冗余的操作信息字节。
+  - **初始化优化**: 节点启动时优先使用配置的 `switchId` 作为默认反馈目标，无需等待首次按键触发即可正常同步状态。
+  - **协议兼容性**: 强制指示灯反馈使用 `DEVICE_TYPE_LIGHT (0x01)` 类型，兼容 Symi/Clowire 全系面板固件。
+- **Mesh实体注册增强**: 
+  - **无MAC实体持久化**: 支持无 MAC 地址的实体通过短地址持久化，解决 Mesh 网关模式下部分设备（如仅上报状态的窗帘）无法生成实体的问题。
+  - **动态类型识别**: 收到状态帧时立即根据 `msgType` 推断设备类型，无需等待设备列表响应即可控制。
+- **窗帘控制深度优化**: 
+  - **端点状态纠偏**: 当位置到达 0% 或 100%（容差±2%）时，强制重置状态为“停止”，彻底消除到达端点后点击反向无反应（误判为暂停）的问题。
+  - **智能暂停恢复**: 修复运动过程中的暂停功能，通过位置变化和时间推断运动状态，确保中途点击能正确触发“暂停”。
+  - **逻辑对齐**: 统一 `toggle` 和 `cycle` 逻辑，基于实时位置和上次动作智能决策下一步动作。
+- **物理面板直连**: Mesh透传节点新增内置协议解析，直接支持Symi/Clowire面板控制 (支持03场景指令)，复用 `Lightweight Protocol` 标准解析逻辑，确保协议完全兼容。
+- **安装与文档规范**: 
+  - **路径修正**: 明确本地安装路径应为 Node-RED 用户目录（如 `~/.node-red`）。
+  - **文档优化**: 合并了 README.md 中重复的更新日志条目。
+  - **日志体验提升**: 优化 `serial-port-config` 日志输出，Mesh 实体更新日志增加中文动作描述（打开/关闭/停止）和位置百分比。
+
+### v2.10.7 (2026-01-22)
+- **协议解析增强**: 修复 `serial-port-config` 无法解析字符串格式数据的问题，支持直接处理 Hex 字符串帧（如 `53 80 ...`）。
+- **Mesh实体管理**: 
+  - **双重匹配机制**: 优先使用 MAC 地址匹配实体（Mesh网关模式），无 MAC 时自动降级为短地址匹配（透传模式），确保所有设备均可被发现和控制。
+  - **无MAC实体支持**: 完美支持透传节点上报的无MAC状态帧（如窗帘 `53 80`），自动基于短地址注册并持久化实体，不再强制依赖 MAC。
+  - **智能类型推断**: 收到状态帧时立即根据 `msgType` 推断设备类型（如窗帘、调光），无需等待设备列表响应即可使用。
+  - **自动补全**: 在后续收到设备列表（带MAC）时，自动为无MAC实体补全 MAC 地址，实现平滑升级。
+- **队列优先级**: 明确指令优先级：从站开关 (3) > 继电器 (2) > Mesh透传 (1) > 普通 (0)。
+- **文档更新**: 更新 `README.md` 和 `透传节点协议.md`，补充最新的协议细节和注意事项。
+
+### v2.10.6 (2026-01-17)
+- **多节点LED状态聚合**: 支持多个 `从站开关` 节点配置为同一物理按键（相同 Switch ID 和 Button ID）但控制不同继电器。系统会自动聚合所有关联继电器的状态（OR逻辑），实现“任意开则灯亮，全关则灯灭”的智能反馈，完美支持“一键多控”场景。
+- **全关指令优化**: 支持 Symi/Clowire 协议的“全关”指令，降低总线负载。
+- **Symi协议深度优化**: 新增支持 Symi 协议的“全关”指令（0x05 MULTI）。
+- **日志优化**: 对网络错误日志进行限流，避免刷屏。
+- **稳定性增强**: 优化了全局状态管理的内存回收机制。
+
+### v2.10.5 (2026-01-15)
+- **多主站精准隔离架构**：引入 `masterId` 指令定向机制。
+- **真·状态翻转 (Toggle) 逻辑**：继电器输出节点新增状态感知能力。
+- **指示灯反馈机制重构**：优化了 `modbus-slave-switch` 的反馈锁与初始化逻辑。
+- **生产级日志分级**：对全局日志进行了分级处理。
+- **资源管理与稳定性**：规范化了所有节点的 `close` 生命周期管理。
+
+### v2.10.4 (2026-01-14)
+- **Modbus超时优化**：将默认Modbus通信超时时间（Timeout）统一调整为 **3000ms**。
+- **锁等待恢复合理值**：将写入锁等待超时恢复为 **3000ms**。
+- **断连彻底静默**：移除写入队列在断连时的错误日志提醒。
+- **缓存策略优化**：连接断开时立即清空所有待处理的写入任务。
+- **连接恢复优化**：移除重连后的自动任务恢复逻辑。
+
+### v2.10.3 (2026-01-14)
+- **协议兼容性**: 完善 Symi 协议解析逻辑，全面支持 `0x03 SET`、`0x04 REPORT` 和 `0x05 STATUS` 帧类型。
+- **稳定性修复**: 紧急修复物理回显导致的“继电器无限跳动”死循环问题。
+- **并发优化**: 优化主站写入锁等待机制，将最大等待时间延长至 **500ms**。
+- **指示灯同步**: 引入物理按键“强制同步”机制。
+- **多主站联动**: 优化 `relay-output` 和 `modbus-slave-switch` 的事件路由。
+- **架构解耦**: 明确指示灯同步职责。
+
+### v2.10.2 (2026-01-14)
+- **轮询优化**: 引入轮询暂停机制。
+- **反馈增强**: 强制使用 REPORT (0x04) 协议进行指示灯同步。
+- **并发管理**: 优化写入队列机制。
+- **Mesh深度支持**: 完善 Mesh 模式下的 LED 反馈。
+- **稳定性提升**: 优化主站轮询逻辑。
+- **隔离机制**: 引入多串口/多网关作用域隔离。
+
+### v2.10.1 (2026-01-13)
+- **名称校准**: HA 实体名称校准。
+- **防抖优化**: 引入全局按键事件去重防抖。
+- **组网支持**: 改进 LED 反馈机制。
+
+## 许可证
+
+MIT License
+
+## 支持与反馈
+
+- GitHub: https://github.com/symi-daguo/node-red-contrib-symi-modbus
+- Issues: https://github.com/symi-daguo/node-red-contrib-symi-modbus/issues
+- NPM: https://www.npmjs.com/package/node-red-contrib-symi-modbus