一、描述

如果您为产品定义了物模型，设备可以根据物模型来上报属性和事件，以进行设备状态监测、实时数据展示 或 使用平台设备消息流转功能将消息流转至您的服务器。服务端也可以通过下发设置属性和调用行为的指令，来对设备进行控制。

• 物模型功能定义数据类型为float时，对应参数值（即使值为整数）至少携带一位小数位。例如10.0、11.1。
• 设备上、下行通信中的消息ID（id）在当前设备中具有唯一性，且在每天内的消息中保证唯一即可。
• 物联网平台云端下行消息中id用于异步下行消息匹配设备端的返回响应，由物联网平台系统保证每天的唯一性。设备端上行消息中id需由设备端自行保证每天的唯一性。

二、数据交互图

三、通讯协议

3.1 通讯方式

3.2 Topic定义

3.3 method 枚举

四、场景示例

示例以灯泡设备为例，属性为灯泡的颜色，定义属性名为 color ，值有 red、green等值。

4.1 设备上报属性当前值

1. 上报物模型属性值

设备属性/状态变更，根据业务判断出需将数据上报服务端时使用Topic:/${productId}/${deviceId}/thing/property/up 上报。

发送的JSON格式如下：

{
  "method":"reported",
  "messageId":"157889065984",
  "property":{
      "default":{
        "color":{
              "value":"red",
              "time": 1686279797398
        }
    }
  }
}

字段说明：

2. 校验属性值后保存属性信息

物模型服务接收到属性上报消息后，会根据物模型的TSL文件进行校验属性的类型、长度等，如校验通过，则进行保存，不通过则响应错误信息。

3. 返回上报物模型属性结果

物模型服务处理上报物模型消息后，发送结果到Topic：/${productId}/${deviceId}/thing/property/up/reply

1）若成功保存，发送到该Topic的消息格式如下：

{
    "messageId":"157889065984",
    "method":"reported",
    "payload":{
        "code":0
    }
}

2）若保存失败，发送到该Topic的消息格式如下：

{
    "messageId":"157889065984",
    "method":"reported",
    "payload":{
        "code": ${errorcode},
        "msg": "${errormessage}"
    }
}

4. 发送物模型属性更改

物模型服务在成功保存属性后，将尝试下发物模型属性变更到Topic:/${productId}/${deviceId}/thing/property/down，如 应用在线 并 订阅了该Topic，则能实时获取到变更消息。

发送到该Topic的JSON格式如下：

{
  "method":"reported",
  "messageId":"157889065985",
  "property":{
      "default":{
      "color":{
          "value":"red",
          "time": 1686279797398
       }
    }
  }
}

字段说明：

4.2 设置属性值

说明：物联网领域指令下发和设备收到并执行命令是异步的，因此大多数应用程序（米家App、石头App等）采用异步控制交互方式。若应用程序的交互需要实现类似互联网领域请求响应式的同步控制交互，可参照下述方案：

• 应用程序：通过HTTP接口查询设备在线状态，在设备在线时进行才允许进行设置属性值。
• 应用程序：通过HTTP接口或 Topic:/${productId}/${deviceId}/thing/property/up 在设置物模型数值指令发送后进入loading/变更UI状态。若收到物模型服务的设置物模型属性异常，则停止loading并进行对应错误码提示，异常错误码请看 错误码枚举。
• 设备端：在收到物模型属性设置消息后执行属性值对应的业务逻辑，通过上报物模型属性值 Topic:/${productId}/${deviceId}/thing/property/up 进行上报。
• 应用程序：
  • 若在一定时间范围（建议为5s）内通过 Topic:/${productId}/${deviceId}/thing/property/down 订阅到设备上报的属性值，则结束loading并根据 “设备上报的属性当前值” 判断是否符合用户控制的预期进行对应提示。
  • 若在时间范围内未收到 “设备上报的属性值”，则提示“设备响应超时”并主动从云端获取设备属性快照以恢复UI状态 。

1. 设置物模型属性值

重要：因为云端下发属性设置命令和设备收到并执行该命令是异步的，所以调用该接口时，返回的成功结果只表示云端下发属性设置的请求成功，不能保证设备端收到并执行了该请求。即需设备端 / 设备端SDK成功响应云端设置设备属性值的请求，设备属性值才能真正设置成功。设备上报属性说明，请参见本文设备上报属性值。

应用程序使用Topic：/${productId}/${deviceId}/thing/property/up 为设备设置具体属性。发送的JSON格式如下：

{
  "method":"set",
  "messageId":"157889065986",
  "property":{
      "default":{
        "color":{
          "value":"red",
            "time": 1686279797398
        }
    }
  }
}

字段说明：

2. 校验属性值后保存属性信息

物模型服务接收到设置属性的消息后，会根据物模型的TSL文件进行校验属性的类型、长度等，如校验通过，则进行保存，不通过则响应错误信息。

3. 返回设置物模型属性结果

物模型服务在验证通过TSL后，会返回设置物模型属性结果到Topic：/${productId}/${deviceId}/thing/property/up/reply。

1）若成功设置，发送到该Topic的JSON格式如下：

{
    "messageId":"157889065986",
    "method":"set",
    "payload":{
        "code":0,
        "downMessageId":"15788906598611241"
    }
}

2）若获取失败，发送到该Topic的消息为：

{
    "messageId":"157889065986",
    "method":"set",
    "payload":{
        "code": ${errorcode},
        "msg": "${errormessage}"
    }
}

字段说明：

4. 下发物模型属性设置消息

物模型服务在验证设置消息通过后，下发设置消息到Topic:/${productId}/${deviceId}/thing/property/down,发送的JSON格式如下：

{
  "method":"set",
  "messageId":"157889065987",
  "property":{
     "default":{
        "color":{
           "value":"red",
           "time": 1686279797398
        }
    }

  }
}

字段说明：

5. 返回下发物模型属性设置结果

设备收到属性下发消息后可选择通过本地物模型TSL进行数据校验，校验后返回本次下发物模型属性设置结果，并发送到Topic:/${productId}/${deviceId}/thing/property/down/reply中。

备注：因为服务端已进行数据格式校验了，设备端可以选择不对下行数据进行校验。

1）若成功设置，发送到该Topic的JSON格式如下：

{
    "messageId":"157889065987",
    "method":"set",
    "payload":{
        "code":0
    }
}

2）若获取失败，发送到该Topic的消息为：

{
    "messageId":"157889065987",
    "method":"set",
    "payload":{
        "code": ${errorcode},
        "msg": "${errormessage}"
    }
}

字段说明：

6. 执行属性对应业务逻辑

设备收到数据后，根据属性对应的业务进行业务逻辑处理。

7. 上报物模型属性信息

设备执行业务逻辑后，需要上报最新的物模型属性值，整体步骤参考上报属性值，文档内不再赘述。

4.3 设置属性期望值

在一些不关注设备在离线状态、关注属性最终一致的场景，可以通过设置期望属性值来控制设备。

• 在云端设置设备期望属性值后，若设备在线，将实时更新设备属性状态；
• 若设备离线，期望属性值将缓存云端，待设备上线后，获取期望属性值，并更新属性状态。

1. 设置物模型属性期望值

应用程序进行操作物模型属性后，使用Topic: /${productId}/${deviceId}/thing/property/up 设置对应属性期望值，发送的JSON格式如下：

{
  "method":"setDesired",
  "messageId":"157889065986",
  "property":{
      "default":{
        "color":{
              "value":"bulue",
              "time": 1686279797398
         }    
    }

  }
}

字段说明：

2. 校验属性期望值后保存物模型属性期望值

物模型服务接收到设置属性期望值消息后，会根据物模型的TSL文件进行校验属性的类型、长度等，如校验通过，则进行保存，不通过则响应错误信息。

3. 下发物模型属性期望值设置消息

3.1 返回设置物模型属性设置期望值结果

物模型服务处理物模型属性设置期望值消息后，发送结果到Topic:/${productId}/${deviceId}/thing/property/up/reply中。

1）若成功设置，发送到该Topic的JSON格式如下：

{
    "messageId":"157889065986",
    "method":"setDesired",
    "payload":{
        "code":0
    }
}

2）若设置失败，发送到该Topic的消息为：

{
    "messageId":"157889065986",
    "method":"setDesired",
    "payload":{
        "code": ${errorcode},
        "msg": "${errormessage}"
    }
}

字段说明：

3.2 下发物模型属性设置消息

物模型服务成功处理设置属性期望值后，会尝试发送一条设置属性值消息到设备，如设备在线，则能直接收到设置消息进行处理。数据交互过程请看下发设置属性值

4. 获取属性期望值

设备在重新联网后，可发送消息到Topic:/${productId}/${deviceId}/thing/property/up主动获取属性的期望值，发送的JSON格式如下：

{
  "method":"getDesired",
  "messageId":"157889065988",
  "properties": {
        "default":[
             "power",
              "color"
        ]
    }
}

字段说明：

6. 返回属性对应期望值信息

物模型服务获取属性对应的期望值后，发送结果到Topic:/${productId}/${deviceId}/thing/property/up/reply中。

1）若成功获取，发送到该Topic的JSON格式如下：

{
    "method":"getDesired",
    "messageId":"157889065988",
    "payload":{
        "code":0,
        "default":{
            "color":{
                "value":"bulue",
                "time": 1686279797398
            },
            "power":{
                "value":1,
                "time": 1686279797398
             }
        }
    }
}

2）若设置失败，发送到该Topic的消息为：

{
    "messageId":"157889065988",
    "method":"getDesired",
    "payload":{
        "code": ${errorcode},
        "msg": "${errormessage}"
    }
}

字段说明：

7. 根据期望值进行逻辑执行

设备在获取到属性期望值后，进行本地的逻辑执行。可以是直接处理业务，也可以是处理业务后上报属性当前值的更新。

8. 删除物模型属性期望值

设备或应用程序在属性期望值已经无效后，可发送消息到Topic:/${productId}/${deviceId}/thing/property/up。

删除属性期望值，发送的JSON格式如下：

{
  "method":"deleteDesired",
  "messageId":"157889065990",
  "property":{
      "default":{
        "color":{
            "time":1686105184915
        }    
    }

  }
}

字段说明：

删除属性期望值并且上报属性值，发送的JSON格式如下：

{
  "method":"reportedAndDeleteDesired",
  "messageId":"157889065990",
  "property":{
      "default":{
        "color":{
            "value":"red",
            "time":1686105184919
        }
    }
  }
}

注意：上报并且删除期望值，服务器会同时校验该属性的上报值和期望值的最新更新时间，如任一值不满足，则提示版本冲突，不进行处理

字段说明：

注意：删除期望值的责任可以根据具体的应用场景和设计选择由应用程序或设备端来承担。

1. 应用程序删除期望值：应用程序通常具有更高级别的控制权限，因此可以负责管理期望值的创建、更新和删除。应用程序可以根据业务需求和用户操作来决定何时删除特定的期望值。例如:

   • 智能家居应用程序：假设您的智能家居应用程序允许用户设置温度期望值。当用户通过应用程序调整温度设定并保存时，应用程序可以发送请求到物模型服务，删除之前设置的温度期望值。
   • 任务管理应用程序：假设您的任务管理应用程序允许用户设置提醒期望值。当用户完成任务或取消提醒时，应用程序可以向物模型服务发送请求，删除相关的提醒期望值。

2. 设备端删除期望值：设备端通常负责执行实际的操作和状态管理，并根据期望值来调整自身的状态。设备端可以根据内部逻辑或传感器数据来判断何时达到期望状态，然后删除相应的期望值。

   • 温湿度控制设备：假设您的应用程序系统具有温度和湿度控制的期望值。当温室内的温度和湿度达到预设的目标范围时，设备端可以根据实际情况删除相应的温度和湿度期望值。
   • 智能窗帘/智能灯具设备：当用户设置窗帘关闭的期望值时，设备端可能会逐渐减慢窗帘的运动速度，以确保平稳地关闭窗帘，而不是突然停止。这种情况下，设备端会根据内部逻辑和控制算法，逐步调整设备的行为。当满足期望值后删除期望值。

9. 删除物模型属性期望值

物模型服务接收到删除属性期望值消息后，进行删除物模型属性期望值。

10. 返回删除物模型属性期望值结果

物模型服务删除属性对应的期望值后，发送结果到Topic:/${productId}/${deviceId}/thing/property/up/reply中。

1）若成功删除，发送到该Topic的JSON格式如下：

{
    "messageId":"157889065986",
    "method":"deleteDesired",
    "payload":{
        "code":0
    }
}

2）若删除失败，发送到该Topic的消息为：

{
    "messageId":"157889065986",
    "method":"deleteDesired",
    "payload":{
        "code": ${errorcode},
        "msg": "${errormessage}"
    }
}

字段说明：

4.4 获取设备属性值

1. 发送获取属性值消息

应用程序在希望通过物模型服务直接获取到设备属性的最新值时，可发送消息到Topic:/${productId}/${deviceId}/thing/property/up，发送的JSON格式如下：

{
  "method":"get",
  "messageId":"157889065989",
  "properties": {
        "default":[
              "power",
               "color"
         ]
   }
}

字段说明：

2. 校验属性物模型

物模型服务在接受到获取属性值消息之后，对传入的属性标识符进行校验，只有读写类型为 “读&上报“ 才可以进行主动获取操作。

3. 下发获取属性值消息

物模型服务在进行校验属性物模型之后，发送结果到Topic:/${productId}/${deviceId}/thing/property/up/reply中。

1）若成功获取，发送到该Topic的JSON格式如下：

{
    "method":"get",
    "messageId":"157889065989",
    "payload":{
        "code":0,
    }
}

2）若设置失败，发送到该Topic的消息为：

{
    "messageId":"157889065989",
    "method":"get",
    "payload":{
        "code": ${errorcode},
        "msg": "${errormessage}"
    }
}

如校验通过，物模型服务还将下发获取属性指令消息到Topic:/${productId}/${deviceId}/thing/property/down，发送到该Topic的JSON格式如下：

{
  "method":"get",
  "messageId":"157889065989",
  "properties": {
        "default":[
              "power",
               "color"
         ]
   }
}

4. 校验物模型

如设备在线，收到获取属性消息后，对获取的属性进行校验。

5. 上报属性

设备上报属性值步骤上报物模型属性当前信息。

4.5 获取设备属性上报频率

1. 发送获取属性值消息

设备在获取物模型属性的最新上报频率时，可发送消息到Topic:/${productId}/${deviceId}/thing/property/up，发送的JSON格式如下：

{
  "method":"getFrequency",
  "messageId":"157889065989",
  "properties": {
        "default":[
              "power",
               "color"
         ]
   }
}

字段说明：

2. 下发获取属性频率信息

物模型服务在进行校验属性物模型之后，发送结果到Topic:/${productId}/${deviceId}/thing/property/up/reply中。

1）若成功获取，发送到该Topic的JSON格式如下：

{
    "method":"getFrequency",
    "messageId":"157889065989",
    "payload":{
        "code":0,
        "default":{
            "power":5
        }
    }
}

2）若获取失败，发送到该Topic的消息为：

{
    "messageId":"157889065989",
    "method":"getFrequency",
    "payload":{
        "code": ${errorcode},
        "msg": "${errormessage}"
    }
}

字段说明：

五、错误码枚举