A device shadow is a persistent virtual shadow of a device built on the IoT Platform based on a special topic for the related device. This device synchronizes its status to the cloud using this device shadow. The cloud can quickly obtain the device status from the device shadow even when the device is not connected to the IoT Platform.

Background information

Note: For products that support device modelling, reported information is kept in the cloud, so the device shadow is only applicable to the Basic Edition of the Alibaba Cloud IoT Platform.

Procedure

  • The C SDK provides the IOT_Shadow_Construct function to create the device shadow. The function is declared as follows:
/**
* @brief Construct the Device Shadow.
* This function initializes the data structures, and establishes the 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);
  • Use the IOT_Shadow_RegisterAttribute function to register the properties of the device shadow. The function is declared as follows:
/**
* @brief Create a data type registered to the server.
*
* @param [in] handle: The handle of device shadow.
* @param [in] pattr: The parameter 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);
  • You can use the IOT_Shadow_Pull interface in the C-SDK to synchronize device status from the cloud whenever the device shadow starts. The function is declared as follows:
/**
* @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);
  • When the device updates its status, you can use IOT_Shadow_PushFormat_Init, IOT_Shadow_PushFormat_Add, and IOT_Shadow_PushFormat_Finalize in the C SDK to update the device status, and use IOT_Shadow_Push in the C SDK to synchronize the status to the cloud. The function is declared as follows:
/**
* @brief Start to 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 processing of 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);
  • To disconnect the device from IoT Platform, use IOT_Shadow_DeleteAttribute and IOT_Shadow_Destroy in the C SDK to delete all properties that have been created for this device on IoT Platform, and release the device shadow. The function is declared as follows:
/**
* @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);