node-red-contrib-symi-modbus 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 symi-daguo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,509 @@
+# node-red-contrib-symi-modbus
+
+Node-RED的Modbus继电器控制节点，支持TCP/串口通信和MQTT集成。
+
+## 功能特性
+
+- ✅ **多协议支持**：支持Modbus TCP和Modbus RTU（串口）
+- ✅ **多设备轮询**：最多支持10台Modbus从站设备同时轮询
+- ✅ **32路继电器**：每台设备支持32个线圈（继电器通道）
+- ✅ **灵活配置**：可自定义轮询间隔、线圈范围、从站地址
+- ✅ **MQTT集成**：自动生成Home Assistant兼容的MQTT发现消息
+- ✅ **实时状态**：实时监控和控制继电器状态
+- ✅ **主从模式**：提供主站节点和从站控制节点
+
+## 安装
+
+### 通过npm安装
+
+在Node-RED用户目录中运行：
+
+```bash
+cd ~/.node-red
+npm install node-red-contrib-symi-modbus
+```
+
+### 通过Node-RED界面安装
+
+1. 点击右上角菜单 → 设置 → 节点管理
+2. 搜索 `node-red-contrib-symi-modbus`
+3. 点击安装
+
+### 本地开发安装
+
+```bash
+# 克隆或下载项目后
+cd node-red-contrib-symi-modbus
+npm install
+
+# 安装到Node-RED（使用你的实际项目路径）
+cd ~/.node-red
+npm install /path/to/node-red-contrib-symi-modbus
+
+# 或者在Mac上
+cd ~/.node-red
+npm install /Volumes/your-disk/path/to/node-red-contrib-symi-modbus
+```
+
+**安装后需要重启Node-RED**
+
+```bash
+# 重启Node-RED
+# 如果用命令行运行，按 Ctrl+C 停止，然后重新运行
+node-red
+
+# 如果用服务管理器，重启服务
+# macOS: brew services restart node-red
+# Linux: sudo systemctl restart node-red
+```
+
+## 节点说明
+
+### 1. Modbus主站节点 (modbus-master)
+
+主站节点负责与Modbus继电器设备通信，执行轮询操作，并可选择发布状态到MQTT服务器。
+
+#### 配置参数
+
+**连接配置**
+- **连接类型**：选择TCP/IP或串口
+- **TCP主机**：Modbus TCP服务器地址（默认：127.0.0.1）
+- **TCP端口**：Modbus TCP端口（默认：502）
+- **串口**：串口名称（如：COM1、/dev/ttyUSB0）
+- **波特率**：串口波特率（9600/19200/38400/57600/115200）
+- **数据位**：数据位数（7或8，默认8）
+- **停止位**：停止位数（1或2，默认1）
+- **校验位**：校验方式（无/奇校验/偶校验，默认无）
+
+**从站设备配置**
+- **动态添加从站**：点击"添加从站"按钮可添加最多10个从站设备
+- **从站地址**：每个从站的Modbus地址（1-247，默认从10=0x0A开始递增）
+- **起始线圈**：该从站的起始线圈编号（0-31）
+- **结束线圈**：该从站的结束线圈编号（0-31）
+- **轮询间隔**：该从站的轮询间隔，单位毫秒（默认：200ms，推荐≥100ms）
+- **配置持久化**：所有从站配置自动保存，重启Node-RED后不丢失
+
+**MQTT配置**
+- **启用MQTT**：是否启用MQTT功能
+- **MQTT服务器**：MQTT Broker地址（如：mqtt://localhost:1883）
+- **MQTT用户名**：可选
+- **MQTT密码**：可选
+- **MQTT基础主题**：消息主题前缀（默认：modbus/relay）
+
+#### 输入消息
+
+```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
+{
+    payload: {
+        slave: 10,                          // 从站地址
+        coils: [true, false, true, ...],    // 线圈状态数组
+        timestamp: 1234567890               // 时间戳
+    }
+}
+```
+
+#### MQTT主题结构
+
+启用MQTT后，自动生成以下主题：
+
+- **状态主题**：`modbus/relay/{从站地址}/{线圈编号}/state`
+  - 内容：`ON` 或 `OFF`
+  - 示例：`modbus/relay/10/0/state` → `ON`
+  
+- **命令主题**：`modbus/relay/{从站地址}/{线圈编号}/set`
+  - 接受：`ON` 或 `OFF`
+  - 示例：`modbus/relay/10/0/set` ← `OFF`
+  
+- **可用性主题**：`modbus/relay/{从站地址}/availability`
+  - 内容：`online` 或 `offline`
+  - 用于显示设备在线/离线状态
+  
+- **发现主题**（Home Assistant）：`homeassistant/switch/modbus_relay_{从站}_{线圈}/config`
+  - 符合Home Assistant MQTT Discovery标准
+  - 包含完整的设备信息和配置
+
+### 2. Modbus开关从站节点 (modbus-slave-switch)
+
+从站开关节点用于控制单个继电器线圈。
+
+#### 配置参数
+
+- **名称**：节点显示名称
+- **主站节点**：关联的主站节点
+- **从站地址**：目标从站设备地址
+- **线圈编号**：要控制的线圈编号（0-31）
+
+#### 输入消息
+
+```javascript
+// 布尔值
+msg.payload = true;   // 开
+msg.payload = false;  // 关
+
+// 字符串
+msg.payload = "ON";   // 开
+msg.payload = "OFF";  // 关
+
+// 数字
+msg.payload = 1;      // 开
+msg.payload = 0;      // 关
+```
+
+#### 输出消息
+
+```javascript
+{
+    payload: true,  // 当前状态
+    topic: "modbus/10/0"  // 主题
+}
+```
+
+## 快速开始
+
+### 基础使用
+
+1. 拖拽 **Modbus主站** 节点到流程画布
+2. 双击配置连接参数（TCP或串口）
+3. 设置从站地址和线圈范围
+4. 部署流程
+
+### 导入示例流程
+
+项目包含示例流程文件 `examples/basic-flow.json`：
+
+1. 点击右上角菜单 → 导入
+2. 选择 `examples/basic-flow.json` 文件
+3. 导入后即可测试所有功能
+
+示例流程包含：
+- 启动/停止轮询
+- 写单个线圈
+- 开关节点控制
+- 调试输出
+
+### TCP连接示例
+
+```
+配置：
+- 连接类型：TCP/IP
+- TCP主机：192.168.1.100
+- TCP端口：502
+
+从站1：
+- 地址：10 (0x0A)
+- 线圈范围：0-31
+- 轮询间隔：200ms
+
+从站2：（点击"添加从站"按钮）
+- 地址：11 (0x0B)（自动递增）
+- 线圈范围：0-31
+- 轮询间隔：200ms
+```
+
+### 串口连接示例
+
+```
+配置：
+- 连接类型：串口
+- 串口：COM3（Windows）或 /dev/ttyUSB0（Linux）
+- 波特率：9600
+- 数据位：8
+- 停止位：1
+- 校验位：无
+```
+
+### MQTT集成示例
+
+启用MQTT后，可与Home Assistant或其他MQTT平台集成：
+
+1. 在主站节点中启用MQTT
+2. 配置MQTT服务器地址
+3. 部署流程
+4. Home Assistant会自动发现设备
+
+## Home Assistant集成
+
+本节点完全兼容Home Assistant的MQTT Discovery标准，支持自动发现和持久化：
+
+### 集成步骤
+
+1. **配置MQTT集成**
+   - 确保Home Assistant已配置MQTT集成
+   - 记下MQTT Broker地址（如：mqtt://192.168.1.100:1883）
+
+2. **配置Node-RED节点**
+   - 在主站节点中启用MQTT
+   - 配置MQTT Broker地址、用户名、密码
+   - 添加从站设备（点击"添加从站"按钮，可添加多个设备）
+   - 默认第一个从站地址为10，后续自动递增为11、12...
+
+3. **部署流程**
+   - 点击Node-RED的Deploy按钮
+   - 节点会自动发布MQTT Discovery消息
+   - 设备自动出现在Home Assistant中
+
+4. **验证集成**
+   - 在HA中查看：设置 → 设备与服务 → MQTT → 设备
+   - 每个从站显示为一个设备（如：`Modbus继电器-10`）
+   - 每个继电器显示为一个开关实体
+
+### 实体和设备规则
+
+**唯一ID规则（确保不重复）：**
+- 设备唯一标识符：`modbus_relay_{从站地址}`
+- 实体唯一ID：`modbus_relay_{从站地址}_{线圈编号}`
+- 实体ID：`switch.relay_{从站地址}_{线圈编号}`
+
+**示例：**
+```
+从站地址=10，线圈0-31：
+├─ 设备：Modbus继电器-10 (标识符: modbus_relay_10)
+│  ├─ 实体：switch.relay_10_0  (继电器 10-0)
+│  ├─ 实体：switch.relay_10_1  (继电器 10-1)
+│  └─ ... (共32个实体)
+│
+从站地址=11，线圈0-31：
+├─ 设备：Modbus继电器-11 (标识符: modbus_relay_11)
+   ├─ 实体：switch.relay_11_0  (继电器 11-0)
+   └─ ...
+```
+
+### 持久化和稳定性保证
+
+✅ **唯一ID稳定性**
+- 使用从站地址作为设备标识符
+- 使用从站地址+线圈编号作为实体唯一ID
+- 断电、重启、重新部署不会创建重复实体
+
+✅ **MQTT retain消息**
+- 所有发现消息使用`retain=true`
+- HA重启后自动重新发现设备
+
+✅ **设备可用性状态**
+- 每个从站有独立的availability主题
+- 节点关闭时自动发送`offline`状态
+- 节点启动时自动发送`online`状态
+
+✅ **避免重复实体的机制**
+1. 稳定的unique_id（基于从站地址）
+2. MQTT retain消息保持配置
+3. 设备标识符保持不变
+4. HA会自动识别并更新现有实体，不会创建新的
+
+### 多从站配置示例
+
+**场景1：3台32路继电器**
+```
+从站配置（点击3次"添加从站"）：
+- 从站1：地址10，线圈0-31，间隔200ms
+- 从站2：地址11，线圈0-31，间隔200ms
+- 从站3：地址12，线圈0-31，间隔200ms
+
+Home Assistant结果：
+- 设备10：32个实体（switch.relay_10_0 到 switch.relay_10_31）
+- 设备11：32个实体（switch.relay_11_0 到 switch.relay_11_31）
+- 设备12：32个实体（switch.relay_12_0 到 switch.relay_12_31）
+总计：3个设备，96个实体
+```
+
+**场景2：10台32路继电器（最大容量）**
+```
+从站配置（点击10次"添加从站"）：
+- 从站1-10：地址10-19，每个线圈0-31，间隔200ms
+
+Home Assistant结果：
+10个设备（地址10-19），总计320个实体
+```
+
+**场景3：不同线圈范围配置**
+```
+从站配置：
+- 从站1：地址10，线圈0-7（仅8路继电器），间隔150ms
+- 从站2：地址15，线圈0-15（16路继电器），间隔200ms
+- 从站3：地址20，线圈0-31（全部32路），间隔250ms
+
+Home Assistant结果：
+- 设备10：8个实体
+- 设备15：16个实体
+- 设备20：32个实体
+总计：3个设备，56个实体
+```
+
+### 故障恢复测试
+
+✅ **断网/通网**：不影响，MQTT自动重连，retain消息保持配置
+✅ **断电/通电**：不影响，节点重启后自动发送online状态
+✅ **HA重启**：不影响，通过retain消息自动重新发现
+✅ **Node-RED重启**：不影响，unique_id保持不变
+
+## 技术规格
+
+- **Modbus协议**：Modbus TCP / Modbus RTU
+- **功能码支持**：
+  - 0x01：读线圈状态（Read Coils）
+  - 0x05：写单个线圈（Write Single Coil）
+  - 0x0F：写多个线圈（Write Multiple Coils）
+- **从站地址范围**：1-247
+- **线圈数量**：每台设备32个（0-31）
+- **最大设备数**：10台同时轮询
+- **轮询间隔**：最小10ms，默认200ms，推荐≥100ms
+- **连接超时**：5秒
+- **自动重连**：连接失败后每5秒重试
+- **错误恢复**：自动检测连接断开并重连
+- **兼容性**：
+  - Node.js: >= 14.0.0
+  - Node-RED: >= 2.0.0
+  - 已在 Node-RED v4.0.8 / Node.js v23.1.0 上测试通过
+
+## 故障排除
+
+### 节点没有出现在面板中
+
+**症状**：安装后在Node-RED左侧面板找不到节点
+
+**解决方案**：
+1. 确认已重启Node-RED（**必须重启！**）
+2. 检查安装路径：`~/.node-red/node_modules/node-red-contrib-symi-modbus`
+3. 查看Node-RED启动日志是否有错误
+4. 清除浏览器缓存并刷新页面
+
+```bash
+# 重启Node-RED
+# 按 Ctrl+C 停止，然后重新运行
+node-red
+```
+
+### 连接失败
+
+**TCP连接失败**：
+- 检查网络连通性：`ping <IP地址>`
+- 确认Modbus TCP服务器地址和端口
+- 检查防火墙设置
+- 确认设备已启动Modbus TCP服务
+
+**串口连接失败**：
+- 确认串口名称正确（Windows设备管理器或Linux `ls /dev/tty*`）
+- 检查串口权限（Linux需要：`sudo usermod -a -G dialout $USER`）
+- 确认波特率等参数与设备匹配
+- 确保串口没有被其他程序占用
+
+### 轮询错误
+
+1. 检查从站地址是否正确（默认10，即0x0A）
+2. 确认设备在线且响应正常
+3. 验证线圈范围是否超出设备限制
+4. 适当增加轮询间隔（快速轮询可能导致超时）
+5. 查看Node-RED日志获取详细错误信息
+
+### MQTT问题
+
+1. 确认MQTT Broker地址正确且可访问
+2. 检查用户名密码（如果需要）
+3. 查看Node-RED日志确认MQTT连接状态
+4. 测试MQTT连接：`mosquitto_pub -h localhost -t test -m "hello"`
+
+### 测试设备
+
+如果没有真实Modbus设备，可以使用模拟器测试：
+
+**Windows**：
+- ModRSsim2（免费Modbus模拟器）
+- 下载：https://sourceforge.net/projects/modrssim2/
+
+**跨平台**：
+```bash
+# 安装pymodbus
+pip install pymodbus
+
+# 运行TCP模拟器
+python -m pymodbus.server tcp --port 502
+```
+
+## 开发计划
+
+### 即将推出的功能
+
+- [ ] **调光从站节点**：支持0-100%调光控制
+- [ ] **窗帘从站节点**：开关、停止、位置控制
+- [ ] **温控从站节点**：温度设置和模式控制
+- [ ] **更多Modbus功能码**：读保持寄存器、输入寄存器等
+- [ ] **数据持久化**：保存设备状态
+- [ ] **设备分组管理**：批量操作多个设备
+- [ ] **Web配置界面**：可视化配置工具
+
+### 贡献
+
+欢迎贡献代码、报告问题、提出建议！
+
+## 更新日志
+
+### 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) 文件
+
+## 作者
+
+**symi-daguo**
+
+- NPM: https://www.npmjs.com/~symi-daguo
+- GitHub: https://github.com/symi-daguo
+
+## 支持
+
+如有问题或建议：
+- 📧 提交Issue：[GitHub Issues]
+- 📦 NPM包：https://www.npmjs.com/package/node-red-contrib-symi-modbus
+- 🌐 Node-RED Flow Library：[待提交]
+
+## 致谢
+
+感谢以下开源项目：
+- [Node-RED](https://nodered.org/) - 流程编程平台
+- [modbus-serial](https://github.com/yaacov/node-modbus-serial) - Modbus通信库
+- [MQTT.js](https://github.com/mqttjs/MQTT.js) - MQTT客户端库
+- Node-RED社区的支持和贡献