Modbus 设备接入

名尚智联内置 Modbus 主站，支持 TCP（MBAP）和 RTU 两种传输模式，自动轮询寄存器并映射到物模型属性。

---

一、支持功能

传输	函数码	说明
TCP (MBAP)	1 线圈 / 2 离散量 / 3 保持寄存器 / 4 输入寄存器	主动轮询
RTU（经 TCP 透传串口服务器）	同 TCP	transport: RTU + 指定串口服务器
点位缩放	scale + offset	自动换算（如原始值 2560 → 温度 25.6℃）
数据类型	BOOL / INT16 / UINT16 / INT32_BE / INT32_LE / FLOAT_BE / FLOAT_LE / RAW	大小端自动处理
离线判定	连续 N 次采集失败	可配置 fail-tolerance

---

二、网关配置

2.1 application.yml

ms:
  modbus:
    enabled: true
    connect-timeout-ms: 3000
    request-timeout-ms: 3000
    gateways:
      - name: 一号车间网关
        serial: GW-MODBUS-001           # 需在 ms_device 中存在
        transport: TCP                   # TCP=MBAP；RTU=串口服务器
        host: 192.168.1.50
        port: 502
        unit-id: 1                      # RTU 从站地址
        interval-ms: 5000               # 采集周期
        fail-tolerance: 3               # 连续 N 次失败判离线
        points:
          - identifier: temperature      # 物模型属性标识
            function: 3                  # 3=保持寄存器
            address: 0
            quantity: 2                  # 2 个寄存器（FLOAT）
            data-type: FLOAT_BE          # 大端浮点数
            scale: 0.1                   # 原始值 × 0.1
            offset: -40                  # 再减 40
          - identifier: humidity
            function: 3
            address: 2
            quantity: 2
            data-type: FLOAT_BE
            scale: 0.1
            offset: 0

2.2 动态更新

网关配置可通过 REST API 热加载，无需重启后端：

# 查询所有网关
curl -H "Authorization: <token>" http://localhost:8080/api/modbus/gateways

# 重载配置
curl -X POST -H "Authorization: <token>" http://localhost:8080/api/modbus/reload

---

三、数据类型映射

data-type	长度	说明	示例原始值 → 实际值
BOOL	1 bit	布尔	1 → true
INT16	2 bytes	有符号 16 位	-1 → -1
UINT16	2 bytes	无符号 16 位	65535 → 65535
INT32_BE	4 bytes	大端有符号 32 位	0x00010000 → 65536
INT32_LE	4 bytes	小端有符号 32 位	0x00010000 → 256
FLOAT_BE	4 bytes	大端 IEEE 754	0x41C80000 → 25.0
FLOAT_LE	4 bytes	小端 IEEE 754	0x0000C841 → 25.0
RAW	可变	原始字节（hex）	→ "FF00"

---

四、scale + offset 计算

实际值 = 原始值 × scale + offset

典型场景：

寄存器	原始值	scale	offset	实际含义
温度	256	0.1	-40	-14.4℃（传感器偏移）
湿度	623	0.1	0	62.3% RH
电压	2200	0.1	0	220.0 V
电流	15	0.01	0	0.15 A

---

五、监控

5.1 采集日志

Redis Key：ms:modbus:{gatewaySerial}:{timestamp}

redis-cli -p 6380 LRANGE ms:modbus:GW-MODBUS-001 0 5
# → ["2026-10-17T20:00:00 temperature=25.6", "2026-10-17T19:59:55 temperature=25.5"]

5.2 设备状态

设备离线时自动标记 online=0，重新连上自动恢复。

---

六、常见问题

问题	排查
网关始终离线	检查 host:port 是否可达、unit-id 是否正确、防火墙是否放行 502
读取值异常	检查 data-type 大小端是否正确，FLOAT_BE vs FLOAT_LE
轮询过于频繁	调整 interval-ms，Modbus RTU 建议 ≥ 200ms
寄存器地址错	Modbus 地址有 0 起始 / 1 起始两种约定，注意核对