node-red-contrib-symi-modbus

v2.9.5

Published

9 hours ago

Node-RED Modbus节点，支持TCP/串口通信、串口自动搜索、多设备轮询、可选MQTT集成（支持纯本地模式和MQTT模式）、Home Assistant自动发现、HomeKit网桥、可视化控制看板、自定义协议转换和物理开关面板双向同步，工控机长期稳定运行

Downloads

588

0High
0Medium
0Low

symi-daguo

node-red modbus modbus-tcp modbus-rtu relay mqtt automation home-assistant smart-home iot industrial plc

node-red-contrib-symi-modbus

Node-RED的Modbus继电器控制节点，支持TCP/串口通信和MQTT集成，专为智能家居场景设计。

核心特性

双模式运行：
- 本地模式：纯串口/TCP通信，断网也能稳定运行，无需MQTT
- MQTT模式：可选接入Home Assistant等第三方平台
多协议支持：
- Modbus RTU（串口直连RS485）
- Modbus TCP（标准Modbus TCP）
- Modbus RTU over TCP（TCP转RS485网关）
- Telnet ASCII（推荐用于TCP转RS485网关）
Symi开关集成：
- RS-485开关：自动识别并处理Symi私有协议按键事件
- 蓝牙Mesh开关：支持Symi蓝牙Mesh网关和1-6路Mesh开关
- 双向同步：开关面板与继电器状态实时同步
- 设备持久化：Mesh设备列表自动保存，重启无需重新扫描
HomeKit网桥：一键桥接到Apple HomeKit，支持Siri语音控制，自动同步主站配置，名称可自定义
智能写入队列：所有写入操作串行执行，支持HomeKit群控160个继电器同时动作，流畅无卡顿
可视化控制看板：实时显示和控制所有继电器状态，美观易用，适合现场调试和日常监控
自定义协议转换：支持非标准485协议设备，窗帘循环控制，配置界面可测试发送
多设备轮询：支持最多10台Modbus从站设备，每台32路继电器
智能轮询机制：从站上报时自动暂停轮询，优先处理数据，避免冲突
稳定可靠：完整的内存管理、错误处理、断线重连，适合7x24小时长期运行
总线数据过滤：自动忽略总线上的无关数据，只处理本节点相关的数据

快速开始

1. 安装

通过npm安装（推荐）

cd ~/.node-red
npm install node-red-contrib-symi-modbus
node-red-restart

通过Node-RED界面安装

点击右上角菜单 → 设置 → 节点管理
搜索 node-red-contrib-symi-modbus
点击安装

2. 选择运行模式

本节点支持两种运行模式，根据需求选择：

模式1：本地模式（推荐用于纯串口控制）

适用场景：

无需对接第三方平台
断网环境下稳定运行
纯本地化控制，不受网络影响

配置方法：

主站节点：不启用MQTT或不配置MQTT服务器
从站开关节点：不配置MQTT服务器
无需连线：主站和从站通过内部事件自动通信

优势：

断网也能稳定运行
不依赖外部服务
响应速度更快
配置更简单
无需手动连线（免连线通信）

模式2：MQTT模式（推荐用于Home Assistant集成）

适用场景：

需要对接Home Assistant等平台
需要远程控制
需要状态持久化

配置方法：

拖拽任意节点到流程画布
双击节点，找到"MQTT服务器"字段
点击编辑按钮，填写MQTT服务器信息：
- MQTT Broker: mqtt://localhost:1883 (或你的MQTT服务器地址)
- 用户名/密码: 按需填写
- 基础主题: modbus/relay (默认)

优势：

Home Assistant自动发现
支持远程控制
状态持久化存储

3. 配置主站节点

拖拽 Modbus主站 节点到流程画布
配置连接参数：
- 串口模式（直连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设备
配置从站设备：
- 从站地址: 10 (默认，可添加多个，如10、11、12、13)
- 线圈范围: 0-31
- 轮询间隔: 200ms (默认，支持100-10000ms)
MQTT配置（可选）：
- 本地模式：不启用MQTT或留空
- MQTT模式：启用MQTT并选择MQTT服务器配置
部署流程

4. 配置RS-485连接配置节点（用于从站开关）

如果需要物理开关面板控制，首先创建RS-485连接配置：

点击右上角菜单 → 配置节点
添加新的 serial-port-config 配置节点
选择连接类型：
- 串口模式（本地RS-485总线）：
  - 连接类型: 串口
  - 串口路径: /dev/ttyUSB0 (可点击"搜索"按钮自动发现)
  - 波特率: 9600
  - 数据位: 8
  - 停止位: 1
  - 校验位: 无 (N)
- TCP模式（通过TCP转RS485网关）：
  - 连接类型: TCP网关
  - TCP主机: 192.168.2.110
  - TCP端口: 1031
保存配置

5. 配置从站开关节点（可选）

使用物理开关面板控制继电器，支持三种模式：

模式1：RS-485开关模式（传统有线开关）

拖拽 从站开关 节点到流程画布
选择刚创建的RS-485连接配置
配置开关面板信息：
- 面板品牌: 亖米 (默认)
- 按钮类型: 开关按钮（RS-485）
- 开关ID: 物理面板地址 (0-255)
- 按钮编号: 按键编号 (1-8)
配置映射到的继电器：
- 目标从站地址: 10
- 目标线圈编号: 1（用户输入1-32）
无需连线：主站和从站通过内部事件自动通信
部署流程

模式2：RS-485场景模式（场景触发）

配置步骤同上，但按钮类型选择 场景按钮（RS-485）
每次按键触发状态翻转（ON→OFF或OFF→ON）
适用于场景联动、一键控制等场景

模式3：Mesh开关模式（蓝牙Mesh无线开关）

适用场景：使用Symi蓝牙Mesh网关和Mesh开关面板

配置步骤：

准备工作
- 确保Mesh网关已通过TCP或串口连接到Node-RED
- 确保Mesh开关已配网到网关
添加节点
- 拖拽 从站开关 节点到流程画布
- 选择Mesh网关的连接配置（TCP或串口）
扫描Mesh设备
- 按钮类型: 选择 Mesh开关（蓝牙Mesh）
- 点击 扫描设备 按钮
- 系统发送 53 12 00 41 协议帧到网关
- 网关立即返回所有Mesh开关列表（通常5秒内完成）
- 设备列表自动持久化保存到 ~/.node-red/mesh-devices-persist/
- 重启Node-RED无需重新扫描，直接从持久化存储加载
选择设备和按键
- Mesh设备: 从下拉框选择开关（显示格式：MAC地址 (X路开关)）
- 按钮编号: 选择要使用的按键（1-6路）
- 无线模式（可选）: 勾选此选项后，该按键不响应LED反馈
  - 适用场景：按键用于触发场景（如全开/全关），继电器状态变化不应点亮该按键LED
  - 例如：按键3控制线圈16（全开触发），勾选无线模式后，线圈0-15状态变化不会点亮按键3的LED
- 多个节点可共享同一设备列表，无需重复扫描
配置目标继电器
- 目标从站地址: 10
- 目标线圈编号: 1（用户输入1-32）
部署流程
- 点击"完成"并部署
- Mesh开关按键会自动控制对应继电器
- 继电器状态变化会自动反馈到Mesh开关LED（无线模式按键除外）

Mesh模式特点：

无线控制，无需布线
支持1-6路开关
双向同步（按键→继电器，继电器→LED）
支持无线模式（场景触发按键不响应LED反馈）
设备列表持久化保存
短地址自动更新（如果网关重新配网）
与RS-485开关使用方式完全一致

6. 配置HomeKit网桥节点（可选）

将Modbus继电器桥接到Apple HomeKit，实现Siri语音控制：

配置步骤：

添加网桥节点
- 拖拽 HomeKit网桥 节点到流程画布
- 双击节点打开配置界面
基础配置
- 网桥名称: Modbus继电器网桥（在HomeKit中显示）
- 选择主站节点: 从下拉框选择已配置的主站
- 配对码: 031-45-154（添加到HomeKit时使用）
- 端口: 51828（保持默认）
配置继电器名称（推荐）
- 选择主站后，下方会自动显示所有继电器
- 为每个继电器输入友好的中文名称
- 例如：客厅灯、卧室灯、空调插座等
- 配置后在HomeKit中直接显示，无需再修改
部署并添加到HomeKit
- 点击"完成"并部署流程
- 打开iPhone/iPad的"家庭"App
- 点击右上角"+" → "添加配件"
- 选择"更多选项"
- 找到"Modbus继电器网桥"
- 输入配对码：031-45-154
- 完成配对

使用说明：

线圈0-15显示为开关，线圈16-31显示为插座
支持Siri语音控制："嘿Siri，打开客厅灯"
支持HomeKit自动化和场景
配置会自动保存，重启后无需重新配对
群控性能：支持同时控制多个继电器（如创建编组），智能队列机制确保流畅无卡顿

群控说明（客户友好模式）：

本节点专为智能家居群控场景优化，支持以下高性能操作：

HomeKit编组群控：
- 在HomeKit中创建房间或编组，可同时控制多个继电器
- 例如：创建"客厅"编组，包含10个灯光开关，一键全开/全关
- 智能优先队列机制确保触发源面板最快响应，其他继电器按序执行
- 10个继电器同时动作仅需约400ms（40ms间隔×10），触发源面板优先反馈
场景联动：
- 支持HomeKit场景（如"回家模式"、"离家模式"）
- 场景可包含多个继电器动作，自动串行执行
- 前16个线圈（继电器）可同时动作，后16个线圈（场景）按需触发
性能保证：
- 最大支持10台继电器（每台32路），共320个线圈
- 前160个线圈（10台×16路）可用于继电器控制，支持群控
- 后160个线圈（10台×16路）可用于场景触发，一般不会全部同时动作
- 智能写入队列确保所有操作串行执行，避免总线冲突
- 长期稳定运行，反复控制不会造成内存增加、卡顿或死机
技术细节：
- 写入队列间隔：40ms（确保总线稳定，优化指示灯反馈）
- 智能优先队列：触发源面板优先处理（500ms优先窗口）
- 轮询恢复时间：20ms（快速响应）
- 锁等待超时：100ms（快速检测异常）
- 队列自动处理，无需手动干预

核心特性说明

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（开=亮，关=灭）
协议特征：操作信息为0x11、0x12、0x13等（高4位=1表示场景模式）
适用场景：
- 场景触发（回家模式、离家模式等）
- 一键全开/全关
- 需要状态指示的场景按钮
技术特点：
- 使用REPORT协议（0x04）发送LED反馈
- 使用原始设备地址确保LED精确反馈
- 支持物理按键和Home Assistant远程控制
- 200ms防抖，避免重复触发
- 自动识别场景模式（根据操作信息高4位判断）

两种模式对比：

| 特性 | 开关按钮 | 场景按钮 | |------|---------|---------| | 控制方式 | 开/关独立 | Toggle切换 | | 操作信息 | 0x00/0x01 | 0x11/0x12/0x13等 | | LED反馈协议 | SET (0x03) | REPORT (0x04) | | 按键事件 | 独立开/关码 | 统一触发码 | | LED同步 | ✓ 完美同步 | ✓ 完美同步 | | HA远程控制 | ✓ 支持 | ✓ 支持 | | 推荐场景 | 灯光/插座 | 场景触发 | | 自动识别 | ✓ 支持 | ✓ 支持 |

配置说明：

RS-485连接：选择串口配置节点（波特率9600，8N1）
MQTT服务器（可选）：
- 本地模式：不启用MQTT，主站和从站通过内部事件自动通信（免连线）
- MQTT模式：启用MQTT并选择MQTT配置节点
面板配置：
- 面板品牌：选择亖米（Symi）
- 按钮类型：开关按钮或场景按钮（也可自动识别）
- 开关ID：物理面板的RS-485地址（0-255）
- 按钮编号：面板上的按键序号（1-8）
继电器映射：
- 从站地址：Modbus继电器地址（10-247）
- 继电器路数：继电器通道（1-32路）

使用示例：

示例1：客厅灯光开关（本地模式）

面板：开关ID=2，按键1（开关按钮）
继电器：从站10，1路
配置：不启用MQTT，主站和从站自动通信（免连线）
效果：按下面板按键，客厅灯开/关，面板LED同步状态，断网也能正常工作

示例2：全开场景（MQTT模式）

面板：开关ID=2，按键8（场景按钮）
继电器：从站10，32路
配置：启用MQTT，连接到Home Assistant
效果：按下面板按键，触发全开场景，HA中可远程控制，面板LED同步状态

示例3：三键场景开关（本地模式）

面板：开关ID=1，按键1/2/3（场景按钮，自动识别）
继电器：从站10，1/2/3路
配置：不启用MQTT，主站和从站自动通信（免连线）
效果：按下按键1/2/3，分别控制对应继电器，LED指示灯同步状态

智能轮询机制

主站轮询时，从站开关可以同时使用。当从站开关上报数据到服务器后：

自动暂停轮询：主站检测到写入操作，立即暂停轮询
优先处理数据：处理从站上报的数据（写入Modbus继电器）
继续轮询：数据处理完成后（100ms延迟），自动恢复轮询
日志记录：记录轮询暂停时长和跳过的轮询次数

这种机制确保：

主站轮询不会与从站写入冲突
从站上报的数据得到优先处理
系统响应迅速，状态同步及时

总线数据过滤与稳定性

本节点具备完善的总线数据过滤机制，确保长期稳定运行：

数据过滤机制：

CRC校验：所有Symi协议帧都经过CRC8校验，无效数据自动丢弃
静默忽略：总线上的非相关数据（其他设备、其他协议）静默忽略，不影响正常通信
精确匹配：只处理本节点配置的从站地址和线圈范围内的数据
TCP粘包处理：TCP模式下自动处理粘包和分包问题，确保数据完整性

稳定性保障：

写入队列：多个节点同时写入时自动排队，避免并发冲突
断线重连：TCP和串口断线后自动重连，指数退避策略（最大60秒）
内存管理：定时清理缓存，防止内存泄漏
错误日志限流：避免日志刷屏影响性能
MQTT独立性：MQTT开启或关闭都不影响主站和从站的本地通信

网络适应性：

离线通信：串口模式完全脱离网络依赖，断网也能正常工作
TCP稳定性：TCP模式支持局域网通信，网络恢复后自动重连
MQTT可选：MQTT仅用于对接第三方平台，不影响本地控制

调试节点（modbus-debug）

用于抓取并显示原始RS485字节流数据（HEX），帮助定位串口或TCP网关下的Modbus通信问题。

数据来源：
- 共享连接：serial-port-config（推荐，复用主站/从站的同一连接）
- 独立连接：modbus-server-config（直接连接TCP或串口）
输出内容：
- msg.payload：格式化的HEX字符串（可选大写）
- msg.buffer：原始Buffer数据
- msg.meta：来源信息与连接参数（串口或TCP详情）
- msg.timestamp：时间戳（可选）
显示控制：
- maxBytes：限制显示字节数，超过会截断并在meta.truncated标记

使用步骤：

将 modbus-debug 节点拖入画布。
选择“数据来源”：
- 选“共享串口配置（serial-port-config）”以复用主站/从站连接；或
- 选“Modbus服务器（modbus-server-config）”进行独立直连。
可选：勾选“大写HEX”、勾选“时间戳”、设置“最大字节数”。
部署后，节点自动输出捕获到的原始数据。

典型用法：

联调TCP转RS485网关时，观察上行/下行原始数据帧是否完整。
排查波特率/数据位/校验位配置是否正确（串口模式）。
与 modbus-master 或 modbus-slave-switch 同时使用，定位现场设备通信异常。

MQTT自动发现

启用MQTT后，自动生成Home Assistant兼容的Discovery配置：

唯一性保证：每个实体使用稳定的unique_id，避免重复生成
设备分组：同一从站的所有继电器自动分组到一个设备下
状态持久化：使用retain=true确保状态持久化
在线状态：自动发布设备可用性状态

配置持久化

所有节点配置自动保存到Node-RED的flows文件中：

从站地址、线圈范围、轮询间隔
MQTT服务器配置
开关面板映射关系

部署后配置永久生效，重启Node-RED后自动恢复。

长期稳定运行

针对工控机24/7长期运行优化：

内存管理：自动清理缓存，释放无用对象
事件监听器清理：关闭时移除所有监听器，防止内存泄漏
智能日志限流：错误日志10分钟输出一次，避免日志刷屏
智能重连机制：
- Modbus连接断开自动重连（指数退避：5秒→10秒→20秒...最大60秒）
- MQTT连接断开自动重连（支持多地址fallback）
- 串口拔插自动检测并重连
- TCP网络故障自动恢复
- 连接前彻底清理旧实例，避免资源泄漏
互斥锁机制：防止读写冲突导致的数据异常
TCP永久连接：
- 禁用TCP超时（永久连接），避免无数据时超时断开
- Keep-Alive心跳10秒间隔，确保连接活跃
- 适应客户长期不在家、总线无数据的场景
- 网络故障自动重连，恢复后立即恢复通信

技术规格

Modbus协议

协议类型：Modbus TCP / Modbus RTU
底层库：modbus-serial ^8.0.23（内部封装serialport，支持TCP和串口）
功能码支持：0x01（读线圈）、0x05（写单个线圈）、0x0F（写多个线圈）
从站地址范围：1-247（建议从10开始）
线圈数量：每台设备32个（0-31）
最大设备数：10台同时轮询
轮询间隔：默认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 / EMQX / Any MQTT 3.1.1/5.0
Home Assistant: 2024.x+（MQTT Discovery标准）
操作系统: Windows / Linux / macOS / HassOS

Home Assistant集成

自动发现

启用MQTT后，设备自动出现在Home Assistant中：

实体ID: switch.relay_{从站地址}_{线圈编号}
设备名称: Modbus继电器-{从站地址}
自动分组: 同一从站的所有继电器分组到一个设备

MQTT主题结构

状态主题: modbus/relay/{从站}/{线圈}/state
命令主题: modbus/relay/{从站}/{线圈}/set
可用性主题: modbus/relay/{从站}/availability
发现主题: homeassistant/switch/modbus_relay_{从站}_{线圈}/config

故障排除

串口连接失败

Linux:

# 查看串口设备
ls -l /dev/ttyUSB* /dev/ttyS*

# 添加用户到dialout组（需要重新登录）
sudo usermod -a -G dialout $USER

macOS:

# 查看串口设备（注意macOS使用cu.*而不是tty.*）
ls -l /dev/cu.*

Docker/HassOS:

# 在docker-compose.yml或HassOS插件配置中添加设备映射
devices:
  - /dev/ttyUSB0:/dev/ttyUSB0

MQTT连接失败

确认MQTT broker正在运行：

# Linux
sudo systemctl status mosquitto
   
# macOS
brew services list | grep mosquitto

测试MQTT连接：
```
mosquitto_sub -h localhost -t test
```
检查Node-RED日志中的MQTT连接信息

主站轮询不工作

检查从站配置：确认已添加所有从站设备（如10、11、12、13）
检查轮询间隔：默认200ms，建议300-500ms（多台从站时避免总线拥堵）
查看Node-RED调试日志：部署后查看日志中的轮询信息
检查串口波特率：确认波特率为9600（与从站设备一致）
检查从站地址：确认从站地址正确（1-247）

轮询超时或频繁报错

轮询永不停止原则：
- 即使从站不响应，轮询也会持续运行
- 不会因超时而跳过任何从站
- 只记录错误日志，不影响总线轮询机制
正常超时：偶尔超时是正常的，系统会自动重试
- 超时设置：2-3秒（串口/TCP）
- 只记录日志，不停止轮询
- 轮询会持续运行，不受超时影响
频繁超时：
- 检查Modbus连接是否稳定
- 调整轮询间隔（默认200ms，可增加到500ms）
- 检查从站设备是否在线
- 查看总线是否有其他设备干扰
总线干扰：
- 总线上的其他数据（如Symi网关通信、其他Modbus设备）可能导致偶尔超时或CRC错误
- 系统已优化容错机制，会自动忽略异常数据并继续轮询
- 非超时错误（如CRC错误）不累积计数，只记录日志
长期稳定性保障：
- 轮询循环采用try-catch包裹，确保异常不会中断轮询
- 每1000轮输出一次调试日志，证明轮询持续运行
- 定时清理机制（每小时）防止内存泄漏
- 所有定时器在节点关闭时正确清除

总线上出现未知数据

识别数据来源：
- 使用modbus-debug节点监听总线数据（必须使用共享的serial-port-config，避免串口冲突）
- 查看Node-RED日志中的"写入线圈"日志，确认是否是本节点发送的
- 检查是否有其他Modbus设备或Symi网关在总线上通信
常见数据格式：
- 01 05 00 01 FF 00 ...：写单个线圈（功能码0x05）
- 01 0F 00 00 00 20 ...：写多个线圈（功能码0x0F）
- 7E 01 03 ...：Symi轻量级协议数据
影响：
- 总线上的其他数据不会影响轮询稳定性
- 可能导致偶尔的CRC错误或超时，但系统会自动忽略并继续轮询

串口冲突错误

错误信息：

串口监听错误: Port is not open
串口监听错误: Error Resource temporarily unavailable Cannot lock port

原因：

多个节点试图独立打开同一个串口
串口只能被一个进程同时打开

解决方案：

modbus-debug节点：必须使用"serial"源类型，选择共享的serial-port-config配置节点
不要使用独立连接：不要让多个节点独立打开同一个串口
共享连接配置：所有节点（主站、从站开关、modbus-debug）都应该使用同一个serial-port-config配置节点

批量更换连接配置

问题：如何批量更换所有节点的RS-485连接配置？

Node-RED原生方法（推荐）：

创建新的serial-port-config配置节点
点击右上角菜单 → 配置节点
找到旧的serial-port-config配置节点
点击删除按钮
Node-RED会提示"此配置节点被X个节点使用，是否替换为其他配置？"
选择新创建的配置节点
点击确认，所有使用旧配置的节点会自动更换为新配置

注意：

这是Node-RED的原生功能，安全可靠
删除配置节点前必须先创建新配置
替换后需要部署才能生效

确认从站设备在线：使用Modbus调试工具测试从站是否响应
检查MQTT连接：确保MQTT broker地址正确，轮询不依赖MQTT但状态发布需要MQTT
测试连接：
- TCP连接问题：先用 modbus-serial 单独测试TCP连接
- 串口问题：先用 serialport 单独测试串口通信

从站开关无响应

检查免连线通信（v2.6.7+推荐）：
- 无需连线：主站和从站通过内部事件自动通信，无需手动连线
- 查看Node-RED日志，确认是否有"内部事件模式：发送命令到从站X 线圈Y"的日志
- 查看主站节点日志，确认是否有"收到内部事件：从站X 线圈Y"的日志
- 查看主站节点日志，确认是否有"内部事件写入成功，已广播状态变化"的日志
- 查看从站开关节点日志，确认是否有"收到状态变化事件"和"LED反馈已发送"的日志
检查RS-485连接：
- 确认RS-485连接配置正确（串口路径、波特率等）
- 查看节点状态显示是否为"MQTT未启用 - 使用内部事件模式"
- 物理面板连接：确认物理面板连接到正确的RS-485总线（TCP或串口）
检查开关面板配置：
- 确认开关面板地址和按钮编号正确
- 场景模式开关：操作信息为0x11、0x12、0x13等（高4位=1）
- 开关模式开关：操作信息为0x00（关）或0x01（开）
检查继电器映射：
- 确认目标从站地址和线圈编号正确
- 线圈编号范围：0-31（对应用户输入的1-32路）
查看调试日志：
- 使用modbus-debug节点抓取原始总线数据
- 查看Node-RED日志中的协议解析信息
- 确认按键事件是否被正确识别
- 确认LED反馈协议帧是否正确发送（查看日志中的HEX字符串）

输入消息格式

主站节点

// 启动轮询
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]  // 线圈值数组
};

从站开关节点

// 发送开关命令
msg.payload = true;   // 或 false
msg.payload = "ON";   // 或 "OFF"
msg.payload = 1;      // 或 0

HomeKit网桥节点

HomeKit网桥节点无需输入消息，自动同步主站配置和状态。

配置参数：

主站节点：选择要桥接的Modbus主站节点（必填）
网桥名称：在HomeKit中显示的网桥名称（默认：Modbus继电器网桥）
MAC地址：HomeKit网桥的唯一标识符（自动生成，无需修改）
配对码：HomeKit配对时使用的PIN码（格式：XXX-XX-XXX，默认：031-45-154）
端口：HomeKit网桥监听端口（默认：51828）
继电器名称配置：为每个继电器配置友好的中文名称（可选）

自动同步规则：

自动读取主站节点配置的所有从站和线圈
线圈0-15（1-16路）：创建为开关（Switch）配件
线圈16-31（17-32路）：创建为插座（Outlet）配件
监听主站的状态变化事件，实时同步到HomeKit
接收HomeKit控制命令，发送到主站执行

使用示例：

在Node-RED中配置好主站节点和从站
添加HomeKit网桥节点，选择主站节点
为每个继电器配置友好的名称（例如：客厅灯、卧室灯）
部署流程
在iPhone的"家庭"App中添加配件，输入配对码
完成配对后，即可在HomeKit中控制继电器，支持Siri语音控制

注意事项：

确保主站节点已正确配置并运行
配对码格式必须为XXX-XX-XXX（8位数字）
端口不能与其他服务冲突（默认51828）
配置信息持久化存储在~/.node-red/homekit-persist目录
重启Node-RED后自动恢复配对状态，无需重新配对

控制看板节点（客户友好模式）

控制看板节点提供可视化界面，实时显示和控制所有从站的继电器状态，适合现场调试和日常监控。

配置参数：

节点名称：控制看板的显示名称（默认：Modbus控制看板）
主站节点：选择要监控的Modbus主站节点（必填）

功能特性：

实时状态显示：在配置界面中显示所有从站和线圈的实时状态
一键控制：点击按钮即可控制继电器开关，无需部署流程
美观布局：网格布局，按从站分组显示，一目了然
名称同步：自动同步HomeKit网桥配置的继电器名称
快速响应：状态实时更新（500ms轮询），响应迅速
零开销：不参与实际Modbus通信，不影响主站性能

使用步骤：

在Node-RED中添加控制看板节点
选择已配置的Modbus主站节点
双击节点打开配置界面，即可看到所有继电器状态
点击按钮即可控制继电器开关（绿色=ON，红色=OFF）
部署流程后，节点会显示"监控中"状态

使用场景：

现场调试：快速测试继电器是否正常工作
日常监控：实时查看所有继电器状态
批量控制：快速控制多个继电器
客户演示：美观的界面，适合向客户展示系统功能

技术细节：

使用HTTP API与主站通信，通过内部事件发送控制命令
状态缓存机制，减少网络请求
仅在配置界面打开时才轮询状态，关闭后自动停止
与HomeKit网桥共享继电器名称配置，保持一致性

注意事项：

确保主站节点已正确配置并运行
控制看板只在配置界面打开时才轮询状态
继电器名称需在HomeKit网桥节点中配置
本节点不参与实际Modbus通信，不会增加主站负担

自定义协议节点

用于控制非标准Modbus协议的485设备（如窗帘、特殊开关等）。

配置步骤：

添加自定义协议节点到流程画布
选择设备类型（开关/窗帘/其他）
选择串口配置节点
输入16进制指令（空格分隔，自动格式化为大写）
- 打开指令：例如 01 05 00 00 FF 00 8C 3A
- 关闭指令：例如 01 05 00 00 00 00 CD CA
- 暂停指令：仅窗帘模式需要，例如 01 05 00 01 FF 00 DD FA
点击"测试"按钮验证指令是否正确发送
连线：从站开关 → 自定义协议节点
部署流程

设备类型说明：

开关模式：收到true发送打开指令，收到false发送关闭指令
窗帘模式：每次触发循环发送下一个指令（打开 → 暂停 → 关闭 → 暂停 → 打开...）
其他模式：与开关模式相同

使用场景：

窗帘控制：支持打开/暂停/关闭循环控制
特殊开关：非标准Modbus协议的485设备
自定义设备：任何需要发送固定16进制指令的设备

注意事项：

每个指令最多48字节
窗帘模式需配置三个指令（打开、关闭、暂停）
测试功能需先选择串口配置
无需连线到debug节点，直接通过串口配置节点发送数据

输出消息格式

主站节点

{
    payload: {
        slave: 10,                // 从站地址
        coils: [true, false, ...], // 线圈状态数组
        timestamp: 1234567890     // 时间戳
    }
}

从站开关节点

{
    payload: true,                    // 开关状态
    topic: "switch_0_btn1",          // 主题
    switchId: 0,                     // 开关面板ID
    button: 1,                       // 按钮编号
    targetSlave: 10,                 // 目标从站地址
    targetCoil: 0                    // 目标线圈编号
}

性能指标

内存占用：< 50MB（单个主站节点，轮询10个设备）
CPU占用：< 5%（正常轮询状态）
连接延迟：Modbus响应 < 100ms，MQTT发布 < 50ms
稳定运行：经过工控机7x24小时长期运行验证
容错能力：Modbus从站离线不影响其他从站，MQTT断线自动重连

示例Flow

[
    {
        "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"
    }
]

完整示例请参考项目中的 examples/basic-flow.json 文件。

技术栈

Node.js: >=14.0.0
Node-RED: >=2.0.0
modbus-serial: ^8.0.23
serialport: ^12.0.0
mqtt: ^5.14.1（可选）
hap-nodejs: ^1.2.0
node-persist: ^4.0.4

版本信息

当前版本: v2.9.5 (2025-12-15)

v2.9.5 更新内容：

重要修复：重启Node-RED时设备自动动作问题
- 修复重启后继电器会自动动作一次的bug
- 问题根因：首次轮询（source='init'）时modbus-slave-switch向下游发送状态消息，触发下游节点执行控制命令
- 解决方案：首次轮询时只同步内部状态和LED反馈，不发送消息到下游节点
- 现在重启Node-RED不会导致任何继电器动作，只会同步指示灯状态

v2.9.4 更新内容：

重要修复：场景按钮LED反馈不同步问题
- 修复场景按钮按下后背光灯不跟随继电器状态变化的bug
- 问题根因：场景模式下currentState提前更新，导致后续状态变化事件被认为"未变化"而跳过LED反馈
- 解决方案：场景按钮触发时立即发送LED反馈，不等待状态变化事件
新功能：按键背光灯选项
- 在按钮编号下拉框中新增"按键背光灯"选项（通道0x0F）
- 用于红外感应触发背光灯的联动控制
- 未选择此选项时，红外感应帧会被正确忽略，避免误触发

核心特性：

支持Modbus RTU/TCP协议，兼容标准Modbus设备和TCP转RS485网关
支持Symi RS-485开关和蓝牙Mesh开关，实现双向状态同步
支持Mesh开关无线模式（场景触发按键不响应LED反馈）
内置HomeKit网桥，支持Siri语音控制
可视化控制看板，实时显示和控制所有继电器状态
智能写入队列，支持大规模批量控制（160+继电器）流畅无卡顿
完整的内存管理和错误处理，适合7x24小时长期稳定运行

Mesh开关LED反馈机制：

按键触发：100ms内完成控制和LED反馈，响应迅速
继电器控制：100ms防抖，智能合并多次状态变化后发送一次LED反馈
全控场景：无论多少个继电器同时变化，只发送一次LED反馈，包含所有按钮的最新状态
无线模式：勾选无线模式的按键不响应LED反馈，适用于场景触发按键
全局锁定：LED反馈发送期间（100ms），忽略所有Mesh面板的状态上报，避免误触发

稳定性保障：

连接永久保持：串口/TCP连接一旦建立就保持打开，避免部署时频繁开关导致的锁定问题
内存泄漏防护：每5分钟自动检查并清理异常积压数据
日志防护：错误日志限流，避免硬盘被填满
配置持久化：所有配置和Mesh设备列表自动保存，重启后自动恢复
断网/断电不影响：本地模式下完全脱离网络依赖
RS-485独立运行：RS-485开关功能完全独立，不受Mesh功能影响

实际使用场景：

主站轮询：200ms/台，支持5-10台从站设备
开关面板：支持50个以内Mesh面板，约200个按钮
LED同步：部署/重启后1秒内完成所有LED状态同步
批量控制：支持全开/全关等批量操作，LED反馈流畅无卡顿
多面板支持：100个面板同时LED反馈仅需4秒（40ms间隔×100）
场景触发：支持无线模式按键，不受LED反馈影响

许可证

MIT License

支持与反馈

GitHub: https://github.com/symi-daguo/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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

node-red-contrib-symi-modbus

核心特性

快速开始

1. 安装

2. 选择运行模式

模式1：本地模式（推荐用于纯串口控制）

模式2：MQTT模式（推荐用于Home Assistant集成）

3. 配置主站节点

4. 配置RS-485连接配置节点（用于从站开关）

5. 配置从站开关节点（可选）

模式1：RS-485开关模式（传统有线开关）

模式2：RS-485场景模式（场景触发）

模式3：Mesh开关模式（蓝牙Mesh无线开关）

6. 配置HomeKit网桥节点（可选）

核心特性说明

Symi开关自动识别

方式1：Modbus RTU轮询（标准）

方式2：Symi私有协议（自动）

智能轮询机制

总线数据过滤与稳定性

调试节点（modbus-debug）

MQTT自动发现

配置持久化

长期稳定运行

技术规格

Modbus协议

兼容性

Home Assistant集成

自动发现

MQTT主题结构

故障排除

串口连接失败

MQTT连接失败

主站轮询不工作

轮询超时或频繁报错

总线上出现未知数据

串口冲突错误

批量更换连接配置

从站开关无响应

输入消息格式

主站节点

从站开关节点

HomeKit网桥节点

控制看板节点（客户友好模式）

自定义协议节点

输出消息格式

主站节点

从站开关节点

性能指标

示例Flow

技术栈

版本信息

许可证

支持与反馈