node-red-contrib-symi-modbus 2.10.20 → 2.10.29

package/README.md

@@ -30,11 +30,11 @@ Node-RED的Modbus继电器控制节点，支持TCP/串口通信和MQTT集成。
 | 节点名称 | 功能描述 |
 | :--- | :--- |
 | **Modbus主站** | 核心调度中心，负责协议解析、多设备轮询和状态管理。 |
-| **从站开关** | 监听物理面板（Symi/Clowire）按键事件并联动继电器，支持LED同步。 |
+| **从站开关** | 监听物理面板（Symi/Clowire/LF拉斐）按键事件并联动继电器，支持LED同步。 |
 | **HomeKit网桥** | 一键将所有 Modbus 继电器接入 Apple HomeKit，支持自定义名称。 |
 | **控制看板** | 在 Node-RED 编辑器内直接控制和查看所有继电器的实时状态。 |
 | **Mesh透传** | 适配 Symi 蓝牙 Mesh 网关，支持窗帘、杜亚电机及各种子设备。 |
-| **继电器输出** | 灵活的联动节点，支持按键触发、延时控制和多种动作逻辑。 |
+| **继电器输出** | 灵活的联动节点，支持按键触发、延时控制、多种动作逻辑，LF 品牌支持指示灯跟随与睡眠模式。 |
 | **Modbus调试** | 实时监控原始 485 总线报文，方便现场调试和协议分析。 |
 | **自定义协议** | 支持通过 JavaScript 编写自定义协议转换逻辑。 |
 | **配置节点** | 包含串口配置、MQTT配置和Modbus服务器配置。 |
@@ -117,7 +117,7 @@ node-red-restart
 1. 拖拽 **从站开关** 节点到流程画布
 2. 选择刚创建的RS-485连接配置
 3. 配置开关面板信息：
-   - 面板品牌: `Symi` / `Clowire`（克伦威尔）
+   - 面板品牌: `Symi` / `Clowire`（克伦威尔）/ `LF`（拉斐）
    - 开关ID: 物理面板地址 (0-255)
    - 按钮编号: 按键编号 (1-8)
    - 按钮类型:
@@ -128,6 +128,45 @@ node-red-restart
    - 目标线圈编号: `0`
 5. 部署流程
 
+#### LF（拉斐）485 弱电开关
+
+- **串口**：9600 8N1，指令间隔 ≥50ms（由 `serial-port-config` 写入队列保证）
+- **面板地址**：1–42（出厂默认 2），开关 ID 填十进制地址
+- **按键上报**（主动发送 8 字节）：`[地址][03][00][02][绝对键值][按键掩码][CRC]`
+- **指示灯控制**：写寄存器 `0x1008` 一次写入完整 bitmask（变背光产品高字节 BIT8=1，节点自动处理）
+- **待机指示灯**：继电器全部关闭时默认下发 `0x0100`（仅 BIT8 背光），**不会**自动全灭；全灭 `0x0000` 仅用于显式熄灭
+- **继电器输出（LF）**：可选 **指示灯跟随状态**——勾选则按键灯与绑定线圈同步；不勾选则按键后瞬时亮灯，本按键关联的全部继电器动作完成后恢复待机背光
+- **睡眠模式（LF）**：继电器输出节点勾选 **睡眠模式** 后，该按键触发的继电器动作完成时面板全部指示灯熄灭（含背光）；任意面板按键按下后自动退出睡眠，恢复正常显示
+- **RCU 模式**：首次 LED 控制自动写 `0x1003=0x0006` 并保存 `0x100F`
+- **多键同步**：同面板任意按键/继电器变化，经 `scheduleLfPanelLedSync` **面板级防抖** 后只发 **一条** `0x1008` 帧（非逐节点、非逐线圈各发一帧）
+
+**面板地址 1 · 变背光 · 单键亮（测试码）：**
+
+| 操作 | Hex |
+|------|-----|
+| 按键1亮 | `01 06 10 08 01 01 CC 98` |
+| 按键2亮 | `01 06 10 08 01 02 8C 99` |
+| 按键3亮 | `01 06 10 08 01 04 0C 9B` |
+| 按键4亮 | `01 06 10 08 01 08 0C 9E` |
+| 按键5亮 | `01 06 10 08 01 10 0C 94` |
+| 按键6亮 | `01 06 10 08 01 20 0C 80` |
+| 按键7亮 | `01 06 10 08 01 40 0C A8` |
+| 按键8亮 | `01 06 10 08 01 80 0C F8` |
+| **待机指示灯** | `01 06 10 08 01 00 0D 58` |
+| **全灭** | `01 06 10 08 00 00 0C C8` |
+
+**单键灭（`0x1008` 写剩余 bitmask，非逐键单独灭指令）：**
+
+| 操作 | Hex |
+|------|-----|
+| 仅灭当前唯一亮键（全灭） | `01 06 10 08 00 00 0C C8` |
+| 灭键1、键2仍亮 | `01 06 10 08 01 02 8C 99` |
+| 灭键2、键1+3仍亮 | `01 06 10 08 01 05 CD 5B` |
+| 键1+3亮 | `01 06 10 08 01 05 CD 5B` |
+| 键1–4全亮 | `01 06 10 08 01 0F 4D 5C` |
+
+**修改面板地址**：广播 `FF 06 10 00 00 [新地址] [CRC]`，再向新地址发 `XX 06 10 0F 00 FE [CRC]` 保存。
+
 ### 6. 进阶功能配置
 
 #### HomeKit 接入
@@ -487,6 +526,15 @@ msg.payload = 1;      // 或 0
 
 ### 更新日志
 
+#### v2.10.29 (2026-07-09)
+
+- **[LF485 开关]** 拉斐 LF 485 弱电开关完整对接：主动收发、RCU 模式自动启用、变背光 BIT8、面板级 `0x1008` 单帧聚合（同面板 8 键只发一条指示灯帧）。
+- **[LF485 睡眠模式]** 继电器输出节点新增 **睡眠模式** 勾选项（仅 LF 品牌）：勾选后该按键触发的继电器动作完成时，面板全部指示灯熄灭（`0x1008=0x0000`，含背光）；任意面板按键按下后自动退出睡眠，恢复正常显示。
+- **[LF485 指示灯跟随]** 继电器输出节点 LF 品牌新增 **指示灯跟随状态**（默认不跟随）：勾选=按键灯与绑定线圈同步；不勾选=瞬时亮灯，同按键全部继电器动作完成后回待机背光。
+- **[LF485 待机背光]** 继电器全关时默认 **待机背光**（`0x1008=0x0100`），不再误发全灭。
+- **[适配]** 从站开关 / 继电器输出 / Mesh 透传节点支持 LF 品牌；`lf-protocol.js` 单元测试覆盖 PDF 范例与用户抓包。
+- **[修复]** `RED.nodes.eachNode` 空指针崩溃防护；补全按键 7/8 从站开关节点；场景键不再误写 Modbus 线圈；移除未使用参数。
+
 #### v2.10.20 (2026-06-30)
 
 - **[打包]** 修复 npm 发布包误含 `.codebase-memory/` 开发索引的问题，包体积约 158KB；规范 `.npmignore` / `.gitignore`，开发缓存目录不进入发布包。

package/lib/lf-led-registry.js

@@ -0,0 +1,364 @@
+"use strict";
+
+/**
+ * LF 面板指示灯聚合状态（从站开关 + 继电器输出共享）
+ *
+ * 设计原则：同一面板 (serialPortConfigId + switchId) 任意时刻只通过
+ * scheduleLfPanelLedSync 汇聚为 **一条** 0x1008 帧；禁止多路径各自立即发送。
+ *
+ * 待机：0x1008 = 0x0100（仅 BIT8 背光）
+ * 全灭：0x0000（仅显式熄灭场景）
+ */
+
+let syncCallback = null;
+const lfRelayOutputs = new Map();
+const lfMomentaryButtons = new Map();
+const lfPendingActions = new Map();
+const lfPanelSyncTimers = new Map();
+// 睡眠模式：面板级状态，激活时指示灯全灭（0x0000），任意按键退出
+const lfSleepModePanels = new Set();
+
+const BATCH_FALLBACK_MARGIN_MS = 3000;
+const PANEL_LED_DEBOUNCE_MS = 200;
+const PANEL_LED_DEDUPE_MS = 200;
+
+function getPanelKey(serialPortConfigId, switchId) {
+    return `${serialPortConfigId}:${parseInt(switchId, 10)}`;
+}
+
+/**
+ * 设置面板睡眠模式
+ * @param {string} serialPortConfigId 串口配置ID
+ * @param {number|string} switchId 面板地址
+ * @param {boolean} enabled true=进入睡眠（全灭），false=退出睡眠
+ */
+function setPanelSleepMode(serialPortConfigId, switchId, enabled) {
+    const panelKey = getPanelKey(serialPortConfigId, switchId);
+    if (enabled) {
+        lfSleepModePanels.add(panelKey);
+    } else {
+        lfSleepModePanels.delete(panelKey);
+    }
+}
+
+/**
+ * 查询面板是否处于睡眠模式
+ */
+function isPanelSleepMode(serialPortConfigId, switchId) {
+    return lfSleepModePanels.has(getPanelKey(serialPortConfigId, switchId));
+}
+
+/**
+ * 清除所有睡眠模式状态（节点卸载/重启时调用）
+ */
+function clearAllSleepMode() {
+    lfSleepModePanels.clear();
+}
+
+function getPendingKey(serialPortConfigId, switchId, buttonNumber) {
+    return `${getPanelKey(serialPortConfigId, switchId)}:${parseInt(buttonNumber, 10)}`;
+}
+
+function setLfLedSyncCallback(fn) {
+    syncCallback = fn;
+}
+
+function cancelPanelSyncTimer(panelKey) {
+    const timer = lfPanelSyncTimers.get(panelKey);
+    if (timer) {
+        clearTimeout(timer);
+        lfPanelSyncTimers.delete(panelKey);
+    }
+}
+
+/**
+ * 面板级 LED 调度：多次请求合并为一次 0x1008 发送
+ * @param {object} [options]
+ * @param {boolean} [options.immediate] 立即发送（仅按键瞬时亮灯等需要即时反馈的场景）
+ * @param {number} [options.debounceMs] 防抖毫秒，默认 200
+ */
+function scheduleLfPanelLedSync(serialPortConfigId, switchId, options) {
+    const opts = options || {};
+    const panelId = parseInt(switchId, 10);
+    const panelKey = getPanelKey(serialPortConfigId, panelId);
+
+    cancelPanelSyncTimer(panelKey);
+
+    if (opts.immediate === true) {
+        if (typeof syncCallback === "function") {
+            syncCallback(serialPortConfigId, panelId);
+        }
+        return;
+    }
+
+    const debounceMs = opts.debounceMs !== undefined ? opts.debounceMs : PANEL_LED_DEBOUNCE_MS;
+    const timer = setTimeout(() => {
+        lfPanelSyncTimers.delete(panelKey);
+        if (typeof syncCallback === "function") {
+            syncCallback(serialPortConfigId, panelId);
+        }
+    }, debounceMs);
+    lfPanelSyncTimers.set(panelKey, timer);
+}
+
+/** @deprecated 请使用 scheduleLfPanelLedSync；保留兼容入口 */
+function requestLfPanelLedSync(serialPortConfigId, switchId) {
+    scheduleLfPanelLedSync(serialPortConfigId, switchId, { debounceMs: PANEL_LED_DEBOUNCE_MS });
+}
+
+function registerLfRelayOutput(node) {
+    if (!node || node.switchBrand !== "lf" || node.buttonType === "input") {
+        return;
+    }
+    const configId = node.serialPortConfig || node.id || "global";
+    const key = getPanelKey(configId, node.switchId);
+    if (!lfRelayOutputs.has(key)) {
+        lfRelayOutputs.set(key, new Set());
+    }
+    lfRelayOutputs.get(key).add(node);
+}
+
+function unregisterLfRelayOutput(node) {
+    if (!node) {
+        return;
+    }
+    const configId = node.serialPortConfig || node.id || "global";
+    const key = getPanelKey(configId, node.switchId);
+    const set = lfRelayOutputs.get(key);
+    if (!set) {
+        return;
+    }
+    set.delete(node);
+    if (set.size === 0) {
+        lfRelayOutputs.delete(key);
+    }
+}
+
+function getRelayOutputsForButton(serialPortConfigId, switchId, buttonNumber) {
+    const key = getPanelKey(serialPortConfigId, switchId);
+    const set = lfRelayOutputs.get(key);
+    if (!set) {
+        return [];
+    }
+    const btn = parseInt(buttonNumber, 10);
+    return Array.from(set).filter((ro) => parseInt(ro.buttonNumber, 10) === btn);
+}
+
+function getMomentaryOutputs(serialPortConfigId, switchId, buttonNumber) {
+    return getRelayOutputsForButton(serialPortConfigId, switchId, buttonNumber)
+        .filter((ro) => ro.lfLedFollowState !== true);
+}
+
+function hasMomentaryRelayOutputs(serialPortConfigId, switchId, buttonNumber) {
+    return getMomentaryOutputs(serialPortConfigId, switchId, buttonNumber).length > 0;
+}
+
+function clearMomentary(serialPortConfigId, switchId, buttonNumber) {
+    const key = getPanelKey(serialPortConfigId, switchId);
+    const active = lfMomentaryButtons.get(key);
+    if (!active) {
+        return;
+    }
+    active.delete(parseInt(buttonNumber, 10));
+    if (active.size === 0) {
+        lfMomentaryButtons.delete(key);
+    }
+}
+
+function finishMomentaryBatch(serialPortConfigId, switchId, buttonNumber, pendingKey) {
+    const pending = lfPendingActions.get(pendingKey);
+    if (!pending) {
+        return;
+    }
+    if (pending.fallbackTimer) {
+        clearTimeout(pending.fallbackTimer);
+    }
+    lfPendingActions.delete(pendingKey);
+    clearMomentary(serialPortConfigId, switchId, buttonNumber);
+    // 批次结束：只调度一次聚合同步（含继电器状态稳定等待）
+    scheduleLfPanelLedSync(serialPortConfigId, switchId, { debounceMs: PANEL_LED_DEBOUNCE_MS });
+}
+
+/**
+ * 面板上是否有进行中的瞬时亮灯批次（继电器动作尚未全部完成）
+ */
+function hasActiveMomentaryBatch(serialPortConfigId, switchId) {
+    const prefix = `${getPanelKey(serialPortConfigId, switchId)}:`;
+    for (const [key, pending] of lfPendingActions.entries()) {
+        if (key.startsWith(prefix) && pending.completed < pending.expected) {
+            return true;
+        }
+    }
+    return false;
+}
+
+function isMomentaryBatchActive(serialPortConfigId, switchId, buttonNumber) {
+    const pendingKey = getPendingKey(serialPortConfigId, switchId, buttonNumber);
+    const pending = lfPendingActions.get(pendingKey);
+    return !!(pending && pending.completed < pending.expected);
+}
+
+/**
+ * 在 modbus:buttonPressed 派发之前调用
+ */
+function beginLfButtonActionBatch(serialPortConfigId, switchId, buttonNumber) {
+    const configId = serialPortConfigId;
+    const panelId = parseInt(switchId, 10);
+    const btn = parseInt(buttonNumber, 10);
+    const panelKey = getPanelKey(configId, panelId);
+    const pendingKey = getPendingKey(configId, panelId, btn);
+
+    const momentaryOutputs = getMomentaryOutputs(configId, panelId, btn);
+    if (momentaryOutputs.length === 0) {
+        return false;
+    }
+
+    if (lfPendingActions.has(pendingKey)) {
+        const old = lfPendingActions.get(pendingKey);
+        if (old && old.fallbackTimer) {
+            clearTimeout(old.fallbackTimer);
+        }
+    }
+
+    if (!lfMomentaryButtons.has(panelKey)) {
+        lfMomentaryButtons.set(panelKey, new Set());
+    }
+    lfMomentaryButtons.get(panelKey).add(btn);
+
+    const maxDelay = momentaryOutputs.reduce((max, ro) => Math.max(max, ro.delayMs || 0), 0);
+    const pending = {
+        expected: momentaryOutputs.length,
+        completed: 0,
+        maxDelay: maxDelay,
+        startedAt: Date.now()
+    };
+    pending.fallbackTimer = setTimeout(() => {
+        if (lfPendingActions.has(pendingKey)) {
+            finishMomentaryBatch(configId, panelId, btn, pendingKey);
+        }
+    }, maxDelay + BATCH_FALLBACK_MARGIN_MS);
+
+    lfPendingActions.set(pendingKey, pending);
+    return true;
+}
+
+function ensureLfButtonActionBatch(serialPortConfigId, switchId, buttonNumber) {
+    const pendingKey = getPendingKey(serialPortConfigId, switchId, buttonNumber);
+    if (lfPendingActions.has(pendingKey)) {
+        return true;
+    }
+    return beginLfButtonActionBatch(serialPortConfigId, switchId, buttonNumber);
+}
+
+function onLfRelayActionComplete(node) {
+    if (!node || node.switchBrand !== "lf" || node.lfLedFollowState === true) {
+        return;
+    }
+    const configId = node.serialPortConfig || node.id || "global";
+    const btn = parseInt(node.buttonNumber, 10);
+    const pendingKey = getPendingKey(configId, node.switchId, btn);
+    const pending = lfPendingActions.get(pendingKey);
+    if (!pending) {
+        return;
+    }
+
+    pending.completed += 1;
+    if (pending.completed < pending.expected) {
+        return;
+    }
+
+    finishMomentaryBatch(configId, node.switchId, btn, pendingKey);
+}
+
+function computeLfPanelLedMask(serialPortConfigId, switchId, lfProtocol, lfPanelNodes) {
+    // 睡眠模式优先：指示灯全灭（0x0000，连背光都灭），任意按键退出后自动恢复
+    if (lfSleepModePanels.has(getPanelKey(serialPortConfigId, switchId))) {
+        return 0;
+    }
+
+    let keyMask = 0;
+    const panelKey = getPanelKey(serialPortConfigId, switchId);
+
+    const collectFromSlave = function(n) {
+        if (!n || !n.config || n.config.switchBrand !== "lf") {
+            return;
+        }
+        if (parseInt(n.config.switchId, 10) !== parseInt(switchId, 10)) {
+            return;
+        }
+        if (!n.serialPortConfig || n.serialPortConfig.id !== serialPortConfigId) {
+            return;
+        }
+        if (n.config.syncLight === false) {
+            return;
+        }
+        if (n.config.buttonType === "scene") {
+            return;
+        }
+        if (n.currentState) {
+            keyMask |= lfProtocol.buttonToMask(n.config.buttonNumber);
+        }
+    };
+
+    const registered = lfPanelNodes.get(panelKey);
+    if (registered && registered.size > 0) {
+        registered.forEach(collectFromSlave);
+    }
+
+    const momentary = lfMomentaryButtons.get(panelKey);
+    if (momentary) {
+        momentary.forEach((btn) => {
+            keyMask |= lfProtocol.buttonToMask(btn);
+        });
+    }
+
+    const relaySet = lfRelayOutputs.get(panelKey);
+    if (relaySet) {
+        const followByButton = new Map();
+        relaySet.forEach((ro) => {
+            if (ro.lfLedFollowState !== true) {
+                return;
+            }
+            const btn = parseInt(ro.buttonNumber, 10);
+            const lit = ro.currentCoilState === true;
+            if (!followByButton.has(btn)) {
+                followByButton.set(btn, false);
+            }
+            if (lit) {
+                followByButton.set(btn, true);
+            }
+        });
+        followByButton.forEach((lit, btn) => {
+            if (lit) {
+                keyMask |= lfProtocol.buttonToMask(btn);
+            }
+        });
+    }
+
+    if (keyMask === 0) {
+        return lfProtocol.LED_STANDBY_MASK;
+    }
+    return lfProtocol.finalizeLedMask(keyMask, true);
+}
+
+module.exports = {
+    PANEL_LED_DEBOUNCE_MS,
+    PANEL_LED_DEDUPE_MS,
+    setLfLedSyncCallback,
+    scheduleLfPanelLedSync,
+    requestLfPanelLedSync,
+    registerLfRelayOutput,
+    unregisterLfRelayOutput,
+    beginLfButtonActionBatch,
+    ensureLfButtonActionBatch,
+    onLfRelayActionComplete,
+    hasActiveMomentaryBatch,
+    isMomentaryBatchActive,
+    hasMomentaryRelayOutputs,
+    getMomentaryOutputs,
+    computeLfPanelLedMask,
+    getPanelKey,
+    setPanelSleepMode,
+    isPanelSleepMode,
+    clearAllSleepMode
+};