Before you connect a device to IoT Platform, you must register the device with IoT Platform so that IoT Platform can identity the device.

You can use the following methods to register devices:

  • Unique-certificate-per-device. Create a device in IoT Platform, obtain the device certificate, and then use the certificate information as the unique identifier. The certificate information includes the ProductKey, DeviceName, and DeviceSecret. Burn the certificate information into the firmware of the device. After the device is connected to IoT Platform, the device can communicate with IoT Platform. For more information, see Unique-certificate-per-device authentication.
  • Dynamic registration. You can dynamically register sub-devices and directly connected devices. Dynamic registration based on the unique-certificate-per-product authentication is used to register directly connected devices.
    • To dynamically register a directly connected device based on the unique-certificate-per-product authentication, perform the following steps:
      1. Create a device in IoT Platform and obtain the product certificate that includes the ProductKey and ProductSecret. When you create the device, set the DeviceName parameter to the serial number or MAC address of the device.
      2. Enable dynamic registration for the product to which the device belongs in the IoT Platform console.
      3. Burn the product certificate into the firmware of the device.
      4. The device initiates an authentication request to IoT Platform. If the authentication succeeds, IoT Platform assigns a DeviceSecret to the device.
      5. The device uses the device certificate to establish a connection with IoT Platform.

      For more information, see Unique-certificate-per-product authentication.

    • To dynamically register a sub-device, perform the following steps:
      1. Create a sub-device in IoT Platform and obtain the ProductKey. When you create the sub-device, set the DeviceName parameter to the serial number or MAC address of the sub-device.
      2. Enable dynamic registration for the product to which the sub-device belongs in the IoT Platform console.
      3. Burn the ProductKey into the firmware of the sub-device or the gateway.
      4. The gateway initiates an authentication request to IoT Platform on behalf of the sub-device. If the authentication succeeds, IoT Platform assigns a DeviceSecret to the sub-device.

Dynamically register a sub-device

A gateway can initiate a dynamic registration request on behalf of a sub-device by sending an upstream request to IoT Platform. If the sub-device registration succeeds, IoT Platform returns the device certificate of the sub-device.

The following topics are used when a device sends requests to IoT Platform and IoT Platform sends responses to the device:

  • Request topic: /sys/{productKey}/{deviceName}/thing/sub/register
  • Response topic: /sys/{productKey}/{deviceName}/thing/sub/register_reply

Sample request:

{
  "id": "123",
  "version": "1.0",
  "sys":{
      "ack":0
  },
  "params": [
    {
      "deviceName": "deviceName1234",
      "productKey": "a1234******"
    }
  ],
  "method": "thing.sub.register"
}

Sample response:

{
  "id": "123",
  "code": 200,
  "data": [
    {
      "iotId": "12344",
      "productKey": "a1234******",
      "deviceName": "deviceName1234",
      "deviceSecret": "xxxxxx"
    }
  ]
}

The following table describes the parameters.

Parameter Type Description
id String The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
version String The version number of the protocol. Set the value to 1.0.
sys Object The parameter for extended features. The value contains the fields for each feature.
Note If no extended features are configured when you use a device SDK to develop device features, this parameter is unavailable. The extended features use the default configurations.
ack Integer The extended feature field in the sys parameter. This field specifies whether IoT Platform needs to return response data for the registration request. Valid values:
  • 1: indicates that IoT Platform needs to return response data.
  • 0: indicates that IoT Platform does not need to return response data.
Note

If this feature is not configured, this parameter is unavailable. By default, IoT Platform returns response data for a registration request.

params List The parameters used for dynamic registration.
deviceName String The name of the sub-device.
productKey String The key of the product to which the sub-device belongs.
iotId String The unique identifier of the sub-device.
deviceSecret String The key of the sub-device.
method String The request method. Set the value to thing.sub.register.
code Integer The status code that indicates the result.

The following table describes the error codes.

Error code Error message Description
460 request parameter error The error code returned because the request parameters are invalid.
6402 topo relation cannot add by self The error code returned because a device cannot be added as a sub-device of itself.
401 request auth error The error code returned because the signature verification has failed.

Dynamically register a directly connected device based on the unique-certificate-per-product authentication

Directly connected devices send dynamic registration requests by using HTTP. You must enable dynamic registration based on unique-certificate-per-product for the products to which the directly connected devices belong in the IoT Platform console.

  • URL template: https://iot-auth.cn-shanghai.aliyuncs.com/auth/register/device
  • HTTP method: POST.

Sample request:

POST /auth/register/device  HTTP/1.1
Host: iot-auth.cn-shanghai.aliyuncs.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 123
productKey=a1234******&deviceName=deviceName1234&random=567345&sign=adfv123hdfdh&signMethod=HmacMD5

Sample response:

{
  "code": 200,
  "data": {
    "productKey": "a1234******",
    "deviceName": "deviceName1234",
    "deviceSecret": "adsfw******"
  },
  "message": "success"
}

The following table describes the parameters.

Parameter Type Description
Method String The request method. Set the value to POST.
Host String The endpoint. Set the value to iot-auth.cn-shanghai.aliyuncs.com.
Content-Type String The encoding format of the upstream data that the device sends to IoT Platform.
productKey String The unique identifier of the product.
deviceName String The name of the device.
random String The random number.
sign String The signature.

You can generate a signature in the following way:

  1. Sort all parameters that are submitted to IoT Platform excluding sign and signMethod in alphabetical order, and concatenate the parameters and values in sequence without concatenation operators.
  2. Use the signature method that is specified by the signMethod parameter and the key of the product to generate a signature.

Example:

hmac_sha1(productSecret, deviceNamedeviceName1234productKeya1234******random123)
signMethod String The signature method. Valid values: hmacmd5, hmacsha1, and hmacsha256.
code Integer The status code that indicates the result.
deviceSecret String The key of the device.