node-red-contrib-symi-modbus 1.3.0 → 1.5.6

package/README.md

@@ -14,7 +14,10 @@ Node-RED的Modbus继电器控制节点，支持TCP/串口通信和MQTT集成。
 
 ## 安装
 
-### 通过npm安装
+[![npm version](https://badge.fury.io/js/node-red-contrib-symi-modbus.svg)](https://www.npmjs.com/package/node-red-contrib-symi-modbus)
+[![npm downloads](https://img.shields.io/npm/dm/node-red-contrib-symi-modbus.svg)](https://www.npmjs.com/package/node-red-contrib-symi-modbus)
+
+### 通过npm安装（推荐）
 
 在Node-RED用户目录中运行：
 
@@ -29,6 +32,8 @@ npm install node-red-contrib-symi-modbus
 2. 搜索 `node-red-contrib-symi-modbus`
 3. 点击安装
 
+**已发布到npm：** https://www.npmjs.com/package/node-red-contrib-symi-modbus
+
 ### 本地开发安装
 
 ```bash
@@ -293,8 +298,11 @@ msg.payload = {
 - **MQTT服务器**：选择或添加MQTT服务器配置节点（需与主站节点使用相同配置）
 
 **物理开关面板配置**
+- **面板品牌**：选择开关面板品牌
+  - **亖米（Symi）**：默认品牌，完整实现轻量级协议V0.13
+  - **其他品牌**：预留扩展接口，后续支持更多1-8键开关品牌
 - **开关ID**：物理开关面板的设备地址（0-255，RS-485总线地址）
-- **按钮编号**：物理面板上的按键编号（1-8）
+- **按钮编号**：物理面板上的按键编号（1-8键开关）
 
 **映射到继电器设备**
 - **目标从站地址**：要控制的Modbus继电器设备地址（10-247）
@@ -363,28 +371,30 @@ msg.payload = 0;      // 关
 
 #### 配置映射示例
 
-**示例1：开关ID=0，按钮1 → 继电器10-线圈0**
+**示例1：亖米开关ID=0，按钮1 → 继电器10-线圈0**
 ```
 物理面板配置：
+├─ 面板品牌：亖米（Symi）
 ├─ 开关ID：0（物理面板地址）
 ├─ 按钮编号：1（面板按钮1）
 映射到继电器：
-├─ 目标从站地址：10（Modbus继电器设备10）
-└─ 目标线圈编号：0（继电器通道0）
+├─ 从站地址：10（Modbus继电器设备10）
+└─ 线圈编号：0（继电器通道0）
 
 MQTT主题：
 ├─ 订阅状态：modbus/relay/10/0/state
 └─ 发布命令：modbus/relay/10/0/set
 ```
 
-**示例2：开关ID=5，按钮3 → 继电器11-线圈15**
+**示例2：亖米开关ID=5，按钮3 → 继电器11-线圈15**
 ```
 物理面板配置：
+├─ 面板品牌：亖米（Symi）
 ├─ 开关ID：5（物理面板地址）
 ├─ 按钮编号：3（面板按钮3）
 映射到继电器：
-├─ 目标从站地址：11（Modbus继电器设备11）
-└─ 目标线圈编号：15（继电器通道15）
+├─ 从站地址：11（Modbus继电器设备11）
+└─ 线圈编号：15（继电器通道15）
 
 MQTT主题：
 ├─ 订阅状态：modbus/relay/11/15/state
@@ -444,7 +454,20 @@ MQTT主题：
 #### 配置主站节点
 
 1. 拖拽 **Modbus主站** 节点到流程画布
-2. 双击节点，配置连接参数（TCP或串口）
+2. 双击节点，配置连接参数：
+   
+   **TCP连接：**
+   - 连接类型：TCP/IP
+   - TCP主机：192.168.1.100
+   - TCP端口：502
+   
+   **串口连接：**
+   - 连接类型：串口
+   - 点击"搜索串口"按钮查找可用串口
+   - 从下拉列表中选择串口（自动填入）
+   - 或手动输入：COM1 / /dev/ttyUSB0 / /dev/ttyS1
+   - 波特率：9600（或根据设备要求，8-N-1已固定）
+   
 3. 配置从站设备：
    - 默认已有1个从站（地址10）
    - 点击"添加从站"按钮可添加更多（最多10个）
@@ -460,21 +483,28 @@ MQTT主题：
 
    **RS-485总线连接：**
    - **连接类型**：TCP/IP 或 串口
+   
+   TCP模式：
    - **TCP主机**：192.168.1.200（RS-485转TCP网关地址）
    - **TCP端口**：8888
-   - 或**串口**：/dev/ttyUSB0（直连串口）
-   - **波特率**：9600（协议固定）
+   
+   串口模式：
+   - 点击"搜索串口"按钮查找可用串口
+   - 从下拉列表中选择串口（自动填入）
+   - 或手动输入：COM1 / /dev/ttyUSB0 / /dev/ttyS1
+   - **波特率**：9600（亖米协议固定，8-N-1已自动配置）
    
    **MQTT服务器：**
    - 选择与主站相同的MQTT配置
    
    **开关面板：**
+   - **面板品牌**：亖米（Symi）- 默认，支持1-8键开关
    - **开关ID**：0（物理面板地址，0-255）
    - **按钮编号**：1（面板按钮，1-8）
    
    **映射到继电器：**
-   - **目标从站地址**：10（Modbus继电器）
-   - **目标线圈编号**：0（继电器通道，0-31）
+   - **从站地址**：10（Modbus继电器设备地址）
+   - **线圈编号**：0（继电器通道，0-31）
 
 3. 连接输入节点（可选，用于手动控制）
 4. 连接输出节点（如：debug节点）查看状态
@@ -485,6 +515,7 @@ MQTT主题：
 【完整配置】
 RS-485连接：TCP网关192.168.1.200:8888（或串口/dev/ttyUSB0 9600）
 MQTT服务器：本地MQTT服务器（192.168.1.100:1883）
+面板品牌：亖米（Symi）- 支持1-8键开关
 物理面板：开关ID=0，按钮1
 映射到：继电器10，线圈0
 
@@ -535,16 +566,24 @@ MQTT服务器：本地MQTT服务器（192.168.1.100:1883）
 - 轮询间隔：200ms
 ```
 
-### 串口连接示例
+### 串口连接示例（支持自动搜索）
 
 ```
-配置：
+配置方式1：自动搜索（推荐）
+1. 连接类型：串口
+2. 点击"搜索串口"按钮
+3. 等待系统检测串口（1-2秒）
+4. 从下拉列表中选择串口
+   - 支持：COM1, COM2, COM3... (Windows)
+   - 支持：/dev/ttyUSB0, /dev/ttyS1, /dev/ttyS2... (Linux/macOS)
+   - 显示厂商信息，便于识别设备
+5. 波特率：9600（默认，已自动配置8-N-1）
+
+配置方式2：手动输入
 - 连接类型：串口
-- 串口：COM3（Windows）或 /dev/ttyUSB0（Linux）
+- 串口：COM3（Windows）或 /dev/ttyUSB0 或 /dev/ttyS1（Linux/macOS）
 - 波特率：9600
-- 数据位：8
-- 停止位：1
-- 校验位：无
+- 其他参数：8-N-1（已固定，无需配置）
 ```
 
 ### MQTT集成示例
@@ -679,6 +718,34 @@ Home Assistant结果：
 ✅ **HA重启**：不影响，通过retain消息自动重新发现  
 ✅ **Node-RED重启**：不影响，配置自动加载，连接自动建立
 
+## 智能日志系统
+
+### 日志限流机制
+
+为避免日志过多导致内存占用过大，本节点实现了智能日志限流系统：
+
+**工作原理**：
+- **首次错误**：立即显示完整错误信息
+- **重复错误**：10分钟内不再重复显示相同错误
+- **10分钟后**：再次显示错误，确保持续监控
+- **重新部署**：清除日志记录，允许立即显示错误
+
+**日志提示**：
+```
+[warn] 轮询从站10失败（不影响其他从站）: Timed out [此错误将在10分钟后再次显示]
+```
+
+**好处**：
+- ✅ 避免日志文件快速增长
+- ✅ 防止内存占用过大
+- ✅ 保持错误监控能力
+- ✅ 不影响正常功能
+
+**适用场景**：
+- Modbus设备未连接时的超时错误
+- MQTT服务器未配置时的连接错误
+- 其他周期性重复的错误
+
 ## 可靠性保证
 
 ### 消息队列和并发处理
@@ -762,6 +829,19 @@ Home Assistant结果：
 
 ### 轻量级协议（从站节点，V0.13）
 
+#### 品牌支持
+
+- **亖米（Symi）**：默认品牌，完整实现轻量级协议V0.13
+  - 支持1-8键开关面板
+  - RS-485总线通信（TCP网关或串口）
+  - 完整的按键监听和指示灯控制
+  - CRC8校验保证数据完整性
+- **其他品牌**：预留扩展接口
+  - 可通过修改协议适配其他品牌1-8键开关
+  - 后续版本将陆续增加更多品牌支持
+
+#### 亖米协议规格
+
 - **物理层**：RS-485总线
 - **串口参数**：波特率9600，1起始位，8数据位，1停止位，无校验位
 - **帧格式**：`[0x7E][数据][CRC8][0x7D]`
@@ -854,10 +934,18 @@ node-red
 - 确认设备已启动Modbus TCP服务
 
 **串口连接失败**：
+- **使用串口搜索功能**：点击"搜索串口"按钮自动检测可用串口
 - 确认串口名称正确（Windows设备管理器或Linux `ls /dev/tty*`）
-- 检查串口权限（Linux需要：`sudo usermod -a -G dialout $USER`）
+- 检查串口权限（Linux需要：`sudo usermod -a -G dialout $USER`，然后重新登录）
 - 确认波特率等参数与设备匹配
 - 确保串口没有被其他程序占用
+- 重新拔插USB串口适配器
+
+**串口列表为空**：
+- 确认系统已正确安装USB驱动
+- Windows：检查设备管理器中的"端口(COM和LPT)"
+- Linux/macOS：运行 `ls /dev/tty*` 查看串口设备（/dev/ttyUSB0、/dev/ttyS1等）
+- 可以手动输入串口路径，无需依赖自动搜索
 
 ### 轮询错误
 
@@ -867,12 +955,78 @@ node-red
 4. 适当增加轮询间隔（快速轮询可能导致超时）
 5. 查看Node-RED日志获取详细错误信息
 
+**关于日志输出**：
+- 本节点使用智能日志限流机制，相同的错误每10分钟只显示一次
+- 重新部署流程时会清除日志记录，允许再次显示错误
+- 这样可以避免日志过多导致内存占用过大
+- 如果看到"[此错误将在10分钟后再次显示]"提示，说明日志限流正在工作
+
 ### MQTT问题
 
-1. 确认MQTT Broker地址正确且可访问
-2. 检查用户名密码（如果需要）
-3. 查看Node-RED日志确认MQTT连接状态
-4. 测试MQTT连接：`mosquitto_pub -h localhost -t test -m "hello"`
+**症状**：HA实体显示不可用，或MQTT错误日志
+
+**原因分析**：
+1. MQTT broker未运行（如：mosquitto服务未启动）
+2. MQTT broker地址配置错误
+3. MQTT broker需要认证但未配置用户名密码
+4. 网络连接问题
+
+**解决方案**：
+
+1. **检查MQTT broker是否运行**
+   ```bash
+   # macOS/Linux查看mosquitto服务状态
+   ps aux | grep mosquitto
+   
+   # 或使用systemctl（Linux）
+   sudo systemctl status mosquitto
+   
+   # macOS使用brew services
+   brew services list | grep mosquitto
+   ```
+
+2. **启动MQTT broker**
+   ```bash
+   # macOS
+   brew services start mosquitto
+   
+   # Linux (systemd)
+   sudo systemctl start mosquitto
+   
+   # 或直接运行
+   mosquitto -v
+   ```
+
+3. **验证MQTT连接**
+   ```bash
+   # 订阅测试主题（打开一个终端）
+   mosquitto_sub -h localhost -t test
+   
+   # 发布测试消息（打开另一个终端）
+   mosquitto_pub -h localhost -t test -m "hello"
+   
+   # 如果收到消息，说明MQTT broker正常运行
+   ```
+
+4. **检查Node-RED日志**
+   - 查看是否有"正在连接MQTT broker: xxx"日志
+   - 查看MQTT错误提示，根据提示信息定位问题
+   - 如果提示"无法连接到MQTT broker"，检查broker是否运行
+   - 如果提示"MQTT已启用但broker地址未配置"，在MQTT服务器配置节点中填写broker地址
+
+5. **正确配置MQTT服务器节点**
+   - 在Node-RED中打开任意主站或从站节点
+   - 找到"MQTT服务器"字段，点击编辑按钮
+   - 填写正确的broker地址（如：`mqtt://localhost:1883`或`mqtt://192.168.1.100:1883`）
+   - 如果需要认证，填写用户名和密码
+   - 点击"添加"保存配置
+   - 重新部署流程
+
+6. **HA实体不可用的特殊情况**
+   - 如果HA中实体显示不可用（unavailable），首先确保MQTT连接正常
+   - 然后确保主站节点已启动轮询（查看日志："开始轮询 X 个从站设备"）
+   - 如果轮询成功，实体应该在几秒内变为可用状态
+   - v1.5.5+版本已修复初始状态发布问题，确保使用最新版本
 
 ### 测试设备
 
@@ -909,73 +1063,36 @@ python -m pymodbus.server tcp --port 502
 
 ## 更新日志
 
-### v1.3.0 (2025-10-17) - 轻量级协议完整实现
-- ✅ **完整协议实现**：实现轻量级智能家居通信协议（V0.13）
-- ✅ **协议解析**：完整的帧解析、CRC8校验、按键事件检测
-- ✅ **协议构建**：单灯控制、多灯控制、查询指令完整实现
-- ✅ **按键监听**：实时监听RS-485总线上的按键按下事件
-- ✅ **指示灯控制**：通过轻量级协议同步控制物理面板指示灯
-- ✅ **完整三向同步**：
-  - 物理按键 → RS-485协议 → MQTT命令 → 继电器动作
-  - 继电器状态 → MQTT状态 → RS-485协议 → 指示灯同步
-  - 远程控制 → MQTT → 继电器 + 指示灯同步
-- ✅ **协议帧格式**：0x7E帧头 + 数据 + CRC8 + 0x7D帧尾
-- ✅ **多种操作类型**：单灯控制(0x00)、多灯控制(0x05)、查询(0x02)
-- ✅ **CRC8校验**：完整的CRC8算法实现，确保数据完整性
-- ✅ **自动应答**：接收到按键事件后自动发送MQTT命令
-- ✅ **状态同步**：MQTT状态变化自动发送RS-485控制指令
-
-### v1.2.0 (2025-10-17) - 完整RS-485总线支持
-- ✅ **新增RS-485总线连接**：从站节点支持连接物理开关面板的RS-485总线
-- ✅ **TCP/串口双模式**：支持RS-485转TCP网关或直连串口
-- ✅ **监听按键事件**：实时监听物理面板的按钮按下事件
-- ✅ **控制指示灯**：同步控制物理面板的指示灯状态
-- ✅ **三向同步**：物理面板 ↔ 从站 ↔ MQTT ↔ 主站 ↔ Modbus继电器
-- ✅ **双协议桥接**：RS-485协议 + MQTT协议无缝桥接
-- ✅ **状态显示优化**：显示RS-485和MQTT连接状态
-- ✅ **自动重连**：RS-485和MQTT都支持5秒自动重连
-- ✅ **配置持久化**：所有RS-485配置自动保存
-- ✅ **协议扩展接口**：预留轻量级协议实现接口
-
-### v1.1.0 (2025-10-17) - 重大可靠性提升
-- ✅ **新增MQTT服务器配置节点**：统一管理MQTT连接信息
-- ✅ **简化配置流程**：主站和从站共享MQTT配置，避免重复输入
-- ✅ **防止配置错误**：确保所有节点使用相同的MQTT服务器和主题
-- ✅ **配置持久化**：MQTT服务器配置自动保存，重启不丢失
-- ✅ **QoS=1消息保证**：所有命令和状态消息使用QoS=1，确保不丢失
-- ✅ **持久化会话**：clean=false，断线重连后继续接收未读消息
-- ✅ **自动重连机制**：MQTT 5秒自动重连，Modbus 5秒自动重连
-- ✅ **完整双向同步**：控制命令和状态反馈双向实时同步
-- ✅ **支持一对多/多对一**：灵活的按钮到继电器映射关系
-- ✅ **大量设备支持**：测试验证100+节点并发无遗漏
-- ✅ **断电断网恢复**：所有配置和状态自动恢复，零数据丢失
-- ✅ **符合Node-RED规范**：使用标准config节点模式，官方开发规范
-
-### v1.0.1 (2025-10-17)
-- ✅ **重新设计从站开关节点**：支持物理开关面板（RS-485）到Modbus继电器的映射
-- ✅ **开关ID分离**：开关ID（0-255）对应物理面板，不是继电器地址
-- ✅ **完整映射配置**：物理面板（开关ID+按钮）→ 继电器（从站+线圈）
-- ✅ **优化配置界面**：更清晰的配置说明和示例
-- ✅ **本地验证通过**：所有功能测试正常
-
-### v1.0.0 (2025-10-17)
-- ✅ 初始版本发布
-- ✅ Modbus主站节点（TCP/串口支持）
-- ✅ **动态从站管理**：支持动态添加/删除从站设备（最多10台）
-- ✅ **独立配置**：每个从站独立配置地址、线圈范围、轮询间隔
-- ✅ **容错机制**：单个从站失败不影响其他从站继续轮询
-- ✅ **配置持久化**：所有从站配置自动保存
-- ✅ MQTT集成和Home Assistant MQTT Discovery（完全兼容）
-- ✅ 开关从站节点
-- ✅ 完整文档和示例流程
-- ✅ 优化的错误处理和自动重连机制
-- ✅ 连接断开自动检测和恢复
-- ✅ 完善的资源清理和内存管理
-- ✅ 稳定的唯一ID机制（避免重复实体）
-- ✅ 设备可用性状态管理（online/offline）
-- ✅ MQTT retain消息支持（断电重启不丢失配置）
-- ✅ 智能状态显示（正常设备数/总设备数）
-- ✅ 本地测试验证通过（Node-RED v4.0.8）
+### v1.5.6 (2025-10-18) - MQTT错误提示优化 ✅最新版本
+- ✅ **MQTT错误提示改进**：
+  - 当MQTT连接失败且错误消息为空时，提供友好的默认提示
+  - 明确提示broker地址和可能的原因："无法连接到MQTT broker: xxx，请检查broker是否运行"
+  - 添加MQTT连接日志："正在连接MQTT broker: xxx"，便于调试
+  - 帮助用户快速定位MQTT配置问题
+- ✅ **调试信息完善**：
+  - MQTT连接过程增加详细日志输出
+  - 错误提示更加明确和友好
+  - 便于用户排查MQTT连接问题
+
+### v1.5.5 (2025-10-18) - HA自动发现修复和初始状态发布
+- ✅ **修复HA实体不可用问题**：
+  - 添加MQTT broker配置验证，空地址时不尝试连接并给出警告
+  - 第一次轮询成功后立即发布所有线圈的初始状态到MQTT
+  - 确保HA能立即获取到设备的真实状态，实体显示为可用
+  - 解决初始状态为false时不发布导致实体不可用的问题
+- ✅ **初始状态发布机制**：
+  - 新增initialPublished标志，记录每个从站是否已发布初始状态
+  - 第一次轮询成功后，无论状态值是什么，都发布到MQTT
+  - 后续轮询只在状态改变时发布，减少MQTT消息量
+  - 确保HA自动发现后立即显示正确的设备状态
+- ✅ **MQTT配置优化**：
+  - 主站和从站都添加broker地址验证
+  - 配置无效时不尝试连接，避免无意义的错误日志
+  - 提供清晰的警告信息，帮助用户配置
+- ✅ **完整测试验证**：
+  - 从站轮询正常，HA实体自动创建并显示可用
+  - 初始状态正确同步到HA
+  - 配置持久化保存正常
 
 ## 许可证
 
@@ -991,9 +1108,10 @@ MIT License - 详见 [LICENSE](LICENSE) 文件
 ## 支持
 
 如有问题或建议：
-- 📧 提交Issue：[GitHub Issues]
+- 📧 提交Issue：https://github.com/symi-daguo/node-red-contrib-symi-modbus/issues
 - 📦 NPM包：https://www.npmjs.com/package/node-red-contrib-symi-modbus
-- 🌐 Node-RED Flow Library：[待提交]
+- 👤 NPM作者：https://www.npmjs.com/~symi-daguo
+- 🌐 Node-RED Flow Library：即将提交
 
 ## 致谢