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

Overview

You can use the following methods to register devices:

MQTT-based dynamic registration of sub-devices

  • 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 returns a response to the registration request. Valid values:
  • 1: IoT Platform returns a response.
  • 0: IoT Platform does not return a response.
Notice For more information about how to configure this feature, see Device Modelling Programming.

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

params List The parameters used for dynamic registration.
deviceName String The DeviceName of the sub-device.
productKey String The ProductKey of the sub-device.
iotId String The unique identifier of the sub-device.
deviceSecret String The DeviceSecret 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.

HTTP status code Error message Description
460 request parameter error The error message 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.

HTTPS-based dynamic registration of directly connected devices

  • URL format: 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 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 specified device.
    random String The random number.
    sign String The signature.

    You can create a signature by using the following method:

    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 ProductKey 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 DeviceSecret of the sub-device.