物联网开发平台物模型协议-设备端开发指南-文档中心-腾讯云

简介
物模型可将物理世界中的设备功能进行数字化定义，便于应用更便利的管理设备。平台为用户提供了基于物模型的业务协议，既可以满足智慧生活场景应用，也可满足物联网各垂直行业应用需求。
智慧生活场景：基于物模型协议，用户将设备相关属性、事件等上报云端后，可无缝使用腾讯连连小程序或自主品牌小程序与 App，无需处理云端与小程序或 App 的通信细节，以提升用户在智慧生活场景下的应用开发效率。
垂直行业应用场景：基于物模型协议，无需用户解析设备数据，可使用物联网开发平台的数据分析、告警和存储服务及腾讯云相关云产品，以提升垂直行业应用的开发效率。
物模型协议
概述
产品定义物模型后，设备可以根据物模型中的定义上报属性、事件，并可对设备下发控制指令。物模型的管理详见 产品定义。物模型协议包括了以下几部分。
设备属性上报：设备端将定义的属性根据设备端的业务逻辑向云端上报。
设备远程控制：从云端向设备端下发控制指令，即从云端设置设备的可写属性。
获取设备最新上报信息：获取设备最新的上报数据。
设备事件上报：设备可根据定义的物模型中的事件，当事件被触发，则根据设备事件上报的协议上报告警、故障等事件信息。
设备行为调用：云端可以通过 RPC 的方式通知设备执行某个动作行为，适用于应用需要实时获取设备的执行结果的场景。
设备初始信息上报：设备连接平台时上报的初始信息，便于小程序或 App 展示设备详细信息，如设备 MAC 地址、IMEI 号。
用户删除设备：用户在腾讯连连小程序或用户自主品牌小程序删除设备时由云端发送给设备的通知消息，便于设备重置或网关类设备清除子设备数据。
设备属性上报
1. 当设备需要向云端上报设备运行状态的变化时，以通知应用端小程序、App 实时展示或云端业务系统接收设备上报属性数据，物联网开发平台为设备设定了默认的 Topic：
设备属性上行请求 Topic： $thing/up/property/{ProductID}/{DeviceName}
设备属性下行响应 Topic： $thing/down/property/{ProductID}/{DeviceName}
2. 请求。
设备端请求报文示例：
{
    "method":"report",
    "clientToken":"123",
    "timestamp":1628646783,
    "params":{
        "power_switch":1,
        "color":1,
        "brightness":32
       }
}
请求参数说明：
参数
类型
说明
method
String
report 表示设备属性上报。
clientToken
String
用于上下行消息配对标识。
timestamp
Integer
属性上报的时间，格式为 UNIX 系统时间戳，不填写该字段表示默认为当前系统时间。单位为秒。
params
JSON
JSON 结构内为设备上报的属性值。
params.power_switch
Boolean
布尔型属性的值一般为0或1。
params.color
Enum
枚举整型属性的值为整数值，数值类型填写错误或超过枚举项定义范围出现406返回码，表示物模型格式校验错误。
params.brightness
Integer
整数型属性的值为整数值，数值类型填写错误或超过数值范围会出现406返回码，表示物模型格式校验错误。
3. 响应。
云端返回设备端报文示例：
{
    "method":"report_reply",
    "clientToken":"123",
    "code":0,
    "status":"some message where error"
}
响应参数说明：
参数
类型
说明
method
String
report_reply 表示云端接收设备上报后的响应报文。
clientToken
String
用于上下行消息配对标识。
code
Integer
0表示云端成功收到设备上报的属性。
status
String
当 code 非0的时候，提示错误信息。
设备远程控制
1. 使用物模型协议的设备，当需要通过云端控制设备时，设备需订阅下发 Topic 接收云端指令：
下发 Topic： $thing/down/property/{ProductID}/{DeviceName}
响应 Topic： $thing/up/property/{ProductID}/{DeviceName}
2. 请求。
远程控制请求消息格式：
{
    "method": "control",
    "clientToken": "123",	
    "params": {
        "power_switch": 1,
        "color": 1,
        "brightness": 66	
    }
}
请求参数说明：
参数
类型
说明
method
String
control 表示云端向设备发起控制请求。
clientToken
String
用于上下行消息配对标识。
params
JSON
JSON 结构内为设备属性的设置值，可写的属性值才可控制成功。
3. 响应。
设备响应远程控制请求消息格式：
{
    "method":"control_reply",
    "clientToken":"123",
    "code":0,
    "status":"some message where error"
}
响应参数说明：
参数
类型
说明
method
String
表示设备向云端下发的控制指令的请求响应。
clientToken
String
用于上下行消息配对标识。
code
Integer
0表示设备成功接收到云端下发的控制指令。
status
String
当 code 非0的时候，提示错误信息。
获取设备最新上报信息
1. 设备从云端接收最新消息使用的 Topic：
请求 Topic： $thing/up/property/{ProductID}/{DeviceName}
响应 Topic： $thing/down/property/{ProductID}/{DeviceName}
2. 请求。
请求消息格式：
{
    "method": "get_status",
    "clientToken": "123",
    "type" : "report", 
    "showmeta": 0
}
请求参数说明：
参数
类型
说明
method
String
get_status 表示获取设备最新上报的信息。
clientToken
String
消息 Id，回复的消息将会返回该数据，用于请求响应消息的对比。
type
String
表示获取什么类型的信息。report 表示设备上报的信息。
showmeta
Integer
标识回复消息是否带 metadata，缺省为0表示不返回 metadata。
3. 响应。
响应消息格式： 
{
    "method": "get_status_reply",
    "code": 0,
    "clientToken": "123",
    "type": "report",
    "data": {
        "reported": {
            "power_switch": 1,
            "color": 1,
            "brightness": 66
        }
    }
}
响应参数说明：
参数
类型
说明
method
String
表示获取设备最新上报信息的 reply 消息。
code
Integer
0标识云端成功收到设备上报的属性。
clientToken
String
消息 Id，回复的消息将会返回该数据，用于请求响应消息的对比。
type
String
表示获取什么类型的信息。report 表示设备上报的信息。
data
JSON
返回具体设备上报的最新数据内容。
设备事件上报
1. 当设备需要向云端上报事件时，如上报设备的故障、告警数据，平台为设备设定了默认的 Topic：
设备事件上行请求 Topic： $thing/up/event/{ProductID}/{DeviceName}
设备事件下行响应 Topic： $thing/down/event/{ProductID}/{DeviceName}
2. 请求。
设备端请求报文示例：
{
    "method":"event_post",
    "clientToken":"123",
    "version":"1.0",
    "eventId":"PowerAlarm",
    "type":"fault",
    "timestamp":1212121221,
    "params":{
        "Voltage":2.8,
        "Percent":20
     }
}
请求参数说明：
参数
类型
说明
method
String
event_post 表示事件上报。
clientToken
String
消息 ID，回复的消息将会返回该数据, 用于请求响应消息的对比。
version
String
协议版本，默认为1.0。
eventId
String
事件的 Id，在物模型事件中定义。
type 
String   
事件类型。
info：信息。
alert：告警。
fault：故障。
params
String
事件的参数，在物模型事件中定义。
timestamp
Integer
事件上报的时间，不填写该字段表示默认为当前系统时间。单位为秒。
3. 响应。
响应消息格式：
{
    "method": "event_reply",
    "clientToken": "123",
    "version": "1.0",
    "code": 0,
    "status": "some message where error",
    "data": {}
}
响应参数说明：
参数
类型
说明
method
String
event_reply 表示是云端返回设备端的响应。
clientToken
String
消息 Id，回复的消息将会返回该数据，用于请求响应消息的对比。
version
String
协议版本，默认为1.0。
code
Integer
事件上报结果，0表示成功。
status
String
事件上报结果描述。
data
JSON
事件上报返回的内容。
设备行为调用
1. 当应用通过云端向设备发起某个行为调用时，平台为设备行为的处理设定了默认的 Topic：
应用调用设备行为 Topic： $thing/down/action/{ProductID}/{DeviceName}
设备响应行为执行结果 Topic： $thing/up/action/{ProductID}/{DeviceName}
2. 请求。
应用端发起设备行为调用报文示例：
{					
    "method": "action",			
    "clientToken": "20a4ccfd-d308-****-86c6-5254008a4f10",				
    "actionId": "openDoor",				
    "timestamp": 1212121221,		
    "params": {					
        "userid": "323343"			
    }
}
请求参数说明：
参数
类型
说明
method
String
action 表示是调用设备的某个行为。
clientToken
String
消息 Id，回复的消息将会返回该数据，用于请求响应消息的对比。
actionId
String
actionId 是物模型中的行为标识符，由开发者自行根据设备的应用场景定义。
timestamp
Integer
行为调用的当前时间，不填写则默认为调用行为的当前系统时间，单位为秒。
params
String
行为的调用参数，在物模型的行为中定义。
3. 响应。
响应消息格式：
{			
    "method": "action_reply",		
    "clientToken": "20a4ccfd-d308-11e9-86c6-5254008a4f10",		
    "code": 0,			
    "status": "some message where error",		
    "response": {		  
        "Code":  0			
     }
}
响应参数：
参数
类型
说明
method
String
action_reply 表示是设备端执行完指定的行为向云端回复的响应。
clientToken
String
消息 Id，回复的消息将会返回该数据, 用于请求响应消息的对比。
code
Integer
行为执行结果，0表示成功。
status
String
行为执行失败后的错误信息描述。
response
JSON
设备行为中定义的返回参数，设备行为执行成功后，向云端返回执行结果。
设备基础信息上报
1. 小程序或 App 展示设备详细信息时，一般会展示设备的 MAC 地址、IMEI 号、时区等基础信息。设备信息上报使用的 Topic：
上行请求 Topic： $thing/up/property/{ProductID}/{DeviceName}
下行响应 Topic： $thing/down/property/{ProductID}/{DeviceName}
2. 请求。
设备端请求报文示例：
{
    "method": "report_info",
    "clientToken": "1234567",
    "params": {
        "name": "dev001",
        "imei": "ddd",
        "module_hardinfo": "ddd",      
        "mac": "ddd",
        "device_label": {
            "append_info": "ddddd"
        }
    }
}
请求参数说明：
参数
类型
说明
method
String
report_info 表示设备基础信息上报。
clientToken
String
用于上下行消息配对标识。
imei
String
设备的 IMEI 号信息，非必填项。
mac
String
设备的 MAC 信息，非必填项。
module_hardinfo
String
模组具体硬件型号。
append_info
String
设备商自定义的产品基础信息，以 KV 方式上报。
3. 响应。
云端返回设备端报文示例：
{		
    "method":"report_info_reply",	
    "clientToken":"1234567",	
    "code":0,	
    "status":"success"
}
响应参数说明：
参数
类型
说明
method
String
report_reply 表示云端接收设备上报后的响应报文。
clientToken
String
用于上下行消息配对标识。
code
Integer
0 表示云端成功收到设备上报的属性。
status
String
当 code 非0的时候，提示错误信息。
用户删除设备
1. 当用户在小程序或 App 中删除已绑定成功的设备，平台会下发用户删除设备的通知到设备，设备接收后可根据业务需求自行处理。如网关类设备接收到子设备被删除。
下发用户删除设备 Topic： $thing/down/service/{ProductID}/{DeviceName}
2. 请求。
应用端发起用户删除设备报文示例：
{
    "method": "unbind_device",	
    "clientToken": "20a4ccfd-****-11e9-86c6-5254008a4f10",		
    "timestamp": 1212121221					
}
请求参数说明：
参数
类型
说明
method
String
unbind_device 表示是用户在小程序或 App 中删除或解绑某个设备。
timestamp
Integer
用户删除设备的系统时间戳。
用户绑定设备通知消息
1. 当用户在小程序或 App 中成功绑定设备后，平台会下发设备已被用户绑定的通知消息到设备，设备接收后可根据业务需求自行处理。该消息用于手机应用端通知设备端，无需设备端回复。
下发用户绑定设备通知消息 Topic： $thing/down/service/{ProductID}/{DeviceName}
2. 请求。
应用端发起用户绑定设备通知消息报文示例：
{
    "method": "bind_device",	
    "clientToken": "20a4ccfd-****-11e9-86c6-5254008a4f10",		
    "timestamp": 1212121221					
}
请求参数说明：
参数
类型
说明
method
String
bind_device 表示是用户在小程序或 App 中绑定某个设备。
clientToken
String
用于上下行消息配对标识。
timestamp
Integer
用户绑定设备的系统时间戳。
位置服务围栏告警消息下发
1. 当用户在 控制台 位置服务功能或者小程序、App 中为设备创建并关联了地理电子围栏，设备触发围栏告警条件时，平台会下发围栏告警消息通知到设备，设备接收后可根据业务需求自行处理，如设备收到围栏告警消息，语音播报提醒设备的使用用户或者管理者注意安全。
下发围栏告警消息Topic： $thing/down/service/{ProductID}/{DeviceName}
设备响应回复 Topic： $thing/up/service/{ProductID}/{DeviceName}
2. 云端下发围栏告警消息。
云端下发告警消息报文示例：
{
    "method":"alert_fence_event",
    "clientToken":"xx",
    "timestamp": 0,
    "data": {
        "alert_type":"xx", //事件，In Out InOrOut
        "alert_condition":"xx", //设备绑定围栏的触发条件 In Out InOrOut
        "alarm_time": 0, // 告警时间
        "fence_name":"xx", // 围栏名称
        "long": 0,
        "lat": 0
    }
}
请求参数说明：
参数
类型
说明
method
String
alert_fence_event 表示围栏告警事件。
clientToken
String
用于上下行消息配对标识。
timestamp
Integer
时间戳，单位为秒。
data.alert_type
String
告警事件类型：In 、Out 、InOrOut。
data.alert_condition
String
设备绑定围栏的触发条件In 、Out 、InOrOut。
data.alarm_time
Int
告警时间。
data.fence_name
String
围栏名称。
data.long
Float
经度。
data.lat
Float
纬度。
3. 设备端回复。
设备端返回云端报文示例：
{
    "method":"alert_fence_event_reply",
    "clientToken":"xx",
    "timestamp": 0,
    "code":0,
    "status":"success"
}
响应参数说明：
参数
类型
说明
method
String
alert_fence_event_reply 表示围栏告警回复。
clientToken
String
用于上下行消息配对标识。
timestamp
Int
时间戳。
code
Int
0 表示已经正确处理。
status
String
当 code 非0时，提示错误信息。
错误码
code
说明
400
报文格式非 JSON 格式。
403
错误的 method 标识符或属性、事件、行为标识符与物模型定义的标识符不一致。
405
时间戳错误，当前时间和上报时间相差24小时，注意时间戳是秒。
406
物模型参数输入值数据类型错误或数据超出定义范围。
503
系统内部错误。
﻿
参数	类型	说明
method	String	report 表示设备属性上报。
clientToken	String	用于上下行消息配对标识。
timestamp	Integer	属性上报的时间，格式为 UNIX 系统时间戳，不填写该字段表示默认为当前系统时间。单位为秒。
params	JSON	JSON 结构内为设备上报的属性值。
params.power_switch	Boolean	布尔型属性的值一般为0或1。
params.color	Enum	枚举整型属性的值为整数值，数值类型填写错误或超过枚举项定义范围出现406返回码，表示物模型格式校验错误。
params.brightness	Integer	整数型属性的值为整数值，数值类型填写错误或超过数值范围会出现406返回码，表示物模型格式校验错误。
code	说明
400	报文格式非 JSON 格式。
403	错误的 method 标识符或属性、事件、行为标识符与物模型定义的标识符不一致。
405	时间戳错误，当前时间和上报时间相差24小时，注意时间戳是秒。
406	物模型参数输入值数据类型错误或数据超出定义范围。
503	系统内部错误。
物模型协议

本页目录：

简介

物模型协议

概述

设备属性上报

设备远程控制

获取设备最新上报信息

设备事件上报

设备行为调用

设备基础信息上报

用户删除设备

用户绑定设备通知消息

位置服务围栏告警消息下发

错误码
