背景信息
设备影子是指通过特别的Topic在云端构建一个设备的影子,设备同步状态至云端。当设备离线时,云端仍可以快速通过影子获取到设备的状态。
说明
对于使用物模型在物联网平台进行定义的产品,其属性会保存在云端,无需使用设备影子来告知物联网平台保存其数据。
操作步骤
- 设备C-SDK提供接口IOT_Shadow_Construct ,创建设备影子。函数声明如下:
/** * @brief Construct the Device Shadow. * This function initialize the data structures, establish MQTT connection. * and subscribe the topic: "/shadow/get/${YourProduct_key}/${YourDevice_name}". * * @param [in] pparam: The specific initial parameter. * @retval NULL : Construct shadow failed. * @retval NOT_NULL : Construct success. * @see None. */ void *IOT_Shadow_Construct(iotx_shadow_para_pt pparam);
- 使用IOT_Shadow_RegisterAttribute接口,注册设备影子的属性。函数声明如下:
/** * @brief Create a data type registered to the server. * * @param [in] handle: The handle of device shadow. * @param [in] pattr: The parameter which registered to the server. * @retval SUCCESS_RETURN : Success. * @retval other : See iotx_err_t. * @see None. */ iotx_err_t IOT_Shadow_RegisterAttribute(void *handle, iotx_shadow_attr_pt pattr);
- 设备影子在每次开机时,设备C-SDK提供IOT_Shadow_Pull接口,从云端同步设备状态。函数声明如下:
/** * @brief Synchronize device shadow data from cloud. * It is a synchronous interface. * @param [in] handle: The handle of device shadow. * @retval SUCCESS_RETURN : Success. * @retval other : See iotx_err_t. * @see None. */ 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将状态同步到云端。函数声明如下:
/** * @brief Start a process the structure of the data type format. * * @param [in] handle: The handle of device shadow. * @param [out] pformat: The format struct of device shadow. * @param [in] buf: The buf which store device shadow. * @param [in] size: Maximum length of device shadow attribute. * @retval SUCCESS_RETURN : Success. * @retval other : See iotx_err_t. * @see None. */ iotx_err_t IOT_Shadow_PushFormat_Init( void *handle, format_data_pt pformat, char *buf, uint16_t size); /** * @brief Format the attribute name and value for update. * * @param [in] handle: The handle of device shadow. * @param [in] pformat: The format struct of device shadow. * @param [in] pattr: To have created the data type of the format in the add member attributes. * @retval SUCCESS_RETURN : Success. * @retval other : See iotx_err_t. * @see None. */ iotx_err_t IOT_Shadow_PushFormat_Add( void *handle, format_data_pt pformat, iotx_shadow_attr_pt pattr); /** * @brief Complete a process the structure of the data type format. * * @param [in] handle: The handle of device shadow. * @param [in] pformat: The format struct of device shadow. * @retval SUCCESS_RETURN : Success. * @retval other : See iotx_err_t. * @see None. */ iotx_err_t IOT_Shadow_PushFormat_Finalize(void *handle, format_data_pt pformat);
- 当设备需要与云端断开连接时,设备C-SDK提供接口IOT_Shadow_DeleteAttribute和IOT_Shadow_Destroy,删除云端创建的属性并释放设备影子。函数声明如下:
/** * @brief Deconstruct the specific device shadow. * * @param [in] handle: The handle of device shadow. * @retval SUCCESS_RETURN : Success. * @retval other : See iotx_err_t. * @see None. */ iotx_err_t IOT_Shadow_Destroy(void *handle);