版本: v1.0 修改日期: 2026-05-29 文档定位：本手册面向项目经理，只讲”该做什么、向厂家要什么、怎么判断资料齐了”。技术细节由技术团队负责。

完成后你将能够：确定对接方案（A1 / A2 / B）、向厂家收齐全部资料，通过提资入口提交，技术团队即可开始配置。

阅读路径：确认适用场景（第 1 节）→ 确定对接方案（第 3 节）→ 收资料（第 4 节）→ 自查提交（第 6 节）。

1 确认是否走本手册

1.1 适用场景

满足以下任一条件，走本手册：

• 现场是物联网设备（智能网关、4G 模块、Lora 网关、智能传感器）
• 厂家答复”我们的设备走 MQTT 协议上报”
• 数据特点：量小、频繁、设备分散、需双向（平台也能下发指令到设备）

1.2 不走本手册的情况

2 术语速览

💡 clientId 重要常识

• 全局唯一：同一个 Broker 上不能有两个相同的 clientId
• 重名后果：后连上的会把前面的踢下线，反复掉线、数据丢失
• 命名规则：加项目前缀，如 proj-abc-device-001

3 对接前必须明确：对接方案（A1 / A2 / B）

MQTT 对接和其他协议最大的不同：Broker 由谁提供 + 数据格式由谁定义，组合出三种方案。方案没定，后续所有资料都没法谈。

3.1 三种方案对比

3.2 方案 A1：厂家按自有格式推送到我方 Broker

3.3 方案 A2：厂家按我方规范推送到我方 Broker（✅ 最推荐）

3.4 方案 B：viSCADA 从厂家 Broker 读取数据

📌 方案选择建议

1. 优先争取 A2：开发量最小、维护成本最低、运行最稳定。
2. 厂家不愿改格式但可改推送方向 → A1：Broker 在我方，便于监控、留痕、重放消息。
3. 厂家 Broker 不可替代（已有大量设备接入）→ B：我方按客户端方式接入。

⚠️ 项目经理须向厂家确认方案，并通过邮件书面留痕。

4 资料清单（按方案区分）

📌 提交命名：项目名-MQTT-接口清单

图例：⭕ 我方提供给厂家 ｜ ✅ 厂家提供给我方

4.1 关键要求

1. Topic 三件套必须齐：上报（采集）、下发（控制）、应答（回执，如有）缺一不可，逐条标注方向（设备→平台 / 平台→设备）。
2. 报文示例不可省：每类 Topic 至少 1 条完整 JSON 样例，不接受”联调时抓包看”的回复。
3. 点表：优先提供可编辑 Excel，其他格式可接受，但内容须清晰准确。
4. A2 方案下点表仍由厂家提供：点位清单只有厂家清楚，我方只规定 Topic 结构和报文外壳。

5 操作步骤

① 项目经理向厂家确认方案 A1 / A2 / B（邮件留痕）
        │
        ├── A1 厂家格式 + 我方 Broker
        │     → 联系物联同事获取 Broker 信息 + 专属凭证
        │     → 打包发送给厂家
        │     → 要求厂家回传 Topic、报文示例、点表
        │
        ├── A2 我方格式 + 我方 Broker
        │     → 联系物联同事获取 Broker 信息 + 专属凭证
        │     → 按 viSCADA 南向规范分配 Topic
        │     → 打包发送给厂家（Broker 信息 + 规范 + Topic 清单）
        │     → 要求厂家回传点表
        │
        └── B 厂家 Broker
              → 按本手册第 4 节清单向厂家索取全部资料
              → 如厂家提供测试环境，请备注说明
        │
② 对照第 6 节自查清单逐项勾验
        │
③ 确认网络放通方向正确（详见第 7 节常见问题）
        │
④ 资料齐备后提交实施 / 开发进入联调

6 提交前自查清单

6.1 通用项（三种方案都要）

• 已书面确认方案 A1 / A2 / B
• 已获取上报、下发、应答 Topic（方向已标注）
• 已获取每类 Topic 的完整 JSON 示例
• 已获取完整点表（含编码、Topic、读写属性、单位、采集周期）
• 已完成 网络连通性 验证
• 已通过 统一提资入口  提交资料
• 已在泛微系统发起技术服务流程

6.2 方案 A（A1 / A2 通用）专属

• 已向实施同事获取我方 Broker 地址、端口
• 已签发并发送给厂家专属用户名、密码、clientId
• 已确认网络放通：厂家 → 我方 Broker 通

6.3 方案 A2 额外项

• 已附送 viSCADA 南向 MQTT 规范 给厂家
• 已按规范分配并下发 Topic 清单给厂家

6.4 方案 B 专属

• 已获取厂家 Broker 地址、端口
• 已获取实际鉴权凭证（如有测试环境请备注说明）
• 已确认 clientId 命名规则与同名复用策略
• 已获取厂家对接文档
• 已确认网络放通：viSCADA → 厂家 Broker 通

7 常见问题与处置

⚠️ 方案没定就推进

• 后果：A1 / A2 / B 决定了”谁出 Broker、谁出格式、谁出文档、谁开发”——方案不定，资料清单和责任分工全部混乱，后期一定返工。
• 处置：由项目经理向厂家确认方案，通过邮件书面留痕。

⚠️ 只给 Topic 名，不给报文示例

• 后果：仅有 devices/+/telemetry 这样的 Topic 名称，不知道 JSON 里的字段是什么，无法解析数据，联调必然失败。
• 处置：要求厂家提供每类 Topic 至少 1 条真实的完整 JSON 示例，不接受”联调时抓包看”。

⚠️ Topic 不区分方向

• 后果：一堆 Topic 摆在一起，分不清哪个是设备上报、哪个是平台下发，消息发错方向，控制指令打到采集频道。
• 处置：要求逐条标注方向（设备→平台 或 平台→设备），以表格形式提供。

⚠️ clientId 规则不明 / 重名

• 后果：后连上的设备会把前面的踢下线，导致设备反复掉线、数据丢失。
• 处置：方案 A 由我方签发，确保唯一；方案 B 必须问清厂家的 clientId 命名规则，严禁同名复用。

⚠️ 网络放通方向搞反

• 后果：A1 / A2 方案需放通”厂家→我方”，B 方案需放通”viSCADA→厂家”，方向混淆导致连接永远建不起来。
• 处置：提资时明确告知网络管理员放通的具体方向与端口，并测试连通性。

⚠️ 方案 B 未说明是否有测试环境

• 后果：对接过程中才发现环境不明确，需重新确认地址与凭证，影响进度。
• 处置：获取厂家 Broker 信息时，同步确认是否提供测试环境，如有请备注说明。

8 点表与报文示例（A2 方案参考格式）

8.1 点表样例

8.2 上报报文（telemetry）

{
  "deviceId": "DEV-001",
  "ts": 1744416000000,
  "data": { "temp": 25.6, "humidity": 62.3 }
}

8.3 下发指令（command）

{
  "deviceId": "DEV-001",
  "ts": 1744416000000,
  "cmdId": "cmd-20260412-001",
  "data": { "relay_1": true }
}

8.4 应答回执（command/ack）

{
  "deviceId": "DEV-001",
  "ts": 1744416001200,
  "cmdId": "cmd-20260412-001",
  "result": "success",
  "data": { "relay_1": true }
}

📌 A1 与 B 方案的点表和报文由厂家提供，格式以厂家文档为准。上述仅作 A2 方案参考。

9 遇到问题的三步处置

1. 先排查：网络方向错、clientId 冲突、端口配置不匹配——三类问题覆盖 80% 的卡点。
2. 对照清单：参考第 4 节资料清单，逐项确认是否到位。
3. 同步技术团队：将已收集资料、网络测试结果、当前卡点整理后一并发送，避免反复沟通。

10 关联资料

• 🔗 viSCADA 南向 MQTT 规范
• 🔗 网络连通性验证指引
• 🔗 统一提资入口（钉钉文档）