node-red-contrib-modbus

Node-RED 的一体化 Modbus TCP 和串口贡献包

公共 LTS 版本： v5.x（当前：5.60.0） · 许可证 BSD-3-Clause · 仓库：GitHub

如果您喜欢这个包，请在 GitHub 上给我们一个星标。

要求

	最低要求
Node.js	`>= 22` (`package.json` engines)
Node-RED	`>= 4` (`node-red.version`)
安装	Palette Manager 或 `npm install node-red-contrib-modbus`

旧版 Node.js / Node-RED 组合：请参阅 HISTORY.md 中的历史记录。建议在此发布系列中继续使用当前 LTS 版本的 Node.js。

包内包含内容 (v5)

TCP / 串口 Modbus 客户端 节点，以及包内自带的 缓冲 Modbus TCP 服务器，用于演示和测试。

调色板节点	角色
Modbus-Client	配置：TCP 或串口，队列，重连 (XState FSM)
Modbus-Read	周期性 FC1–4 轮询
Modbus-Getter	按需 FC1–4 读取
Modbus-Flex-Getter	基于负载的 FC1–4 读取
Modbus-Write	FC5 / 6 / 15 / 16 写入
Modbus-Flex-Write	基于负载的写入
Modbus-Flex-Sequencer	有序多范围读取
Modbus-Flex-FC	自定义 FC 映射 (`extras/argumentMaps`)
Modbus-Flex-Connector	运行时重连 / 端点切换
Modbus-Queue-Info	客户端队列深度 / 重置
Modbus-Response	响应状态显示
Modbus-IO-Config	命名 IO JSON 映射
Modbus-Response-Filter	按名称过滤 IO 负载
Modbus-Server	基于缓冲的 TCP 从站 (jsmodbus)

v5 中不包含： TLS 客户端 (Modbus-Client-TLS 属于 v6)，基于流的动态请求/响应网关 (#567 → 建议作为独立包)，modbus-flex-server (独立包 — 见下文)。

自 5.46 以来的亮点 / 5.50.0 中的内容

客户端 FSM / 重连 / 队列 加固 (自 5.46.x 起)
更安全的 unit ID 处理 (unitId / unitid，包括 unit 0)
Modbus 地址/数量验证改进
编号 学习示例 01…15 + 学习路径文档
需要 Node-RED >= 4 和 Node.js >= 22

请参阅 CHANGELOG.md 获取完整列表。

如何使用 / 学习路径

推荐： 使用包内的编号学习示例（01 … 15）。

安装此包并重启 Node-RED。
打开 菜单 → 导入 → 示例 → node-red-contrib-modbus。
按顺序处理这些流（或跳转到单个节点教程）。

文档	内容
学习路径指南	阶段，Modbus 速查表，节点 ↔ 示例映射
示例索引	完整文件列表，TCP 端口，IO 路径，旧→新映射
文档中心	所有文档入口

每个示例选项卡都有一个英文注释节点，包含运行说明。节点侧边栏帮助指向匹配的示例文件名。

学习…	导入示例
Modbus 寄存器 & FCs	`01-Modbus-Basics-Registers-And-FCs`
第一个 TCP 客户端 + 服务器	`02-Getting-Started-Client-And-Server`
轮询 / 按需 / 灵活读写	`03` … `06`
顺序器，Flex-FC，连接器，队列，IO	`07` … `11`
缓冲区服务器 & 模式（HTTP，串口，网关）	`12` … `15`

另见：Wiki / DEBUG · YouTube 播放列表 · Leanpub Modbus 书籍 · 可选的旧流在 flows.nodered.org

Flow Example

安装

在你的 Node-RED 用户目录中（通常为 ~/.node-red）：

npm install node-red-contrib-modbus

全局（较少见）：

npm install -g node-red-contrib-modbus

如果原生模块构建失败：

npm install node-red-contrib-modbus --unsafe-perm --build-from-source

列出已发布的版本：

npm show node-red-contrib-modbus versions

安装特定版本（示例）：

npm install node-red-contrib-modbus@5.45.2

运行时库

包	在此 contrib 中的角色
`@openp4nr/modbus-serial`	Modbus 客户端 I/O（TCP / 串口 / ASCII 等）
`jsmodbus`	包内 Modbus-Server（缓冲从站）
`@xstate/fsm`	客户端连接状态机
`serialport` / `@serialport/list`	可选 — 在 UI 中列出串口（非运行时 Modbus 栈）

如果 TCP 失败，请先使用普通的 Modbus 客户端验证连接性。如果串口失败，请先使用 serialport 验证端口。

日志记录使用 debug 包（而非 winston — winston 是 v6 的方向）：

DEBUG=contribModbus*,modbus-serial node-red -v

更多选项：Wiki DEBUG。

Modbus Flex Server（独立软件包）

Modbus-Flex-Server 已从本软件包中移出（vm2 / 维护边界）。如果仍需要它，请安装专用的 contrib。进一步的软件包拆分（客户端与服务器）仍是 v6 架构的长期议题；v5 在本软件包中保留 Modbus-Server 作为演示和测试的缓冲从站。

P4NR B2B 社区

P4NR B2B 社区（由 Iniationware 驱动）支持围绕 Node-RED 的 Modbus 开发与商业支持。Bianco Royal 与 P4NR 合作。

Leanpub 在线书籍

在线 Leanpub 书籍深入介绍了 v5.x 节点和选项（“一次购买，永久更新”）。要在此仓库中免费入门，请使用 学习路径。

错误与状态

从 v5.22 开始，客户端和服务器节点会捕获许多网络和协议错误，因此 Node-RED 不应因这些已处理的情况而崩溃。请始终关注您的流程中的 node status、Catch 节点以及可选的 empty-msg-on-fail 设置。

贡献

欢迎贡献者。请 Fork 仓库并向 develop 提交 PR（或通过 issues 讨论）。对于较大的功能，请参阅 docs/p4nr/ 下的维护者流水线。

有用的脚本（参见 package.json）：

npm run build          # lint + gulp → modbus/
npm test               # Mocha (parallel)
npm run test:units
npm run coverage
npm run dev-link       # local link into Node-RED