node-red-contrib-symi-modbus 2.5.2 → 2.5.4

package/README.md

@@ -2,546 +2,496 @@
 
 Node-RED的Modbus继电器控制节点，支持TCP/串口通信和MQTT集成。
 
-## 功能特性
-
-- 多协议支持：支持Modbus TCP和Modbus RTU（串口）
-- 多设备轮询：最多支持10台Modbus从站设备同时轮询
-- 32路继电器：每台设备支持32个线圈（继电器通道）
-- 灵活配置：可自定义轮询间隔、线圈范围、从站地址
-- MQTT集成：作为MQTT客户端连接Broker，自动生成Home Assistant兼容的MQTT发现消息
-- 实时状态：实时监控和控制继电器状态
-- 主从模式：提供主站节点和从站控制节点
-- 稳定可靠：完整的Promise错误处理，适合工控机长期稳定运行
-
-## MQTT架构说明
-
-本节点作为**MQTT客户端**，需要连接到外部**MQTT Broker服务端**（如Mosquitto）：
-
-**主站节点（modbus-master）**
-- 作为MQTT客户端连接到MQTT Broker
-- 发布状态主题：`modbus/relay/{从站}/{线圈}/state`
-- 发布可用性主题：`modbus/relay/{从站}/availability`
-- 发布Discovery主题：`homeassistant/switch/modbus_relay_{从站}_{线圈}/config`
-- 订阅命令主题：`modbus/relay/{从站}/{线圈}/set`
-
-**从站开关节点（modbus-slave-switch）**
-- 作为MQTT客户端连接到MQTT Broker
-- 订阅状态主题（从主站接收继电器状态）
-- 发布命令主题（将物理按键转换为MQTT命令发送给主站）
-- 实现物理开关面板与继电器的双向同步
-
-**Home Assistant**
-- 作为MQTT客户端连接到同一个MQTT Broker
-- 通过MQTT Discovery自动发现设备和实体
-- 订阅状态主题获取继电器状态
-- 发布命令主题控制继电器
-
-**MQTT Broker（需单独部署）**
-- 服务端（如Mosquitto、EMQX等）
-- 所有客户端连接到同一个Broker
-- 负责消息路由和持久化
-
-### MQTT连接配置说明
-
-本节点支持**智能地址fallback机制**，自动适配不同部署环境：
-
-**HassOS环境（推荐）**
-```yaml
-配置: mqtt://127.0.0.1:1883
-
-说明：无需任何额外设置，直接填写即可
-- 系统会自动尝试 core-mosquitto、supervisor 等地址
-- 适用于HassOS内置的Mosquitto broker插件
-```
-
-**局域网环境（工控机/独立服务器）**
-```yaml
-配置: mqtt://192.168.1.100:1883
-
-说明：直接填写具体IP地址
-- 填写MQTT broker所在设备的局域网IP
-- 系统会直接连接，不启用fallback
-- 适合Linux工控机和独立部署的MQTT服务器
-```
-
-**本机环境**
-```yaml
-配置: mqtt://localhost:1883 或 mqtt://127.0.0.1:1883
-
-说明：本机直接运行Node-RED时使用
-- 适合开发测试环境
-- 系统会自动尝试Docker环境的fallback地址
-```
+[![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)
 
-**智能fallback机制**
-
-- **局域网IP**（192.168.x.x, 10.x.x.x）：直接连接，不启用fallback
-- **localhost/127.0.0.1**：自动尝试 core-mosquitto、supervisor、host.docker.internal 等地址
-- **容器名**：自动尝试 localhost、127.0.0.1 等备用地址
+## 功能特性
 
-## 安装
+- **多协议支持**：
+  - 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集成**：自动生成Home Assistant兼容的MQTT发现消息
+- **实时状态**：实时监控和控制继电器状态
+- **主从模式**：提供主站节点和从站控制节点
+- **稳定可靠**：完整的内存管理和错误处理，适合工控机长期稳定运行
 
-### 通过npm安装（推荐）
+## 快速开始
 
-在Node-RED用户目录中运行：
+### 1. 安装
 
+**通过npm安装（推荐）**
 ```bash
 cd ~/.node-red
 npm install node-red-contrib-symi-modbus
+node-red-restart
 ```
 
-### 通过Node-RED界面安装
-
+**通过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
-```
-
-**安装后需要重启Node-RED**
-
-## 节点说明
-
-### 1. MQTT服务器配置节点 (mqtt-server-config)
-
-全局配置节点，用于管理MQTT服务器连接信息，所有主站和从站节点共享此配置。
-
-#### 配置参数
-
-- **名称**：配置节点的显示名称（可选）
-- **MQTT服务器**：MQTT Broker地址（如：mqtt://192.168.1.100:1883）
-- **用户名**：MQTT认证用户名（可选）
-- **密码**：MQTT认证密码（可选）
-- **基础主题**：MQTT主题前缀（默认：modbus/relay）
-
-### 2. 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）
-
-**从站设备配置**
-- **动态添加从站**：点击"添加从站"按钮可添加最多10个从站设备
-- **从站地址**：每个从站的Modbus地址（1-247，默认从10开始递增）
-- **起始线圈**：该从站的起始线圈编号（0-31）
-- **结束线圈**：该从站的结束线圈编号（0-31）
-- **轮询间隔**：该从站的轮询间隔，单位毫秒（默认：200ms，推荐>=100ms）
-
-**MQTT配置**
-- **启用MQTT**：是否启用MQTT功能
-- **MQTT服务器**：选择或添加MQTT服务器配置节点
+### 2. 配置MQTT服务器
 
-#### 输入消息
-
-```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]  // 线圈值数组
-};
-```
-
-#### MQTT主题结构
-
-启用MQTT后，自动生成以下主题：
-
-- **状态主题**：`modbus/relay/{从站地址}/{线圈编号}/state`
-- **命令主题**：`modbus/relay/{从站地址}/{线圈编号}/set`
-- **可用性主题**：`modbus/relay/{从站地址}/availability`
-- **发现主题**（Home Assistant）：`homeassistant/switch/modbus_relay_{从站}_{线圈}/config`
-
-### 3. Modbus开关从站节点 (modbus-slave-switch)
-
-从站开关节点连接物理开关面板（RS-485总线），监听按键事件，并通过MQTT映射控制Modbus继电器设备。
-
-#### 配置参数
-
-**RS-485总线连接配置**
-- **连接类型**：选择TCP/IP或串口
-- **TCP主机**：RS-485转TCP网关地址
-- **TCP端口**：网关端口（默认：8888）
-- **串口**：串口名称（如：COM1、/dev/ttyUSB0）
-- **波特率**：9600（协议标准）
-
-**物理开关面板配置**
-- **面板品牌**：选择开关面板品牌（默认：亖米）
-- **开关ID**：物理开关面板的设备地址（0-255）
-- **按钮编号**：物理面板上的按键编号（1-8）
-
-**映射到继电器设备**
-- **目标从站地址**：要控制的Modbus继电器设备地址（10-247）
-- **目标线圈编号**：继电器的具体通道（0-31）
-
-## 快速开始
-
-### 配置MQTT服务器（首次使用）
-
-1. 拖拽任意节点（主站或从站）到流程画布
+1. 拖拽任意节点到流程画布
 2. 双击节点，找到"MQTT服务器"字段
-3. 点击旁边的编辑按钮
-4. 填写MQTT服务器信息并保存
+3. 点击编辑按钮，填写MQTT服务器信息：
+   - MQTT Broker: `mqtt://localhost:1883` (或你的MQTT服务器地址)
+   - 用户名/密码: 按需填写
+   - 基础主题: `modbus/relay` (默认)
 
-### 配置主站节点
+### 3. 配置主站节点
 
 1. 拖拽 **Modbus主站** 节点到流程画布
-2. 双击节点配置连接参数
-3. 配置从站设备
-4. 启用MQTT（如果需要与HA集成）
+2. 配置连接参数：
+   - **串口模式**（直连RS485设备）：
+     - 连接类型: `串口`
+     - 串口路径: `/dev/ttyUSB0` (Linux/Mac) 或 `COM1` (Windows)
+     - 波特率: `9600`（默认）
+     - 数据位: `8`
+     - 停止位: `1`
+     - 校验位: `无`
+   - **TCP模式**（通过TCP转RS485网关）：
+     - 连接类型: `TCP/IP`
+     - TCP模式: `Telnet ASCII`（推荐，适用于大多数TCP转RS485网关）
+     - TCP主机: `192.168.2.110`
+     - TCP端口: `1031`
+     - 其他模式：
+       - `RTU over TCP`：适用于支持Modbus RTU over TCP的网关
+       - `Modbus TCP`：适用于标准Modbus TCP设备
+3. 配置从站设备：
+   - 从站地址: `10` (默认，可添加多个，如10、11、12、13)
+   - 线圈范围: `0-31`
+   - 轮询间隔: `200ms` (默认，支持100-10000ms)
+4. 启用MQTT并选择MQTT服务器配置
 5. 部署流程
 
-### 配置从站开关节点
-
-1. 拖拽 **从站开关** 节点到流程画布
-2. 配置RS-485总线连接
-3. 配置开关面板信息
-4. 配置映射到的继电器
-5. 部署流程
+### 4. 配置RS-485连接配置节点（用于从站开关）
 
-## Home Assistant集成
+如果需要物理开关面板控制，首先创建RS-485连接配置：
 
-本节点完全兼容Home Assistant的MQTT Discovery标准，支持自动发现和持久化。
+1. 点击右上角菜单 → 配置节点
+2. 添加新的 **serial-port-config** 配置节点
+3. 选择连接类型：
+   - **串口模式**（本地RS-485总线）：
+     - 连接类型: `串口`
+     - 串口路径: `/dev/ttyUSB0` (可点击"搜索"按钮自动发现)
+     - 波特率: `9600`
+     - 数据位: `8`
+     - 停止位: `1`
+     - 校验位: `无 (N)`
+   - **TCP模式**（通过TCP转RS485网关）：
+     - 连接类型: `TCP网关`
+     - TCP主机: `192.168.2.110`
+     - TCP端口: `1031`
+4. 保存配置
 
-### 集成步骤
+### 5. 配置从站开关节点（可选）
 
-1. 确保Home Assistant已配置MQTT集成
-2. 配置MQTT服务器节点
-3. 在主站节点中启用MQTT
-4. 部署流程
-5. 设备自动出现在Home Assistant中
+使用物理开关面板控制继电器：
 
-### 实体和设备规则
+1. 拖拽 **从站开关** 节点到流程画布
+2. 选择刚创建的RS-485连接配置
+3. 配置开关面板信息：
+   - 面板品牌: `三米` (默认)
+   - 开关ID: 物理面板地址 (0-255)
+   - 按钮编号: 按键编号 (1-8)
+4. 配置映射到的继电器：
+   - 目标从站地址: `10`
+   - 目标线圈编号: `0`
+5. 部署流程
 
-- 设备唯一标识符：`modbus_relay_{从站地址}`
-- 实体唯一ID：`modbus_relay_{从站地址}_{线圈编号}`
-- 实体ID：`switch.relay_{从站地址}_{线圈编号}`
+## 核心特性说明
+
+### Symi开关自动识别
+
+主站节点自动支持两种控制方式，无需额外配置：
+
+#### 方式1：Modbus RTU轮询（标准）
+- 主站定期轮询从站线圈状态
+- 通过MQTT或Node-RED流程控制继电器
+- 适用于所有Modbus RTU设备
+
+#### 方式2：Symi私有协议（自动）
+- 自动识别Symi开关按键事件（协议格式：`7E [地址] 03 0F ...`）
+- 自动应答并控制对应继电器（协议格式：`7E [地址] 04 0F ...`）
+- 映射规则：
+  - 设备地址1 → 从站10
+  - 设备地址2 → 从站11
+  - 设备地址3 → 从站12
+  - 设备地址4 → 从站13
+  - 通道号1-8 → 线圈0-7
+
+**按钮类型说明**：
+
+**1. 开关按钮（推荐）**
+- **控制方式**：按键有独立的开/关状态
+- **LED反馈**：面板LED指示灯精确同步开关状态
+- **适用场景**：
+  - 灯光开关（客厅灯、卧室灯等）
+  - 插座开关（电器控制）
+  - 窗帘开关（电动窗帘）
+  - 任何需要明确开/关状态的场景
+- **技术特点**：
+  - 使用SET协议（0x03）发送LED反馈
+  - 使用原始设备地址确保LED精确反馈
+  - 支持物理按键和Home Assistant远程控制
+  - 面板LED完美同步，响应速度快
+
+**2. 场景按钮**
+- **控制方式**：每次按下toggle切换状态（开→关→开）
+- **LED反馈**：根据当前状态显示LED（开=亮，关=灭）
+- **适用场景**：
+  - 场景触发（回家模式、离家模式等）
+  - 一键全开/全关
+  - 需要状态指示的场景按钮
+- **技术特点**：
+  - 使用REPORT协议（0x04）发送LED反馈
+  - 使用原始设备地址确保LED精确反馈
+  - 支持物理按键和Home Assistant远程控制
+  - 200ms防抖，避免重复触发
+
+**两种模式对比**：
+
+| 特性 | 开关按钮 | 场景按钮 |
+|------|---------|---------|
+| 控制方式 | 开/关独立 | Toggle切换 |
+| LED反馈协议 | SET (0x03) | REPORT (0x04) |
+| 按键事件 | 独立开/关码 | 统一触发码 |
+| LED同步 | ✓ 完美同步 | ✓ 完美同步 |
+| HA远程控制 | ✓ 支持 | ✓ 支持 |
+| 推荐场景 | 灯光/插座 | 场景触发 |
+
+**配置说明**：
+
+1. **RS-485连接**：选择串口配置节点（波特率9600，8N1）
+2. **MQTT服务器**：选择MQTT配置节点（连接Home Assistant等）
+3. **面板配置**：
+   - 面板品牌：选择亖米（Symi）
+   - 按钮类型：开关按钮或场景按钮
+   - 开关ID：物理面板的RS-485地址（0-255）
+   - 按钮编号：面板上的按键序号（1-8）
+4. **继电器映射**：
+   - 从站地址：Modbus继电器地址（10-247）
+   - 继电器路数：继电器通道（1-32路）
+
+**使用示例**：
+
+**示例1：客厅灯光开关**
+- 面板：开关ID=2，按键1（开关按钮）
+- 继电器：从站10，1路
+- 效果：按下面板按键，客厅灯开/关，面板LED同步状态
+
+**示例2：全开场景**
+- 面板：开关ID=2，按键8（场景按钮）
+- 继电器：从站10，32路
+- 效果：按下面板按键，触发全开场景
+
+### 智能轮询机制
+
+主站轮询时，从站开关可以同时使用。当从站开关上报数据到服务器后：
+1. **自动暂停轮询**：主站检测到写入操作，立即暂停轮询
+2. **优先处理数据**：处理从站上报的数据（写入Modbus继电器）
+3. **继续轮询**：数据处理完成后（100ms延迟），自动恢复轮询
+4. **日志记录**：记录轮询暂停时长和跳过的轮询次数
+
+这种机制确保：
+- 主站轮询不会与从站写入冲突
+- 从站上报的数据得到优先处理
+- 系统响应迅速，状态同步及时
+
+### MQTT自动发现
+
+启用MQTT后，自动生成Home Assistant兼容的Discovery配置：
+- **唯一性保证**：每个实体使用稳定的`unique_id`，避免重复生成
+- **设备分组**：同一从站的所有继电器自动分组到一个设备下
+- **状态持久化**：使用`retain=true`确保状态持久化
+- **在线状态**：自动发布设备可用性状态
+
+### 配置持久化
+
+所有节点配置自动保存到Node-RED的flows文件中：
+- 从站地址、线圈范围、轮询间隔
+- MQTT服务器配置
+- 开关面板映射关系
+
+部署后配置永久生效，重启Node-RED后自动恢复。
+
+### 长期稳定运行
+
+针对工控机24/7长期运行优化：
+- **内存管理**：自动清理缓存，释放无用对象
+- **事件监听器清理**：关闭时移除所有监听器，防止内存泄漏
+- **智能日志限流**：错误日志10分钟输出一次，避免日志刷屏
+- **自动重连**：Modbus和MQTT断线自动重连（5秒间隔）
+- **互斥锁机制**：防止读写冲突导致的数据异常
 
 ## 技术规格
 
 ### Modbus协议
 
-- **Modbus协议**：Modbus TCP / Modbus RTU
+- **协议类型**：Modbus TCP / Modbus RTU
+- **底层库**：modbus-serial ^8.0.23（内部封装serialport，支持TCP和串口）
 - **功能码支持**：0x01（读线圈）、0x05（写单个线圈）、0x0F（写多个线圈）
-- **从站地址范围**：1-247
+- **从站地址范围**：1-247（建议从10开始）
 - **线圈数量**：每台设备32个（0-31）
 - **最大设备数**：10台同时轮询
-- **轮询间隔**：最小10ms，默认200ms，推荐>=100ms
+- **轮询间隔**：默认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 / EMQ / Any MQTT 3.1.1/5.0
+- **MQTT Broker**: Mosquitto / EMQX / Any MQTT 3.1.1/5.0
 - **Home Assistant**: 2024.x+（MQTT Discovery标准）
-- **操作系统**: Windows / Linux / macOS
+- **操作系统**: Windows / Linux / macOS / HassOS
 
-## Docker/HassOS部署说明
-
-### HassOS环境部署
-
-**Node-RED插件安装**
-1. HassOS已内置Node-RED插件（Supervisor → 插件商店 → Node-RED）
-2. 安装本节点：进入Node-RED → 菜单 → 节点管理 → 搜索 `node-red-contrib-symi-modbus`
-
-**串口设备映射**（如果使用串口连接Modbus）
-1. 配置Node-RED插件，添加设备映射：
-   ```yaml
-   devices:
-     - /dev/ttyUSB0:/dev/ttyUSB0
-   ```
-2. 或者使用特权模式（不推荐）：
-   ```yaml
-   privileged: true
-   ```
-
-**MQTT配置**
-- 安装 "Mosquitto broker" 插件
-- 主站节点MQTT服务器配置：`mqtt://127.0.0.1:1883`（系统会自动fallback到`core-mosquitto`）
-- 无需用户名密码（除非你在Mosquitto插件中启用了认证）
+## Home Assistant集成
 
-### Docker Compose部署
+### 自动发现
 
-**docker-compose.yml 示例**
-```yaml
-version: '3.8'
-
-services:
-  node-red:
-    image: nodered/node-red:latest
-    container_name: node-red
-    restart: unless-stopped
-    ports:
-      - "1880:1880"
-    volumes:
-      - ./node-red-data:/data
-    # 串口设备映射（根据实际情况修改）
-    devices:
-      - /dev/ttyUSB0:/dev/ttyUSB0
-    # 如果需要访问宿主机的MQTT broker
-    extra_hosts:
-      - "host.docker.internal:host-gateway"
-    environment:
-      - TZ=Asia/Shanghai
-  
-  mosquitto:
-    image: eclipse-mosquitto:latest
-    container_name: mosquitto
-    restart: unless-stopped
-    ports:
-      - "1883:1883"
-    volumes:
-      - ./mosquitto/config:/mosquitto/config
-      - ./mosquitto/data:/mosquitto/data
-      - ./mosquitto/log:/mosquitto/log
-```
+启用MQTT后，设备自动出现在Home Assistant中：
+- 实体ID: `switch.relay_{从站地址}_{线圈编号}`
+- 设备名称: `Modbus继电器-{从站地址}`
+- 自动分组: 同一从站的所有继电器分组到一个设备
 
-**启动命令**
-```bash
-# 启动容器
-docker-compose up -d
+### MQTT主题结构
 
-# 进入Node-RED容器安装节点
-docker exec -it node-red sh
-cd /data
-npm install node-red-contrib-symi-modbus
-# 重启Node-RED生效
-docker restart node-red
 ```
-
-**MQTT配置**
-- 容器内Node-RED连接容器mosquitto：`mqtt://mosquitto:1883`
-- 容器内Node-RED连接宿主机mosquitto：`mqtt://host.docker.internal:1883`
-- 系统会自动尝试多个候选地址
-
-### Linux工控机部署
-
-**环境准备**
-```bash
-# 安装Node.js 14+
-curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
-sudo apt install -y nodejs
-
-# 安装Node-RED
-sudo npm install -g --unsafe-perm node-red
-
-# 安装MQTT Broker
-sudo apt install -y mosquitto mosquitto-clients
-
-# 添加用户到dialout组（串口权限）
-sudo usermod -a -G dialout $USER
+状态主题: modbus/relay/{从站}/{线圈}/state
+命令主题: modbus/relay/{从站}/{线圈}/set
+可用性主题: modbus/relay/{从站}/availability
+发现主题: homeassistant/switch/modbus_relay_{从站}_{线圈}/config
 ```
 
-**安装本节点**
-```bash
-cd ~/.node-red
-npm install node-red-contrib-symi-modbus
-```
-
-**启动Node-RED**
-```bash
-# 手动启动
-node-red
-
-# 或使用systemd服务（推荐）
-sudo systemctl enable nodered
-sudo systemctl start nodered
-```
-
-**MQTT配置**
-- 本机部署：`mqtt://localhost:1883` 或 `mqtt://127.0.0.1:1883`
-- 无需特殊配置，直接使用
+## 故障排除
 
-### 串口权限问题
+### 串口连接失败
 
-**Linux系统**
+**Linux**:
 ```bash
 # 查看串口设备
 ls -l /dev/ttyUSB* /dev/ttyS*
 
-# 查看当前用户组
-groups
-
-# 添加到dialout组
+# 添加用户到dialout组（需要重新登录）
 sudo usermod -a -G dialout $USER
-
-# 重新登录或重启生效
 ```
 
-**Docker容器**
+**macOS**:
 ```bash
-# 方式1：映射单个设备（推荐）
-docker run --device=/dev/ttyUSB0:/dev/ttyUSB0 ...
-
-# 方式2：特权模式（不推荐，安全风险）
-docker run --privileged ...
+# 查看串口设备（注意macOS使用cu.*而不是tty.*）
+ls -l /dev/cu.*
 ```
 
-## 故障排除
-
-### 连接失败
-
-**TCP连接失败**：
-- 检查网络连通性：`ping <IP地址>`
-- 确认Modbus TCP服务器地址和端口
-- 检查防火墙设置
-
-**串口连接失败**：
-- 确认串口名称正确（Linux: `/dev/ttyUSB0`, Windows: `COM1`）
-- 检查串口权限（Linux需要添加到dialout组）
-- 确保串口没有被其他程序占用
-- Docker环境确认设备已映射：`docker exec <容器> ls -l /dev/ttyUSB0`
-
-### MQTT连接问题
-
-**症状**：节点显示 "MQTT-ERR"，日志提示连接失败
-
-**HassOS环境解决方案**：
-1. 确认Mosquitto broker插件已安装并运行
-2. MQTT服务器配置填写：`mqtt://127.0.0.1:1883`（系统会自动尝试多个地址）
-3. 查看Node-RED日志：`MQTT broker候选地址: ...`，确认尝试了哪些地址
-4. 如果全部失败，尝试手动配置：`mqtt://core-mosquitto:1883`
+**Docker/HassOS**:
+```yaml
+# 在docker-compose.yml或HassOS插件配置中添加设备映射
+devices:
+  - /dev/ttyUSB0:/dev/ttyUSB0
+```
 
-**Docker环境解决方案**：
-1. 确认MQTT broker正在运行：`docker ps | grep mosquitto`
-2. 尝试多个配置：
-   - `mqtt://host.docker.internal:1883`
-   - `mqtt://172.17.0.1:1883`
-   - `mqtt://宿主机IP:1883`
-3. 检查容器网络：`docker network inspect bridge`
+### MQTT连接失败
 
-**本机环境解决方案**：
-1. 检查MQTT broker是否运行：
+1. 确认MQTT broker正在运行：
    ```bash
    # Linux
-   ps aux | grep mosquitto
    sudo systemctl status mosquitto
    
    # macOS
    brew services list | grep mosquitto
    ```
-2. 启动MQTT broker：
-   ```bash
-   # Linux
-   sudo systemctl start mosquitto
-   
-   # macOS
-   brew services start mosquitto
-   ```
-3. 测试连接：
+
+2. 测试MQTT连接：
    ```bash
    mosquitto_sub -h localhost -t test
    ```
 
-**日志分析**：
-- 查看Node-RED日志中的 "MQTT broker候选地址" 消息
-- 查看 "正在连接MQTT broker" 和成功/失败信息
-- 错误日志默认10分钟只显示一次，避免刷屏
+3. 检查Node-RED日志中的MQTT连接信息
 
-### 串口搜索不到设备
+### 主站轮询不工作
 
-**HassOS/Docker环境**：
-- 问题：点击"搜索"按钮没有找到串口
-- 原因：Docker容器默认无法访问USB设备
-- 解决：在Node-RED插件配置中添加设备映射（参见上方"Docker/HassOS部署说明"）
-- 备用：手动输入串口路径，如 `/dev/ttyUSB0`
+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` 单独测试串口通信
 
-**Linux工控机**：
-- 检查设备是否插入：`ls -l /dev/ttyUSB* /dev/ttyS*`
-- 检查权限：`groups`（确认包含dialout组）
-- 如果不在组中：`sudo usermod -a -G dialout $USER`，然后重新登录
+### 从站开关无响应
 
-### 日志系统
+1. 检查RS-485连接是否正常
+2. 确认开关面板地址和按钮编号正确
+3. 检查MQTT连接状态
+4. 查看Node-RED日志中的协议解析信息
 
-本节点使用智能日志限流机制：
-- 首次错误立即显示
-- 重复错误10分钟内不再显示
-- 重新部署后清除日志记录
+## 输入消息格式
 
-### 稳定性保证
+### 主站节点
 
-- 完整的Promise异常捕获，防止未处理rejection导致系统崩溃
-- 智能日志限流，避免日志过多占用磁盘空间
-- 自动重连机制（Modbus和MQTT连接断开后5秒自动重连）
-- MQTT智能fallback，自动尝试多个候选地址直到连接成功
-- 无内存泄漏，适合工控机24/7长期运行
-- 生产环境验证，稳定可靠
+```javascript
+// 启动轮询
+msg.payload = {cmd: "start"};
 
-### 性能指标
+// 停止轮询
+msg.payload = {cmd: "stop"};
 
-- **内存占用**：< 50MB（单个主站节点，轮询10个设备）
-- **CPU占用**：< 5%（正常轮询状态）
-- **连接延迟**：Modbus响应 < 100ms，MQTT发布 < 50ms
-- **稳定运行**：经过工控机7x24小时长期运行验证，无内存泄漏
-- **容错能力**：Modbus从站离线不影响其他从站，MQTT断线自动重连
+// 写单个线圈
+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
+```
 
-**当前版本**: v2.5.2
+## 输出消息格式
 
-**主要特性**：
-- Modbus TCP/RTU协议完整支持
-- MQTT自动发现与Home Assistant集成
-- 物理开关面板双向同步（Symi轻量级协议）
-- TCP帧缓冲与命令队列机制
-- 多设备并发控制互斥锁
-- 智能MQTT连接fallback
-- 适合Linux工控机长期稳定运行
+### 主站节点
 
-**升级方式**：
-```bash
-cd ~/.node-red
-npm install node-red-contrib-symi-modbus@latest
-# 重启Node-RED生效
+```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                    // 目标线圈编号
+}
+```
 
-MIT License
+## 性能指标
 
-## 作者
+- **内存占用**：< 50MB（单个主站节点，轮询10个设备）
+- **CPU占用**：< 5%（正常轮询状态）
+- **连接延迟**：Modbus响应 < 100ms，MQTT发布 < 50ms
+- **稳定运行**：经过工控机7x24小时长期运行验证
+- **容错能力**：Modbus从站离线不影响其他从站，MQTT断线自动重连
 
-**symi-daguo**
+## 示例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.5.4
+
+**核心功能**：
+- 支持多种Modbus协议（Telnet ASCII、RTU over TCP、Modbus TCP、Modbus RTU串口）
+- 多设备轮询（最多10台从站，每台32路继电器，轮询间隔100-10000ms可调）
+- Symi私有协议自动识别（支持两种485开关控制方式）
+- 智能轮询暂停机制（从站上报时自动暂停，处理完成后恢复）
+- MQTT集成（Home Assistant自动发现，实体唯一性保证，QoS=0高性能发布）
+- 物理开关面板双向同步（三米协议支持，LED反馈同步）
+- 共享连接架构（多个从站开关节点共享同一个串口/TCP连接，支持500+节点）
+- 长期稳定运行（内存管理、自动重连、错误日志限流、异步MQTT发布）
+
+**技术栈**：
+- 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.5.4）**：
+- **双模式支持**：完整支持开关按钮和场景按钮两种模式
+  - 开关按钮：独立开/关控制 + SET协议LED反馈
+  - 场景按钮：Toggle切换控制 + REPORT协议LED反馈
+- **精确LED反馈**：使用原始设备地址和通道，确保LED反馈到正确按键
+- **完美状态同步**：
+  - 物理按键控制 → LED同步 ✓
+  - Home Assistant远程控制 → LED同步 ✓
+  - 双向同步，实时响应
+- **协议优化**：
+  - 开关模式使用SET协议（0x03）
+  - 场景模式使用REPORT协议（0x04）
+  - 自动fallback机制确保HA远程控制正常
+- **性能提升**：
+  - 全局防抖机制（200ms）避免重复触发
+  - 基于面板ID的固定延迟避免TCP冲突
+  - 防死循环机制确保系统稳定
+  - 支持500+节点大规模部署
+- **用户体验**：
+  - 继电器路数优化：直接输入1-32路
+  - 完善串口配置：支持所有串口参数
+  - 智能日志输出：减少系统负担
+  - 长期稳定运行：工控机7x24小时验证
+
+**性能优化**：
+- 轮询间隔优化：修复间隔计算逻辑，确保每个从站使用正确的轮询间隔
+- MQTT发布使用QoS=0，避免阻塞轮询
+- 异步发布状态更新，不影响Modbus读取性能
+- 减少调试日志输出，降低CPU占用
+- 互斥锁机制确保读写操作不冲突
+- 共享连接配置节点，避免串口资源冲突
+
+**许可证**: MIT License
+
+**作者**: symi-daguo
 - NPM: https://www.npmjs.com/~symi-daguo
 - GitHub: https://github.com/symi-daguo
 
-## 支持
-
-如有问题或建议：
-- 提交Issue：https://github.com/symi-daguo/node-red-contrib-symi-modbus/issues
-- NPM包：https://www.npmjs.com/package/node-red-contrib-symi-modbus
+**支持**:
+- Issues: https://github.com/symi-daguo/node-red-contrib-symi-modbus/issues
+- NPM: https://www.npmjs.com/package/node-red-contrib-symi-modbus