Device distribution

Limits

Device distribution is supported between any regions where IoT Platform is available.

Scenarios

• Pre-flashing devices: Flash all devices with the region-agnostic global endpoint during manufacturing, then distribute them across regions from the IoT Platform console.

• Business migration: Move devices across regions, instances, or accounts when the connected region or instance changes.

The following distribution policies are available:

• Specified region: Distributes devices to a known destination region and instance.

• Proximity-based connection: Select an instance for each region during configuration. Devices dynamically connect to the nearest region based on their IP address.

Instructions

Distribution objects

Device distribution moves devices across instances, regions, or accounts.

After distribution, some device data and product data are also moved. The following table describes the distribution objects.

Notes

Distribution process

1. For new devices, create a product and device in the IoT Platform console to obtain the device certificate (ProductKey, DeviceName, and DeviceSecret). Create a product. Create a single device. Create multiple devices in batches.

2. Develop the physical device using the C Link SDK for C V4.x provided by Alibaba Cloud, or develop the device based on the interaction protocol to implement the following features.

   Note

   We recommend the C Link SDK for C from Alibaba Cloud. Device distribution overview.

   After distribution, the device connects to IoT Platform as follows:

   1. Based on the device development scenario, use one of the following methods to send a Bootstrap request.

      • Alibaba Cloud C Link SDK connection

        The device calls the encapsulated Bootstrap interface of the SDK. The call sends a request that contains the ProductKey and DeviceName to the global domain name of the device distribution center: https://iot-auth-global.aliyuncs.com.

        Overview.

      • Custom connection without an SDK

        Send a request to https://iot-auth-global.aliyuncs.com/auth/bootstrap with the following protocol.

        Table 1. Request parameters

        Parameter	Required	Description
        productKey	Required	The ProductKey of the product to which the device belongs. Obtain it from the IoT Platform console. Create a single device.
        deviceName	Required	The DeviceName of the device. Obtain it from the IoT Platform console.
        clientId	Optional	The client ID. The ID can be up to 64 characters long.
        version	Optional	The version number of the authentication service.
        timestamp	Optional	The timestamp. No time window is checked for the timestamp.
        resources	Optional	The description of the resources you want to obtain, such as MQTT. Separate multiple resource names with commas.

        Table 2. Response parameters

        Parameter	Type	Description
        resources	Struct	The resource information, such as the address of the ApsaraMQ for MQTT client.

        Sample request

        POST /auth/bootstrap HTTP/1.1
        Host: iot-auth-global.aliyuncs.com
        Content-Type: application/x-www-form-urlencoded
        Content-Length: 123
        productKey=123&timestamp=123&version=default&clientId=123&resources=mqtt&deviceName=test

        Sample response

        HTTP/1.1 200 OK
        Server: Tengine
        Date: Wed, 29 Mar 2017 13:08:36 GMT
        Content-Type: application/json;charset=utf-8
        Connection: close
        {
          "code" : 200,
          "data" : {
            "resources" : {
              "mqtt" : {
                "host" : "xxx.iot-as-mqtt.cn-shanghai.aliyuncs.com",
                "port" : 1883
              }
            }
          },
          "message" : "success"
        }

   2. The distribution center returns the destination instance endpoint. For proximity-based connections, the destination is dynamically determined based on the device's IP address.

   3. The device uses its device certificate (ProductKey, DeviceName, and DeviceSecret) and the returned instance endpoint to establish an MQTT connection with IoT Platform.

      • Alibaba Cloud C Link SDK connection

        Use SDK V4.x to connect the device. Overview.

      • Creating a custom connection without an SDK

        Use the open source Paho MQTT project for embedded C to connect the device. Paho-MQTT for C (embedded) connection example.

   4. (Optional) After distribution from the console, the device receives an MQTT message indicating it has been distributed and will be forced offline.

      MQTT message, data downstream.

      Request topic: /sys/${productKey}/${deviceName}/thing/bootstrap/notify.

      Alink request data format:

      {
          "id": "****",
          "version": "1.0", 
          "method": "thing.bootstrap.notify", 
          "params": {
            "cmd": 0
          }
      }

      Response topic: /sys/${productKey}/${deviceName}/thing/bootstrap/notify_reply.

      Alink response data format:

      {
          "id": "****",
          "code":200,
          "data" : {}
      }

   Important

   Complete the first three steps on each connection to prevent failures caused by endpoint inconsistencies.

   Devices can store endpoint information locally. If the connection information is lost or the connection fails, the device can send a Bootstrap request to retrieve it again.

3. After you complete device development, perform the following operations based on your scenario:

   • For existing devices that do not support device distribution, upgrade them using an OTA update to the version developed in the previous step. OTA update overview.

     Important

     Existing devices must be upgraded to support device distribution before they are distributed. Otherwise, the devices cannot connect to IoT Platform after distribution.

   • For new devices, flash the device certificate to the device. Flash device certificates.

4. Distribute devices to the target region, instance, and account in the console.

   1. Log on to the IoT Platform console.

   2. In the top navigation bar, select China (Shanghai) from the region drop-down list.

      Important

      The device distribution feature is available only for Standard, Premium Enterprise, and public instances in the IoT Platform console when the China (Shanghai) region is selected. There are no restrictions on the source and destination regions for device distribution.

   3. On the Overview page, click All environment. On the All environment tab, find the instance that you want to manage and click the instance ID or instance name.

   4. In the navigation pane on the left, choose Device Management > Device Distribution.

   5. On the Device Distribution page, click Distribute Devices.

   6. Enter the required information.

      Configure the following parameters:

      Parameter	Description
      Distribution method	The distribution method: Current account: Distribute to another region or instance within the current account. Cross-account: Distribute to another account. Note The proximity-based connection policy is not supported for cross-account distribution.
      Destination account	Available when Distribution method is set to Cross-account. Specify the destination account by: Destination account name: Enter the name of the Alibaba Cloud account. Destination account ID: Enter the ID of the Alibaba Cloud account. Note To view your Alibaba Cloud account ID, log on to the IoT Platform console, click your profile picture, and go to the Security Settings page.
      Authorization code	After you specify the destination account, click Get Authorization Code. An authorization code is sent to the mobile phone number of the destination account. The code is valid for 5 minutes. Contact the recipient for the code.
      Source region	The region of the devices to distribute.
      Source instance	The instance of the devices to distribute.
      Distribution policy	The distribution policy: Specified region: Distribute devices to a specified region. Proximity-based connection: Select multiple regions. Devices will dynamically connect to the nearest region based on their IP address.
      Destination region	Available when Distribution policy is set to Specified region. Select the destination region.
      Destination instance	Available when Distribution policy is set to Specified region. Select the destination instance. If you set Distribution method to Current account, select the destination instance. If you set Distribution method to Cross-account, enter the destination instance ID. If you leave this blank, the legacy public instance is used by default. Important If the destination instance is a new public instance or an Enterprise instance, you must enter the instance ID. View and configure instance endpoint information.
      Region scope	Available when Distribution policy is set to Proximity-based connection. Select destination regions. If the source region is a possible destination, include it. If a region has multiple instances, select the destination instance from the drop-down list.
      Device selection method	Select devices to distribute: Manual selection: Select the product, then select devices from the device list. Selections persist across pages. If you set Distribution policy to Specified region and do not select any devices, only the product is distributed. File upload: Upload a CSV file with up to 1,000 device records. Click Download Template for the file template.

   7. Click Confirm.

   IoT Platform immediately starts the distribution task:

   • If you select the Specified region policy, the product data and device data are distributed to the specified region.

   • If you select the Proximity-based connection policy, the product data is distributed to all specified regions. The device data is dynamically distributed to the nearest region based on the device's IP address when it connects.

   Monitor the task status in the batch list:

   Status	Description
   Task initializing	The task information is being initialized.
   Distribution task in progress	The distribution task is in progress. If the task remains in this state for a long time, retry the task.
   Distribution task completed	The distribution task is complete. A completed task does not mean all devices were distributed successfully. Click Download Distribution Results to check individual device status. Some devices may fail if they do not exist or for other reasons.
   Distribution task failed	The distribution task may have failed due to network jitter. Retry the task. If the problem persists, contact customer service or submit a ticket.

   After the distribution task is complete, the device connects to the destination region and instance as described in Step 2.

Related API

FAQ

• Why can't I find the entry point for the device distribution feature in the console?

• How do I move a device back from its destination instance in IoT Platform?

• How can a device from one Alibaba Cloud account's IoT Platform connect to another account's IoT Platform?

• Is it possible to distribute IoT Platform products and devices across accounts?

• Can the ProductKey of a product be changed?

• Can device distribution be used to move a device from another account to a new account?

• Is device distribution between Enterprise instances the same as instance migration?

• After a device is distributed to a destination instance, which instance incurs the costs, the source or the destination?

• Is device-generated data distributed?

• After device distribution is complete, where can the recipient view the distributed products and devices?

• Does device distribution affect the secret and ProductKey of the source device?