联犀开发者文档

Modbus协议接入

约 1570 字大约 5 分钟

设备接入第三方协议Modbus工业协议

2026-08-20

简介

Modbus 是工业领域应用最广泛的通信协议之一，联犀平台通过 modbus 协议网关适配各类 Modbus 设备（电表、水表、传感器、PLC 等），支持 TCP/IP、UDP/IP、RTU over TCP/IP、RTU over UDP/IP 四种传输模式。

核心能力：平台提供「点位映射编辑器」，将 Modbus 寄存器/线圈地址与物模型属性一一对应，无需编写任何代码即可完成设备接入与数据采集。

应用场景

  • 工业设备采集：电表、水表、气表、温度传感器等 Modbus 从站设备的数据采集
  • 多模式传输：支持串口 RTU、以太网 TCP/UDP、RTU over TCP 等多种组网方式
  • 按位读取：bool 类型属性可指定寄存器内的位偏移读取
  • 定时轮询：按配置的采集周期自动轮询所有启用点位

前置条件

  1. 协议容器已部署：protocol-modbus 容器运行正常
  2. 设备可达：Modbus 从站设备 TCP/UDP 端口或串口可被协议容器访问
  3. 产品已创建：产品传输协议选择 MQTT，协议类型选择 modbus

产品配置

1. 创建产品

创建产品时选择协议 modbus（传输协议 MQTT），创建后进入产品详情。

2. 物模型配置

配置产品的物模型属性（如电压、电流、温度等），每个属性对应一个 Modbus 点位。

3. 点位映射（重点）

进入产品详情「设备接入」Tab，打开点位映射编辑器：

Modbus 产品点位映射

编辑器包含启用、物模型属性、寄存器地址、寄存器类型、数据类型、起始位、位长、字符串长度、字节交换、字交换、多寄存器写等字段。为需要采集的物模型属性「启用」并配置 Modbus 点位参数：

字段说明
identifier物模型属性标识符（只读，来自物模型）
enabled启用开关，仅启用的点位参与轮询采集
address寄存器/线圈起始地址（0 是合法地址，即第一个寄存器）
registerType寄存器类型：COIL 线圈 / DISCRETE_INPUT 离散输入 / INPUT_REGISTER 输入寄存器 / HOLDING_REGISTER 保持寄存器
valueType数据类型（uint16/int16/uint32/float32/string 等），按物模型属性类型自动建议
bit / bitLen位读取（bool 属性）：起始位 + 连续位长度
strLen字符串长度（string 类型点位）
byteSwap / wordSwap字节交换 / 字交换（大小端处理）
multiWrite是否支持多寄存器写（默认 true）

默认勾选与使用说明（与配置页顶部说明一致）：

  • 「启用」默认不勾选：未启用的属性不参与轮询采集，保存时也不写入产品协议配置
  • 「字节交换 / 字交换」默认不勾选：即标准大端序，仅设备为小端/字序交换时才勾选
  • 「多寄存器写」默认勾选：多数设备的写操作要求多寄存器写
  • 寄存器地址从 0 开始，0 是合法地址（第一个寄存器）；「全部不启用」按钮可将所有属性一键重置为不启用

功能码对应：

寄存器类型读功能码写功能码
COIL（线圈）0105/0F
DISCRETE_INPUT（离散输入）02-
INPUT_REGISTER（输入寄存器）04-
HOLDING_REGISTER（保持寄存器）0306/10

冲突校验：多个启用的点位地址+寄存器类型重复会冲突，保存时校验并提示。

保存点位时，仅启用的点位写入产品协议配置 protocolConf.points；未配置的属性走旧版物模型扩展配置（extendConfig）回退读取。

设备接入

1. 创建设备

在产品下创建设备，进入设备详情「设备接入」Tab，配置连接参数：

Modbus 设备接入连接参数

连接参数表单包含地址 address、连接模式 mode、波特率 baudRate、数据位 dataBits、停止位 stopBits、校验 parity、请求超时 timeout、采集周期 duration，并提供「连通测试」「保存」按钮。

2. 连接参数

参数说明默认值
address设备地址（Modbus 从站地址）-
mode连接模式：rtuovertcp / rtuoverudp / rtu（串口）/ tcp / tcp+tls / udptcp
baudRate波特率（仅串口）19200
dataBits数据位（仅串口）8
stopBits停止位（仅串口）1
parity校验（仅串口）：0无 / 1偶 / 2奇0
timeout请求超时（毫秒）1000
duration采集周期（毫秒）10000

3. 连通测试

配置页提供「连通测试」按钮，以当前表单参数调用协议自有接口，验证与设备的 TCP/串口连通性。

技术方案

接入架构

Modbus 从站设备 ──TCP/UDP/RTU──> protocol-modbus 容器 ──MQTT──> 联犀平台
  1. 协议容器按 duration 采集周期轮询所有启用点位（ReadDev 遍历 Point 数组）
  2. 按点位 registerType 映射功能码读取寄存器（RegMap：HOLDING/INPUT → 读寄存器）
  3. 按 valueType/bit/byteSwap/wordSwap 解析原始值
  4. 解析结果按物模型属性 identifier 上报平台

数据流

  • 上行（采集）：定时轮询 → 读寄存器 → 解析 → 属性上报
  • 下行（控制）：平台下发 → 按 registerType 写线圈/寄存器（05/06/0F/10 功能码）

接入示例

1. 模拟器测试（无真实设备）

使用 modpoll 或任意 Modbus 模拟器：

# 启动 Modbus TCP 模拟器监听 5020 端口（模拟保持寄存器）
modpoll -m tcp -t 4:hex -r 0 -c 10 localhost

# 协议容器连接模拟器（设备 address=1, mode=tcp, address=模拟器IP:5020）

2. 真实设备

  • 确认设备 IP/端口、从站地址、寄存器地址与数据类型
  • 产品配置点位映射（寄存器类型 + 地址 + 数据类型）
  • 设备配置连接参数 + 连通测试
  • 等待采集周期，物模型属性出现数据

注意事项

  • 寄存器地址从 0 开始，0 是合法地址
  • 多个启用点位地址+类型重复会冲突，需调整
  • bool 属性用 bit/bitLen 按位读取（valueType 建议 uint16）
  • tcp+tls 模式需客户端证书，暂不支持页面配置
  • 串口模式（rtu）需正确配置波特率/数据位/停止位/校验

更新日志

2026/8/31 14:31
查看所有更新日志
  • 2fc1c-Merge #36 into master from docs/user-facing-cleanup于
  • eb33f-Merge #35 into master from docs/third-party-protocols-update于
  • 70dbb-Merge #34 into master from docs/third-party-protocols-update于
  • 4ab8f-Merge #25 into master from docs/third-party-protocols于