物模型协议

约 4069 字大约 14 分钟

2025-03-03

简介

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

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

概述

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

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

通用请求参数

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

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

基础

设备基础信息上报

小程序或 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",
    "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.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",
  "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	是	事件类型。info：信息,alert：告警,fault：故障
type	String	是	表示获取什么类型的信息。report 表示设备上报的信息

响应

响应消息格式：

{
  "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}/
设备响应行为执行结果或设备请求服务端行为 Topic： $thing/up/action/{ProductID}/

请求

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

{                    
  "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的时候，提示错误信息