node-red-contrib-symi-modbus 1.5.4 → 1.5.7

package/README.md

@@ -34,6 +34,88 @@ npm install node-red-contrib-symi-modbus
 
 **已发布到npm：** https://www.npmjs.com/package/node-red-contrib-symi-modbus
 
+### Docker/容器环境安装
+
+本节点依赖`modbus-serial`包，该包包含native C++模块（serialport），需要编译环境。
+
+#### ⚠️ 如果遇到安装错误
+
+**错误示例：**
+```
+npm error code 127
+npm error command sh -c node-gyp-build
+npm error sh: node-gyp-build: not found
+```
+
+**原因：** Docker容器缺少编译工具（python、make、g++）
+
+**解决方案1：使用官方Node-RED Docker镜像（推荐）**
+
+官方镜像已包含编译工具：
+```bash
+docker pull nodered/node-red:latest
+```
+
+**解决方案2：在Dockerfile中添加编译依赖**
+
+Alpine基础镜像：
+```dockerfile
+FROM nodered/node-red:latest
+# 或者自定义镜像时添加
+RUN apk add --no-cache \
+    python3 \
+    make \
+    g++ \
+    linux-headers
+```
+
+Debian/Ubuntu基础镜像：
+```dockerfile
+FROM nodered/node-red:latest
+# 或者
+RUN apt-get update && apt-get install -y \
+    python3 \
+    make \
+    g++ \
+    build-essential
+```
+
+**解决方案3：在运行中的容器安装**
+
+```bash
+# 进入容器
+docker exec -it <container_id> /bin/sh
+
+# Alpine
+apk add --no-cache python3 make g++ linux-headers
+
+# Debian/Ubuntu
+apt-get update && apt-get install -y python3 make g++ build-essential
+
+# 退出容器后，在Node-RED界面重新安装节点
+```
+
+**解决方案4：使用docker-compose（推荐）**
+
+```yaml
+version: '3.8'
+services:
+  node-red:
+    image: nodered/node-red:latest
+    ports:
+      - "1880:1880"
+    volumes:
+      - node-red-data:/data
+    # 如果需要串口设备，添加设备映射
+    devices:
+      - "/dev/ttyUSB0:/dev/ttyUSB0"
+    # 如果需要串口权限
+    user: "1000:20"  # dialout组ID通常是20
+
+volumes:
+  node-red-data:
+```
+
 ### 本地开发安装
 
 ```bash
@@ -963,10 +1045,70 @@ node-red
 
 ### 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+版本已修复初始状态发布问题，确保使用最新版本
 
 ### 测试设备
 
@@ -1003,144 +1145,52 @@ python -m pymodbus.server tcp --port 502
 
 ## 更新日志
 
-### v1.5.4 (2025-10-18) - MQTT错误日志优化 ✅最新版本
-- ✅ **MQTT错误日志限流**：
-  - MQTT连接错误也采用10分钟限流机制
-  - 避免MQTT未配置时频繁输出错误日志（每几秒一次）
-  - 与Modbus错误日志统一管理，保持日志整洁
-  - 重新部署时清除MQTT错误日志记录，允许再次显示
-- ✅ **日志系统完善**：
-  - 所有错误日志都采用10分钟限流机制
-  - 提示信息统一："[此错误将在10分钟后再次显示]"
-  - 不影响功能正常运行，只是减少重复日志输出
-- ✅ **默认配置确认**：
-  - RS-485串口参数默认9600-8-N-1（符合亖米协议）
-  - 面板品牌默认SYMI，支持1-8键开关
-  - 所有默认参数都已正确配置并持久化
+### v1.5.7 (2025-10-18) - Docker/容器环境支持文档 ✅最新版本
+- ✅ **Docker环境安装指南**：
+  - 添加完整的Docker/容器环境安装说明
+  - 详细解释native模块编译错误的原因和解决方案
+  - 提供4种解决方案：官方镜像、Dockerfile配置、运行时安装、docker-compose
+  - 包含Alpine和Debian/Ubuntu两种基础镜像的配置示例
+- ✅ **错误码127说明**：
+  - 明确说明`npm error code 127`是环境问题，不是代码问题
+  - 提供清晰的错误诊断步骤
+  - 帮助用户快速定位和解决serialport编译问题
+- ✅ **docker-compose示例**：
+  - 提供完整的docker-compose.yml配置
+  - 包含串口设备映射和权限配置
+  - 适合生产环境部署
+
+### 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地址验证
+  - 配置无效时不尝试连接，避免无意义的错误日志
+  - 提供清晰的警告信息，帮助用户配置
 - ✅ **完整测试验证**：
-  - 日志限流机制测试通过
-  - Node-RED持久稳定运行
+  - 从站轮询正常，HA实体自动创建并显示可用
+  - 初始状态正确同步到HA
   - 配置持久化保存正常
 
-### v1.5.3 (2025-10-18) - 界面优化和智能日志系统
-- ✅ **串口选择界面优化**：
-  - 输入框和下拉框一体化，不再单独占用一行
-  - 点击搜索后，下拉框替换输入框显示检测到的串口
-  - 选择串口后自动填充并恢复输入框显示
-  - 完美支持所有类型串口（COM1、/dev/ttyUSB0、/dev/ttyS1等）
-- ✅ **智能日志限流系统**：
-  - Modbus超时错误每10分钟只提示一次，避免日志过多
-  - 重新部署时清除日志记录，允许再次显示错误
-  - 减少日志输出，防止内存占用过大
-  - 保持功能正常，不影响错误监控
-- ✅ **界面布局完善**：
-  - 主站节点：Grid布局，从站地址/线圈范围/轮询间隔完美对齐
-  - 标签在输入框上方，清晰的垂直布局
-  - 移除所有emoji图标，保持专业简洁
-  - 渐变配色和阴影效果，现代化视觉
-- ✅ **错误处理优化**：
-  - RS-485连接添加配置验证，防止无效配置重试
-  - 串口未配置时提供明确提示
-  - 配置错误时不重试，避免无用日志
-- ✅ **完整测试验证**：
-  - Node-RED v4.0.8 / Node.js v23.1.0测试通过
-  - 日志输出优化，10分钟内不重复显示相同错误
-  - 界面布局完美，串口选择流畅
-  
-### v1.5.0 (2025-10-18) - 串口搜索和完整测试
-- ✅ **串口自动搜索**：主站和从站节点支持一键搜索本机可用串口
-  - 点击"搜索串口"按钮自动检测系统串口
-  - 双击列表项自动填入串口名称
-  - 显示串口厂商信息，便于识别
-  - 兼容serialport v9和v10+
-- ✅ **串口连接修复**：优化串口列表API，使用modbus-serial自带的serialport模块
-- ✅ **代码规范检查**：符合Node-RED开发标准
-- ✅ **完整测试验证**：Node-RED启动正常，节点加载成功
-- ✅ **文档完善**：更新所有配置说明和使用指南
-
-### v1.4.0 (2025-10-18) - 界面优化和品牌扩展
-- ✅ **品牌选择功能**：从站开关节点增加品牌选择（默认亖米，预留其他品牌扩展）
-- ✅ **界面布局优化**：
-  - 主站节点：从站地址/线圈标签紧贴输入框，更清晰的布局
-  - 从站节点：所有标签优化对齐，提升配置体验
-- ✅ **全面美化**：
-  - 统一间距和对齐方式
-  - 优化配置区域分组（颜色、边框、圆角）
-  - 改进提示信息样式（蓝色、黄色、绿色主题）
-  - 增强按钮视觉效果（悬停、禁用状态）
-- ✅ **代码规范检查**：确保符合Node-RED开发标准
-- ✅ **本地测试验证**：安装测试通过，节点加载正常
-
-### v1.3.0 (2025-10-17) - 轻量级协议完整实现 ✅已发布到npm
-- ✅ **完整协议实现**：实现轻量级智能家居通信协议（V0.13）
-- ✅ **协议解析**：完整的帧解析、CRC8校验、按键事件检测
-- ✅ **协议构建**：单灯控制、多灯控制、查询指令完整实现
-- ✅ **按键监听**：实时监听RS-485总线上的按键按下事件
-- ✅ **指示灯控制**：通过协议同步控制物理面板指示灯
-- ✅ **完整三向同步**：
-  - 物理按键 → RS-485协议 → MQTT命令 → 继电器动作
-  - 继电器状态 → MQTT状态 → RS-485协议 → 指示灯同步
-  - 远程控制 → MQTT → 继电器 + 指示灯同步
-- ✅ **协议帧格式**：0x7E帧头 + 数据 + CRC8 + 0x7D帧尾
-- ✅ **多种操作类型**：单灯控制(0x00)、多灯控制(0x05)、查询(0x02)
-- ✅ **CRC8校验**：完整的CRC8算法实现，确保数据完整性
-- ✅ **自动应答**：接收到按键事件后自动发送MQTT命令
-- ✅ **状态同步**：MQTT状态变化自动发送RS-485控制指令
-- ✅ **已发布npm**：https://www.npmjs.com/package/node-red-contrib-symi-modbus
-- ✅ **npm安装验证**：从npm安装测试通过
-
-### 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）
-
 ## 许可证
 
 MIT License - 详见 [LICENSE](LICENSE) 文件

package/nodes/modbus-master.js

@@ -106,7 +106,8 @@ module.exports = function(RED) {
                 coils: new Array(32).fill(false),
                 lastUpdate: null,
                 error: null,
-                config: slave  // 保存该从站的配置
+                config: slave,  // 保存该从站的配置
+                initialPublished: false  // 标记是否已发布初始状态
             };
         });
         
@@ -160,6 +161,14 @@ module.exports = function(RED) {
                 return;
             }
             
+            // 验证MQTT broker配置
+            if (!node.config.mqttBroker || node.config.mqttBroker.trim() === '') {
+                node.warn('MQTT已启用但broker地址未配置，跳过MQTT连接');
+                return;
+            }
+            
+            node.log(`正在连接MQTT broker: ${node.config.mqttBroker}`);
+            
             const options = {
                 clientId: `modbus_master_${Math.random().toString(16).substr(2, 8)}`,
                 clean: false,  // 持久化会话，断线重连后继续接收消息
@@ -190,7 +199,8 @@ module.exports = function(RED) {
                     const shouldLog = (now - node.lastMqttErrorLog) > node.errorLogInterval;
                     
                     if (shouldLog) {
-                        node.error(`MQTT错误: ${err.message} [此错误将在10分钟后再次显示]`);
+                        const errorMsg = err.message || `无法连接到MQTT broker: ${node.config.mqttBroker}，请检查broker是否运行`;
+                        node.error(`MQTT错误: ${errorMsg} [此错误将在10分钟后再次显示]`);
                         node.lastMqttErrorLog = now;
                     }
                 });
@@ -390,6 +400,8 @@ module.exports = function(RED) {
                 const data = await node.client.readCoils(slave.coilStart, coilCount);
                 
                 // 更新设备状态
+                const isFirstPoll = !node.deviceStates[slaveId].initialPublished;
+                
                 for (let i = 0; i < coilCount; i++) {
                     const coilIndex = slave.coilStart + i;
                     const oldValue = node.deviceStates[slaveId].coils[coilIndex];
@@ -397,8 +409,8 @@ module.exports = function(RED) {
                     
                     node.deviceStates[slaveId].coils[coilIndex] = newValue;
                     
-                    // 如果状态改变，发布到MQTT和触发事件
-                    if (oldValue !== newValue) {
+                    // 第一次轮询或状态改变时，发布到MQTT和触发事件
+                    if (isFirstPoll || oldValue !== newValue) {
                         node.publishMqttState(slaveId, coilIndex, newValue);
                         node.emit('stateUpdate', {
                             slave: slaveId,
@@ -410,6 +422,7 @@ module.exports = function(RED) {
                 
                 node.deviceStates[slaveId].lastUpdate = Date.now();
                 node.deviceStates[slaveId].error = null;
+                node.deviceStates[slaveId].initialPublished = true;  // 标记已发布初始状态
                 
                 // 输出消息
                 const output = {

package/nodes/modbus-slave-switch.js

@@ -294,6 +294,12 @@ module.exports = function(RED) {
         
         // 连接MQTT
         node.connectMqtt = function() {
+            // 验证MQTT broker配置
+            if (!node.config.mqttBroker || node.config.mqttBroker.trim() === '') {
+                node.warn('MQTT broker地址未配置，跳过MQTT连接');
+                return;
+            }
+            
             const options = {
                 clientId: `modbus_switch_${node.id}`,
                 clean: false,  // 持久化会话，断线重连后继续接收消息
@@ -329,7 +335,8 @@ module.exports = function(RED) {
                     const shouldLog = (now - node.lastMqttErrorLog) > node.errorLogInterval;
                     
                     if (shouldLog) {
-                        node.error(`MQTT错误: ${err.message} [此错误将在10分钟后再次显示]`);
+                        const errorMsg = err.message || `无法连接到MQTT broker: ${node.config.mqttBroker}，请检查broker是否运行`;
+                        node.error(`MQTT错误: ${errorMsg} [此错误将在10分钟后再次显示]`);
                         node.lastMqttErrorLog = now;
                     }
                     node.updateStatus();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-red-contrib-symi-modbus",
-  "version": "1.5.4",
+  "version": "1.5.7",
   "description": "Node-RED Modbus节点，支持TCP/串口通信、串口自动搜索（包括/dev/ttyS1等）、多设备轮询、智能日志限流、MQTT集成、Home Assistant自动发现和多品牌开关面板，现代化美观配置界面",
   "main": "nodes/modbus-master.js",
   "scripts": {