设备影子

背景信息

设备影子是指通过特别的Topic在云端构建一个设备的影子，设备同步状态至云端。当设备离线时，云端仍可以快速通过影子获取到设备的状态。

注：对于使用物模型在物联网平台进行定义的产品，其属性会保存在云端，无需使用设备影子来告知物联网平台保存其数据

操作步骤

  • 设备C-SDK提供接口IOT_Shadow_Construct ，创建设备影子。函数声明如下：
  1. /**
  2. * @brief Construct the Device Shadow.
  3. * This function initialize the data structures, establish MQTT connection.
  4. * and subscribe the topic: "/shadow/get/${YourProduct_key}/${YourDevice_name}".
  5. *
  6. * @param [in] pparam: The specific initial parameter.
  7. * @retval NULL : Construct shadow failed.
  8. * @retval NOT_NULL : Construct success.
  9. * @see None.
  10. */
  11. void *IOT_Shadow_Construct(iotx_shadow_para_pt pparam);
  • 使用IOT_Shadow_RegisterAttribute接口，注册设备影子的属性。函数声明如下：
  1. /**
  2. * @brief Create a data type registered to the server.
  3. *
  4. * @param [in] handle: The handle of device shaodw.
  5. * @param [in] pattr: The parameter which registered to the server.
  6. * @retval SUCCESS_RETURN : Success.
  7. * @retval other : See iotx_err_t.
  8. * @see None.
  9. */
  10. iotx_err_t IOT_Shadow_RegisterAttribute(void *handle, iotx_shadow_attr_pt pattr);
  • 设备影子在每次开机时，设备C-SDK提供IOT_Shadow_Pull接口，从云端同步设备状态。函数声明如下：
  1. /**
  2. * @brief Synchronize device shadow data from cloud.
  3. * It is a synchronous interface.
  4. * @param [in] handle: The handle of device shaodw.
  5. * @retval SUCCESS_RETURN : Success.
  6. * @retval other : See iotx_err_t.
  7. * @see None.
  8. */
  9. iotx_err_t IOT_Shadow_Pull(void *handle);
  • 当设备端状态发生变化时，设备C-SDK提供接口IOT_Shadow_PushFormat_Init、IOT_Shadow_PushFormat_Add和IOT_Shadow_PushFormat_Finalize接口更新状态，通过接口IOT_Shadow_Push将状态同步到云端。函数声明如下：
  1. /**
  2. * @brief Start a process the structure of the data type format.
  3. *
  4. * @param [in] handle: The handle of device shaodw.
  5. * @param [out] pformat: The format struct of device shadow.
  6. * @param [in] buf: The buf which store device shadow.
  7. * @param [in] size: Maximum length of device shadow attribute.
  8. * @retval SUCCESS_RETURN : Success.
  9. * @retval other : See iotx_err_t.
  10. * @see None.
  11. */
  12. iotx_err_t IOT_Shadow_PushFormat_Init(
  13.                     void *handle,
  14.                     format_data_pt pformat,
  15.                     char *buf,
  16.                     uint16_t size);
  19. /**
  20. * @brief Format the attribute name and value for update.
  21. *
  22. * @param [in] handle: The handle of device shaodw.
  23. * @param [in] pformat: The format struct of device shadow.
  24. * @param [in] pattr: To have created the data type of the format in the add member attributes.
  25. * @retval SUCCESS_RETURN : Success.
  26. * @retval other : See iotx_err_t.
  27. * @see None.
  28. */
  29. iotx_err_t IOT_Shadow_PushFormat_Add(
  30.                     void *handle,
  31.                     format_data_pt pformat,
  32.                     iotx_shadow_attr_pt pattr);
  35. /**
  36. * @brief Complete a process the structure of the data type format.
  37. *
  38. * @param [in] handle: The handle of device shaodw.
  39. * @param [in] pformat: The format struct of device shadow.
  40. * @retval SUCCESS_RETURN : Success.
  41. * @retval other : See iotx_err_t.
  42. * @see None.
  43. */
  44. iotx_err_t IOT_Shadow_PushFormat_Finalize(void *handle, format_data_pt pformat);
  • 当设备需要与云端断开连接时，设备C-SDK提供接口IOT_Shadow_DeleteAttribute和IOT_Shadow_Destroy，删除云端创建的属性并释放设备影子。函数声明如下：
  1. /**
  2. * @brief Deconstruct the specific device shadow.
  3. *
  4. * @param [in] handle: The handle of device shaodw.
  5. * @retval SUCCESS_RETURN : Success.
  6. * @retval other : See iotx_err_t.
  7. * @see None.
  8. */
  9. iotx_err_t IOT_Shadow_Destroy(void *handle);
阿里云首页 设备接入Link SDK 相关技术圈