胜透物联网通信协议 - MQTT版本

1. 协议概述

本协议用于胜透物联网设备与服务端基于MQTT协议的数据通信，统一设备数据上报、事件、报警、物模型、命令等交互格式，便于服务端自动发现、解析和管理设备。

2. Topic约定

• Topic结构：{nameSpace}/{deviceType}/{clientCode}/{deviceId}/{messageType}
• nameSpace：命名空间，默认为shengtou
• deviceType：设备类型（如sensor、gateway等）
• clientCode：客户代码/客户ID
• deviceId：设备唯一标识
• messageType：消息类型，见下表

• 设备端需严格按照上述Topic结构进行消息发布和订阅。

3. 消息格式约定

• 所有消息均为JSON格式，包含如下通用字段：
• messageId：唯一消息ID
• timestamp：消息时间戳（毫秒）
• clientCode：客户代码/客户ID
• deviceId：设备ID
• deviceType：设备类型
• version：协议版本号
• data：具体数据内容

3.1 设备属性数据（properties）

{
  "messageId": "msg_20250614_001",
  "timestamp": 1718380800000,
  "clientCode": "Data-It_XzOffice",
  "deviceId": "TH001",
  "deviceType": "sensor",
  "version": "1.0",
  "data": {
    "properties": {
      "temperature": { "value": 25.6, "unit": "°C", "quality": "good", "timestamp": 1718380800000 },
      "humidity": { "value": 65.2, "unit": "%RH", "quality": "good", "timestamp": 1718380800000 }
    }
  }
}

3.2 设备事件数据（events）

{
  "messageId": "evt_20250614_001",
  "timestamp": 1718380800000,
  "clientCode": "Data-It_XzOffice",
  "deviceId": "TH001",
  "deviceType": "sensor",
  "version": "1.0",
  "data": {
    "events": [
      { "eventType": "startup", "eventLevel": "info", "eventCode": "EVT_001", "description": "设备启动完成", "timestamp": 1718380800000 }
    ]
  }
}

3.3 设备报警数据（alarms）

{
  "messageId": "alm_20250614_001",
  "timestamp": 1718380800000,
  "clientCode": "Data-It_XzOffice",
  "deviceId": "TH001",
  "deviceType": "sensor",
  "version": "1.0",
  "data": {
    "alarms": [
      { "alarmId": "ALM_001", "alarmType": "threshold_exceeded", "alarmLevel": "warning", "alarmCode": "TEMP_HIGH", "description": "温度超出上限阈值", "triggerValue": 35.8, "threshold": 35.0, "property": "temperature", "timestamp": 1718380800000, "status": "active" }
    ]
  }
}

3.4 设备物模型定义（model）

{
  "messageId": "mdl_20250614_001",
  "timestamp": 1718380800000,
  "clientCode": "Data-It_XzOffice",
  "deviceId": "TH001",
  "deviceType": "sensor",
  "version": "1.0",
  "data": {
    "model": {
      "deviceInfo": { "manufacturer": "胜透科技", "model": "ST-TH-001", "version": "1.0.0", "description": "温湿度传感器" },
      "properties": {
        "temperature": { "dataType": "float", "unit": "°C", "range": { "min": -40, "max": 85 }, "precision": 1, "description": "环境温度" },
        "humidity": { "dataType": "float", "unit": "%RH", "range": { "min": 0, "max": 100 }, "precision": 1, "description": "相对湿度" }
      },
      "events": { "startup": { "eventType": "info", "description": "设备启动事件" } },
      "alarms": { "TEMP_HIGH": { "alarmType": "threshold_exceeded", "description": "温度过高报警", "defaultThreshold": 35.0 } }
    }
  }
}

3.5 设备状态（status）

{
  "messageId": "sts_20250614_001",
  "timestamp": 1718380800000,
  "clientCode": "Data-It_XzOffice",
  "deviceId": "TH001",
  "deviceType": "sensor",
  "version": "1.0",
  "data": {
    "status": { "online": true, "lastHeartbeat": 1718380800000, "uptime": 86400000 }
  }
}

3.6 服务端下行命令（commands/config）

{
  "messageId": "cmd_20250614_001",
  "timestamp": 1718380800000,
  "clientCode": "Data-It_XzOffice",
  "deviceId": "TH001",
  "deviceType": "sensor",
  "version": "1.0",
  "data": {
    "command": { "commandType": "setProperty", "commandId": "SET_001", "parameters": { "reportInterval": 60000 }, "timeout": 30000 }
  }
}

4. 物模型自动发现约定

• 设备首次上线后，需主动向model Topic发布自身物模型定义。
• 物模型内容应完整描述设备的属性、事件、报警、设备信息等。
• 设备物模型发生变更时，需重新发布。
• 服务端通过订阅{nameSpace}/+/+/+/model实现自动发现和注册新设备。
• 设备重启时建议再次发布物模型。

4.1 物模型消息重发机制

为降低物模型消息丢失导致服务端无法及时发现设备的风险，协议建议如下重发机制：

• 设备在首次上线、重启或物模型变更时，主动向model Topic发布物模型消息。
• 设备在首次发布后，建议在短时间内（如3~5秒）自动重发1~2次物模型消息，以提高消息送达成功率。
• 物模型消息建议使用QoS 1，确保消息至少送达一次。
• 若设备端支持，建议在收到服务端确认（如下行命令或配置）后停止重发。
• 服务端应具备**幂等**处理能力，能正确识别和忽略重复的物模型消息。

通过上述机制，可有效提升设备自动发现的可靠性，避免因单次消息丢失导致设备无法被服务端识别。

4.2 设备主动上报依赖与健壮性提升方法

为降低协议对设备主动上报物模型和状态的依赖、提升自动发现的健壮性，建议如下：

• 设备端应严格遵循协议，确保每次上线、重启、物模型变更时，均主动上报物模型和状态。
• 设备端应实现自动重发机制，确保物模型和状态消息可靠送达。
• 服务端可定期检查设备状态Topic的活跃性，若长时间未收到设备状态或属性数据，可主动下发请求，提醒设备重新上报物模型和状态。
• 服务端可对设备的活跃性和数据上报情况进行监控，发现异常及时告警和处理。
• 协议可约定设备端在收到服务端特定请求（如“重新上报物模型”命令）时，必须立即重新上报物模型和状态。

通过上述方法，即使部分设备端实现不规范，也能通过服务端主动检测和交互机制，提升自动发现和管理的健壮性，减少因设备未主动上报导致的识别遗漏。

4.3 消息幂等处理机制

为避免因消息重发、网络抖动等原因导致的重复数据处理，协议要求服务端具备消息幂等处理能力。实现原理与方法如下：

• 协议规定所有上报消息（如物模型、属性、事件、报警等）必须包含唯一的messageId字段。
• 服务端在接收每条消息时，应根据messageId、deviceId等关键信息进行去重判断。
• 对于已处理过的messageId，服务端应忽略重复消息，确保数据只被处理一次。
• 服务端可通过维护消息ID缓存、数据库唯一索引等方式实现幂等性。
• 幂等机制适用于所有可能因重发导致重复的消息类型，尤其是物模型、报警、事件等重要消息。

通过上述机制，可有效防止重复数据写入和业务逻辑重复执行，保障系统数据一致性和协议健壮性。

4.4 大规模场景下的优化与扩展

为支持大规模设备接入和高并发数据处理，协议建议如下优化与分布式扩展方法：

• Topic设计应支持分层和分组，便于服务端按需批量订阅和分区处理。
• 服务端可采用分布式MQTT集群或多实例部署，提升消息接收和处理能力。
• 数据存储层建议采用分布式数据库或分区表设计，支持高并发写入和大数据量存储。
• 消息处理流程可通过消息队列、流式处理等方式实现异步解耦和负载均衡。
• 对于热点设备或高频Topic，可采用分区消费、负载均衡订阅等机制，避免单点瓶颈。
• 服务端应具备动态扩容能力，支持根据设备规模和业务压力灵活扩展。
• 协议版本和物模型管理应支持多版本并存，便于平滑升级和兼容历史设备。

通过上述方法，可有效支撑成千上万设备的并发接入和数据上报，保障系统的高可用性和可扩展性。

4.5 物模型变更的兼容性与变更通知

为保障设备物模型变更后的兼容性和服务端适配能力，协议建议如下：

• 设备物模型发生变更（如属性、事件、报警结构调整）时，必须及时向model Topic重新发布完整的最新物模型。
• 物模型消息中应包含明确的modelVersion字段，标识物模型版本。
• 服务端应支持多版本物模型的并存和兼容，确保历史数据和新数据均可正确解析。
• 服务端在检测到设备物模型版本变更时，应自动适配新模型，并可根据需要进行数据结构升级或兼容处理。
• 协议建议服务端在物模型变更后，向相关订阅方或管理系统推送变更通知，便于业务系统及时感知和适配。
• 设备端如收到服务端下发的“重新上报物模型”命令时，需立即重新发布当前物模型。

通过上述机制，可确保设备物模型变更时系统具备良好的兼容性和可维护性，避免因模型变更导致的数据解析或业务中断。

5. 其它约定

• 所有消息建议使用UTF-8编码。
• 时间戳统一为毫秒级Unix时间戳。
• 建议属性、事件、报警等字段与物模型保持一致。
• 设备属性、事件、报警等数据字段应与物模型定义严格对应。
• 设备应定期发布状态（status）消息，建议每60秒一次。
• 设备离线时，Broker应通过Last Will机制发布离线状态。

6. 数据质量与报警级别

7. QoS建议

8. 安全与权限

• 设备需使用唯一ID和密钥进行MQTT认证。
• 建议使用TLS/SSL加密。
• 设备仅能发布/订阅自身相关Topic。
• 服务端拥有所有Topic的读写权限。

9. 版本管理

• 当前协议版本：1.1
• 版本号需在消息头中标识
• 重大变更需升级协议版本

文档版本: 1.1
创建日期: 2025年7月14日
维护者: 岱特智能物联网团队