All Products
Document Center

Remote Configuration

Last Updated: Jun 29, 2020

The IoT platform can send the remote configuration information to a device, and a device can also query the remote configuration information from the platform. If the remote configuration information was published by IoT platform while the device is offline, the device can obtain the information by querying.

For more information about remote configuration, refer to Remote Configuration

Process explanation 1: The IoT platform actively distributes the remote configuration information to the device

The function of the server actively distributing the remote configuration information to the device is now explained step by step with reference to the examples/linkkit/linkkit_example_cota.c process

  1. Define and register the callback function when receiving the remote configuration information

  1. /* Define the callback function */
  2. static int user_cota_event_handler(int type, const char *config_id, int config_size, const char *get_type,
  3. const char *sign, const char *sign_method, const char *url)
  4. {
  5. char buffer[128] = {0};
  6. int buffer_length = 128;
  7. user_example_ctx_t *user_example_ctx = user_example_get_ctx();
  8. if (type == 0) {
  9. EXAMPLE_TRACE("New Config ID: %s", config_id);
  10. EXAMPLE_TRACE("New Config Size: %d", config_size);
  11. EXAMPLE_TRACE("New Config Type: %s", get_type);
  12. EXAMPLE_TRACE("New Config Sign: %s", sign);
  13. EXAMPLE_TRACE("New Config Sign Method: %s", sign_method);
  14. EXAMPLE_TRACE("New Config URL: %s", url);
  15. IOT_Linkkit_Query(user_example_ctx->master_devid, ITM_MSG_QUERY_COTA_DATA, (unsigned char *)buffer, buffer_length);
  16. }
  17. return 0;
  18. }
  19. /* Register the callback function */
  20. int linkkit_main(void *paras)
  21. {
  22. ...
  23. IOT_RegisterCallback(ITE_COTA, user_cota_event_handler);
  24. ...
  25. }
  1. Set up trituple

  1. memset(&master_meta_info, 0, sizeof(iotx_linkkit_dev_meta_info_t));
  2. memcpy(master_meta_info.product_key, PRODUCT_KEY, strlen(PRODUCT_KEY));
  3. memcpy(master_meta_info.product_secret, PRODUCT_SECRET, strlen(PRODUCT_SECRET));
  4. memcpy(master_meta_info.device_name, DEVICE_NAME, strlen(DEVICE_NAME));
  5. memcpy(master_meta_info.device_secret, DEVICE_SECRET, strlen(DEVICE_SECRET));
  1. /* Choose Login Server, domain should be configured before IOT_Linkkit_Open() */
  5. #else
  6. int domain_type = IOTX_CLOUD_REGION_SHANGHAI;
  7. IOT_Ioctl(IOTX_IOCTL_SET_DOMAIN, (void *)&domain_type);
  8. #endif
  9. /* Choose Login Method */
  10. int dynamic_register = 0;
  11. IOT_Ioctl(IOTX_IOCTL_SET_DYNAMIC_REGISTER, (void *)&dynamic_register);
  1. The primary device establishes a connection

  1. /* Create Master Device Resources */
  2. user_example_ctx->master_devid = IOT_Linkkit_Open(IOTX_LINKKIT_DEV_TYPE_MASTER, &master_meta_info);
  3. if (user_example_ctx->master_devid < 0) {
  4. EXAMPLE_TRACE("IOT_Linkkit_Open Failed\n");
  5. return -1;
  6. }
  7. /* Start Connecting Aliyun Server */
  8. res = IOT_Linkkit_Connect(user_example_ctx->master_devid);
  9. if (res < 0) {
  10. EXAMPLE_TRACE("IOT_Linkkit_Connect Failed\n");
  11. return -1;
  12. }

IOT_Linkkit_Connect will subscribe to the remote configuration related topic, therefore the device can receive the remote configuration information when it is released by the IoT platform.

Process explanation 2: The device queries the platform for remote configuration information

With a few changes to the above example after step 4, a device can actively obtain remote configuration information from the server.

  1. IOT_Linkkit_Query(user_example_ctx->master_devid, ITM_MSG_REQUEST_COTA, NULL, 0);

When IOT_Linkkit_Query queries the IoT platform for remote configuration information, if the information exists on the server, it is sent to the device and the user_cota_event_handler will be called.

Remote Configuration feature API

Function name Description
IOT_Linkkit_Open Create a local resource. This interface must be called to get a session handle before you can interact with network messages.
IOT_Linkkit_Connect For the primary device/gateway, the communication between the device and the cloud is established. For a child device, the child device is registered with the cloud (if required) and the primary and secondary device topology is added.
IOT_Linkkit_Yield If the SDK occupies a separate thread, the function only distributes the received network messages to the user’s callback function, otherwise, it means that the CPU is handed over to the SDK to receive the network messages and distribute the messages to the user’s callback function.
IOT_Linkkit_Close If the session handle in the incoming parameters is the primary device/gateway, the network connection is closed and all resources occupied by the SDK for the session are released.
IOT_Linkkit_TriggerEvent Send event messages such as error codes and abnormal alarms to the cloud
IOT_Linkkit_Report Send uplink messages without cloud service data distribution to the cloud, including messages such as attribute values /device labels/binary transparent data/ sub-device management
IOT_Linkkit_Query Send query messages with cloud service data distribution to the cloud, including messages such as OTA status query/OTA firmware download/sub-device topology query/NTP time query

HAL that needs to be implemented