node-red-contrib-symi-modbus 2.6.6 → 2.6.8

package/README.md

@@ -1,30 +1,27 @@
 # 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私有协议按键事件，实现开关面板与继电器的双向同步
+- **HomeKit网桥**：一键桥接到Apple HomeKit，支持Siri语音控制，自动同步主站配置，名称可自定义
+- **多设备轮询**：支持最多10台Modbus从站设备，每台32路继电器
+- **智能轮询机制**：从站上报时自动暂停轮询，优先处理数据，避免冲突
+- **稳定可靠**：完整的内存管理、错误处理、断线重连，适合7x24小时长期运行
+- **总线数据过滤**：自动忽略总线上的无关数据，只处理本节点相关的数据
 
 ## 快速开始
 
@@ -56,13 +53,14 @@ node-red-restart
 **配置方法**：
 1. 主站节点：不启用MQTT或不配置MQTT服务器
 2. 从站开关节点：不配置MQTT服务器
-3. 将从站开关节点的输出连线到主站节点的输入
+3. **无需连线**：主站和从站通过内部事件自动通信（v2.6.7+）
 
 **优势**：
 - ✅ 断网也能稳定运行
 - ✅ 不依赖外部服务
 - ✅ 响应速度更快
 - ✅ 配置更简单
+- ✅ 无需手动连线（免连线通信）
 
 #### 模式2：MQTT模式（推荐用于Home Assistant集成）
 
@@ -142,10 +140,49 @@ node-red-restart
    - 面板品牌: `亖米` (默认)
    - 开关ID: 物理面板地址 (0-255)
    - 按钮编号: 按键编号 (1-8)
+   - 按钮类型: 开关按钮或场景按钮（也可自动识别）
 4. 配置映射到的继电器：
    - 目标从站地址: `10`
    - 目标线圈编号: `0`
-5. 部署流程
+5. **无需连线**：主站和从站通过内部事件自动通信，无需手动连线
+6. 部署流程
+
+### 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自动化和场景
+- 配置会自动保存，重启后无需重新配对
 
 ## 核心特性说明
 
@@ -187,6 +224,7 @@ node-red-restart
 **2. 场景按钮**
 - **控制方式**：每次按下toggle切换状态（开→关→开）
 - **LED反馈**：根据当前状态显示LED（开=亮，关=灭）
+- **协议特征**：操作信息为0x11、0x12、0x13等（高4位=1表示场景模式）
 - **适用场景**：
   - 场景触发（回家模式、离家模式等）
   - 一键全开/全关
@@ -196,25 +234,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 +266,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 +297,28 @@ node-red-restart
 - 从站上报的数据得到优先处理
 - 系统响应迅速，状态同步及时
 
+### 总线数据过滤与稳定性
+
+本节点具备完善的总线数据过滤机制，确保长期稳定运行：
+
+**数据过滤机制**：
+- **CRC校验**：所有Symi协议帧都经过CRC8校验，无效数据自动丢弃
+- **静默忽略**：总线上的非相关数据（其他设备、其他协议）静默忽略，不影响正常通信
+- **精确匹配**：只处理本节点配置的从站地址和线圈范围内的数据
+- **TCP粘包处理**：TCP模式下自动处理粘包和分包问题，确保数据完整性
+
+**稳定性保障**：
+- **写入队列**：多个节点同时写入时自动排队，避免并发冲突
+- **断线重连**：TCP和串口断线后自动重连，指数退避策略（最大60秒）
+- **内存管理**：定时清理缓存，防止内存泄漏
+- **错误日志限流**：避免日志刷屏影响性能
+- **MQTT独立性**：MQTT开启或关闭都不影响主站和从站的本地通信
+
+**网络适应性**：
+- **离线通信**：串口模式完全脱离网络依赖，断网也能正常工作
+- **TCP稳定性**：TCP模式支持局域网通信，网络恢复后自动重连
+- **MQTT可选**：MQTT仅用于对接第三方平台，不影响本地控制
+
 ## 调试节点（modbus-debug）
 
 用于抓取并显示原始RS485字节流数据（HEX），帮助定位串口或TCP网关下的Modbus通信问题。
@@ -304,7 +377,11 @@ node-red-restart
   - TCP网络故障自动恢复
   - 连接前彻底清理旧实例，避免资源泄漏
 - **互斥锁机制**：防止读写冲突导致的数据异常
-- **Keep-Alive心跳**：TCP连接启用30秒心跳检测
+- **TCP永久连接**：
+  - 禁用TCP超时（永久连接），避免无数据时超时断开
+  - Keep-Alive心跳10秒间隔，确保连接活跃
+  - 适应客户长期不在家、总线无数据的场景
+  - 网络故障自动重连，恢复后立即恢复通信
 
 ## 技术规格
 
@@ -397,6 +474,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. **测试连接**：
@@ -405,10 +556,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字符串）
 
 ## 输入消息格式
 
@@ -447,6 +616,40 @@ 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后自动恢复配对状态，无需重新配对
+
 ## 输出消息格式
 
 ### 主站节点
@@ -507,27 +710,48 @@ msg.payload = 1;      // 或 0
 
 ## 项目信息
 
-**版本**: v2.6.6
+**版本**: v2.6.8
 
 **核心功能**：
 - 支持多种Modbus协议（Telnet ASCII、RTU over TCP、Modbus TCP、Modbus RTU串口）
 - 多设备轮询（最多10台从站，每台32路继电器，轮询间隔100-10000ms可调）
-- Symi私有协议自动识别（支持两种485开关控制方式）
-- 智能轮询暂停机制（从站上报时自动暂停，处理完成后恢复）
 - 🔥 **双模式支持**（本地模式和MQTT模式可选切换，断网也能稳定运行）
-- MQTT集成（可选启用，Home Assistant自动发现，实体唯一性保证，QoS=0高性能发布）
-- 物理开关面板双向同步（亖米协议支持，LED反馈同步）
-- 共享连接架构（多个从站开关节点共享同一个串口/TCP连接，支持500+节点）
-- 长期稳定运行（内存管理、智能重连、错误日志限流、异步MQTT发布）
+- 🔥 **免连线通信**（主站和从站通过内部事件通信，无需连线）
+- 🔥 **HomeKit网桥**（一键桥接到Apple HomeKit，支持Siri语音控制）
+- MQTT集成（可选启用，Home Assistant自动发现）
+- 物理开关面板双向同步（支持开关模式和场景模式）
+- 长期稳定运行（内存管理、智能重连、异步处理）
 
-**技术栈**：
-- 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
 
-**最新更新（v2.6.6）**：
+**最新更新（v2.6.8）**：
+- **🔥 新增HomeKit网桥节点**：
+  - 一键桥接Modbus继电器到Apple HomeKit
+  - 自动同步主站配置的所有从站和继电器
+  - 支持在Node-RED中配置继电器友好名称
+  - 双向同步：HomeKit控制继电器，继电器状态实时同步到HomeKit
+  - 支持Siri语音控制和HomeKit自动化场景
+  - 持久化存储配对信息，重启后自动恢复
+  - 线圈0-15显示为开关，线圈16-31显示为插座（避免误触发）
+
+**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候选、认证、重连等
@@ -632,7 +856,11 @@ msg.payload = 1;      // 或 0
   - TCP网络故障自动恢复
   - 连接前彻底清理旧实例，避免资源泄漏
 - **互斥锁机制**：防止读写冲突导致的数据异常
-- **Keep-Alive心跳**：TCP连接启用30秒心跳检测
+- **TCP永久连接**：
+  - 禁用TCP超时（永久连接），避免无数据时超时断开
+  - Keep-Alive心跳10秒间隔，确保连接活跃
+  - 适应客户长期不在家、总线无数据的场景
+  - 网络故障自动重连，恢复后立即恢复通信
 
 ## 技术规格
 
@@ -835,7 +1063,7 @@ msg.payload = 1;      // 或 0
 
 ## 项目信息
 
-**版本**: v2.6.6
+**版本**: v2.6.8
 
 **核心功能**：
 - 支持多种Modbus协议（Telnet ASCII、RTU over TCP、Modbus TCP、Modbus RTU串口）
@@ -843,14 +1071,18 @@ msg.payload = 1;      // 或 0
 - Symi私有协议自动识别（支持两种485开关控制方式）
 - 智能轮询暂停机制（从站上报时自动暂停，处理完成后恢复）
 - 🔥 **双模式支持**（本地模式和MQTT模式可选切换，断网也能稳定运行）
+- 🔥 **免连线通信**（主站和从站通过内部事件通信，无需连线，支持本地模式和MQTT模式）
+- 🔥 **HomeKit网桥**（一键桥接到Apple HomeKit，支持Siri语音控制，名称可自定义）
 - MQTT集成（可选启用，Home Assistant自动发现，实体唯一性保证，QoS=0高性能发布）
-- 物理开关面板双向同步（亖米协议支持，LED反馈同步）
+- 物理开关面板双向同步（亖米协议支持，LED反馈同步，支持开关模式和场景模式）
 - 共享连接架构（多个从站开关节点共享同一个串口/TCP连接，支持500+节点）
-- 长期稳定运行（内存管理、智能重连、错误日志限流、异步MQTT发布）
+- 长期稳定运行（内存管理、智能重连、错误日志限流、异步MQTT发布、TCP永久连接）
 
 **技术栈**：
 - modbus-serial: ^8.0.23（内部封装serialport，支持TCP和串口）
 - serialport: ^12.0.0（原生串口通信）
 - mqtt: ^5.14.1（最新稳定版，可选依赖）
+- hap-nodejs: ^1.2.0（HomeKit桥接）
+- node-persist: ^4.0.4（持久化存储）
 - Node.js: >=14.0.0
 - Node-RED: >=2.0.0