设备连接与遥测数据采集 MQTT 指南

MQTT (Message Queuing Telemetry Transport) 是一种轻量级的、基于发布/订阅模型的双向消息传输协议。在我们的系统中，MQTT 被专门作为**物理硬件设备（传感器、网关、执行器）**与云端通信的核心通道。

---

1. 物理拓扑与数据路由

设备终端通过 TCP (加密端口 8883) 或是 WebSockets (加密端口 9001) 与生产环境下的 Mosquitto Broker 建立低开销的长连接。

flowchart LR
    Device1[IoT 终端设备 A] -->|1. 发布 Telemetry| Broker[Mosquitto Broker]
    Device2[IoT 终端设备 B] -->|1. 发布 Telemetry| Broker
    Broker -->|2. 共享订阅推送| Backend[Laravel 业务网关集群]
    Backend -->|3. 存储/处理| DB[(时序数据库 / MySQL)]
    
    Backend -->|4. 发布 Control Commands| Broker
    Broker -->|5. 下发命令| Device1

1. 数据采集 (上行): 设备将物理状态和传感器数值序列化为 JSON，周期性向指定遥测主题推送。业务后端通过共享订阅的方式从 Broker 中消费遥测数据，以防在高并发下产生重复消费。
2. 反向控制 (下行): 移动端/控制台通过调用 RESTful 接口触发配置更新，业务后端将控制指令转化为 MQTT 报文发布至 Broker，最终分发给目标设备。

---

2. 规范化主题命名空间 (Topics)

为保证安全隔离与有序路由，我们对 MQTT 的 Topic 层级结构进行了严格限定。

2.1 遥测数据上报 (Telemetry)

• 主题格式: devices/{device_id}/telemetry
• QoS 级别: QoS 1（保证至少送达一次，确保时序指标数据不丢失）
• 方向: 设备发布 (Publish)，后端订阅 (Subscribe)。

2.2 云端控制命令下发 (Commands)

• 主题格式: devices/{device_id}/commands
• QoS 级别: QoS 1（控制命令极度重要，要求 Broker 必须持久化保留直至设备在线并确认执行）
• 方向: 后端发布，设备订阅。

2.3 状态与遗嘱消息 (Last Will and Testament - LWT)

• 主题格式: devices/{device_id}/status
• QoS 级别: QoS 1，且设置 Retained = true。
• 方向: 设备在建立连接时向 Broker 注册其 Will 消息。当连接异常终止时（如断电、网络死锁），Broker 会自动向该主题发布离线状态。

---

3. 标准遥测与状态 JSON 数据模型

为了维护系统数据一致性，所有通过 MQTT 流转的载荷 (Payload) 必须为符合以下契约的 JSON。

3.1 遥测数据载荷示例 (Telemetry Payload)

设备周期性发送至 devices/{device_id}/telemetry 主题的数据结构：

{
  "deviceId": "dev_f49b10a2",
  "timestamp": 1716000000000,
  "metrics": {
    "temperature": 25.4,
    "humidity": 48.6,
    "voltage": 3.6,
    "rssi": -65,
    "status": "online"
  }
}

3.2 离线告警/状态变更载荷示例 (Status/LWT Payload)

当设备离线（由 Broker 遗嘱触发）或上线时发送至 devices/{device_id}/status 的数据结构：

{
  "deviceId": "dev_f49b10a2",
  "timestamp": 1716000085000,
  "status": "offline",
  "reason": "LWT_TRIGGERED"
}

注：当设备成功上线重连时，也需主动向该主题发布 {"status": "online", "reason": "DEVICE_CONNECTED"} 以覆盖原有的 Retained 离线状态。