Distribute devices - IoT Platform - Alibaba Cloud Documentation Center

IoT Platform allows you to distribute devices across regions, instances, or accounts. After you distribute the devices, IoT Platform sends new endpoints to the devices. After the devices receive the endpoints, the devices can connect to IoT Platform by using the new endpoints. This eliminates the need to burn the new endpoints to the devices.

Scenarios

You can distribute devices in the following scenarios:

Device burning before connection: Before you deliver devices from the factory, you do not need to hard-code different endpoints for devices based on the IoT Platform instances or regions in which the instances reside. A globally unique endpoint that does not contain the region information is burned to each device. After the devices leave the factory, you can distribute the devices to different regions in the IoT Platform console. This way, the devices can connect to IoT Platform from different regions around the world.
Business migration: If you migrate your business, you may need to change the region or instance to which a device is connected. In this case, you can distribute devices across regions, instances, or accounts.

The following distribution policies apply to different scenarios:

Specified region: Devices are distributed to the specified region and instance. If you can confirm the destination region and instance to which the devices need to be distributed, we recommend that you use this policy. This way, you can distribute devices in an efficient manner.
Nearest access: Devices may be used in different regions around the world. When you distribute the devices, you can select one or more regions and select an instance from each region. Then, the devices are connected to the nearest region based on their IP addresses. This way, a device can be connected to the nearest region regardless of the device location.

Usage notes

Item	Description
Distribution scope	You can distribute devices across all regions in which IoT Platform is deployed. You can distribute a device multiple times.
Cross-account distribution	If multiple public instances of the previous version reside in the same region, you cannot distribute devices across the instances. For more information, see Manage the endpoint of an instance. The nearest access policy is not supported.
Distribution to a specified region	If you distribute a product, the data of the product is distributed, but the data of the devices that belong to the product is not distributed. If you distribute a device, the data of the device that you specified in a distribution policy and the data of the product to which the device belongs are distributed. For more information about the items that can be distributed, see Distributable items.
Distribution to the nearest region	You cannot distribute only products. If you distribute a device, the data of the product to which the device belongs is distributed. The device data is distributed based on the IP address of the endpoint to which the devices are connected.

Distributable items

You can distribute devices across instances, regions, or accounts.

After a device is distributed, specific device data and product data are also distributed. The following table describes the distributable items.

Distributable item	Limits
Maximum number of devices	You can distribute up to 10,000 devices at the same time.
Device data	The device certificate is distributed and used to authenticate the connection between the device and a new instance. The certificate includes the ProductKey, DeviceName, and DeviceSecret. The following device data is not distributed: Runtime data. Runtime data is generated when a device is running. The data includes the device status, Thing Specification Language (TSL) data, device shadows, files, and logs. If a device is distributed, the device becomes inactive. After the device is reconnected to IoT Platform, the device is activated and can go online or offline. The runtime data of the device is retained in the source region, instance, and account. If the device is redistributed to the source region, the data can still be used. The data of topological relationships, tags, and groups. If a device is distributed, the data is cleared.
Product data	The product information, topic categories, TSL features, and data parsing scripts are distributed. Recipients can only view the data of distributed products. Recipients cannot edit or delete the data on the Product Information, Topic Categories, Define Feature, or Data Parsing tabs of the Product Details page. Recipients cannot also create devices for the distributed products in the IoT Platform console. Important If a device is distributed, take note of the following items: If you create a device in the original product of the source instance, the DeviceName of the new device must be different from the device that is distributed. You cannot delete the distributed device from the destination instance. To delete the device, distribute the device from the destination instance to the source instance. Then, you can delete the device from the source instance.

Precautions

Item affected by device distribution	Description
Billing	Devices can be distributed regardless of whether overdue payments exist on the source or destination instance. After a device is distributed, the destination instance is charged for the usage of the device based on the billing rules of IoT Platform.
Device distribution task	A device distribution task that is initiated cannot be canceled. If a device is online when you distribute the device, the device is forced to go offline.
Messaging	If you want to use the Advanced Message Queuing Protocol (AMQP) server-side subscription and data forwarding features on a distributed device, you must reconfigure the features on the destination instance.
OTA update	If you want to configure an over-the-air (OTA) update for the device that is distributed, take note of the following items: Before you can configure an OTA update for the device that is distributed across regions or instances, you must switch to the destination region or instance in the IoT Platform console. If the device is distributed across accounts, you must use the destination account to configure an OTA update for the device. You can obtain an update package from the owner of the source account. For more information about the OTA update feature, see Overview of OTA updates.
Product data update	After a product is distributed, operations that are performed on the product, such as creating custom topics, defining TSL models, and editing data parsing scripts from the source instance, do not affect the distributed product on the destination instance.

Procedure

Create a product and a device in the product and then obtain the device certificate in the IoT Platform console. The certificate includes the ProductKey, DeviceName, and DeviceSecret. For more information, see Create a product, Create a device, and Create multiple devices at a time.

Use Link SDK for C V4.x to configure the physical device, or configure the device based on a communication protocol to implement the following feature.

Note

To configure the device, we recommend that you use Link SDK for C. For more information, see Overview of device distribution.

After you distribute the device in the IoT Platform console, you can connect the device to IoT Platform by performing the following operations:

Use one of the following methods to initiate a Bootstrap request based on the device development method:

Connect the device by using Link SDK for C
The device calls the Bootstrap method that is encapsulated in the SDK and carries the ProductKey and DeviceName parameters to send a request to the globally unique endpoint https://iot-auth-global.aliyuncs.com.
For information about how to develop the Bootstrap feature, see Overview of device distribution.

Connect the device without using the SDK

Send a request to https://iot-auth-global.aliyuncs.com/auth/bootstrap based on the protocol that you use. The following table describes the request parameters.

Table 1 Request parameters
Parameter	Required	Description
productKey	Required	The ProductKey of the product to which the device belongs. You can view the ProductKey in the IoT Platform console. For information about how to obtain the ProductKey, see Create a device.
deviceName	Required	The DeviceName of the device. You can view the DeviceName in the IoT Platform console.
clientId	Optional	The ID of the client. The ID must be 1 to 64 characters in length.
version	Optional	The version number of the verification service.
timestamp	Optional	The timestamp. The timestamp is not verified by using the sliding window algorithm.
resources	Optional	The names of the resources that you want to obtain. Example: MQTT. Separate multiple resource names with commas (,).

Table 2 Response parameters
Parameter	Type	Description
resources	Struct	The resource information, such as the endpoint of the Message Queuing Telemetry Transport (MQTT) broker.

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"
}

IoT Platform returns an endpoint based on the destination region and instance. If you set the Distribution Policy parameter to Nearest Access, IoT Platform determines the destination region and instance based on the IP address of the device.
The device connects to IoT Platform over MQTT based on the device certificate and the endpoint information of the instance to which the device can connect. The device certificate includes the ProductKey, DeviceName, and DeviceSecret. The endpoint information is returned by the distribution service.
- Connect the device by using Link SDK for C
  To connect the device, we recommend that you use the SDK V4.x. For more information about how to connect the device to IoT Platform, see Overview of device connection over MQTT.
- Connect the device without using the SDK
  Use the open source Paho MQTT project for embedded C to connect the device to IoT Platform. For more information, see Use the Paho MQTT for embedded C library to connect a device to IoT Platform.
Optional. If you distribute the device in the IoT Platform console, the device receives an MQTT message indicating that a distribution operation is performed. Then, the device is forced to go offline.
The following topics are used when IoT Platform sends downstream MQTT requests and the device sends responses to IoT Platform:
Request topic: /sys/${productKey}/${deviceName}/thing/bootstrap/notify
Sample request in the Alink JSON format:
```
{
    "id": "****",
    "version": "1.0", 
    "method": "thing.bootstrap.notify", 
    "params": {
      "cmd": 0
    }
}
```
Response topic: /sys/${productKey}/${deviceName}/thing/bootstrap/notify_reply
Sample response in the Alink JSON format:
```
{
    "id": "****",
    "code":200,
    "data" : {}
}
```

Important

Each time you connect the device to IoT Platform, we recommend that you complete the first three stages of the preceding process. This ensures that the endpoint stored on the device is the same as the endpoint that is sent by IoT Platform. Otherwise, the device may fail to connect to IoT Platform.

The endpoint information can be stored on the device. If the connection information is lost or a connection attempt fails, the device can initiate a Bootstrap request to obtain the endpoint information again.

After you configure a device, perform one of the following operations based on the actual conditions:
- Before you can distribute an existing device for which the device distribution feature is disabled, you must perform an OTA update to update the device to the version that is developed in the previous step. For information about how to update the device, see Overview of OTA updates.
  Important
  If the device distribution feature of an existing device is disabled, you must perform an OTA update to enable the feature before you distribute the device. Otherwise, the device cannot connect to IoT Platform after distribution.
- After you create a device, you must burn the device certificate to the device. For information about how to burn the device certificate, see Overview of obtaining device certificates.

Distribute the device to a specific region, instance, and account in the IoT Platform console based on your business requirements.

Log on to the IoT Platform console.
In the top navigation bar, select China (Shanghai) from the drop-down list.
Note
This step is performed to use the device distribution feature. It does not specify the source or destination region for device distribution.
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.
In the left-side navigation pane, choose Resource Allocation > Device Distribution.
On the Device Distribution page, click Device Distribution.

Configure the parameters.

The following table describes the parameters.

Parameter	Description
Distribution Method	The method that is used to distribute devices. Valid values: This Account: Distribute the devices to another instance or region of the current account. Cross-account: Distribute the devices to another account. Note If you set the Distribution Method parameter to Cross-account, you cannot set the Distribution Policy parameter to Nearest Access.
Destination Account	The destination account to which the devices are distributed. If you set the Distribution Method parameter to Cross-account, this parameter is required. You can specify the destination account by using the account name or account ID. Destination Account Name: Enter the name of an Alibaba Cloud account. Destination Account ID: Enter the ID of an Alibaba Cloud account. Note To view the ID of the Alibaba Cloud account, perform the following steps: Log on to the IoT Platform console and click the profile picture in the upper-right corner to go to the Security Settings page.
Verification Code	After you specify the destination account, click Send Verification Code. IoT Platform sends a verification code to the mobile phone number that is associated with the account. The verification code is valid for 5 minutes. Contact the owner of the destination account to obtain the verification code.
Source Region	The region from which the devices are distributed.
Source Instance	The instance from which the devices are distributed.
Distribution Policy	The policy that is used to distribute the devices. Valid values: Update Region: Distribute the devices to a specified region. Nearest Access: Distribute the devices to the nearest region based on the IP address of the devices. You can select one or more regions.
Destination Region	If you set the Distribution Policy parameter to Update Region, this parameter is required. Select the region to which you want to distribute the devices.
Destination Instance	If you set the Distribution Policy parameter to Update Region, this parameter is required. The instance to which you want to distribute the devices. If you set the Distribution Method parameter to This Account, you must select a destination instance. If you set the Distribution Method parameter to Cross-account, you must specify an instance ID. Otherwise, a public instance of the previous version is used. Important If the destination instance is a new public instance or an Enterprise Edition instance, you must specify an instance ID. For more information, see Manage the endpoint of an instance.
Region	If you set the Distribution Policy parameter to Nearest Access, this parameter is required. You can select one or more regions. If you want to distribute the devices to the source region, select the source region. If multiple instances reside in the destination region, you can select an instance from the drop-down list.
Devices	You can select the devices by using one of the following methods: Select: Select a product from the product list and then select one or more devices from the device list. The devices remain selected even if you change the page of the device list. If you set the Distribution Method parameter to Update Region and do not specify a device, IoT Platform distributes only products. Choose File: Upload a file that contains a device list. The file must be in the CSV format and can contain up to 1,000 entries. You can click Download Template to obtain the file template.

Click OK.

IoT Platform immediately performs the distribution task.

If you set the Distribution Policy parameter to Update Region, the product data and device data are distributed to a specified region.
If you set the Distribution Policy parameter to Nearest Access, the product data is distributed to the specified regions. When a device is connected to IoT Platform, IoT Platform dynamically distributes the device data to the nearest region based on the IP address of the device.

The following table describes the different status of a distribution task. The status is displayed on the Batch List tab.

Status	Description
Initializing	The distribution task is being initialized.
Distributing	The distribution task is being executed. If a distribution task is in this state for an extended period of time, you can click Retry in the Actions column.
Distributed	The distribution task is complete. This distributed status does not indicate that all devices are distributed. To check whether all devices are distributed, click Download Record in the Actions column and view the result. If a specific device does not exist, the device fails to be distributed.
Failed	The distribution task failed due to network jitter. You can click Retry in the Actions column. If the issue persists, contact customer service or submit a ticket.

After the distribution task is complete and a device is connected to IoT Platform, the device connects to the destination region and instance by performing operations in Step 2.