更新时间:2023-06-07 GMT+08:00
分享

设备影子

概述

物联网平台支持创建设备的“影子”。设备影子是一个JSON文件,用于存储设备的在线状态、设备最近一次上报的设备属性值、应用服务器期望下发的配置。每个设备有且只有一个设备影子,设备可以获取和设置设备影子以此来同步设备属性值,这个同步可以是影子同步给设备,也可以是设备同步给影子。

设备影子上有desired区和reported区。
  • desired区用于存储对设备属性的配置,即期望值。当需要修改设备的服务属性值时,可修改设备影子的desired区的属性值,设备在线时,desired属性值立即同步到设备。如果设备不在线,待设备上线或上报数据时,desired属性值同步到设备。
  • reported区用于存储设备最新上报的设备属性值,即上报值。当设备上报数据时,平台刷新reported区属性值为设备上报的设备属性值。
    • 设备影子可以通过调用应用侧API接口配置,也可以通过登录控制台,在设备详情->设备影子->属性配置页面配置。(设备影子主要针对设备属性配置,它的配置依赖产品模型)。
    • 设备影子配置属于异步命令,物联网平台会直接回复配置响应,然后平台通过设备在线状态,决定立即下发还是缓存下发。
    • 设备上线后,影子服务会下发desired值给设备,待设备属性上报时,影子服务检查属性值与下发的desired值是否匹配。若匹配,则说明影子数据在设备侧配置成功,缓存清除;若不匹配,则说明影子数据在设备侧未配置成功,在下次设备上线或属性上报时,会继续下发缓存desired值给设备,直到下发配置成功。
    • 限制:设备影子JSON文档中的key不允许特殊字符:点(.)、dollar符号($)、空char(十六进制的ASCII码为00)。如果包含了以上特殊字符则无法正常刷新影子文档。
    • 设备影子desired配置给设备后,需要设备回响应表示已收到请求。如果设备不回响应(平台则认为设备侧未适配影子设置流程,平台设置设备属性),则平台有个5 分钟的保护期,避免过多流量冲击设备,保护期内设备属性上报时,平台比对reported和desired即使有差异,也不会下发差值。设备正常适配下发流程中的属性设置响应,平台则每次属性上报都会将差值下发给设设备。

应用场景

适合资源受限低功耗设备,长期处于休眠状态的场景。

  • 查询设备最新上报数据和设备最新在线状态:

    • 当在控制台上查询设备上报数据时,由于设备可能长时间处于离线状态或因网络不稳定掉线,而无法获取到最新数据。通过设备影子机制,设备影子中始终保持设备最新上报的数据和设备当前状态,控制台上只需要查询设备影子中存储的数据,即可获取设备最新上报的数据和设备状态。

    • 很多应用服务器频繁的查询设备在线状态,由于设备处理能力有限,频繁查询会损耗设备性能。使用设备影子机制,设备只需要主动同步状态给设备影子一次,多个应用程序请求设备影子获取设备状态,即可获取设备最新状态,从而将应用程序和设备解耦。
  • 修改设备属性值:用户通过设备 > 设备详情 > 设备影子修改设备的属性值。由于设备可能长时间处于离线状态,修改设备属性值的操作不能及时下发给设备。在这种情况下,物联网平台可以将修改设备的属性信息存储在设备影子中,待设备上线后,将修改的设备属性值同步给设备,从而完成设备属性值的修改。

业务流程

修改设备属性值

修改desired区属性值,如果设备在线,则设备影子直接同步设备属性值到设备,否则等待设备上线或上报数据时,再同步设备属性值到设备。

  1. 用户通过控制台或应用服务器修改设备属性值。消息样例如下:
    PUT https://{Endpoint}/v5/iot/{project_id}/devices/{device_id}/shadow
    Content-Type: application/json
    X-Auth-Token: ********
    Instance-Id: ********
    
    {
      "shadow" : [ {
        "desired" : {
          "temperature" : "60"
        },
        "service_id" : "WaterMeter",
        "version" : 1
      } ]
    }
  2. 物联网平台修改desired区属性值。
  3. 物联网平台返回响应消息。
  4. 物联网平台判断设备上线或上报数据。
  5. 物联网平台将设备属性同步到设备。消息样例如下:
    Topic: $oc/devices/{device_id}/sys/properties/set/request_id={request_id} 
    数据格式:  
    {
        "object_device_id": "{object_device_id} ",
        "services": [
            {
                "service_id": "Temperature",
                "properties": {
                    "value": 57,
                    "value2": 60
                }
            },
            {
                "service_id": "Battery",
                "properties": {
                    "level": 80,
                    "level2": 90
                }
            }
        ]
    }
  6. 设备返回响应消息。设备影子desired区的属性值发送给设备后,需要设备回响应表示已收到请求。消息样例如下:
    Topic:$oc/devices/{device_id}/sys/properties/set/response/request_id={request_id}
    数据格式:  
    {
        "result_code": 0,
        "result_desc": "success"
    }

7.设备上报数据,当设备进行属性上报时,平台会存储设备最新上报的设备属性值。

  • 设备上报属性时,物联网平台修改设备影子reported区属性值为设备上报的设备属性值。消息样例如下:
Topic: $oc/devices/{device_id}/sys/properties/report   
数据格式:
{
    "services": [
        {
            "service_id": "Temperature",
            "properties": {
                "value": 57,
                "value2": 60
            },
            "event_time": "20151212T121212Z"
        },
        {
            "service_id": "Battery",
            "properties": {
                "level": 80,
                "level2": 90
            },
            "event_time": "20151212T121212Z"
        }
    ]
}
  • 设备主动删除设备影子的reported区
    • 设备主动删除reported区service下的单个属性
      设备上报属性时,将属性设置为null,平台会将该属性从设备影子reported区删除,消息样例如下:
      Topic: $oc/devices/{device_id}/sys/properties/report  
      {
          "services": [
              {
                  "service_id": "Temperature",
                  "properties": {
                      "value": null,
                      "value2": 60
                  },
                  "event_time": "20151212T121212Z"
              }
          ]
      }
    • 设备主动删除影子reported区的service下的全部的属性
      设备上报属性时,将service对应的properties设置为{}时,平台会将reported区该service模块下所有属性从设备影子reported区删除,消息样例如下:
      Topic: $oc/devices/{device_id}/sys/properties/report 
      {
          "services": [
              {
                  "service_id": "Temperature",
                  "properties": {},
                  "event_time": "20151212T121212Z"
              }
          ]
      }

查询设备属性值

设备影子保存的是设备最新的设备属性值,一旦设备属性值产生变化,设备会将设备属性值同步到设备影子。用户便可以及时获取查询结果,无需关注设备是否在线。

  1. 用户通过控制台或应用服务器查询设备属性值。消息样例如下:
    GET https://{Endpoint}/v5/iot/{project_id}/devices/{device_id}/shadow
    Content-Type: application/json
    X-Auth-Token: ********
    Instance-Id: ********
  2. 物联网平台返回desired属性值和report属性值,即期望值和上报值。消息样例如下:

    Status Code: 200 OK

    Content-Type: application/json
    
    {
      "device_id" : "40fe3542-f4cc-4b6a-98c3-61a49ba1acd4",
      "shadow" : [ {
        "desired" : {
          "properties" : {
            "temperature" : "60"
          },
          "event_time" : "20151212T121212Z"
        },
        "service_id" : "WaterMeter",
        "reported" : {
          "properties" : {
            "temperature" : "60"
          },
          "event_time" : "20151212T121212Z"
        },
        "version" : 1
      } ]
    }

查询和修改设备影子

查询设备影子

方法1:应用服务器调用查询设备影子数据接口。

方法2:登录管理控制台,在左侧导航栏选择“设备”,单击具体的设备进入到设备的详情页面,在“设备影子”页签中,可以查看当前设备属性数据,包括“上报值”和“期望值”。
  • 如果当前界面中看到“上报值”与“期望值”不一致,原因可能是设备未在线,暂时存储在设备影子中,待同步给设备,期望值会存在深色底纹。
  • 如果当前界面看到的“上报值”与“期望值”一致,则表示设备最近一次上报的属性值与用户期望下发的属性值一致,期望值为白色底纹。

修改设备影子

方法1:应用服务器调用配置设备影子预期数据接口。

方法2:登录管理控制台,在左侧导航栏选择“设备”,单击具体的设备进入到设备的详情页面,在“设备影子”页面,单击“属性配置”,在弹出窗口中输入服务属性对应的期望值。

分享:

    相关文档

    相关产品