基于设备影子Topic通讯

背景信息

• 设备影子功能的更多信息，请参见 设备影子。
• 完整的设备影子数据流及错误码，请参见 设备影子数据流。
• 设备影子功能基于MQTT接入，开发过程中涉及MQTT接入的代码说明，请参见 MQTT接入。

步骤一：设备主动获取设备影子内容

若应用程序发送指令时设备离线，设备重连MQTT后，需要主动获取设备影子内容。

1. 设备通过Topic:/${productId}/${deviceId}/shadow/update，向物联网平台发送查询指令，获取设备影子内容。请求内容如下：

{
  "method":"get",
  "messageId":"157065985"
}

字段说明

2. 物联网平台收到查询指令后，返回查询结果。下发到Topic:/${productId}/${deviceId}/shadow/get中，消息示例：

{
  "method": "reply",
  "messageId":"157065985",
  "payload": {
    "code": 0,
    "state": {
    },
    "metadata": {
    }
},
  "timestamp": 0
}

字段说明

示例消息表示请求发送成功，获取的消息值未空，未上报过消息。

步骤二：设备主动上报状态

设备在线时，若设备状态有变更，应当主动上报设备状态到影子，以便应用程序主动获取设备影子状态。

1. 设备调用Topic:/${productId}/${deviceId}/shadow/update 向物联网平台上报最新状态到影子。上报消息示例：

{
  "method":"update",
  "messageId":"157889065985",
  "state":{
    "reported": {    
          "color": "red"
     }
  },
  "timestamp": 0
}

字段说明

2. 物联网平台接收到设备影子的消息后，更新影子文件。然后通过Topic:/${productId}/${deviceId}/shadow/get ，进行广播设备影子更新事件。

{
    "method":"update",
    "messageId":"157889065985",
    "payload":{
        "code":0,
        "state":{
            "reported":{
                "color":"red"
            }
        },
        "metadata":{
            "reported":{
                "color":{
                    "timestamp":1626317187000
                }
            }
        }
    },
    "timestamp":1626317187000
}

字段说明

表示响应失败,并返回具体错误码和错误消息。

{
    "method":"reply",
    "messageId":"157889065985",
    "payload":{
        "code": ${errorcode},
        "msg": "${errormessage}"
     }
}

表示影子版本冲突导致响应失败。设备影子服务会返回云端设备影子更新时间，设备端应保存该设备影子最新更新时间。然后设备端应当检查当前messageId对应的上报数值是否与本地属性值一致，如一致则使用设备影子最新更新时间再次进行上报更新，如不一致则丢弃该上报消息。

{
    "method":"reply",
    "messageId":"157889065985",
    "payload":{
        "code":900010,
        "msg":"影子版本冲突。"
    },
    "timestamp":1626317187000
}

步骤三：应用程序改变设备状态

应用程序向设备影子发送期望属性，最终实现改变设备状态。

1. 下发期望状态给设备影子。

   • 可以开发云端应用程序，调用API下发设备影子期望属性，详细说明，请参见下发设备影子期望值。

2. 物联网平台根据下发的期望状态消息更新影子内容，然后通过Topic:/${productId}/${deviceId}/shadow/get 向设备返回应答报文。下发期望状态的消息示例：

   {
   "method":"control",
   "messageId":"157889865984",
   "payload":{
     "code": 0,
    "state":{
        "desired":{
            "color":"green"
        }
    },
    "metadata":{
        "desired":{
            "color": {
                "timestamp": 1369564576000
            }
        }
    }
   },
   "timestamp":1369564576000
   }

如果设备不在线，具体操作，请参见步骤一
示例消息为设置期望color属性值为green

3. 设备根据期望值进行状态更新/业务处理，更新完成后上报最新的状态至设备影子，并处理应答报文。具体操作，请参见步骤二。