# 物模型协议
# 什么是物模型?
物模型协议是指用于描述物联网设备的数据模型和通信协议。它定义了设备的属性(Properties)、事件(Events)和服务(Services),并规定了设备与其他设备或系统之间的通信方式。物模型协议的目的是实现设备之间的互操作性,使不同厂商的设备能够相互通信和协同工作。常见的物模型协议包括物联网领域的标准化协议,如MQTT、CoAP和HTTP等。这些协议提供了一种统一的方式来描述和交换物联网设备的数据。
属性(Properties)
了物联网设备的状态、特征或配置信息。它可以是设备的各种参数、状态、配置或其他相关信息。属性可以是只读的,用于读取设备的当前状态,也可以是可写的,用于修改设备的属性值。
事件(Events)
是物联网设备发生的特定事情或状态变化的通知。设备可以通过触发事件来通知其他设备或系统发生了某种情况。事件可以包含相关的数据和信息,用于传递设备的状态变化或重要通知。
服务(Services)
定义了物联网设备可以提供的特定功能或操作。它描述了设备支持的一组操作,其他设备或系统可以通过调用这些服务来实现与设备的交互。服务可以包含输入参数和输出结果,用于传递操作所需的数据和返回的结果。
# 网关&直连设备
# 属性上报
设备向云端上报设备运行状态的变化时 Topic:
- 设备属性上行请求 Topic:
iotlink/thing/up/${proudctId}/${deviceName}
- 设备属性下行响应 Topic:
iotlink/thing/down/${proudctId}/${deviceName}
- 设备属性上行请求 Topic:
请求。
设备端请求报文示例:
{ "method": "report", "messageId": "42c5324c-2901-4c8b-968c-e7af1015fa8e", "version": "1.0.0", "timestamp": 1693298448345, "params": { "power_switch": 1, "color": "red", "brightness": 32 } }
请求参数说明:
参数 类型 必选 说明 method String 是 上报属性时值固定为report messageId String 是 用于上下行消息配对标识 version String 是 协议版本,默认为1.0.0 timestamp Long 是 当前时间戳 params Object 是 属性值
响应。
云端返回设备端报文示例:
{ "method": "report_reply", "messageId": "42c5324c-2901-4c8b-968c-e7af1015fa8e", "code": 1, "status": "some message where error" }
响应参数说明:
参数 类型 必选 说明 method String 是 report_reply 表示云端接收设备上报属性后的响应报文 messageId String 是 用于上下行消息配对标识 code Integer 是 0表示云端成功收到设备上报的属性 status String 是 当 code 非0的时候,提示错误信息
# 事件上报
设备向云端上报设备事件信息 Topic:
- 设备属性上行请求 Topic:
iotlink/thing/up/${proudctId}/${deviceName}
- 设备属性下行响应 Topic:
iotlink/thing/down/${proudctId}/${deviceName}
- 设备属性上行请求 Topic:
请求。
设备端请求报文示例:
{ "method": "event_post", "messageId": "42c5324c-2901-4c8b-968c-e7af1015fa8e", "identifier": "PowerAlarm", "version": "1.0.0", "timestamp": 1693298448345, "params": { "power_switch": 1, "color": "red", "brightness": 32 } }
请求参数说明:
参数 类型 必选 说明 method String 是 子设备上报属性时值固定为sub_report messageId String 是 用于上下行消息配对标识 version String 是 协议版本,默认为1.0.0 timestamp Long 是 当前时间戳 identifier String 是 事件的 Id,在物模型事件中定义。 devices.params String 是 事件中携带的参数值
响应。
云端返回设备端报文示例:
{ "method": "event_reply", "messageId": "42c5324c-2901-4c8b-968c-e7af1015fa8e", "code": 1, "status": "some message where error" }
响应参数说明:
参数 类型 必选 说明 method String 是 sub_report_reply 表示云端接收设备上报事件后的响应报文 messageId String 是 用于上下行消息配对标识 code Integer 是 0表示云端成功收到设备上报的属性 status String 是 当 code 非0的时候,提示错误信息
# 获取最新上报信息
云端向设备下发指令获取设备最新的属性信息 Topic:
- 设备属性上行请求 Topic:
iotlink/thing/up/${proudctId}/${deviceName}
- 设备属性下行响应 Topic:
iotlink/thing/down/${proudctId}/${deviceName}
- 设备属性上行请求 Topic:
请求。
设备端请求报文示例:
{ "method": "get_status", "messageId": "42c5324c-2901-4c8b-968c-e7af1015fa8e", "version": "1.0.0", "timestamp": 1693298448345, "params": [ "power_switch", "color", "brightness" ] }
请求参数说明:
参数 类型 必选 说明 method String 是 子设备上报属性时值固定为sub_report messageId String 是 用于上下行消息配对标识 version String 是 协议版本,默认为1.0.0 timestamp Long 是 当前时间戳 params Array 是 需要获取的参数值。
响应。
云端返回设备端报文示例:
{ "method": "get_status_reply", "messageId": "42c5324c-2901-4c8b-968c-e7af1015fa8e", "code": 1, "status": "some message where error" }
响应参数说明:
参数 类型 必选 说明 method String 是 get_status_reply 表示设备向云端上报获取属性请求响应 messageId String 是 用于上下行消息配对标识 code Integer 是 0表示云端成功收到设备上报的属性 status String 是 当 code 非0的时候,提示错误信息
# 远程控制
云端下发指令进行设置物模型属性 Topic:
- 设备属性上行请求 Topic:
iotlink/thing/up/${proudctId}/${deviceName}
- 设备属性下行响应 Topic:
iotlink/thing/down/${proudctId}/${deviceName}
- 设备属性上行请求 Topic:
请求。
设备端请求报文示例:
{ "method": "control", "messageId": "42c5324c-2901-4c8b-968c-e7af1015fa8e", "version": "1.0.0", "timestamp": 1693298448345, "params": { "power_switch": 1, "color": "red", "brightness": 32 } }
请求参数说明:
参数 类型 必选 说明 method String 是 设备远程控制时值固定为control messageId String 是 用于上下行消息配对标识 version String 是 协议版本,默认为1.0.0 timestamp Long 是 当前时间戳 params Object 是 需要设置的参数值。
响应。
云端返回设备端报文示例:
{ "method": "control_reply", "messageId": "42c5324c-2901-4c8b-968c-e7af1015fa8e", "code": 1, "status": "some message where error" }
响应参数说明:
参数 类型 必选 说明 method String 是 control_reply 表示设备向云端下发的控制指令的请求响应 messageId String 是 用于上下行消息配对标识 code Integer 是 0表示云端成功收到设备上报的属性 status String 是 当 code 非0的时候,提示错误信息
# 子设备
# 属性上报
子设备向云端上报设备运行状态的变化时 Topic:
- 设备属性上行请求 Topic:
iotlink/thing/up/${proudctId}/${deviceName}
- 设备属性下行响应 Topic:
iotlink/thing/down/${proudctId}/${deviceName}
- 设备属性上行请求 Topic:
请求。
设备端请求报文示例:
{ "method": "sub_report", "messageId": "42c5324c-2901-4c8b-968c-e7af1015fa8e", "version": "1.0.0", "timestamp": 1693298448345, "devices": [ { "productId": "vJlqmfDGN7", "deviceName": "230829001", "params": { "power_switch": 1, "color": "red", "brightness": 32 } }, { "productId": "vJlqmfDGN7", "deviceName": "230829002", "params": { "power_switch": 1, "color": "red", "brightness": 32 } } ] }
请求参数说明:
参数 类型 必选 说明 method String 是 子设备上报属性时值固定为sub_report messageId String 是 用于上下行消息配对标识 version String 是 协议版本,默认为1.0.0 timestamp Long 是 当前时间戳 devices Array 是 子上报列表 devices.productId String 是 子设备的产品id devices.productId String 是 子设备的设备名称 devices.params String 是 子设备上报的数据集
响应。
云端返回设备端报文示例:
{ "method": "sub_report_reply", "messageId": "42c5324c-2901-4c8b-968c-e7af1015fa8e", "code": 1, "status": "some message where error" }
响应参数说明:
参数 类型 必选 说明 method String 是 sub_report_reply 表示云端接收子设备上报属性后的响应报文 messageId String 是 用于上下行消息配对标识 code Integer 是 0表示云端成功收到设备上报的属性 status String 是 当 code 非0的时候,提示错误信息
# 事件上报
子设备向云端上报事件信息 Topic:
- 设备属性上行请求 Topic:
iotlink/thing/up/${proudctId}/${deviceName}
- 设备属性下行响应 Topic:
iotlink/thing/down/${proudctId}/${deviceName}
- 设备属性上行请求 Topic:
请求。
设备端请求报文示例:
{ "method": "sub_event_post", "messageId": "42c5324c-2901-4c8b-968c-e7af1015fa8e", "version": "1.0.0", "timestamp": 1693298448345, "devices": [ { "productId": "vJlqmfDGN7", "deviceName": "230829001", "identifier": "PowerAlarm", "params": { "power_switch": 1, "color": "red", "brightness": 32 } }, { "productId": "vJlqmfDGN7", "deviceName": "230829002", "identifier": "PowerAlarm", "params": { "power_switch": 1, "color": "red", "brightness": 32 } } ] }
请求参数说明:
参数 类型 必选 说明 method String 是 子设备上报属性时值固定为sub_report messageId String 是 用于上下行消息配对标识 version String 是 协议版本,默认为1.0.0 timestamp Long 是 当前时间戳 devices.productId String 是 子设备的产品id devices.deviceName String 是 子设备的设备名称 devices.identifier String 是 子设备事件的标识符 devices.params String 是 子设备事件携带的参数值
响应。
云端返回设备端报文示例:
{ "method": "sub_event_reply", "messageId": "42c5324c-2901-4c8b-968c-e7af1015fa8e", "code": 1, "status": "some message where error" }
响应参数说明:
参数 类型 必选 说明 method String 是 sub_event_reply 表示云端接收子设备上报事件后的响应报文 messageId String 是 用于上下行消息配对标识 code Integer 是 0表示云端成功收到设备上报的属性 status String 是 当 code 非0的时候,提示错误信息
# 获取最新上报信息
云端下发指令网关设备上报子设备的最新属性信息 Topic:
- 设备属性上行 Topic:
iotlink/thing/up/${proudctId}/${deviceName}
- 设备属性下行 Topic:
iotlink/thing/down/${proudctId}/${deviceName}
- 设备属性上行 Topic:
请求。
设备端请求报文示例:
{ "method": "sub_get_status", "messageId": "42c5324c-2901-4c8b-968c-e7af1015fa8e", "version": "1.0.0", "timestamp": 1693298448345, "productId": "vJlqmfDGN7", "deviceName": "230829001", "params": [ "power_switch", "color", "brightness" ] }
请求参数说明:
参数 类型 必选 说明 method String 是 子设备上报属性时值固定为sub_report messageId String 是 用于上下行消息配对标识 version String 是 协议版本,默认为1.0.0 timestamp Long 是 当前时间戳 productId String 是 子设备的产品id deviceName String 是 子设备的设备名称 params String 是 子设备的属性参数
响应。
云端返回设备端报文示例:
{ "method": "sub_get_status_reply", "messageId": "42c5324c-2901-4c8b-968c-e7af1015fa8e", "code": 1, "status": "some message where error" }
响应参数说明:
参数 类型 必选 说明 method String 是 sub_get_status_reply 表示网关设备接收远程控制的响应 messageId String 是 用于上下行消息配对标识 code Integer 是 0表示云端成功收到设备上报的属性 status String 是 当 code 非0的时候,提示错误信息
# 远程控制
云端下发指令网关设备设置子设备的最新属性信息 Topic:
- 设备属性上行 Topic:
iotlink/thing/up/${proudctId}/${deviceName}
- 设备属性下行 Topic:
iotlink/thing/down/${proudctId}/${deviceName}
- 设备属性上行 Topic:
请求。
设备端请求报文示例:
{ "method": "sub_control", "messageId": "42c5324c-2901-4c8b-968c-e7af1015fa8e", "version": "1.0.0", "timestamp": 1693298448345, "devices": [ { "productId": "vJlqmfDGN7", "deviceName": "230829001", "params": { "power_switch": 1, "color": "red", "brightness": 32 } }, { "productId": "vJlqmfDGN7", "deviceName": "230829002", "params": { "power_switch": 1, "color": "red", "brightness": 32 } } ] }
请求参数说明:
参数 类型 必选 说明 method String 是 子设备远程控制时值固定为sub_control messageId String 是 用于上下行消息配对标识 version String 是 协议版本,默认为1.0.0 timestamp Long 是 当前时间戳 devices.productId String 是 子设备的产品id devices.deviceName String 是 子设备的设备名称 devices.params String 是 子设备的属性参数值
响应。
云端返回设备端报文示例:
{ "method": "sub_control_reply", "messageId": "42c5324c-2901-4c8b-968c-e7af1015fa8e", "code": 1, "status": "some message where error" }
响应参数说明:
参数 类型 必选 说明 method String 是 sub_control_reply 表示网关设备接收远程控制的响应 messageId String 是 用于上下行消息配对标识 code Integer 是 0表示云端成功收到设备上报的属性 status String 是 当 code 非0的时候,提示错误信息