node-red-contrib-symi-modbus 2.6.5 → 2.6.7

package/README.md

@@ -1,30 +1,26 @@
 # node-red-contrib-symi-modbus
 
-Node-RED的Modbus继电器控制节点，支持TCP/串口通信和MQTT集成。
+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等第三方平台
 - **多协议支持**：
+  - Modbus RTU（串口直连RS485）
   - Modbus TCP（标准Modbus TCP）
   - Modbus RTU over TCP（TCP转RS485网关）
   - Telnet ASCII（推荐用于TCP转RS485网关）
-  - Modbus RTU（串口直连）
-- **Symi开关支持**：自动识别并处理Symi私有协议按键事件，无需额外配置
-- **多设备轮询**：最多支持10台Modbus从站设备同时轮询
-- **32路继电器**：每台设备支持32个线圈（继电器通道）
-- **智能轮询**：从站上报时自动暂停轮询，优先处理数据，完成后继续轮询
-- **灵活配置**：可自定义轮询间隔（100-10000ms，默认200ms）、线圈范围、从站地址
-- **🔥 双模式支持**：
-  - **本地模式**：纯串口通信，无需MQTT，断网也能稳定运行
-  - **MQTT模式**：可选接入Home Assistant等第三方平台
-- **MQTT集成**（可选）：自动生成Home Assistant兼容的MQTT发现消息
-- **实时状态**：实时监控和控制继电器状态
-- **主从模式**：提供主站节点和从站控制节点
-- **稳定可靠**：完整的内存管理和错误处理，适合工控机长期稳定运行
+- **Symi开关集成**：自动识别并处理Symi私有协议按键事件，实现开关面板与继电器的双向同步
+- **多设备轮询**：支持最多10台Modbus从站设备，每台32路继电器
+- **智能轮询机制**：从站上报时自动暂停轮询，优先处理数据，避免冲突
+- **稳定可靠**：完整的内存管理、错误处理、断线重连，适合7x24小时长期运行
+- **总线数据过滤**：自动忽略总线上的无关数据，只处理本节点相关的数据
 
 ## 快速开始
 
@@ -56,13 +52,14 @@ node-red-restart
 **配置方法**：
 1. 主站节点：不启用MQTT或不配置MQTT服务器
 2. 从站开关节点：不配置MQTT服务器
-3. 将从站开关节点的输出连线到主站节点的输入
+3. **无需连线**：主站和从站通过内部事件自动通信（v2.6.7+）
 
 **优势**：
 - ✅ 断网也能稳定运行
 - ✅ 不依赖外部服务
 - ✅ 响应速度更快
 - ✅ 配置更简单
+- ✅ 无需手动连线（免连线通信）
 
 #### 模式2：MQTT模式（推荐用于Home Assistant集成）
 
@@ -142,10 +139,12 @@ node-red-restart
    - 面板品牌: `亖米` (默认)
    - 开关ID: 物理面板地址 (0-255)
    - 按钮编号: 按键编号 (1-8)
+   - 按钮类型: 开关按钮或场景按钮（也可自动识别）
 4. 配置映射到的继电器：
    - 目标从站地址: `10`
    - 目标线圈编号: `0`
-5. 部署流程
+5. **无需连线**：主站和从站通过内部事件自动通信，无需手动连线
+6. 部署流程
 
 ## 核心特性说明
 
@@ -187,6 +186,7 @@ node-red-restart
 **2. 场景按钮**
 - **控制方式**：每次按下toggle切换状态（开→关→开）
 - **LED反馈**：根据当前状态显示LED（开=亮，关=灭）
+- **协议特征**：操作信息为0x11、0x12、0x13等（高4位=1表示场景模式）
 - **适用场景**：
   - 场景触发（回家模式、离家模式等）
   - 一键全开/全关
@@ -196,25 +196,30 @@ node-red-restart
   - 使用原始设备地址确保LED精确反馈
   - 支持物理按键和Home Assistant远程控制
   - 200ms防抖，避免重复触发
+  - 自动识别场景模式（根据操作信息高4位判断）
 
 **两种模式对比**：
 
 | 特性 | 开关按钮 | 场景按钮 |
 |------|---------|---------|
 | 控制方式 | 开/关独立 | Toggle切换 |
+| 操作信息 | 0x00/0x01 | 0x11/0x12/0x13等 |
 | LED反馈协议 | SET (0x03) | REPORT (0x04) |
 | 按键事件 | 独立开/关码 | 统一触发码 |
 | LED同步 | ✓ 完美同步 | ✓ 完美同步 |
 | HA远程控制 | ✓ 支持 | ✓ 支持 |
 | 推荐场景 | 灯光/插座 | 场景触发 |
+| 自动识别 | ✓ 支持 | ✓ 支持 |
 
 **配置说明**：
 
 1. **RS-485连接**：选择串口配置节点（波特率9600，8N1）
-2. **MQTT服务器**：选择MQTT配置节点（连接Home Assistant等）
+2. **MQTT服务器**（可选）：
+   - 本地模式：不启用MQTT，主站和从站通过内部事件自动通信（免连线）
+   - MQTT模式：启用MQTT并选择MQTT配置节点
 3. **面板配置**：
    - 面板品牌：选择亖米（Symi）
-   - 按钮类型：开关按钮或场景按钮
+   - 按钮类型：开关按钮或场景按钮（也可自动识别）
    - 开关ID：物理面板的RS-485地址（0-255）
    - 按钮编号：面板上的按键序号（1-8）
 4. **继电器映射**：
@@ -223,15 +228,23 @@ node-red-restart
 
 **使用示例**：
 
-**示例1：客厅灯光开关**
+**示例1：客厅灯光开关（本地模式）**
 - 面板：开关ID=2，按键1（开关按钮）
 - 继电器：从站10，1路
-- 效果：按下面板按键，客厅灯开/关，面板LED同步状态
+- 配置：不启用MQTT，主站和从站自动通信（免连线）
+- 效果：按下面板按键，客厅灯开/关，面板LED同步状态，断网也能正常工作
 
-**示例2：全开场景**
+**示例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指示灯同步状态
 
 ### 智能轮询机制
 
@@ -246,6 +259,56 @@ node-red-restart
 - 从站上报的数据得到优先处理
 - 系统响应迅速，状态同步及时
 
+### 总线数据过滤与稳定性
+
+本节点具备完善的总线数据过滤机制，确保长期稳定运行：
+
+**数据过滤机制**：
+- **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配置：
@@ -276,7 +339,11 @@ node-red-restart
   - TCP网络故障自动恢复
   - 连接前彻底清理旧实例，避免资源泄漏
 - **互斥锁机制**：防止读写冲突导致的数据异常
-- **Keep-Alive心跳**：TCP连接启用30秒心跳检测
+- **TCP永久连接**：
+  - 禁用TCP超时（永久连接），避免无数据时超时断开
+  - Keep-Alive心跳10秒间隔，确保连接活跃
+  - 适应客户长期不在家、总线无数据的场景
+  - 网络故障自动重连，恢复后立即恢复通信
 
 ## 技术规格
 
@@ -369,6 +436,80 @@ devices:
 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. **测试连接**：
@@ -377,10 +518,28 @@ devices:
 
 ### 从站开关无响应
 
-1. 检查RS-485连接是否正常
-2. 确认开关面板地址和按钮编号正确
-3. 检查MQTT连接状态
-4. 查看Node-RED日志中的协议解析信息
+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字符串）
 
 ## 输入消息格式
 
@@ -479,7 +638,7 @@ msg.payload = 1;      // 或 0
 
 ## 项目信息
 
-**版本**: v2.6.5
+**版本**: v2.6.7
 
 **核心功能**：
 - 支持多种Modbus协议（Telnet ASCII、RTU over TCP、Modbus TCP、Modbus RTU串口）
@@ -487,10 +646,11 @@ msg.payload = 1;      // 或 0
 - Symi私有协议自动识别（支持两种485开关控制方式）
 - 智能轮询暂停机制（从站上报时自动暂停，处理完成后恢复）
 - 🔥 **双模式支持**（本地模式和MQTT模式可选切换，断网也能稳定运行）
+- 🔥 **免连线通信**（主站和从站通过内部事件通信，无需连线，支持本地模式和MQTT模式）
 - MQTT集成（可选启用，Home Assistant自动发现，实体唯一性保证，QoS=0高性能发布）
-- 物理开关面板双向同步（亖米协议支持，LED反馈同步）
+- 物理开关面板双向同步（亖米协议支持，LED反馈同步，支持开关模式和场景模式）
 - 共享连接架构（多个从站开关节点共享同一个串口/TCP连接，支持500+节点）
-- 长期稳定运行（内存管理、智能重连、错误日志限流、异步MQTT发布）
+- 长期稳定运行（内存管理、智能重连、错误日志限流、异步MQTT发布、TCP永久连接）
 
 **技术栈**：
 - modbus-serial: ^8.0.23（内部封装serialport，支持TCP和串口）
@@ -499,16 +659,36 @@ msg.payload = 1;      // 或 0
 - Node.js: >=14.0.0
 - Node-RED: >=2.0.0
 
-**最新更新（v2.6.5）**：
-- **🔥 修复MQTT报错问题**：彻底解决未配置MQTT时的错误日志
-  - 从站开关节点新增"启用MQTT"勾选框
+**最新更新（v2.6.7）**：
+- **🔥 修复LED反馈功能**：
+  - 主站轮询检测到状态变化时自动广播事件
+  - 从站开关节点监听状态变化并发送LED反馈到物理面板
+  - 支持开关模式（SET协议）和场景模式（REPORT协议）
+  - LED反馈队列间隔20ms，避免总线拥堵
+- **🔥 TCP连接稳定性优化**：
+  - 禁用TCP超时（永久连接），避免无数据时超时断开
+  - Keep-Alive间隔从30秒优化到10秒
+  - 适应客户长期不在家、总线无数据的场景
+- **日志优化**：
+  - 移除频繁的轮询日志（"轮询持续运行中"、"正在轮询从站X"）
+  - 轮询永久稳定运行，无需频繁确认
+  - 减少日志输出，降低硬盘占用
+
+**v2.6.6更新**：
+- **🔥 彻底解决MQTT日志刷屏问题**：
+  - 局域网IP检测优化：配置192.168.x.x等IP后不再尝试fallback地址
+  - 高频MQTT日志改为debug级别：broker候选、认证、重连等
+  - 默认不输出到日志文件和调试窗口
+  - 配置局域网IP后立即连接，不产生多余日志
+- **日志输出优化**：
+  - 连接成功/失败：仍使用log（重要信息）
+  - 重连尝试、fallback地址、认证信息：改为debug（调试信息）
+  - 仅启用debug模式时才在调试窗口显示
+  - 彻底解决日志刷屏和硬盘占用问题
+
+**v2.6.5更新**：
+- **🔥 修复MQTT报错问题**：从站开关节点新增"启用MQTT"勾选框
   - 默认不启用MQTT，不会尝试连接
-  - 勾选后才显示MQTT服务器配置
-  - 不会在调试窗口产生任何MQTT错误日志
-- **更好的用户体验**：
-  - 节点拖出即可使用（无需配置MQTT）
-  - 不再有烦人的错误提示
-  - 主站和从站开关均支持MQTT可选
   - 本地模式和MQTT模式自由切换
 
 **v2.6.4更新**：
@@ -540,3 +720,289 @@ msg.payload = 1;      // 或 0
 **支持**:
 - Issues: https://github.com/symi-daguo/node-red-contrib-symi-modbus/issues
 - NPM: https://www.npmjs.com/package/node-red-contrib-symi-modbus
+
+### 节点与分类（Palette）
+
+- 侧边栏分类名：`SYMI-MODBUS`
+- 包含节点：`modbus-master`（主站）、`modbus-slave-switch`（从站开关）、`modbus-debug`（调试）
+- 如果未显示该分类或节点：
+  - 刷新浏览器缓存（Shift+刷新）
+  - 重启 Node-RED（如：`node-red-restart` 或系统服务方式）
+  - 在“节点管理（Manage Palette）”确认安装版本为 `v2.6.6`
+
+### 调试节点（modbus-debug）使用要点
+
+- 数据来源选择：`sourceType = serial`（共享串口）或 `modbus`（独立服务器）
+- 共享串口：需要选择并关联一个 `serial-port-config` 配置节点
+- 独立服务器：需要选择并关联一个 `modbus-server-config` 配置节点
+- HEX显示：可选大写、可选时间戳、`maxBytes` 控制显示长度
+- 输出：`msg.payload`（格式化HEX）、`msg.buffer`（原始Buffer）、`msg.meta`（来源信息）
+
+### v2.6.6 重要更新
+
+- 调试节点配置验证修复：根据所选数据来源类型（`serial`/`modbus`）动态校验，避免误报为“配置不正确”
+- 统一侧边栏分类：所有节点统一归类到 `SYMI-MODBUS`
+- 文档更新：补充节点分类、调试节点要点与常见问题处理
+
+典型用法：
+- 联调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）
+6. **确认从站设备在线**：使用Modbus调试工具测试从站是否响应
+7. **检查MQTT连接**：确保MQTT broker地址正确，轮询不依赖MQTT但状态发布需要MQTT
+8. **测试连接**：
+   - TCP连接问题：先用 `modbus-serial` 单独测试TCP连接
+   - 串口问题：先用 `serialport` 单独测试串口通信
+
+### 从站开关无响应
+
+1. 检查RS-485连接是否正常
+2. 确认开关面板地址和按钮编号正确
+3. 检查MQTT连接状态
+4. 查看Node-RED日志中的协议解析信息
+
+## 输入消息格式
+
+### 主站节点
+
+```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
+```
+
+## 输出消息格式
+
+### 主站节点
+
+```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"
+    }
+]
+```
+
+## 项目信息
+
+**版本**: v2.6.7
+
+**核心功能**：
+- 支持多种Modbus协议（Telnet ASCII、RTU over TCP、Modbus TCP、Modbus RTU串口）
+- 多设备轮询（最多10台从站，每台32路继电器，轮询间隔100-10000ms可调）
+- Symi私有协议自动识别（支持两种485开关控制方式）
+- 智能轮询暂停机制（从站上报时自动暂停，处理完成后恢复）
+- 🔥 **双模式支持**（本地模式和MQTT模式可选切换，断网也能稳定运行）
+- 🔥 **免连线通信**（主站和从站通过内部事件通信，无需连线，支持本地模式和MQTT模式）
+- MQTT集成（可选启用，Home Assistant自动发现，实体唯一性保证，QoS=0高性能发布）
+- 物理开关面板双向同步（亖米协议支持，LED反馈同步，支持开关模式和场景模式）
+- 共享连接架构（多个从站开关节点共享同一个串口/TCP连接，支持500+节点）
+- 长期稳定运行（内存管理、智能重连、错误日志限流、异步MQTT发布、TCP永久连接）
+
+**技术栈**：
+- modbus-serial: ^8.0.23（内部封装serialport，支持TCP和串口）
+- serialport: ^12.0.0（原生串口通信）
+- mqtt: ^5.14.1（最新稳定版，可选依赖）
+- Node.js: >=14.0.0
+- Node-RED: >=2.0.0