联犀
  • 使用指南
  • 设备接入
  • 联犀协议
godLei6
2024-08-29
目录

物模型协议

# 简介

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

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

# 概述

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

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

# 通用请求参数

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

示例:

{
  "method": "reportInfo",
  "msgToken": "1234567",
  "sys": {
     "noAsk": false,
     "retMsg": true
  }
}
1
2
3
4
5
6
7
8

# 基础

# 设备基础信息上报

  1. 小程序或 App 展示设备详细信息时，一般会展示设备的 MAC 地址、IMEI 号、时区等基础信息。设备信息上报使用的 Topic：
  • 上行请求 Topic： $thing/up/property/{ProductID}/{DeviceName}
  • 下行响应 Topic： $thing/down/property/{ProductID}/{DeviceName}
  1. 请求
  • 设备端请求报文示例：
{
  "method": "reportInfo",
  "msgToken": "1234567",
  "params": {
    "imei": "867183032145472",
    "mac": "8C:85:90:AB:CD:EF",
    "version": "ddd",
    "hardInfo": "ddd",
    "softInfo": "ddd",
    "position": {
      "coordinateSystem": "WGS84",
      "longitude": 116.442501,
      "latitude": 40.03448
    },
    "tags": {
      "aaa": "ddddd",
      "bbb": "ddddd"
    }, 
    "deviceAlias": "xxx"
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
  • 请求参数说明：
参数 类型 必填 说明
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(百度系)
参考解释 (opens new window)
params.position.longitude Double 否 经度坐标(度格式，十进制)
参考解释 (opens new window)
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)
  1. 响应
  • 云端返回设备端报文示例：
{        
  "method":"reportInfoReply",    
  "msgToken":"1234567",    
  "code":200,    
  "msg":"success"
}
1
2
3
4
5
6
  • 响应参数说明：
参数 类型 说明
method String reportReply 表示云端接收设备上报后的响应报文
msgToken String 用于上下行消息配对标识
code Integer 200 表示云端成功收到设备上报的属性
msg String 当 code 非200的时候，提示错误信息

# 设备属性上报

  1. 当设备需要向云端上报设备运行状态的变化时，以通知应用端小程序、App 实时展示或云端业务系统接收设备上报属性数据，物联网开发平台为设备设定了默认的 Topic：
    • 设备属性上行请求 Topic： $thing/up/property/{ProductID}/{DeviceName}
    • 设备属性下行响应 Topic： $thing/down/property/{ProductID}/{DeviceName}
  2. 请求
    • 设备端请求报文示例：
{
  "method":"report",
  "msgToken":"123",
  "timestamp":1677762028638,
  "params":{
    "power_switch":1,
    "color":1,
    "brightness":32
  }
}
1
2
3
4
5
6
7
8
9
10
  • 请求参数说明：
参数 类型 必填 说明
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返回码，表示物模型格式校验错误
  1. 响应
  • 云端返回设备端报文示例：
{
  "method":"reportReply",
  "msgToken":"123",
  "code":200,
  "msg":"some message where error"
}
1
2
3
4
5
6
  • 响应参数说明：
参数 类型 说明
method String reportReply 表示云端接收设备上报后的响应报文
msgToken String 用于上下行消息配对标识
code Integer 200表示云端成功收到设备上报的属性
msg String 当 code 非200的时候，提示错误信息

# 请求设备上报属性

  1. 需要主动请求设备上报的时候需要用以下方式上报 Topic：
  • 设备属性下行响应 Topic： $thing/down/property/{ProductID}/{DeviceName}
  • 设备属性上行请求 Topic： $thing/up/property/{ProductID}/{DeviceName}
  1. 请求
    • 云端请求报文示例：
{
  "method":"getReport",
  "msgToken":"123",
  "timestamp":1677762028638,
  "identifiers":["power_switch","color","brightness"]
}
1
2
3
4
5
6
  • 请求参数说明：
参数 类型 必填 说明
method String 是 report 表示设备属性上报
msgToken String 是 用于上下行消息配对标识
timestamp Integer 否 属性上报的时间，格式为 UNIX 系统时间戳，不填写该字段表示默认为当前系统时间。单位为毫秒
identifiers array.String 否 内为希望设备上报的属性列表,不填为获取全部
  1. 响应
  • 设备端返回报文示例：
{
  "method":"getReportReply",
  "msgToken":"123",
  "timestamp":1677762028638,
  "data":{
    "power_switch":1,
    "color":1,
    "brightness":32
  },
  "code":200,
  "msg":"some message where error"
}
1
2
3
4
5
6
7
8
9
10
11
12
  • 响应参数说明：
参数 类型 说明
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返回码，表示物模型格式校验错误

# 设备远程控制

  1. 使用物模型协议的设备，当需要通过云端控制设备时，设备需订阅下发 Topic 接收云端指令：
  • 下发 Topic： $thing/down/property/{ProductID}/{DeviceName}
  • 响应 Topic： $thing/up/property/{ProductID}/{DeviceName}
  1. 请求
  • 远程控制请求消息格式：
{
  "method": "control",
  "msgToken": "123",    
  "params": {
    "power_switch": 1,
    "color": 1,
    "brightness": 66    
  }
}
1
2
3
4
5
6
7
8
9
  1. 请求参数说明：
参数 类型 必填 说明
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返回码，表示物模型格式校验错误
  1. 响应
    • 设备响应远程控制请求消息格式：
{
  "method":"controlReply",
  "msgToken":"123",
  "code":200,
  "msg":"some message where error"
}
1
2
3
4
5
6
  • 请求参数说明：
参数 类型 说明
method String 表示设备向云端下发的控制指令的请求响应
msgToken String 用于上下行消息配对标识
code Integer 200表示设备成功接收到云端下发的控制指令
msg String 当 code 非200的时候，提示错误信息

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

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

  1. 设备从云端接收最新消息使用的 Topic：
  • 请求 Topic： $thing/up/property/{ProductID}/{DeviceName}
  • 响应 Topic： $thing/down/property/{ProductID}/{DeviceName}
  1. 请求
  • 请求消息格式：
{
  "method": "getStatus",
  "msgToken": "123",
  "identifiers":["power_switch","color","brightness"]
}
1
2
3
4
5
  • 请求参数说明：
参数 类型 必填 说明
method String 是 getStatus 表示获取设备最新上报的信息
msgToken String 是 消息 Id，回复的消息将会返回该数据，用于请求响应消息的对比
identifiers array.String 否 内为希望设备上报的属性列表,不填为获取全部
  1. 响应
  • 响应消息格式：
{
  "method": "getStatusReply",
  "code": 200,
  "msgToken": "123",
  "data": {
    "power_switch": 1,
    "color": 1,
    "brightness": 66
  }
}
1
2
3
4
5
6
7
8
9
10
  • 响应参数说明：
参数 类型 说明
method String 表示获取设备最新上报信息的 reply 消息
msgToken String 消息 Id，回复的消息将会返回该数据，用于请求响应消息的对比
code Integer 200标识云端成功收到设备上报的属性
data JSON 返回具体设备上报的最新数据内容

# 设备事件上报

  1. 当设备需要向云端上报事件时，如上报设备的故障、告警数据，平台为设备设定了默认的 Topic：
  • 设备事件上行请求 Topic： $thing/up/event/{ProductID}/{DeviceName}
  • 设备事件上行响应 Topic： $thing/down/event/{ProductID}/{DeviceName}
  1. 请求
  • 设备端请求报文示例：
{
  "method":"eventPost",
  "msgToken":"123",
  "version":"1.0",
  "eventID":"PowerAlarm",
  "type":"fault",
  "timestamp":1677762028638,
  "params":{
    "Voltage":2.8,
    "Percent":20
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
  • 请求参数说明：
参数 类型 必填 说明
method String 是 eventPost 表示事件上报
msgToken String 是 消息 Id，回复的消息将会返回该数据，用于请求响应消息的对比
version String 否 协议版本，默认为1.0
eventID String 是 事件类型。info：信息,alert：告警,fault：故障
type String 是 表示获取什么类型的信息。report 表示设备上报的信息
  1. 响应
  • 响应消息格式：
{
  "method": "eventReply",
  "msgToken": "123",
  "version": "1.0",
  "code": 200,
  "msg": "some message where error",
  "data": {}
}
1
2
3
4
5
6
7
8
  • 响应参数说明：
参数 类型 说明
method String eventReply 表示是云端返回设备端的响应
msgToken String 消息 Id，回复的消息将会返回该数据，用于请求响应消息的对比
version String 协议版本，默认为1.0
code Integer 事件上报结果，200表示成功
msg String 事件上报结果描述
data JSON 事件上报返回的内容

# 设备行为调用

  1. 当应用通过云端向设备发起某个行为调用或设备向应用发起某个行为调用时，平台为设备行为的处理设定了默认的 Topic：
  • 应用调用设备行为或服务端响应设备请求执行结果 Topic： $thing/down/action/{ProductID}/{DeviceName}
  • 设备响应行为执行结果或设备请求服务端行为 Topic： $thing/up/action/{ProductID}/{DeviceName}
  1. 请求
  • 应用端发起设备行为调用报文示例：
{                    
  "method": "action",            
  "msgToken": "20a4ccfd-d308-****-86c6-5254008a4f10",                
  "actionID": "openDoor",                
  "timestamp": 1677762028638,        
  "params": {                    
    "userid": "323343"            
  }
}
1
2
3
4
5
6
7
8
9
  • 请求参数说明：
参数 类型 必填 说明
method String 是 action 表示是调用设备的某个行为
msgToken String 是 消息 Id，回复的消息将会返回该数据，用于请求响应消息的对比
actionID String 是 actionID 是物模型中的行为标识符，由开发者自行根据设备的应用场景定义
timestamp Integer 否 行为调用的当前时间，不填写则默认为调用行为的当前系统时间，单位为毫秒
params String 是 行为的调用参数，在物模型的行为中定义
  1. 响应
  • 响应消息格式：
{            
  "method": "actionReply",        
  "msgToken": "20a4ccfd-d308-11e9-86c6-5254008a4f10",        
  "code": 200,            
  "msg": "some message where error",        
  "data": {          
    "Code":  20            
  }
}
1
2
3
4
5
6
7
8
9
  • 响应参数说明：
参数 类型 说明
method String actionReply 表示是设备端执行完指定的行为向云端回复的响应
msgToken String 消息 Id，回复的消息将会返回该数据，用于请求响应消息的对比
code Integer 行为执行结果，200表示成功
msg String 行为执行失败后的错误信息描述
data JSON 设备行为中定义的返回参数，设备行为执行成功后，向云端返回执行结果

# 设备批量上报属性、事件

  1. 设备批量上报属性及事件,网关类型还可以上报旗下子设备的属性及事件。设备信息上报使用的 Topic：
  • 上行请求 Topic： $thing/up/property/{ProductID}/{DeviceName}
  • 下行响应 Topic： $thing/down/property/{ProductID}/{DeviceName}
  1. 请求
  • 设备端请求报文示例：
{
   "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
               }
            }
         ]
      }
   ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
  • 请求参数说明：
参数 类型 必填 说明
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为属性的值
  1. 响应
  • 云端返回设备端报文示例：
{        
  "method":"packReportReply",    
  "msgToken":"1234567",    
  "code":200
}
1
2
3
4
5
  • 响应参数说明：
参数 类型 说明
method String reportReply 表示云端接收设备上报后的响应报文
msgToken String 用于上下行消息配对标识
code Integer 200 表示云端成功收到设备上报的属性
msg String 当 code 非200的时候，提示错误信息
上次更新: 2025/02/17, 09:47:32
设备动态注册
OTA升级

← OTA升级→

Theme by Vdoing | Copyright © 2022-2025 昆明云物通科技有限公司|GNU | 滇ICP备2024043132号-1 |