物模型协议

约 6194 字大约 21 分钟

2025-03-03

简介

属性质量扩展：saas 新版支持。报文格式见本文末尾“属性质量扩展”。

物模型可将物理世界中的设备功能进行数字化定义，便于应用更便利的管理设备。平台为用户提供了基于物模型的业务协议，既可以满足智慧生活场景应用，也可满足物联网各垂直行业应用需求。

智慧生活场景：基于物模型协议，用户将设备相关属性、事件等上报云端后，可无缝使用腾讯连连小程序或自主品牌小程序与 App，无需处理云端与小程序或 App 的通信细节，以提升用户在智慧生活场景下的应用开发效率。
垂直行业应用场景：基于物模型协议，无需用户解析设备数据，可使用物联网开发平台的数据分析、告警和存储服务，以提升垂直行业应用的开发效率。

概述

产品定义物模型后，设备可以根据物模型中的定义上报属性、事件，并可对设备下发控制指令。物模型的管理详见产品定义。物模型协议包括了以下几部分。

设备属性上报：设备端将定义的属性根据设备端的业务逻辑向云端上报。
设备远程控制：从云端向设备端下发控制指令，即从云端设置设备的可写属性。
获取设备最新上报信息：获取设备最新的上报数据。
设备事件上报：设备可根据定义的物模型中的事件，当事件被触发，则根据设备事件上报的协议上报告警、故障等事件信息。
设备行为调用：云端可以通过 RPC 的方式通知设备执行某个动作行为，适用于应用需要实时获取设备的执行结果的场景。
设备初始信息上报：设备连接平台时上报的初始信息，便于小程序或 App 展示设备详细信息，如设备 MAC 地址、IMEI 号。

参数说明

{productID}：产品ID。
{deviceName}：设备ID。
通用请求参数

参数	类型	必填	说明
msgToken	String	是	用于上下行消息配对标识
sys.noAsk	bool	否	云端是否回复设备
sys.retMsg	bool	否	是否返回错误信息,字段为msg
示例:

{
  "method": "reportInfo",
  "msgToken": "1234567",
  "sys": {
    "noAsk": false,
    "retMsg": true
  }
}

数据类型详解

物模型支持 9 种数据类型，用于定义属性、事件参数、行为参数的数据格式。

数据类型概览

类型	标识符	说明	适用场景
布尔型	`bool`	开关状态，值为 0 或 1	电源开关、使能状态
整数型	`int`	整数值，可设范围、步长、单位	温度、亮度、计数器
字符串	`string`	文本内容，可设最大长度	设备名称、描述信息
浮点型	`float`	小数值，可设精度、范围、单位	电压、电流、压力
时间型	`timestamp`	毫秒级 Unix 时间戳	事件时间、更新时间
枚举型	`enum`	预定义选项值	工作模式、档位选择
结构体	`struct`	多字段组合	位置坐标、设备状态
数组	`array`	固定长度数值序列	传感器阵列、多路数据
矩阵	`matrix`	变长数值序列	波形数据、音频采样

各类型详细说明

1. 布尔型（bool）

表示开关状态，值只能为 0（关）或 1（开）。

Define 定义字段：

字段	类型	必填	说明
type	string	是	固定值 `"bool"`
mapping	map	是	布尔值映射，键为 `"0"` 和 `"1"`，值为描述文字（最大 50 字符）
start	string	否	初始值，`"0"` 或 `"1"`

定义示例：

{
  "type": "bool",
  "mapping": {
    "0": "关闭",
    "1": "开启"
  },
  "start": "0"
}

设备上报示例：

{
  "power_switch": 1
}

2. 整数型（int）

表示整数值，可定义数值范围、步长和单位。

Define 定义字段：

字段	类型	必填	说明
type	string	是	固定值 `"int"`
min	string	是	最小值，范围 `-9999999999999` ~ `9999999999999`
max	string	是	最大值，范围 `-9999999999999` ~ `9999999999999`
step	string	否	步长，默认 `"1"`
unit	string	否	单位，最大 12 字符
start	string	否	初始值

定义示例：

{
  "type": "int",
  "min": "0",
  "max": "100",
  "step": "1",
  "unit": "℃",
  "start": "25"
}

设备上报示例：

{
  "temperature": 42
}

3. 字符串（string）

表示文本内容，可定义最大长度。

Define 定义字段：

字段	类型	必填	说明
type	string	是	固定值 `"string"`
max	string	是	最大长度，最大 2048 字节
start	string	否	默认值

定义示例：

{
  "type": "string",
  "max": "128"
}

设备上报示例：

{
  "device_name": "客厅空调"
}

4. 浮点型（float）

表示小数值，可定义数值范围、精度和单位。

Define 定义字段：

字段	类型	必填	说明
type	string	是	固定值 `"float"`
min	string	是	最小值
max	string	是	最大值
step	string	否	步长（精度），默认 `"0.001"`
unit	string	否	单位，最大 12 字符
start	string	否	初始值

定义示例：

{
  "type": "float",
  "min": "0.0",
  "max": "380.0",
  "step": "0.1",
  "unit": "V",
  "start": "220.0"
}

设备上报示例：

{
  "voltage": 225.5
}

5. 时间型（timestamp）

表示毫秒级 Unix 时间戳。

Define 定义字段：

字段	类型	必填	说明
type	string	是	固定值 `"timestamp"`

定义示例：

{
  "type": "timestamp"
}

设备上报示例：

{
  "last_update": 1711552800000
}

6. 枚举型（enum）

表示预定义的选项值，键为整数，值为描述文字。

Define 定义字段：

字段	类型	必填	说明
type	string	是	固定值 `"enum"`
mapping	map	是	枚举映射，键为整数字符串，值为描述文字（最大 50 字符）
start	string	否	初始值（键值）

定义示例：

{
  "type": "enum",
  "mapping": {
    "1": "低速",
    "2": "中速",
    "3": "高速"
  },
  "start": "2"
}

设备上报示例：

{
  "fan_speed": 2
}

7. 结构体（struct）

表示多字段组合，用于复杂结构数据。

Define 定义字段：

字段	类型	必填	说明
type	string	是	固定值 `"struct"`
specs	array	是	结构体成员数组，最多 20 个参数

specs 数组元素：

字段	类型	必填	说明
identifier	string	是	参数标识符
name	string	是	参数名称
dataType	object	是	数据类型定义（同上述各类型）

定义示例：

{
  "type": "struct",
  "specs": [
    {
      "identifier": "longitude",
      "name": "经度",
      "dataType": {
        "type": "float",
        "min": "-180.0",
        "max": "180.0"
      }
    },
    {
      "identifier": "latitude",
      "name": "纬度",
      "dataType": {
        "type": "float",
        "min": "-90.0",
        "max": "90.0"
      }
    }
  ]
}

设备上报示例：

{
  "position": {
    "longitude": 116.4074,
    "latitude": 39.9042
  }
}

8. 数组（array）

表示固定长度的数值序列，支持单独修改某个元素。

Define 定义字段：

字段	类型	必填	说明
type	string	是	固定值 `"array"`
max	string	是	数组最大长度，最大 1024
arrayInfo	object	是	元素类型定义

元素访问方式：

单独访问：identifier.0、identifier.1、identifier.2...
批量赋值：identifier: [1, 2, 3]

定义示例：

{
  "type": "array",
  "max": "8",
  "arrayInfo": {
    "type": "int",
    "min": "0",
    "max": "100"
  }
}

设备上报示例：

{
  "sensor_array": [25, 26, 24, 25, 27, 26, 25, 24]
}

或单独上报某个元素：

{
  "sensor_array.2": 30
}

9. 矩阵（matrix）

表示变长的数值序列，不支持单独修改某个元素，只能整体赋值。

Define 定义字段：

字段	类型	必填	说明
type	string	是	固定值 `"matrix"`
arrayInfo	object	是	元素类型定义

定义示例：

{
  "type": "matrix",
  "arrayInfo": {
    "type": "float",
    "min": "-1.0",
    "max": "1.0"
  }
}

设备上报示例：

{
  "waveform": [0.1, 0.5, 0.8, 0.6, 0.2, -0.3, -0.7, -0.5]
}

array 与 matrix 对比

特性	array（数组）	matrix（矩阵）
长度限制	最大 1024	无限制
元素访问	支持 `a.0`、`a.1` 单独修改	不支持
赋值方式	`[1,2,3]` 或 `a.0: 1`	仅 `[1,2,3]`
适用场景	固定长度数据（传感器阵列）	变长数据（波形、音频）

设备上报传参示例汇总

设备通过 MQTT 上报属性时，params 字段的格式根据数据类型而定：

{
  "method": "report",
  "msgToken": "123456",
  "params": {
    "power_switch": 1,                    // bool: 0 或 1
    "temperature": 25,                    // int: 整数
    "voltage": 220.5,                     // float: 浮点数
    "device_name": "客厅空调",             // string: 字符串
    "last_update": 1711552800000,         // timestamp: 时间戳
    "fan_speed": 2,                       // enum: 枚举值
    "position": {                         // struct: 对象
      "longitude": 116.4074,
      "latitude": 39.9042
    },
    "sensor_array": [25, 26, 24, 25],     // array: 数组
    "waveform": [0.1, 0.5, 0.8, 0.6]      // matrix: 数组
  }
}

基础

设备基础信息上报

小程序或 App 展示设备详细信息时，一般会展示设备的 MAC 地址、IMEI 号、时区等基础信息。设备信息上报使用的 Topic：

上行请求 Topic： $thing/up/property/{ProductID}/{DeviceName}
下行响应 Topic： $thing/down/property/{ProductID}/{DeviceName}

请求

设备端请求报文示例：

{
  "method": "reportInfo",
  "msgToken": "1234567",
  "params": {
    "imei": "867183032145472",
    "mac": "8C:85:90:AB:CD:EF",
    "version": "ddd",
    "hardInfo": "ddd",
    "softInfo": "ddd", 
    "projectID": "123", 
     "localIp": "127.0.0.1",
    "position": {
      "coordinateSystem": "WGS84",
      "longitude": 116.442501,
      "latitude": 40.03448
    },
    "tags": {
      "aaa": "ddddd",
      "bbb": "ddddd"
    }, 
    "deviceAlias": "xxx"
  }
}

请求参数说明：

参数	类型	必填	说明
method	String	是	reportInfo 表示设备基础信息上报
msgToken	String	是	用于上下行消息配对标识
params	Struct	是	JSON结构内为设备上报的设备基础信息
params.imei	String(15)	否	IMEI号信息如 867183032145472
params.mac	String(17)	否	MAC信息如 8C:85:90:AB:CD:EF
params.version	String(64)	否	固件版本
params.module	String(64)	否	固件模块说明上报默认（default）模块的版本号时，可以不上报module参数。设备的默认（default）模块的版本号代表整个设备的固件版本号。)
params.hardInfo	String(64)	否	模组硬件型号
params.softInfo	String(64)	否	模组软件版本
params.localIp	String(64)	否	局域网的ip,方便排查问题
params.position	Struct	否	坐标信息
params.position.coordinateSystem	String	否	坐标系：WGS84(地球系)，GCJ02(火星系,默认)，BD09(百度系) 参考解释
params.position.longitude	Double	否	经度坐标(度格式，十进制) 参考解释
params.position.latitude	Double	否	纬度坐标(度格式，十进制)
params.address	Struct	否	所在地址
params.adcode	Struct	否	地区编码
params.tags	Map[String]String	否	设备标签信息
params.mobileOperator	int64	否	移动运营商:1)移动 2)联通 3)电信 4)广电
params.rssi	int64	否	设备信号（信号极好[-55— 0]，信号好[-70— -55]，信号一般[-85— -70]，信号差[-100— -85]）
params.iccid	string	否	SIM卡卡号
params.deviceAlias	string	否	设备名称(可选,版本>=1.3.0)
params.projectID	string	否	绑定的项目id,如果和实际的不同,会下发绑定变化通知(可选,版本>=1.4.0)

响应

云端返回设备端报文示例：

{        
  "method":"reportInfoReply",    
  "msgToken":"1234567",    
  "code":200,    
  "msg":"success"
}

响应参数说明：

参数	类型	说明
method	String	reportReply 表示云端接收设备上报后的响应报文
msgToken	String	用于上下行消息配对标识
code	Integer	200 表示云端成功收到设备上报的属性
msg	String	当 code 非200的时候，提示错误信息

设备属性上报

当设备需要向云端上报设备运行状态的变化时，以通知应用端小程序、App 实时展示或云端业务系统接收设备上报属性数据，物联网开发平台为设备设定了默认的 Topic：
- 设备属性上行请求 Topic： $thing/up/property/{ProductID}/{DeviceName}
- 设备属性下行响应 Topic： $thing/down/property/{ProductID}/{DeviceName}
请求
- 设备端请求报文示例：

{
  "method":"report",
  "msgToken":"123",
  "timestamp":1677762028638,
  "params":{
    "power_switch":1,
    "color":1,
    "brightness":32
  }
}

请求参数说明：

参数	类型	必填	说明
method	String	是	report 表示设备属性上报
msgToken	String	是	用于上下行消息配对标识
timestamp	Integer	否	属性上报的时间，格式为 UNIX 系统时间戳，不填写该字段表示默认为当前系统时间。单位为毫秒
params	JSON	是	JSON结构内为设备上报的属性值
params.power_switch	Boolean	否	布尔型属性的值一般为0或1
params.color	Enum	否	枚举整型属性的值为整数值，数值类型填写错误或超过枚举项定义范围出现406返回码，表示物模型格式校验错误
params.brightness	Integer	否	整数型属性的值为整数值，数值类型填写错误或超过数值范围会出现406返回码，表示物模型格式校验错误

响应

云端返回设备端报文示例：

{
  "method":"reportReply",
  "msgToken":"123",
  "code":200,
  "msg":"some message where error"
}

响应参数说明：

参数	类型	说明
method	String	reportReply 表示云端接收设备上报后的响应报文
msgToken	String	用于上下行消息配对标识
code	Integer	200表示云端成功收到设备上报的属性
msg	String	当 code 非200的时候，提示错误信息

请求设备上报属性

需要主动请求设备上报的时候需要用以下方式上报 Topic：

设备属性下行响应 Topic： $thing/down/property/{ProductID}/{DeviceName}
设备属性上行请求 Topic： $thing/up/property/{ProductID}/{DeviceName}

请求
- 云端请求报文示例：

{
  "method":"getReport",
  "msgToken":"123",
  "timestamp":1677762028638,
  "identifiers":["power_switch","color","brightness"]
}

请求参数说明：

参数	类型	必填	说明
method	String	是	report 表示设备属性上报
msgToken	String	是	用于上下行消息配对标识
timestamp	Integer	否	属性上报的时间，格式为 UNIX 系统时间戳，不填写该字段表示默认为当前系统时间。单位为毫秒
identifiers	array.String	否	内为希望设备上报的属性列表,不填为获取全部

响应

设备端返回报文示例：

{
  "method":"getReportReply",
  "msgToken":"123",
  "timestamp":1677762028638,
  "data":{
    "power_switch":1,
    "color":1,
    "brightness":32
  },
  "code":200,
  "msg":"some message where error"
}

响应参数说明：

参数	类型	说明
method	String	reportReply 表示云端接收设备上报后的响应报文
msgToken	String	用于上下行消息配对标识
code	Integer	200表示云端成功收到设备上报的属性
msg	String	当 code 非200的时候，提示错误信息
timestamp	Integer	属性上报的时间，格式为 UNIX 系统时间戳，不填写该字段表示默认为当前系统时间。单位为毫秒
data	JSON	JSON结构内为设备上报的属性值
data.power_switch	Boolean	布尔型属性的值一般为0或1
data.color	Enum	枚举整型属性的值为整数值，数值类型填写错误或超过枚举项定义范围出现406返回码，表示物模型格式校验错误
data.brightness	Integer	整数型属性的值为整数值，数值类型填写错误或超过数值范围会出现406返回码，表示物模型格式校验错误

设备远程控制

使用物模型协议的设备，当需要通过云端控制设备时，设备需订阅下发 Topic 接收云端指令：

下发 Topic： $thing/down/property/{ProductID}/{DeviceName}
响应 Topic： $thing/up/property/{ProductID}/{DeviceName}

请求

远程控制请求消息格式：

{
  "method": "control",
  "msgToken": "123",    
  "params": {
    "power_switch": 1,
    "color": 1,
    "brightness": 66    
  }
}

请求参数说明：

参数	类型	必填	说明
method	String	是	control 表示云端向设备发起控制请求
msgToken	String	是	用于上下行消息配对标识
timestamp	Integer	否	属性上报的时间，格式为 UNIX 系统时间戳，不填写该字段表示默认为当前系统时间。单位为毫秒
params	JSON	是	JSON 结构内为设备属性的设置值，可写的属性值才可控制成功
params.power_switch	Boolean	否	布尔型属性的值一般为0或1
params.color	Enum	否	枚举整型属性的值为整数值，数值类型填写错误或超过枚举项定义范围出现406返回码，表示物模型格式校验错误
params.brightness	Integer	否	整数型属性的值为整数值，数值类型填写错误或超过数值范围会出现406返回码，表示物模型格式校验错误

响应
- 设备响应远程控制请求消息格式：

{
  "method":"controlReply",
  "msgToken":"123",
  "code":200,
  "msg":"some message where error"
}

请求参数说明：

参数	类型	说明
method	String	表示设备向云端下发的控制指令的请求响应
msgToken	String	用于上下行消息配对标识
code	Integer	200表示设备成功接收到云端下发的控制指令
msg	String	当 code 非200的时候，提示错误信息

设备获取云端最新上报信息

如果设备存在影子的值,则会返回影子的值,设备回复成功后会更新到数据库中

设备从云端接收最新消息使用的 Topic：

请求 Topic： $thing/up/property/{ProductID}/{DeviceName}
响应 Topic： $thing/down/property/{ProductID}/{DeviceName}

请求

请求消息格式：

{
  "method": "getStatus",
  "msgToken": "123",
  "identifiers":["power_switch","color","brightness"]
}

请求参数说明：

参数	类型	必填	说明
method	String	是	getStatus 表示获取设备最新上报的信息
msgToken	String	是	消息 Id，回复的消息将会返回该数据，用于请求响应消息的对比
identifiers	array.String	否	内为希望设备上报的属性列表,不填为获取全部

响应

响应消息格式：

{
  "method": "getStatusReply",
  "code": 200,
  "msgToken": "123",
  "data": {
    "power_switch": 1,
    "color": 1,
    "brightness": 66
  }
}

响应参数说明：

参数	类型	说明
method	String	表示获取设备最新上报信息的 reply 消息
msgToken	String	消息 Id，回复的消息将会返回该数据，用于请求响应消息的对比
code	Integer	200标识云端成功收到设备上报的属性
data	JSON	返回具体设备上报的最新数据内容

设备事件上报或下行通知

当设备需要向云端上报事件时，如上报设备的故障、告警数据，平台为设备设定了默认的 Topic：

设备事件上行请求 Topic： $thing/up/event/{ProductID}/{DeviceName}
设备事件上行响应 Topic： $thing/down/event/{ProductID}/{DeviceName}
也支持云端下发事件通知到设备，method 仍为 eventPost，下发 Topic 为 $thing/down/event/{ProductID}/{DeviceName}，设备端收到后无需回复 eventReply。

请求

设备端请求报文示例：

{
  "method":"eventPost",
  "msgToken":"123",
  "version":"1.0",
  "eventID":"PowerAlarm",
  "type":"fault",
  "timestamp":1677762028638,
  "params":{
    "Voltage":2.8,
    "Percent":20
  }
}

请求参数说明：

参数	类型	必填	说明
method	String	是	eventPost 表示事件上报
msgToken	String	是	消息 Id，回复的消息将会返回该数据，用于请求响应消息的对比
version	String	否	协议版本，默认为1.0
eventID	String	是	表示获取什么类型的信息。report 表示设备上报的信息
type	String	否	事件类型。info(默认)：信息,alert：告警,fault：故障

响应

响应消息格式：

{
  "method": "eventReply",
  "msgToken": "123",
  "version": "1.0",
  "code": 200,
  "msg": "some message where error",
  "data": {}
}

响应参数说明：

参数	类型	说明
method	String	eventReply 表示是云端返回设备端的响应
msgToken	String	消息 Id，回复的消息将会返回该数据，用于请求响应消息的对比
version	String	协议版本，默认为1.0
code	Integer	事件上报结果，200表示成功
msg	String	事件上报结果描述
data	JSON	事件上报返回的内容

设备行为调用

当应用通过云端向设备发起某个行为调用或设备向应用发起某个行为调用时，平台为设备行为的处理设定了默认的 Topic：

应用调用设备行为或服务端响应设备请求执行结果 Topic： $thing/down/action/{ProductID}/{DeviceName}
设备响应行为执行结果或设备请求服务端行为 Topic： $thing/up/action/{ProductID}/{DeviceName}

请求

应用端发起设备行为调用报文示例：

{                    
  "method": "action",            
  "msgToken": "20a4ccfd-d308-****-86c6-5254008a4f10",                
  "actionID": "openDoor",                
  "timestamp": 1677762028638,        
  "params": {                    
    "userid": "323343"            
  }
}

请求参数说明：

参数	类型	必填	说明
method	String	是	action 表示是调用设备的某个行为
msgToken	String	是	消息 Id，回复的消息将会返回该数据，用于请求响应消息的对比
actionID	String	是	actionID 是物模型中的行为标识符，由开发者自行根据设备的应用场景定义
timestamp	Integer	否	行为调用的当前时间，不填写则默认为调用行为的当前系统时间，单位为毫秒
params	String	是	行为的调用参数，在物模型的行为中定义

响应

响应消息格式：

{            
  "method": "actionReply",        
  "msgToken": "20a4ccfd-d308-11e9-86c6-5254008a4f10",        
  "code": 200,            
  "msg": "some message where error",        
  "data": {          
    "Code":  20            
  }
}

响应参数说明：

参数	类型	说明
method	String	actionReply 表示是设备端执行完指定的行为向云端回复的响应
msgToken	String	消息 Id，回复的消息将会返回该数据，用于请求响应消息的对比
code	Integer	行为执行结果，200表示成功
msg	String	行为执行失败后的错误信息描述
data	JSON	设备行为中定义的返回参数，设备行为执行成功后，向云端返回执行结果

设备批量上报属性、事件

设备批量上报属性及事件,网关类型还可以上报旗下子设备的属性及事件。设备信息上报使用的 Topic：

上行请求 Topic： $thing/up/property/{ProductID}/{DeviceName}
下行响应 Topic： $thing/down/property/{ProductID}/{DeviceName}

请求

设备端请求报文示例：

{
   "method": "packReport",
   "msgToken": "115",
   "timestamp": 1728464318514,
   "properties": [
      {
         "timestamp": 1728464318514,
         "params": {
            "load": 1,
            "tapPosition": 1
         }
      }
   ],
   "events": [
      {
         "timestamp": 1728464318514,
         "eventID": "234",
         "params": {
            "load": 1,
            "tapPosition": 1
         }
      }
   ],
   "subDevices": [
      {
         "productID": "k0sr6Ow4Bsb",
         "deviceName": "FFFFFFFFF",
         "properties": [
            {
               "timestamp": 1728464318514,
               "params": {
                  "load": 1,
                  "tapPosition": 1
               }
            }
         ],
         "events": [
            {
               "timestamp": 1728464318514,
               "eventID": "234",
               "params": {
                  "load": 1,
                  "tapPosition": 1
               }
            }
         ]
      }
   ]
}

请求参数说明：

参数	类型	必填	说明
method	String	是	reportInfo 表示设备基础信息上报
msgToken	String	是	用于上下行消息配对标识
timestamp	Integer	否	行为调用的当前时间，不填写则默认为调用行为的当前系统时间，单位为毫秒
properties	Array	否	设备自身的属性列表
properties.timestamp	Integer	是	当条的时间戳
properties.params	Struct	是	key为属性的id, value为属性的值
events	Array	否	设备自身的事件列表
events.timestamp	Integer	否	当条的时间戳
events.eventID	String	是	当条的时间戳
events.params	Struct	是	key为属性的id, value为属性的值
subDevices	Array	否	子设备上报的属性或事件
subDevices.properties	Array	否	子设备自身的属性列表
subDevices.properties.timestamp	Integer	是	当条的时间戳
subDevices.properties.params	Struct	是	key为属性的id, value为属性的值
subDevices.events	Array	否	子设备自身的事件列表
subDevices.events.timestamp	Integer	否	当条的时间戳
subDevices.events.eventID	String	是	当条的时间戳
subDevices.events.params	Struct	是	key为属性的id, value为属性的值

响应

云端返回设备端报文示例：

{        
  "method":"packReportReply",    
  "msgToken":"1234567",    
  "code":200
}

响应参数说明：

参数	类型	说明
method	String	reportReply 表示云端接收设备上报后的响应报文
msgToken	String	用于上下行消息配对标识
code	Integer	200 表示云端成功收到设备上报的属性
msg	String	当 code 非200的时候，提示错误信息

属性质量扩展（saas 新版支持）

适用版本：saas 新版。

统一规则

字段	类型	规则
timestamp	毫秒整数	沿用现有数据时间；批量 properties 每条记录填写自己的时间
params / data	对象	原有属性标识到属性值的映射
quality	对象，可选	相同属性标识到 GOOD / UNCERTAIN / BAD 的映射，区分大小写

缺少整个 quality 或某个属性的质量时，该属性默认 GOOD。quality 中不得出现本条 params/data 没有的属性；数字值、未知字符串或不合法结构校验失败。数组、结构体按整个属性标记，不增加成员级质量。

采集失败使用 null + BAD；GOOD/UNCERTAIN 仍需有符合物模型的值。code 表示请求处理结果，quality 表示属性数据质量，两者独立。以下 temperature 是示例属性，设备应使用自己物模型的实际标识。

1. 单次属性上报

上行 Topic：$thing/up/property/{ProductID}/{DeviceName}。

{
  "method": "report",
  "msgToken": "1001",
  "timestamp": 1789516800000,
  "params": { "temperature": 26.5 },
  "quality": { "temperature": "GOOD" }
}

接收确认保持原结构；code=200 不代表数据库事务已提交：

{
  "method": "reportReply",
  "msgToken": "1001",
  "code": 200
}

2. 批量属性上报

质量放在每条 properties 记录内，不设置批量顶层质量，不同记录不能互相继承质量。

{
  "method": "packReport",
  "msgToken": "1002",
  "timestamp": 1789516920000,
  "properties": [
    {
      "timestamp": 1789516800000,
      "params": { "temperature": 26.5 },
      "quality": { "temperature": "GOOD" }
    },
    {
      "timestamp": 1789516860000,
      "params": { "temperature": 27.1 },
      "quality": { "temperature": "UNCERTAIN" }
    },
    {
      "timestamp": 1789516920000,
      "params": { "temperature": null },
      "quality": { "temperature": "BAD" }
    }
  ]
}

packReportReply 保持原响应结构。现有 events 可与 properties 同包上报，事件不增加 quality。

3. 网关代子设备上报

{
  "method": "packReport",
  "msgToken": "1003",
  "timestamp": 1789516800000,
  "subDevices": [
    {
      "productID": "example_product",
      "deviceName": "device_001",
      "properties": [
        {
          "timestamp": 1789516800000,
          "params": { "temperature": 26.5 },
          "quality": { "temperature": "GOOD" }
        }
      ]
    }
  ]
}

网关自身 properties 与各子设备 properties 可同包存在，按各自属性标识校验质量。

4. 平台主动获取属性

平台下发 Topic：$thing/down/property/{ProductID}/{DeviceName}，请求结构不变。

{
  "method": "getReport",
  "msgToken": "1004",
  "identifiers": ["temperature"]
}

设备回复仍使用 data，不能改成 params：

{
  "method": "getReportReply",
  "msgToken": "1004",
  "code": 200,
  "timestamp": 1789516800000,
  "data": { "temperature": 26.5 },
  "quality": { "temperature": "GOOD" }
}

若请求处理成功但采集失败：data.temperature=null，quality.temperature=BAD，code 仍可为 200。若请求本身失败，沿用非 200 错误回复，不生成虚构采集数据。

5. 获取云端最新上报状态

设备发起 getStatus 的请求结构不变；云端回复在 data 旁附质量：

{
  "method": "getStatusReply",
  "msgToken": "1005",
  "code": 200,
  "data": { "temperature": null },
  "quality": { "temperature": "BAD" }
}

返回最新实际状态，不回退到旧 GOOD 值。若现有流程合并了期望影子值，quality 只对应实际采集项，期望值不标采集质量。getStatus 是读取云端状态，不代替 getReport 主动采集。

6. HTTP 上报

HTTP 上报 /api/v1/things/device/edge/send/thing/property 的 Body 与上述 MQTT payload 相同，认证及响应外层保持原协议；HTTP 不因此新增下行通道。

更新日志

2026/9/16 14:54

查看所有更新日志

5b100-Merge #40 into master from codex/task-124-quality-protocol于 2026/9/16
7e927-文档站全面重构：目录重排、首页重写、案例独立成站、应用市场下线于 2026/8/4
ff203-docs: add prepaid energy design materials于 2026/4/9
8d8de-docs: 更新小智AI云平台文档于 2026/1/20
bddea-docs: 更新文档结构、添加新内容并优化现有文档于 2025/12/28
706e5-doc于 2025/11/27
c5b0b-doc于 2025/7/14
927cc-doc于 2025/7/8
51ff0-doc于 2025/3/21
1eefd-doc于 2025/3/19
80b39-doc于 2025/3/11
d4fa0-doc: 更换皮肤到最新版于 2025/3/3
82830-doc于 2025/2/17
e6a16-doc于 2025/1/9
6d811-doc于 2025/1/9
f4a75-doc: 完善文档于 2024/11/14
4066c-doc: 完善文档于 2024/11/12
76d3f-doc: 完善文档于 2024/11/9
3f84d-doc: 完善文档于 2024/11/5
61270-doc: 完善文档于 2024/11/5
ec6ca-doc: 完善文档于 2024/10/19
464ec-doc: 完善文档于 2024/10/9
79a65-doc: 完善文档于 2024/10/9
80e85-doc: 完善文档于 2024/10/5
114d1-初始化于 2024/9/19
5741d-初始化于 2024/9/6
8794f-feat: 完善项目`于 2024/8/30
df9b4-初始化于 2024/8/29

物模型

AI与音视频接入

通用接入

场景教程

接续与恢复

AI 语音对话

通话会议与门铃

摄像头与视频

录制与媒体播放

翻译与旁路处理

协议参考

公共约定与鉴权

AI输入回复与工具

媒体协商轨与处理器

应用接口与物模型边界

开发与验证

完整报文示例

物模型协议