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

 

## 1. 协议概述

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

## 2. Topic约定

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

| 消息类型     | 方向         | 说明                 |
|--------------|--------------|----------------------|
| properties   | 设备→服务端  | 设备属性数据上报     |
| events       | 设备→服务端  | 设备事件数据上报     |
| alarms       | 设备→服务端  | 设备报警数据上报     |
| model        | 设备→服务端  | 设备物模型定义       |
| status       | 双向         | 设备在线状态         |
| commands     | 服务端→设备  | 设备控制命令         |
| config       | 服务端→设备  | 设备配置下发         |

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

## 3. 消息格式约定

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

### 3.1 设备属性数据（properties）

```json
{
  "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）

```json
{
  "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）

```json
{
  "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）

```json
{
  "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）

```json
{
  "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）

```json
{
  "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. 数据质量与报警级别

| 质量标识     | 说明     |
|--------------|----------|
| good         | 良好     |
| uncertain    | 不确定   |
| bad          | 坏值     |
| maintenance  | 维护中   |

| 报警级别     | 说明         |
|--------------|--------------|
| info         | 信息         |
| warning      | 警告         |
| minor        | 次要报警     |
| major        | 重要报警     |
| critical     | 严重报警     |

## 7. QoS建议

| 消息类型   | 建议QoS |
|------------|---------|
| 属性数据   | 0       |
| 事件数据   | 1       |
| 报警数据   | 1       |
| 物模型     | 1       |
| 控制命令   | 1       |
| 设备状态   | 0       |

## 8. 安全与权限

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

## 9. 版本管理

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

---

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