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

功能介绍

  • 每个设备有且只有一个设备影子,设备可以通过MQTT获取和设置设备影子来同步设备与物联网平台上存储的数据,该同步可以是云端的影子同步给设备,也可以是设备同步给云端的影子。

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

具体影子的详细介绍见物联网平台的设备影子章节。

SDK使用

监听影子变更

API原型 iot.device#onShadow(callback)
功能说明 监听设备影子的变化,不论是设备端主动更新影子、设备端获取影子都会被调用
参数说明 - callback:回调函数

代码示例:

device.onShadow((res) => {

  console.log('获取最新设备影子,%o', res);

})
            

用户需要分析返回的内容判断是更新成功、失败、还是云端主动向设备推送设备影子等情况,下面将会分情况进行说明。

设备端更新云端影子

API原型 iot.device#postShadow(params)
功能说明 更新设备影子
参数说明 - params:影子的内容,为一个JSON对象

代码示例:

device.postShadow({
  "a": "value"
});
            

设备调用postShadow()之后,device.onShadow()将会被调用,若影子更新成功传递给onShadow()的res内容如下所示:

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

用户可以根据method的数值“reply”得知res的数值是云端对更新的响应,根据“status”为“success”得知影子更新成功;若影子更新失败,则传递给onShadow()的res内容如下所示:

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

用户可以根据“status”的值“error”得知更新影子失败,errorcode的数值定义如下:

errorCode errorMessage
400 不正确的JSON格式
401 影子JSON缺少method信息
402 影子JSON缺少state字段
403 影子JSON version不是数字
404 影子JSON缺少reported字段
405 影子JSON reported属性字段为空
406 影子JSON method是无效的方法
407 影子内容为空
408 影子reported属性个数超过128个
409 影子版本冲突
500 服务端处理异常

查询云端影子数据

API原型 iot.device#getShadow()
功能说明 从物联网平台获取最新的影子数据
参数说明

代码示例:

// 设备主动获取影子,回调函数会触发onShadow方法,返回设备影子信息
device.getShadow();
            

该函数调用之后将会触发物联网平台将影子发送给设备,在onShadow()中收到的数据格式示例如下:

{
  "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
}
            

用户可以解析"payload"->"state"中的"reported"得知设备以前上报的影子,分析"desired"得知云端主动修改的影子的数值。

云端修改影子数值

物联网平台上的应用程序可能修改影子的数值,在这种情况下云端会将影子数据发送给设备,onShadow()中的res数据格式示例如下:

{
  "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
}
            

用户可以通过“method”的数值为“control”得知这时云端更新了影子。同时通过"state"->"desired"得知修改的内容。

删除影子

API原型 iot.device#deleteShadow(keys)
功能说明 删除设备影子
参数说明 - keys:需要删除的设备影子的属性的数组

代码示例:

// 删除影子的单个属性
device.deleteShadow("a");
// 删除影子的多个属性
device.deleteShadow(["a","b"]);
// 删除影子的所有属性
device.deleteShadow()
            

示例代码

Github提供了代码示例供开发者参考。