协议接入：Modbus / MQTT / OPC UA — 华芯智科开发者文档

Matrix · 协议对照

先按场景定协议，再按协议定周期

网关内置 30+ 工业规约库，常用的是下表八类。周期列是工程建议值，不是协议上限。

协议	典型场景	建议周期	网关侧驱动	容易踩的点
Modbus RTU	电表、仪表、变频器	1~5 s 轮询	`hy-collect modbus-rtu`	字序与量程缩放；单口 32 负载上限
Modbus TCP	PLC、边缘控制器	1~2 s	`hy-collect modbus-tcp`	并发会话数；断连后事务 ID 复用
OPC UA	上位机、DCS、MES	订阅 100~500 ms	`hy-collect opcua`	证书有效期 1 年；订阅数上限
MQTT	设备直连平台	事件驱动 / 30 s	内置（无需插件）	QoS 1 重复投递需幂等
DL/T 645	国网电表	15 min~1 h	`hy-collect dlt645`	1997 与 2007 规约要区分
CJ/T 188	水、气、热表	1 h~1 d	`hy-collect cjt188`	表号 BCD 编码，前导零不能丢
CAN FD	车载、BMS、储能	10~100 ms	`hy-canfd`	位率与采样点；终端电阻 120 Ω
CoAP	NB-IoT 微功耗终端	30 min~1 h	平台侧直连	UDP 重传窗口；报文 ≤1 KB 更稳

Modbus · 轮询与映射

轮询预算先算，再填点位表

串口采集的瓶颈是时间不是带宽。先算清一个周期内能不能把所有站轮一遍，再决定点位怎么分组。

/data/hy/collect/modbus-rtu.yaml现场配置

bus:
  port: /dev/ttyS3
  baudrate: 9600
  parity: none          # none / even / odd
  stopbits: 1
  timeout_ms: 300       # 单帧等待上限
  inter_frame_ms: 20    # 站间间隔
  retries: 2

poll_groups:
  - name: fast
    period_ms: 1000
    slaves:
      - id: 1
        reads:
          - {func: 03, addr: 0,   count: 10, type: u16,  scale: 0.1, unit: "C"}
          - {func: 03, addr: 20,  count: 2,  type: f32,  word_order: CDAB}
      - id: 2
        reads:
          - {func: 04, addr: 0,   count: 8,  type: u16,  scale: 0.01, unit: "MPa"}
  - name: slow
    period_ms: 30000
    slaves:
      - id: 5
        reads:
          - {func: 03, addr: 100, count: 32, type: u16, deadband: 0.5}

轮询预算怎么算

参数	9600 bps	19200 bps
单寄存器帧时间（含 3.5 字符静默）	≈ 2.3 ms	≈ 1.2 ms
读 10 寄存器往返（含从站处理）	25~40 ms	15~25 ms
单站预算（含站间间隔 20 ms）	≈ 60 ms	≈ 45 ms
1 s 周期可带站数	≤ 16	≤ 22

超预算的三个信号：① 日志出现连续 timeout；② 同一站点的值偶尔回退到上一周期；③ 丢点计数随时间累积。出现任一情况，先把慢周期点位分离到第二个组，而不是加大 retries。

board — 采集自检上线前

# 语法校验 + 试采集 30 秒（不写入平台）
hy-collect check --config /data/hy/collect/modbus-rtu.yaml
hy-collect probe --config /data/hy/collect/modbus-rtu.yaml --duration 30s

# 输出示例
# slave 1  ok  1000ms  rtt_p50 34ms  rtt_p95 41ms  errors 0
# slave 2  ok  1000ms  rtt_p50 29ms  rtt_p95 36ms  errors 0
# slave 5  WARN 30000ms rtt_p50 118ms rtt_p95 260ms errors 2 (timeout)

# 单点原始值比对（字序排障用）
hy-collect read --config /data/hy/collect/modbus-rtu.yaml \
  --slave 1 --func 03 --addr 20 --count 2 --raw

MQTT · 主题与 QoS

主题按约定生成，重复投递按 ID 消重

主题结构与 payload 规则与快速开始一致。这里补充弱网下的参数取值与幂等要求。

设备 → 平台 · 告警事件QoS 1

topic: <pk>/<dn>/event

{
  "event_id": "evt_20260911_0007",
  "code": "vib_over_limit",
  "level": "major",
  "ts": 1789012345678,
  "value": 4.6,
  "limit": 4.5,
  "duration_ms": 3200
}

# event_id 是幂等键：平台按它去重，
# 重复上报返回 409 duplicate_event，
# 设备侧应视为成功，不要无限重发。

平台 → 设备 · 指令与回执QoS 1 + 超时

topic: <pk>/<dn>/down
{
  "msg_id": "cmd_88f1",
  "action": "write_register",
  "target": {"slave": 1, "addr": 20, "value": 300},
  "timeout_s": 5
}

# 设备执行后必须回执，否则平台按超时重发
topic: <pk>/<dn>/ack
{"msg_id": "cmd_88f1", "code": 0, "cost_ms": 42}

# code 非 0 时附 reason 字段，便于批量统计失败原因

弱网参数	取值	理由
`keepalive`	60 s（弱网 120 s）	平台按 1.5 倍判离线，60 s 对应 90 s 发现延迟
重连退避	1→2→4→…→60 s，抖动 0~30%	避免整批设备同一时刻重连造成二次冲击
遗嘱消息	`<pk>/<dn>/status`，payload `{"online":false}`	异常断开时平台可立即标记离线
单包大小	≤ 4 KB	超过改批量主题或分段，减少弱网半包概率
会话保持	`clean_session=false`	短时断网期间下行指令不丢，重连后补发

OPC UA · 端点与订阅

能用订阅就不要轮询

OPC UA 的服务端本来就支持数据变化通知。走订阅可以把周期压到 100~500 ms，同时减少服务端压力。

/data/hy/collect/opcua.yamlSign & Encrypt

endpoint: opc.tcp://10.20.3.11:4840
security:
  policy: Basic256Sha256
  mode: SignAndEncrypt
  cert: /data/hy/certs/gw-line3.pem
  key: /data/hy/certs/gw-line3.key
  ca: /data/hy/certs/hy-ca.pem

subscription:
  publishing_interval_ms: 200
  lifetime_count: 60          # 3 次丢失即重建订阅
  keepalive_count: 20

nodes:
  - {node_id: "ns=2;s=Line3.Temp",  name: temp_c,  type: f32, scale: 1}
  - {node_id: "ns=2;s=Line3.State", name: run_state, type: u16, map: {1: running, 2: idle}}
  - {node_id: "ns=2;s=Line3.Counter", name: parts, type: u32, deadband: 0}

证书与账号

客户端证书有效期 1 年，平台侧签发；到期前 30 天产生告警，可在线续签。
用户名口令只用于首次信任建立，长期运行依赖证书双向校验。
节点映射表模板见资料中心 · 接线与组态模板，填完可直接导入。
服务端节点数量大（>5000）时，只订阅需要的节点，不整树浏览。

订阅 vs 轮询：服务端支持订阅就一律用订阅；只支持轮询的老服务端，单次读取节点数控制在 200 以内，周期不低于 1 s，否则服务端 CPU 会明显上升。

Mapping · 数据映射与时间

量程、死区、时间戳，三样都写进点位表

数据不准通常不是协议问题，而是这三样没有在点位表里定义清楚。点位表是现场与平台之间唯一的对照物。

SCALE

量程与单位

原始寄存器值必须带 scale 与 unit 两个字段，平台只存储换算后的工程值。

整数 ×0.1 与浮点两种口径不要混用
单位统一用 SI 写法：C、MPa、mm_s

DEADBAND

死区压缩

变化量小于死区就不上报，只在心跳周期补一个当前值。

温度类 0.2，压力类 0.5%FS，振动类 0.05
实测弱网下带宽可节省 70% 以上

TIME

时间戳来源

遥测时间以设备侧采样时刻为准，平台接收时间另存一列，两者都保留。

NTP 对时，多路上行时间戳差应 <2 s
多传感器联动场景启用 PTP（IEEE 1588），对齐到毫秒

Offline · 断网缓存与补传

断网 72 小时零丢失是怎么做到的

本地先落盘、再上行；恢复后按时间顺序补传，并保持原始时间戳。这一节是现场最常问、也最容易漏配的部分。

环节	默认值	可调范围	说明
本地缓存时长	72 h	24~168 h	受 `/data` 可用空间限制，按点位量核算
缓存介质	SQLite（WAL 模式）	—	掉电不丢已提交记录；避免用内存队列
溢出策略	告警优先、最旧遥测先丢	固定	丢弃计数上报到平台，供对账
补传速率	正常速率的 2 倍	1~4 倍	避免恢复瞬间把链路打满
补传时间戳	保留原始采样时间	固定	平台按事件时间入库，不按接收时间
去重	按 `event_id` / 点位+时间戳	固定	重复补传不会产生重复点位

board — 缓存与补传状态现场排障

hy-collect cache status
#  pending 12,480 records / oldest 2026-09-08T02:14:07Z
#  size 38.2 MB / quota 512 MB  (used 7.5%)
#  dropped 0

hy-collect cache flush --rate 2x --watch
#  补传进度与失败原因实时打印；中断后再次执行从断点继续

REST API · 约定

分页、限流、重试与错误码

写集成代码前先看这一节，能省掉大部分「偶发失败」的排查。所有接口走 HTTPS 443，鉴权用 Bearer Token。

分页：limit 默认 100、上限 500；翻页用响应里的 next_cursor，不要用 offset 翻深页。
限流：每租户 200 QPS，突发 400；超限返回 429 并带 Retry-After（秒）。
重试：只重试 429、502、503、504；退避 1→2→4 s，最多 3 次。写操作必须带 Idempotency-Key。
超时：客户端连接超时 3 s、读超时 10 s；批量导出类接口用异步任务 + 轮询结果。
逐页变更：破坏性变更提前 90 天公告，新旧版本并行 180 天；字段新增不视为破坏性变更。

错误码	HTTP	含义	处置
`invalid_payload`	400	JSON 不合法或字段类型不符	本地用 `jq .` 校验后再发
`unauthorized`	401	Token 缺失或过期（有效期 90 天）	重新签发 Token
`device_disabled`	403	设备被禁用或已注销	控制台启用设备；注销不可逆
`device_not_found`	404	三要素不匹配	核对 ProductKey / DeviceName
`duplicate_event`	409	`event_id` 已存在（幂等命中）	视为成功，不重试
`rate_limited`	429	超出限流	按 `Retry-After` 退避
`backend_busy`	503	后端繁忙（滚动升级期间可能出现）	指数退避重试 ≤3 次

Next · 下一步

点位通了之后

傍晚的工位上，工程师把一根蓝色网线插入小型工业网关的端口，桌上是亮着的笔记本、手写记录本、黄色尾纤与手持测试仪 — 现场联调：插线、记录、比对——点位表填完之后，原始值比对是最后一道校验。

端侧运行时与模型部署数据进来之后，模型怎么落盘与校验 运维、OTA 与 SLA告警分级、灰度与可用性口径 接线与组态模板点位表、接线图与节点映射表模板

版本不匹配：本文对应驱动包 2.4.0。网关固件低于 2.3.0 时 hy-collect 的 probe 子命令不可用，请先按 BSP 移植与适配升级到 v2.4.x。

本文档由平台研发组维护，最近复核 2026-09-11。协议字段与实物不一致时，请附仪表手册页、hy-collect probe 输出与抓包文件发至 contact@huayuniot.com.cn。

2026-09-11：新增 CJ/T 188 与 DL/T 645 的周期建议；补充 probe 自检示例。
2026-08-19：REST 章节补充分页游标与 Idempotency-Key 说明。