主页

Index

Module Index

Search Page

目录

设备影子

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

设备影子是一个 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
}

主页

Index

Module Index

Search Page