Modbus协议接入
简介
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 类型属性可指定寄存器内的位偏移读取
- 定时轮询：按配置的采集周期自动轮询所有启用点位
前置条件
- 协议容器已部署：
protocol-modbus容器运行正常 - 设备可达：Modbus 从站设备 TCP/UDP 端口或串口可被协议容器访问
- 产品已创建：产品传输协议选择
MQTT，协议类型选择modbus
产品配置
1. 创建产品
创建产品时选择协议 modbus（传输协议 MQTT），创建后进入产品详情。
2. 物模型配置
配置产品的物模型属性（如电压、电流、温度等），每个属性对应一个 Modbus 点位。
3. 点位映射（重点）
进入产品详情「设备接入」Tab，打开点位映射编辑器：
编辑器包含启用、物模型属性、寄存器地址、寄存器类型、数据类型、起始位、位长、字符串长度、字节交换、字交换、多寄存器写等字段。为需要采集的物模型属性「启用」并配置 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（线圈） | 01 | 05/0F |
| DISCRETE_INPUT（离散输入） | 02 | - |
| INPUT_REGISTER（输入寄存器） | 04 | - |
| HOLDING_REGISTER（保持寄存器） | 03 | 06/10 |
冲突校验：多个启用的点位地址+寄存器类型重复会冲突，保存时校验并提示。
保存点位时，仅启用的点位写入产品协议配置
protocolConf.points；未配置的属性走旧版物模型扩展配置（extendConfig）回退读取。
设备接入
1. 创建设备
在产品下创建设备，进入设备详情「设备接入」Tab，配置连接参数：
连接参数表单包含地址 address、连接模式 mode、波特率 baudRate、数据位 dataBits、停止位 stopBits、校验 parity、请求超时 timeout、采集周期 duration，并提供「连通测试」「保存」按钮。
2. 连接参数
| 参数 | 说明 | 默认值 |
|---|---|---|
address | 设备地址（Modbus 从站地址） | - |
mode | 连接模式：rtuovertcp / rtuoverudp / rtu（串口）/ tcp / tcp+tls / udp | tcp |
baudRate | 波特率（仅串口） | 19200 |
dataBits | 数据位（仅串口） | 8 |
stopBits | 停止位（仅串口） | 1 |
parity | 校验（仅串口）：0无 / 1偶 / 2奇 | 0 |
timeout | 请求超时（毫秒） | 1000 |
duration | 采集周期（毫秒） | 10000 |
3. 连通测试
配置页提供「连通测试」按钮，以当前表单参数调用协议自有接口，验证与设备的 TCP/串口连通性。
技术方案
接入架构
Modbus 从站设备 ──TCP/UDP/RTU──> protocol-modbus 容器 ──MQTT──> 联犀平台- 协议容器按
duration采集周期轮询所有启用点位（ReadDev遍历Point数组） - 按点位
registerType映射功能码读取寄存器（RegMap：HOLDING/INPUT → 读寄存器） - 按
valueType/bit/byteSwap/wordSwap解析原始值 - 解析结果按物模型属性
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 22:31
查看所有更新日志
2fc1c-于eb33f-于70dbb-于4ab8f-于
