All Products
Search
Document Center

IoT Platform:Remote configuration

Last Updated:Sep 12, 2023

The remote configuration feature of IoT Platform allows you to update the configurations of remote devices without the need to restart or stop the devices. The configurations include the system parameters and network parameters.

Prerequisites

The remote configuration feature is supported by the Link SDK that you use. For more information about the topics and Alink JSON formats that are used by devices to request configuration information and used by IoT Platform to push configuration information, see Remote configuration.

Note

For information about how to configure a Link SDK, see Use a Link SDK to connect a device to IoT Platform. If you use Link SDK for C of IoT Platform to configure devices, take note of the following items:

  • Link SDK for C V3.x or V2.x: You must specifyFEATURE_SERVICE_OTA_ENABLED = y in the SDK. You can call the linkkit_cota_init operation of the SDK to initialize remote configurations.

  • Link SDK for C V4.x: On the SDK customization page, set the Advanced Capabilities parameter to OTA to enable the remote configuration feature for devices. For more information, see Obtain the SDK.

Background information

You can push an update package to a device to update device configurations such as the system parameters, network parameters, and security policies. If you use this method, the workloads of firmware version maintenance increase, and the device must stop running to implement an update.

To resolve the preceding issues, IoT Platform provides the remote configuration feature. The feature allows you to update configurations without the need to restart or stop the device.

Note

The remote configuration feature is applied on a product basis. The configuration file that is uploaded to IoT Platform takes effect on all devices of a product. You cannot specify a single device for remote configuration.

Features

You can perform the following operations that are related to the remote configuration feature:

  • Enable or disable the remote configuration feature.

  • Edit configuration files and manage the file versions in the IoT Platform console.

  • Push configuration files from IoT Platform to multiple devices at a time to update the configurations.

  • Enable devices to request configuration files.

Scenarios

The remote configuration feature is suitable for the following scenarios:

  • IoT Platform pushes configuration information to multiple devices at a time. Each device receives the information and modifies the on-premises configuration file based on the information.

  • A device requests a configuration file from IoT Platform and performs an update.

The following sections describe the procedures in the preceding scenarios.

Scenario 1: IoT Platform pushes configuration information to devices

In the IoT Platform console, you can push a configuration file to all devices of a product at a time.

Remote configuration
  1. Connect a device to IoT Platform.

    For information about how to configure a Link SDK, see the Link SDK documentation.

    Important

    When you configure the devices, subscribe to the following topic that is used to push configuration information: /sys/${productKey}/${deviceName}/thing/config/push.

  2. In the IoT Platform console, modify a configuration file.

    1. Log on to the IoT Platform console.

    2. On the Overview page, select an environment, find the instance that you want to manage, and click the instance ID or instance name.

    3. In the left-side navigation pane, choose Device Log.

    4. Select a product, turn on Remote Configuration, and then click Edit.

      Remote configuration
    5. In the code editor of the Configure Template section, write or paste the configuration information in the JSON format.

      Note

      The configuration template is applied to all devices of a product. You cannot push a configuration file to a single device in the IoT Platform console.

    6. Click Save, and then click OK.

      You can push a configuration file to all devices of a product at a time. You can also enable a device to request a configuration file.

  3. Click Batch Update, and then click Confirm Update.

    IoT Platform pushes the configuration file to all devices of the product.

    If IoT Platform determines that the operation is not performed in a trusted environment after you click Batch Update, IoT Platform sends you a text message for verification. IoT Platform sends the configuration file to the devices only after the verification is complete.

    Important
    • After you push a configuration file to a product, you cannot push another configuration file to the product within 1 hour.

    • You can push a configuration file to a product only once in the IoT Platform console. The next time you repeat the preceding steps to push the same configuration file to the product, the push operation fails.

    • If you want to stop batch updates, you can turn off Remote Configuration for the product. After you turn off Remote Configuration for the product, IoT Platform stops pushing configuration files and denies update requests from devices.

  4. Devices automatically update the configurations after the devices receive the download URL of the configuration file from IoT Platform.

    Note

    The download URL is valid for 30 minutes. Devices must download the configuration file within the validity period of the download URL.

  5. Optional. View and manage the versions of configuration files.

    By default, the most recent five versions of a configuration file are saved in the IoT Platform console. After you edit and save a new version of the configuration file, the previous version is automatically displayed in the Configuration Version Record section.

    You can view the update time and content of a configuration file. Find the configuration file whose update time and content you want to view and click View in the Actions column. In the dialog box that appears, you can view the content. You can also click Restore to This Version to restore the content of the selected version to the code editor. Then, you can modify the content and update the configurations of multiple devices at a time.

Scenario 2: Enable a device to request a configuration file

The following figure shows the process.

Remote configuration
  1. Connect a device to IoT Platform.

    For more information about how to use a Link SDK to configure a device and the sample code, see the Link SDK documentation.

    Note

    When you configure a device, subscribe to the following topic that is used by IoT Platform to send responses to configuration information requests from the device: /sys/${productKey}/${deviceName}/thing/config/get_reply.

  2. In the IoT Platform console, enable the remote configuration feature and modify a configuration file. For more information, see Step 2 in .Scenario 1: IoT Platform pushes configuration information to devices

  3. Call the linkkit_invoke_cota_get_config operation to generate a request for remote configuration.

  4. Send the request to the following topic to query the most recent configuration information: /sys/${productKey}/${deviceName}/thing/config/get.

  5. IoT Platform receives the request, and then returns the most recent configure information to the /sys/${productKey}/${deviceName}/thing/config/get_reply topic.

  6. Then, the device uses the URL that is sent from IoT Platform to download the configuration file.

    For example, you can call the cota_callback callback function that is provided by Link SDK for C V3.x to process the download URL of the configuration file and perform an update.

    Note

    The download URL is valid for 30 minutes. Devices must download the configuration file within the validity period of the download URL.