MQTT 主题规范

平台南向驱动与管理/数据中心之间全部通过 EMQX 消息总线交互，遵循 MQTT 5.0 标准。二次开发驱动或对接第三方系统时，可直接按以下主题收发消息。

总线接入

项默认值
地址tcp://localhost:1883（TLS 为 8883）
账号 / 密码unihh / unihh
BrokerEMQX 5.x，支持共享订阅与保留消息

主题总表

业务分类主题（Topic）发布端消费端说明
驱动在线注册iot/driver/register驱动服务管理中心驱动启动自动广播自身元数据与 HTTP 宿主地址
驱动周期心跳iot/driver/heartbeat驱动服务管理中心默认每 5s 上报心跳与活跃通道指标
驱动状态与遗嘱iot/driver/{driverCode}/status驱动 / EMQX管理中心上线/下线通知；进程崩溃时由 Broker 发布 LWT 遗嘱（retained=true）
设备配置同步iot/device/config/update管理中心各驱动服务设备或点位配置变更的全局热通知
专属设备配置iot/driver/{driverCode}/device/config管理中心指定驱动针对具体驱动定向下发设备连接与点位定义
点位数据上报iot/driver/{driverCode}/data驱动服务数据中心周期轮询采集结果，数据中心经共享订阅消费入库
反向控制指令iot/driver/{driverCode}/cmd管理中心指定驱动点位反写（WRITE）或服务调用（SERVICE）专属指令
设备通道状态iot/device/status驱动服务管理中心物理链路断连/恢复通知，平台据此更新设备状态

消费模式说明

  • 共享订阅：iot/driver/+/data 数据流由数据中心以 MQTT 5.0 共享订阅消费，可水平扩展多个数据中心实例分担吞吐；
  • 专属主题：配置同步与反控指令使用带 {driverCode} 的专属主题定向下发，避免无关驱动处理多余报文；
  • 保留消息：驱动状态使用 retained 标记，后上线的消费者能立即获得最近一次状态。

可靠性机制

机制说明
LWT 遗嘱驱动连接时注册遗嘱，异常掉线时由 EMQX 代发离线消息
心跳看门狗平台侧兜底：心跳超过 15s 未刷新即判定驱动离线
通道互斥驱动内部对同一设备通道的读写加公平锁，指令在 MQTT 层并发到达也会在物理层串行执行

自定义对接建议

第三方系统（如 MES）若只消费数据，可直接共享订阅 iot/driver/+/data；若需下发控制，建议通过平台 REST 接口（/api/v1/devices 反控端点）而非直发 MQTT 主题，以便获得鉴权、参数快照与执行日志的完整审计链路。