设备影子

1.设备影子简介

设备影子是一个 JSON 文档，用于存储设备上报状态、应用程序期望状态信息。

1）每个设备有且只有一个设备影子，设备可以通过MQTT获取和设置设备影子以此来同步状态，该同步可以是影子同步给设备，也可以是设备同步给影子。

2）应用程序通过物联网平台的SDK获取和设置设备影子，获取设备最新状态或者下发期望状态给设备。

2.应用场景

场景一：

由于网络不稳定，设备频繁上下线。应用程序发出需要获取当前的设备状态请求时，设备掉线，无法获取设备状态，但下一秒设备又连接成功，应用程序无法正确发起请求。

使用设备影子机制存储设备最新状态，一旦设备状态产生变化，设备会将状态同步到设备影子。应用程序在请求设备当前状态时，只需要获取影子中的状态即可，不需要关心设备是否在线。

场景二：

如果设备网络稳定，很多应用程序请求获取设备状态，设备需要根据请求响应多次，即使响应的结果是一样的，设备本身处理能力有限，无法负载被请求多次的情况。

使用设备影子机制，设备只需要主动同步状态给设备影子一次，多个应用程序请求设备影子获取设备状态，即可获取设备最新状态，做到应用程序和设备的解耦。

场景三：

设备网络不稳定，导致设备频繁上下线，应用程序发送控制指令给设备时，设备掉线，指令无法下达到设备。

1）通过QoS=1或者2实现，但是该方法对于服务端的压力比较大，一般不建议使用。

2）使用设备影子机制，应用程序发送控制指令，指令携带时间戳保存在设备影子中。当设备掉线重连时，获取指令并根据时间戳确定是否执行。

设备真实掉线，指令发送失败。设备再上线时，设备影子功能通过指令加时间戳的模式，保证设备不会执行过期指令。

3.设备影戏json 详解

Desired：设备的预期状态。应用程序可以向本文档desired部分写入数据来更新事物的状态，且无需直接连接到该设备；

Reported：设备的报告状态。设备可以向本文档reported部分写入数据，报告其最新状态。应用程序可以读取本文档部分，获取设备的状态；

Metadata：这部分当用户更新State文档，设备影子服务会自动更新，不需要用户更新。文档state 部分的元数据的信息，其中包括 state 部分中每个属性的时间戳；

Timestamp：影子文档的最新更新时间

Version：用户主动更新version。

详细内容来自：https://helpcdn.aliyun.com/document_detail/53932.html?spm=a2c4g.11186623.6.627.hJa4Ps

4.设备影子数据流

物联网平台为每个设备预定义了两个Topic实现数据流转，定义的Topic都以固定格式呈现。

·        topic/shadow/update/${productKey}/${deviceName}

设备和应用程序发布消息到此Topic，物联网平台收到该topic的消息后，将消息中的状态更新到设备影子中。

·        topic/shadow/get/${productKey}/${deviceName}

设备影子更新状态到该Topic，设备订阅此Topic的消息。

此处以产品灯泡1号下某个具体灯泡设备为例，productkey:10000；deviceName:lightbulb，设备以QoS=1发布订阅定义的两个Topic，举例说明设备、设备影子以及应用程序之间的通信。

1）设备主动上报状态

a.当灯泡lightbulb联网时，设备使用Topic/shadow/update/10000/lightbulb上报最新状态到影子。

发送的JSON消息格式：

上报参数说明：

method：表示设备或者应用程序请求设备影子时的操作类型。当执行更新操作时，method为必填字段，设置为update。

state：表示设备发送给设备影子的状态信息。reported为必填字段，状态信息会同步更新到设备影子的reported部分。

version：表示设备影子检查请求中的版本信息。只有当新版本大于当前版本时，设备影子才会接受设备端的请求，更新设备影子版本到相应的版本。

b.当设备影子接受到灯泡上报状态时，成功更新影子文档。

c. 更新设备影子之后，设备影子会返回结果给设备（灯泡），即发消息到/shadow/get/10000/lightbulb中，设备订阅该Topic

若更新成功，发送到Topic中的消息为：

若更新失败，发送到Topic中的消息为：

错误码说明：

2）应用程序更改设备状态

a. 应用程序下发指令给设备影子，更改灯泡状态；

b. 应用程序发出更新请求，设备影子更新其文档；

c. 设备影子更新完成后，发送消息到topic/shadow/get/10000/lightbulb中，返回结果给设备，返回结果由设备影子决定其构成；

d. 灯泡在线，并且订阅了topic/shadow/get/10000/lightbulb，就会收到消息，并根据请求文档中desired的值更新状态，将灯泡颜色变成绿色。如果有时间戳判断指令过期，也可以选择不更新；

e. 更新完之后，发消息到topic/shadow/update/10000/lightbulb中上报最新状态；

f. 上报状态成功后，设备影子会同步更新，更新影子文档如下所示：

3）设备主动获取设备影子内容

a. 灯泡获取设备影子中保存的灯泡最新状态，发送固定消息到topic/shadow/update/10000/lightbulb中，具体的消息如下;

b. 当设备影子收到这条消息时，发送消息到topic/shadow/get/10000/lightbulb中，灯泡订阅该topic，获得消息，消息内容如下：

c. SDK使用API IOT_Shadow_Pull 完成获取设备影子的动作。

4）设备端删除影子属性

a. 灯泡想要删除设备影子中保存的灯泡某条属性状态，发送删除影子属性的json内容到topic/shadow/update/10000/lightbulb中，具体的消息如下

删除影子某一属性的 json格式

删除影子全部属性的json格式

删除属性只需要把method置为delete，并且属性的值设置为null即可。

b. SDK使用IOT_Shadow_DeleteAttribute参数，取消设备影子的属性。

设备影子开发：https://helpcdn.aliyun.com/document_detail/74007.html?spm=a2c4g.11186623.6.629.bcmMns