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

package/nodes/modbus-master.js

@@ -2,11 +2,66 @@ module.exports = function(RED) {
     "use strict";
     const ModbusRTU = require("modbus-serial");
     const mqtt = require("mqtt");
+    
+    // 串口列表API - 支持Windows、Linux、macOS所有串口设备
+    RED.httpAdmin.get('/modbus-master/serialports', async function(req, res) {
+        try {
+            // 尝试从多个可能的位置获取serialport模块
+            let SerialPort;
+            try {
+                // 优先尝试使用node_modules中的serialport
+                SerialPort = require('serialport');
+            } catch (e) {
+                try {
+                    // 如果失败，尝试从modbus-serial的依赖中获取
+                    const ModbusRTU = require('modbus-serial');
+                    SerialPort = ModbusRTU.SerialPort || require('serialport');
+                } catch (e2) {
+                    // 两种方式都失败，返回空列表
+                    return res.json([]);
+                }
+            }
+            
+            // serialport v10+ (使用SerialPort.SerialPort.list)
+            if (SerialPort && SerialPort.SerialPort && SerialPort.SerialPort.list) {
+                const ports = await SerialPort.SerialPort.list();
+                const portList = ports.map(port => ({
+                    comName: port.path || port.comName,
+                    manufacturer: port.manufacturer || '未知设备',
+                    vendorId: port.vendorId || '',
+                    productId: port.productId || ''
+                }));
+                return res.json(portList);
+            }
+            
+            // serialport v9 (使用SerialPort.list)
+            if (SerialPort && SerialPort.list) {
+                const ports = await SerialPort.list();
+                const portList = ports.map(port => ({
+                    comName: port.path || port.comName,
+                    manufacturer: port.manufacturer || '未知设备',
+                    vendorId: port.vendorId || '',
+                    productId: port.productId || ''
+                }));
+                return res.json(portList);
+            }
+            
+            // 如果以上方法都不可用，返回空列表
+            res.json([]);
+        } catch (err) {
+            // 发生错误时记录日志并返回空列表
+            RED.log.warn(`串口列表获取失败: ${err.message}`);
+            res.json([]);
+        }
+    });
 
     function ModbusMasterNode(config) {
         RED.nodes.createNode(this, config);
         const node = this;
         
+        // 获取MQTT服务器配置节点
+        node.mqttServerConfig = RED.nodes.getNode(config.mqttServer);
+        
         // 配置参数
         node.config = {
             connectionType: config.connectionType,
@@ -24,10 +79,11 @@ module.exports = function(RED) {
                 pollInterval: 200
             }],
             enableMqtt: config.enableMqtt,
-            mqttBroker: config.mqttBroker,
-            mqttUsername: config.mqttUsername,
-            mqttPassword: config.mqttPassword,
-            mqttBaseTopic: config.mqttBaseTopic
+            // 从config节点读取MQTT配置
+            mqttBroker: node.mqttServerConfig ? node.mqttServerConfig.broker : "",
+            mqttUsername: node.mqttServerConfig ? node.mqttServerConfig.username : "",
+            mqttPassword: node.mqttServerConfig ? (node.mqttServerConfig.credentials ? node.mqttServerConfig.credentials.password : "") : "",
+            mqttBaseTopic: node.mqttServerConfig ? node.mqttServerConfig.baseTopic : "modbus/relay"
         };
         
         // Modbus客户端
@@ -39,6 +95,9 @@ module.exports = function(RED) {
         node.deviceStates = {}; // 存储每个设备的状态
         node.mqttClient = null;
         node.isClosing = false;
+        node.lastErrorLog = {}; // 记录每个从站的最后错误日志时间
+        node.lastMqttErrorLog = 0; // MQTT错误日志时间
+        node.errorLogInterval = 10 * 60 * 1000; // 错误日志间隔：10分钟
         
         // 初始化设备状态（基于从站配置列表）
         node.config.slaves.forEach((slave) => {
@@ -73,6 +132,10 @@ module.exports = function(RED) {
                 node.isConnected = true;
                 node.status({fill: "green", shape: "dot", text: "已连接"});
                 
+                // 清除错误日志记录（重新部署或重连时允许再次显示错误）
+                node.lastErrorLog = {};
+                node.lastMqttErrorLog = 0;
+                
                 // 启动轮询
                 node.startPolling();
                 
@@ -98,7 +161,10 @@ module.exports = function(RED) {
             }
             
             const options = {
-                clientId: `modbus_master_${Math.random().toString(16).substr(2, 8)}`
+                clientId: `modbus_master_${Math.random().toString(16).substr(2, 8)}`,
+                clean: false,  // 持久化会话，断线重连后继续接收消息
+                reconnectPeriod: 5000,  // 5秒自动重连
+                queueQoSZero: false  // 不缓存QoS=0的消息
             };
             
             if (node.config.mqttUsername) {
@@ -119,7 +185,14 @@ module.exports = function(RED) {
                 });
                 
                 node.mqttClient.on('error', (err) => {
-                    node.error(`MQTT错误: ${err.message}`);
+                    // 日志限流：MQTT错误最多每10分钟输出一次
+                    const now = Date.now();
+                    const shouldLog = (now - node.lastMqttErrorLog) > node.errorLogInterval;
+                    
+                    if (shouldLog) {
+                        node.error(`MQTT错误: ${err.message} [此错误将在10分钟后再次显示]`);
+                        node.lastMqttErrorLog = now;
+                    }
                 });
                 
                 node.mqttClient.on('message', (topic, message) => {
@@ -215,11 +288,12 @@ module.exports = function(RED) {
             }
             
             const commandTopic = `${node.config.mqttBaseTopic}/+/+/set`;
-            node.mqttClient.subscribe(commandTopic, (err) => {
+            // 使用QoS=1订阅，确保命令不丢失
+            node.mqttClient.subscribe(commandTopic, { qos: 1 }, (err) => {
                 if (err) {
                     node.error(`订阅MQTT命令主题失败: ${err.message}`);
                 } else {
-                    node.log(`已订阅MQTT命令主题: ${commandTopic}`);
+                    node.log(`已订阅MQTT命令主题: ${commandTopic}（QoS=1）`);
                 }
             });
         };
@@ -252,7 +326,12 @@ module.exports = function(RED) {
             const stateTopic = `${node.config.mqttBaseTopic}/${slaveId}/${coil}/state`;
             const payload = value ? 'ON' : 'OFF';
             
-            node.mqttClient.publish(stateTopic, payload, { retain: true });
+            // 使用QoS=1确保消息送达，retain=true确保断线重连后可获取最新状态
+            node.mqttClient.publish(stateTopic, payload, { qos: 1, retain: true }, (err) => {
+                if (err) {
+                    node.warn(`发布状态失败: ${stateTopic} - ${err.message}`);
+                }
+            });
         };
         
         // 开始轮询
@@ -261,6 +340,10 @@ module.exports = function(RED) {
                 return;
             }
             
+            // 清除错误日志记录（重新开始轮询时允许显示错误）
+            node.lastErrorLog = {};
+            node.lastMqttErrorLog = 0;
+            
             node.log(`开始轮询 ${node.config.slaves.length} 个从站设备`);
             node.currentSlaveIndex = 0;
             
@@ -352,9 +435,15 @@ module.exports = function(RED) {
             } catch (err) {
                 node.deviceStates[slaveId].error = err.message;
                 
-                // 容错机制：单个从站失败不影响其他从站
-                // 只记录警告，继续轮询下一个从站
-                node.warn(`轮询从站${slaveId}失败（不影响其他从站）: ${err.message}`);
+                // 日志限流：每个从站的错误日志最多每10分钟输出一次
+                const now = Date.now();
+                const lastLogTime = node.lastErrorLog[slaveId] || 0;
+                const shouldLog = (now - lastLogTime) > node.errorLogInterval;
+                
+                if (shouldLog) {
+                    node.warn(`轮询从站${slaveId}失败（不影响其他从站）: ${err.message} [此错误将在10分钟后再次显示]`);
+                    node.lastErrorLog[slaveId] = now;
+                }
                 
                 // 更新状态显示
                 const failedCount = Object.values(node.deviceStates).filter(s => s.error).length;
@@ -370,7 +459,12 @@ module.exports = function(RED) {
                     (err.message.includes('ECONNRESET') || 
                      err.message.includes('ETIMEDOUT') || 
                      err.message.includes('ENOTCONN'))) {
-                    node.warn('所有从站都失败，检测到连接断开，尝试重连...');
+                    
+                    // 连接断开也使用限流日志
+                    if (shouldLog) {
+                        node.warn('所有从站都失败，检测到连接断开，尝试重连...');
+                    }
+                    
                     node.isConnected = false;
                     node.stopPolling();
                     

package/nodes/modbus-slave-switch.html

@@ -3,67 +3,424 @@
         category: 'modbus',
         color: '#E9967A',
         defaults: {
-            name: {value: "开关"},
-            masterNode: {value: "", type: "modbus-master"},
-            slaveId: {value: 10, validate: RED.validators.number()},
-            coilNumber: {value: 0, validate: RED.validators.number()}
+            name: {value: "从站开关"},
+            // RS-485总线连接配置
+            connectionType: {value: "tcp"},
+            tcpHost: {value: "127.0.0.1"},
+            tcpPort: {value: 8888},
+            serialPort: {value: "COM1"},
+            serialBaudRate: {value: 9600},
+            serialDataBits: {value: 8},
+            serialStopBits: {value: 1},
+            serialParity: {value: "none"},
+            // MQTT配置
+            mqttServer: {value: "", type: "mqtt-server-config"},
+            // 开关面板配置
+            switchBrand: {value: "symi"},  // 品牌选择
+            switchId: {value: 0, validate: RED.validators.number()},
+            buttonNumber: {value: 1, validate: RED.validators.number()},
+            // 映射到继电器
+            targetSlaveAddress: {value: 10, validate: RED.validators.number()},
+            targetCoilNumber: {value: 0, validate: RED.validators.number()}
         },
         inputs: 1,
         outputs: 1,
         icon: "light.png",
         label: function() {
-            return this.name || `开关 ${this.slaveId}-${this.coilNumber}`;
+            return this.name || `开关${this.switchId}-按钮${this.buttonNumber} → 继电器${this.targetSlaveAddress}-${this.targetCoilNumber}`;
+        },
+        oneditprepare: function() {
+            // 切换连接类型时显示/隐藏相关配置
+            $("#node-input-connectionType").on("change", function() {
+                var connType = $(this).val();
+                if (connType === "tcp") {
+                    $(".form-row-tcp").show();
+                    $(".form-row-serial").hide();
+                } else {
+                    $(".form-row-tcp").hide();
+                    $(".form-row-serial").show();
+                }
+            });
+            
+            // 搜索串口按钮
+            $("#btn-search-ports").on("click", function() {
+                var btn = $(this);
+                var inputBox = $("#node-input-serialPort");
+                var selectBox = $("#port-list");
+                
+                btn.prop("disabled", true).html('<i class="fa fa-spinner fa-spin"></i> 搜索中');
+                
+                $.ajax({
+                    url: 'modbus-slave-switch/serialports',
+                    type: 'GET',
+                    success: function(ports) {
+                        selectBox.empty().append('<option value="">-- 选择检测到的串口 --</option>');
+                        
+                        if (ports.length === 0) {
+                            selectBox.append('<option disabled>未找到可用串口</option>');
+                            RED.notify("未找到可用串口，请手动输入串口路径", "warning");
+                        } else {
+                            ports.forEach(function(port) {
+                                var label = port.comName;
+                                if (port.manufacturer && port.manufacturer !== '未知设备') {
+                                    label += ' - ' + port.manufacturer;
+                                }
+                                selectBox.append('<option value="' + port.comName + '">' + label + '</option>');
+                            });
+                            // 显示下拉框，隐藏输入框
+                            inputBox.hide();
+                            selectBox.show();
+                        }
+                        
+                        btn.prop("disabled", false).html('<i class="fa fa-search"></i> 搜索');
+                    },
+                    error: function() {
+                        RED.notify("搜索串口失败", "error");
+                        btn.prop("disabled", false).html('<i class="fa fa-search"></i> 搜索');
+                    }
+                });
+            });
+            
+            // 选择串口（下拉选择）
+            $("#port-list").on("change", function() {
+                var selectedPort = $(this).val();
+                if (selectedPort) {
+                    $("#node-input-serialPort").val(selectedPort).show();
+                    $(this).hide();
+                }
+            });
+            
+            // 初始化显示
+            $("#node-input-connectionType").trigger("change");
         }
     });
 </script>
 
 <script type="text/html" data-template-name="modbus-slave-switch">
+    <!-- 基本配置 -->
     <div class="form-row">
         <label for="node-input-name"><i class="fa fa-tag"></i> 名称</label>
-        <input type="text" id="node-input-name" placeholder="开关">
+        <input type="text" id="node-input-name" placeholder="从站开关">
+    </div>
+    
+    <!-- RS-485总线连接配置 -->
+    <hr style="margin: 15px 0; border: 0; border-top: 2px solid #e0e0e0;">
+    <div class="form-row">
+        <label style="width: 100%; margin-bottom: 8px;">
+            <i class="fa fa-plug" style="color: #ff9800;"></i> 
+            <span style="font-size: 14px; font-weight: 600; color: #333;">RS-485总线连接配置</span>
+        </label>
+        <div style="font-size: 11px; color: #555; padding: 10px 12px; background: linear-gradient(135deg, #fff3cd 0%, #fffbe6 100%); border-left: 4px solid #ffc107; border-radius: 4px; box-shadow: 0 1px 3px rgba(0,0,0,0.08);">
+            <strong>总线说明：</strong>连接物理开关面板的RS-485总线，监听按键事件并发送控制指令
+        </div>
+    </div>
+    
+    <div class="form-row">
+        <label for="node-input-connectionType" style="width: 110px;"><i class="fa fa-exchange"></i> 连接类型</label>
+        <select id="node-input-connectionType" style="width: calc(70% - 110px);">
+            <option value="tcp">TCP/IP</option>
+            <option value="serial">串口</option>
+        </select>
+    </div>
+    
+    <!-- TCP配置 -->
+    <div class="form-row form-row-tcp">
+        <label for="node-input-tcpHost" style="width: 110px;"><i class="fa fa-server"></i> TCP主机</label>
+        <input type="text" id="node-input-tcpHost" placeholder="192.168.1.200" style="width: calc(70% - 110px);">
+        <div style="font-size: 11px; color: #888; margin-left: 110px; margin-top: 3px;">
+            RS-485转TCP网关IP地址
+        </div>
+    </div>
+    
+    <div class="form-row form-row-tcp">
+        <label for="node-input-tcpPort" style="width: 110px;"><i class="fa fa-plug"></i> TCP端口</label>
+        <input type="number" id="node-input-tcpPort" placeholder="8888" style="width: 100px;">
+        <span style="margin-left: 10px; font-size: 12px; color: #666;">默认 8888</span>
+    </div>
+    
+    <!-- 串口配置 -->
+    <div class="form-row form-row-serial">
+        <label for="node-input-serialPort" style="width: 110px;"><i class="fa fa-terminal"></i> 串口</label>
+        <div style="display: inline-block; width: calc(70% - 110px);">
+            <div style="display: flex; gap: 5px; align-items: center;">
+                <input type="text" id="node-input-serialPort" placeholder="COM1, /dev/ttyUSB0, /dev/ttyS1" style="flex: 1; padding: 5px 8px; border: 1px solid #ccc; border-radius: 4px; font-size: 13px;">
+                <select id="port-list" style="flex: 1; padding: 5px; font-family: monospace; font-size: 12px; border: 1px solid #ccc; border-radius: 4px; display: none;">
+                    <option value="">-- 选择检测到的串口 --</option>
+                </select>
+                <button type="button" id="btn-search-ports" style="padding: 6px 12px; background: #2196f3; color: white; border: none; border-radius: 4px; cursor: pointer; font-size: 12px; white-space: nowrap; transition: background 0.3s;">
+                    <i class="fa fa-search"></i> 搜索
+                </button>
+            </div>
+            <div style="font-size: 11px; color: #888; margin-top: 3px;">
+                支持COM1、/dev/ttyUSB0、/dev/ttyS1等RS-485串口设备
+            </div>
+        </div>
+    </div>
+    
+    <div class="form-row form-row-serial">
+        <label for="node-input-serialBaudRate" style="width: 110px;"><i class="fa fa-tachometer"></i> 波特率</label>
+        <select id="node-input-serialBaudRate" style="width: 150px;">
+            <option value="9600">9600</option>
+            <option value="19200">19200</option>
+            <option value="38400">38400</option>
+            <option value="57600">57600</option>
+            <option value="115200">115200</option>
+        </select>
+        <span style="margin-left: 10px; font-size: 11px; color: #888;">8-N-1固定配置（亖米协议）</span>
+    </div>
+    
+    <div class="form-row form-row-serial" style="display: none;">
+        <label for="node-input-serialDataBits" style="width: 110px;"><i class="fa fa-database"></i> 数据位</label>
+        <select id="node-input-serialDataBits" style="width: 100px;">
+            <option value="7">7</option>
+            <option value="8" selected>8</option>
+        </select>
+    </div>
+    
+    <div class="form-row form-row-serial" style="display: none;">
+        <label for="node-input-serialStopBits" style="width: 110px;"><i class="fa fa-stop"></i> 停止位</label>
+        <select id="node-input-serialStopBits" style="width: 100px;">
+            <option value="1" selected>1</option>
+            <option value="2">2</option>
+        </select>
+    </div>
+    
+    <div class="form-row form-row-serial" style="display: none;">
+        <label for="node-input-serialParity" style="width: 110px;"><i class="fa fa-check"></i> 校验位</label>
+        <select id="node-input-serialParity" style="width: 100px;">
+            <option value="none" selected>无</option>
+            <option value="even">偶校验</option>
+            <option value="odd">奇校验</option>
+        </select>
+    </div>
+    
+    <!-- MQTT配置 -->
+    <hr style="margin: 15px 0; border: 0; border-top: 2px solid #e0e0e0;">
+    <div class="form-row">
+        <label style="width: 100%; margin-bottom: 8px;">
+            <i class="fa fa-cloud" style="color: #9c27b0;"></i> 
+            <span style="font-size: 14px; font-weight: 600; color: #333;">MQTT服务器配置</span>
+        </label>
+    </div>
+    
+    <div class="form-row">
+        <label for="node-input-mqttServer" style="width: 110px;"><i class="fa fa-server"></i> MQTT服务器</label>
+        <input type="text" id="node-input-mqttServer" placeholder="选择或添加MQTT服务器配置" style="width: calc(70% - 110px);">
+        <div style="font-size: 11px; color: #888; margin-left: 110px; margin-top: 3px;">
+            选择已配置的MQTT服务器（需与主站节点使用同一配置）
+        </div>
+    </div>
+    
+    <!-- 物理开关面板配置 -->
+    <hr style="margin: 15px 0; border: 0; border-top: 2px solid #e0e0e0;">
+    <div class="form-row">
+        <label style="width: 100%; margin-bottom: 8px;">
+            <i class="fa fa-toggle-on" style="color: #3f51b5;"></i> 
+            <span style="font-size: 14px; font-weight: 600; color: #333;">物理开关面板配置</span>
+        </label>
     </div>
     
     <div class="form-row">
-        <label for="node-input-masterNode"><i class="fa fa-server"></i> 主站节点</label>
-        <input type="text" id="node-input-masterNode" placeholder="选择主站节点">
+        <label for="node-input-switchBrand" style="width: 110px;"><i class="fa fa-trademark"></i> 面板品牌</label>
+        <select id="node-input-switchBrand" style="width: 200px;">
+            <option value="symi">亖米（Symi）</option>
+            <option value="other1" disabled style="color: #999;">其他品牌1（待开发）</option>
+            <option value="other2" disabled style="color: #999;">其他品牌2（待开发）</option>
+        </select>
+        <span style="margin-left: 10px; font-size: 11px; color: #666; font-style: italic;">支持1-8键开关</span>
     </div>
     
     <div class="form-row">
-        <label for="node-input-slaveId"><i class="fa fa-map-marker"></i> 从站地址</label>
-        <input type="number" id="node-input-slaveId" placeholder="10" min="1" max="247">
+        <label for="node-input-switchId" style="width: 110px;"><i class="fa fa-id-card"></i> 开关ID</label>
+        <input type="number" id="node-input-switchId" placeholder="0" min="0" max="255" style="width: 90px; padding: 5px 8px; border: 1px solid #ccc; border-radius: 4px; font-size: 13px;">
+        <span style="margin-left: 10px; color: #666; font-size: 12px;">物理面板地址：<strong>0-255</strong></span>
+        <div style="font-size: 11px; color: #888; margin-left: 110px; margin-top: 3px;">
+            RS-485总线上的设备地址标识
+        </div>
     </div>
     
     <div class="form-row">
-        <label for="node-input-coilNumber"><i class="fa fa-toggle-on"></i> 线圈编号</label>
-        <input type="number" id="node-input-coilNumber" placeholder="0" min="0" max="31">
+        <label for="node-input-buttonNumber" style="width: 110px;"><i class="fa fa-hand-pointer-o"></i> 按钮编号</label>
+        <select id="node-input-buttonNumber" style="width: 150px;">
+            <option value="1">按钮 1</option>
+            <option value="2">按钮 2</option>
+            <option value="3">按钮 3</option>
+            <option value="4">按钮 4</option>
+            <option value="5">按钮 5</option>
+            <option value="6">按钮 6</option>
+            <option value="7">按钮 7</option>
+            <option value="8">按钮 8</option>
+        </select>
+        <span style="margin-left: 10px; font-size: 11px; color: #666; font-style: italic;">面板物理按键</span>
+    </div>
+    
+    <!-- 映射到继电器配置 -->
+    <hr style="margin: 15px 0; border: 0; border-top: 2px solid #e0e0e0;">
+    <div class="form-row">
+        <label style="width: 100%; margin-bottom: 8px;">
+            <i class="fa fa-arrow-right" style="color: #4caf50;"></i> 
+            <span style="font-size: 14px; font-weight: 600; color: #333;">映射到继电器设备</span>
+        </label>
+    </div>
+    
+    <div class="form-row">
+        <label for="node-input-targetSlaveAddress" style="width: 110px;"><i class="fa fa-map-marker"></i> 从站地址</label>
+        <input type="number" id="node-input-targetSlaveAddress" placeholder="10" min="1" max="247" style="width: 90px; padding: 5px 8px; border: 1px solid #ccc; border-radius: 4px; font-size: 13px;">
+        <span style="margin-left: 10px; color: #666; font-size: 12px;">Modbus继电器：<strong>10-19</strong></span>
+        <div style="font-size: 11px; color: #888; margin-left: 110px; margin-top: 3px;">
+            主站节点中配置的从站设备地址
+        </div>
+    </div>
+    
+    <div class="form-row">
+        <label for="node-input-targetCoilNumber" style="width: 110px;"><i class="fa fa-plug"></i> 线圈编号</label>
+        <input type="number" id="node-input-targetCoilNumber" placeholder="0" min="0" max="31" style="width: 90px; padding: 5px 8px; border: 1px solid #ccc; border-radius: 4px; font-size: 13px;">
+        <span style="margin-left: 10px; color: #666; font-size: 12px;">继电器通道：<strong>0-31</strong></span>
+        <div style="font-size: 11px; color: #888; margin-left: 110px; margin-top: 3px;">
+            32路继电器的具体通道编号
+        </div>
+    </div>
+    
+    <div class="form-row" style="margin-top: 20px; padding: 14px; background: linear-gradient(135deg, #e8f5e9 0%, #f1f8f4 100%); border-left: 4px solid #4caf50; border-radius: 6px; box-shadow: 0 2px 4px rgba(0,0,0,0.08);">
+        <div style="font-size: 12px; color: #333; line-height: 1.8;">
+            <div style="font-weight: 600; color: #2e7d32; margin-bottom: 10px; font-size: 13px;">
+                配置说明
+            </div>
+            <div style="margin-bottom: 8px; padding-left: 10px;">
+                <strong>面板品牌：</strong><span style="color: #555;">亖米协议，支持1-8键开关</span><br>
+                <strong>开关ID：</strong><span style="color: #555;">物理面板RS-485地址（0-255）</span><br>
+                <strong>按钮编号：</strong><span style="color: #555;">面板按键序号（1-8）</span><br>
+                <strong>从站地址：</strong><span style="color: #555;">Modbus继电器地址（10-19）</span><br>
+                <strong>线圈编号：</strong><span style="color: #555;">继电器通道号（0-31）</span>
+            </div>
+            <div style="margin-top: 12px; padding-top: 12px; border-top: 1px solid #a5d6a7;">
+                <div style="font-size: 11px; color: #2e7d32; font-weight: 500; margin-bottom: 5px;">
+                    配置示例
+                </div>
+                <div style="background: white; padding: 8px; border-radius: 4px; border: 1px solid #c8e6c9; font-size: 11px; color: #555;">
+                    <strong>场景：</strong>亖米开关ID=0，按钮1 → 控制继电器10的线圈0<br>
+                    <strong>MQTT：</strong><code style="background: #f5f5f5; padding: 2px 6px; border-radius: 3px; color: #e91e63; font-family: monospace;">modbus/relay/10/0/set</code>
+                </div>
+            </div>
+        </div>
     </div>
 </script>
 
 <script type="text/html" data-help-name="modbus-slave-switch">
-    <p>Modbus开关从站节点，用于控制单个继电器线圈。</p>
+    <p>Modbus从站开关节点，将物理开关面板的按钮映射到Modbus继电器设备，通过MQTT实现控制。</p>
+    
+    <h3>工作原理</h3>
+    <p>本节点实现物理开关面板（RS-485）到Modbus继电器的映射：</p>
+    <ul>
+        <li><strong>物理面板</strong>：开关ID（0-255）+ 按钮编号（1-8）</li>
+        <li><strong>映射到</strong>：Modbus从站地址（10-19）+ 线圈编号（0-31）</li>
+        <li><strong>通过MQTT</strong>：内置MQTT客户端，无需连线到主站节点</li>
+    </ul>
     
-    <h3>配置</h3>
+    <h3>MQTT配置</h3>
     <dl class="message-properties">
-        <dt>主站节点<span class="property-type">node</span></dt>
-        <dd>选择关联的Modbus主站节点</dd>
+        <dt>MQTT服务器<span class="property-type">string</span></dt>
+        <dd>MQTT Broker地址（如：mqtt://192.168.1.100:1883）</dd>
         
-        <dt>从站地址<span class="property-type">number</span></dt>
-        <dd>目标从站设备地址</dd>
+        <dt>用户名/密码<span class="property-type">string</span></dt>
+        <dd>MQTT认证信息（可选）</dd>
         
-        <dt>线圈编号<span class="property-type">number</span></dt>
-        <dd>要控制的线圈编号（0-31）</dd>
+        <dt>基础主题<span class="property-type">string</span></dt>
+        <dd>MQTT主题前缀（需与主站节点配置一致，默认：modbus/relay）</dd>
+    </dl>
+    
+    <h3>物理开关面板配置</h3>
+    <dl class="message-properties">
+        <dt>开关ID<span class="property-type">number (0-255)</span></dt>
+        <dd>物理开关面板的设备地址（RS-485总线地址）</dd>
+        
+        <dt>按钮编号<span class="property-type">number (1-8)</span></dt>
+        <dd>物理面板上的按键编号（每个面板最多8个按钮）</dd>
+    </dl>
+    
+    <h3>映射到继电器</h3>
+    <dl class="message-properties">
+        <dt>目标从站地址<span class="property-type">number (10-247)</span></dt>
+        <dd>要控制的Modbus继电器设备地址</dd>
+        
+        <dt>目标线圈编号<span class="property-type">number (0-31)</span></dt>
+        <dd>继电器的具体通道（32路继电器）</dd>
     </dl>
     
     <h3>输入</h3>
     <dl class="message-properties">
         <dt>payload<span class="property-type">boolean|string|number</span></dt>
-        <dd>开关状态：true/false, "ON"/"OFF", 1/0</dd>
+        <dd>开关命令：
+            <ul>
+                <li>布尔值：true=开，false=关</li>
+                <li>字符串："ON"/"OFF", "true"/"false", "1"/"0"</li>
+                <li>数字：1=开，0=关</li>
+            </ul>
+        </dd>
     </dl>
     
     <h3>输出</h3>
     <dl class="message-properties">
         <dt>payload<span class="property-type">boolean</span></dt>
-        <dd>当前开关状态</dd>
+        <dd>当前开关状态（true=开，false=关）</dd>
+        
+        <dt>topic<span class="property-type">string</span></dt>
+        <dd>主题：switch_{开关ID}_btn{按钮编号}</dd>
+        
+        <dt>switchId<span class="property-type">number</span></dt>
+        <dd>物理开关面板ID（0-255）</dd>
+        
+        <dt>button<span class="property-type">number</span></dt>
+        <dd>物理面板按钮编号（1-8）</dd>
+        
+        <dt>targetSlave<span class="property-type">number</span></dt>
+        <dd>映射到的继电器从站地址</dd>
+        
+        <dt>targetCoil<span class="property-type">number</span></dt>
+        <dd>映射到的继电器线圈编号</dd>
     </dl>
+    
+    <h3>MQTT主题</h3>
+    <p>本节点自动订阅和发布以下MQTT主题（基于目标继电器）：</p>
+    <ul>
+        <li><strong>状态主题</strong>：modbus/relay/{目标从站地址}/{目标线圈}/state（订阅）</li>
+        <li><strong>命令主题</strong>：modbus/relay/{目标从站地址}/{目标线圈}/set（发布）</li>
+    </ul>
+    
+    <h3>使用示例</h3>
+    <p><strong>场景1：</strong>开关ID=0（物理面板），按钮1 → 控制继电器10的线圈0</p>
+    <ul>
+        <li>开关ID：0（物理面板地址）</li>
+        <li>按钮编号：1（面板按钮）</li>
+        <li>目标从站地址：10（Modbus继电器）</li>
+        <li>目标线圈编号：0（继电器通道）</li>
+    </ul>
+    <p>MQTT主题：</p>
+    <ul>
+        <li>状态：modbus/relay/10/0/state</li>
+        <li>命令：modbus/relay/10/0/set</li>
+    </ul>
+    
+    <p><strong>场景2：</strong>开关ID=5，按钮3 → 控制继电器11的线圈15</p>
+    <ul>
+        <li>开关ID：5</li>
+        <li>按钮编号：3</li>
+        <li>目标从站地址：11</li>
+        <li>目标线圈编号：15</li>
+    </ul>
+    <p>MQTT主题：</p>
+    <ul>
+        <li>状态：modbus/relay/11/15/state</li>
+        <li>命令：modbus/relay/11/15/set</li>
+    </ul>
+    
+    <h3>特点</h3>
+    <ul>
+        <li>✅ 完全解耦：无需连线到主站节点</li>
+        <li>✅ 内置MQTT：自动管理MQTT连接</li>
+        <li>✅ 自动重连：连接断开自动恢复</li>
+        <li>✅ 状态同步：实时接收设备状态反馈</li>
+        <li>✅ 配置持久化：配置自动保存</li>
+    </ul>
 </script>