设备影子¶

物联网平台提供设备影子功能，用于缓存设备状态。设备在线时，可以直接获取云端指令；设备离线时，上线后可以主动拉取云端指令。

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

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

应用场景:

场景1：网络不稳定，设备频繁上下线
场景2：多程序同时请求获取设备状态
场景3：设备掉线

设备影子JSON文档示例:

{
    "state": {
        "desired": {    % 设备的预期状态,一般是app写
            "color": "RED",
            "sequence": [
                "RED",
                "GREEN",
                "BLUE"
            ]
        },
        "reported": {   % 设备的报告状态,设备写
            "color": "GREEN"
        }
    },
    "metadata": {
        "desired": {
            "color": {
                "timestamp": 1469564492
            },
            "sequence": {
                "timestamp": 1469564492
            }
        },
        "reported": {
            "color": {
                "timestamp": 1469564492
            }
        }
    },
    "timestamp": 1469564492,
    "version": 1
}

实例¶

设备主动上报状态¶

设备在线时，主动上报设备状态到影子，应用程序主动获取设备影子状态。

1.当灯泡lightbulb联网时，使用Topic /shadow/update/a1PbRCFQWfX/lightbulb上报最新状态到影子:

{
  "method": "update",
  "state": {
    "reported": {
      "color": "red"
    }
  },
  "version": 1
}

2.当设备影子接收到灯泡上报状态时，成功更新影子文档:

{
  "state": {
    "reported": {
      "color": "red"
    }
  },
  "metadata": {
    "reported": {
      "color": {
        "timestamp": 1469564492
      }
    }
  },
  "timestamp": 1469564492,
  "version": 1
}

3.影子文件更新后，设备影子会返回结果给设备:

% 成功
{
  "method": "reply",
  "payload": {
    "status": "success",
    "version": 1
  },
  "timestamp": 1469564576
}

% 失败
{
  "method": "reply",
  "payload": {
    "status": "error",
    "content": {
      "errorcode": "${errorcode}",
      "errormessage": "${errormessage}"
    }
  },
  "timestamp": 1469564576
}

应用程序改变设备状态¶

应用程序下发期望状态给设备影子，设备影子将文件下发给设备端。设备根据影子更新状态，并上报最新状态至影子

1.应用程序发消息到Topic /shadow/update/a1PbRCFQWfX/lightbulb/中，要求更改灯泡状态:

{
  "method": "update",
  "state": {
    "desired": {
      "color": "green"
    }
  },
  "version": 2
}

2.设备影子接收到更新请求，更新其影子文档为:

{
  "state": {
    "reported": {
      "color": "red"
    },
    "desired": {
      "color": "green"
    }
  },
  "metadata": {
    "reported": {
      "color": {
        "timestamp": 1469564492
      }
    },
    "desired": {
      "color": {
        "timestamp": 1469564576
      }
    }
  },
  "timestamp": 1469564576,
  "version": 2
}

3.设备影子更新完成后，发送返回结果到Topic/shadow/get/a1PbRCFQWfX/lightbulb中。返回结果信息构成由设备影子决定:

{
  "method": "control",
  "payload": {
    "status": "success",
    "state": {
      "reported": {
        "color": "red"
      },
      "desired": {
        "color": "green"
      }
    },
    "metadata": {
      "reported": {
        "color": {
          "timestamp": 1469564492
        }
      },
      "desired": {
        "color": {
          "timestamp": 1469564576
        }
      }
    }
  },
  "version": 2,
  "timestamp": 1469564576
}

4.因为设备灯泡在线，并且订阅了Topic/shadow/get/a1PbRCFQWfX/lightbulb，所以会收到消息。收到消息后，根据请求文档中desired的值，将灯泡颜色变成绿色。灯泡更新完状态后，上报最新状态到物联网平台:

{
  "method": "update",
  "state": {
    "reported": {
      "color": "green"
    }
  },
  "version": 3
}

5.最新状态上报成功后

5.1设备端发消息到Topic/shadow/update/a1PbRCFQWfX/lightbulb中清空desired属性。消息如下:

{
  "method": "update",
  "state": {
    "desired": "null"
  },
  "version": 4
}

5.2设备影子会同步更新，此时的影子文档如下:

{
  "state": {
    "reported": {
      "color": "green"
    }
  },
  "metadata": {
    "reported": {
      "color": {
        "timestamp": 1469564577
      }
    },
    "desired": {
      "timestamp": 1469564576
    }
  },
  "version": 4
}

设备主动获取影子内容¶

若应用程序发送指令时，设备离线。设备再次上线后，将主动获取设备影子内容

1.灯泡主动发送以下消息到Topic/shadow/update/a1PbRCFQWfX/lightbulb中，获取设备影子中保存的最新状态:

{
    "method": "get"
}

2.当设备影子收到这条消息时，发送最新状态到Topic/shadow/get/a1PbRCFQWfX/lightbulb。灯泡通过订阅该Topic获取最新状态。消息内容如下:

{
  "method": "reply",
  "payload": {
    "status": "success",
    "state": {
      "reported": {
        "color": "red"
      },
      "desired": {
        "color": "green"
      }
    },
    "metadata": {
      "reported": {
        "color": {
          "timestamp": 1469564492
        }
      },
      "desired": {
        "color": {
          "timestamp": 1469564492
        }
      }
    }
  },
  "version": 2,
  "timestamp": 1469564576
}

设备主动删除影子属性¶

若设备端已经是最新状态，设备端可以主动发送指令，删除设备影子中保存的某条属性状态。

发送以下内容到Topic/shadow/update/a1PbRCFQWfX/lightbulb中

1.删除影子中某一属性:

{
  "method": "delete",
  "state": {
    "reported": {
      "color": "null",
      "temperature": "null"
    }
  },
  "version": 1
}

2.删除影子全部属性:

{
  "method": "delete",
  "state": {
    "reported": "null"
  },
  "version": 1
}