Device provisioning service

Preparation for network provisioning

• Retrieve the list of discovered devices
• Filter the list of locally discovered devices

Device provisioning

• Obtain a key
• Add a sub-device to a gateway
• Remove a sub-device from the network topology

Device binding

• Query device certificates by token
• Bind a device using a token (Wi-Fi and Ethernet)
• Bind a device using a time window (Zigbee, cellular, Bluetooth, and others)

Get the list of discovered devices

Description

Request parameters

Response parameters

Examples

• Sample request

  {
      "id": "1509086454180",
      "version": "1.0",
      "request": {
          "apiVer": "1.0.2",
          "iotToken": "token"
      },
      "params": {
          "pageSize": 10,
          "pageNum": 1
      }
  }
                      

• Sample success response

  {
      "code": 200,
      "data": {
          "totalNum":12,
          "items":[
              {
                  "gmtCreate":xxx,
                  "gmtModified":xxx,
                  "regIotId":"xxx",
                  "regProductKey":"xxx",
                  "regDeviceName":"xxx",
                  "enrolleeIotId":"xxx",
                  "enrolleeProductKey":"xxx",
                  "enrolleeDeviceName":"xxx",
                  "bssid":"xxx",
                  "ssid":"xxx",
                  "rssi":"xxx",
                  "type":0,
                  "status":1
              }
          ]
      },
      "message": "success"
  }
                      

Filter the list of locally discovered devices

Description

Request parameters

The following describes the schema of the iotDevices list.

Response parameters

Examples

• Request example

  {
      "id": "1509086454180",
      "version": "1.0",
      "request": {
          "apiVer": "1.0.2",
          "iotToken": "token"
      },
      "params":{
          "iotDevices": [{
              "productKey": "a1xxxxm",
              "deviceName": "xxxxxx"
          },
          {
              "productKey": "a1xxxxb",
              "deviceName": "xxxxxx"
          }]
      }
  }
                      

• Successful response example

  {
      "code": 200,
      "data":[{
                  "productKey":"a1xxxxm",
                  "deviceName":"xxxxxx",
                  "netType":3,
                  "nodeType":0,
                  "categoryKey":"xxx",
                  "categoryName":"xxx",
                  "categoryId":14
              }
      ],
      "message": "success"
  }

Query device certificate information by token

Description

Request parameters

Response parameters

Examples

• Request example

  {
      "request": {
          "iotToken": "109049c80bxxxx62e29a3ba",
          "apiVer": "1.0.9"
      },
      "id": 1508212818676,
      "params": {
          "token":"xxx"
      },
      "version": "1.0"
  }

• Successful response example

  {
    "code": 200,
    "data": {
        "iotId": "xxxx"
        "productKey": "xxxx",
        "deviceName": "xxxx"
      },
    "id": "e2d74ffe-308e-xxxx-xxxx-9b44a43eabc9"
  }

• Error response example

  {
   "code":6608,
   "id":"4fa207ca-fffd-xxxx-xxxx-e6f7ca6c99c3",
   "message":"token not found"
  }

Token-based device attachment

Description

Request parameters

Response parameters

Examples

• Request example

  {
      "id":"xxx",
      "version":"1.0.0",
      "request":{
          "language":"en-US",
          "appKey":"xxx",
          "iotToken":"xxx",
          "apiVer":"1.0.8"
      },
      "params":{
          "homeId":"50f5op1556xxxxf2f28104512",
          "productKey":"xxx",
          "deviceName":"xxx",
          "token":"xxx"
      }
  }

• Successful response example

  {
      "id":"xxx",
      "code":200,
      "message":"success",
      "data":"xxxxxxxxxxxxx"
  } 

Attaching devices based on a time window

Description

Request parameters

Response parameters

Examples

• Request example

  {
      "id":"xxx",
      "version":"1.0.0",
      "request":{
          "language":"en-US",
          "appKey":"xxx",
          "iotToken":"xxx",
          "apiVer":"1.0.8"
      },
      "params":{
          "homeId":"50f5op15xxxxca4f2f28104512",
          "productKey":"xxx",
          "deviceName":"xxx"
      }
  }

• Successful response example

  {
      "id":"xxx",
      "code":200,
      "message":"success",
      "data":"xxxxxxxxxxxxx"
  }

Get a key

Description

Request parameters

The following list describes the valid values for the cipherType parameter.

cipherType=3 Per-product key: Queries the productSecret based on the ProductKey. Key algorithm: sha256(contentByteArray).
contentByteArray=productSecret.getByte()+0x2c+hexToByte(random) 

cipherType=4 Per-device key: Queries the deviceSecret based on the ProductKey and DeviceName. Key algorithm: sha256(contentByteArray).
contentByteArray=deviceSecret.getByte()+0x2c+hexToByte(random)

cipherType=6 BLE per-product key: Key algorithm: sha256(contentByteArray).
contentByteArray=productSecret.getByte()+0x2c+hexToByte(mac)+0x2c+hexToByte(random)

cipherType=7 BLE per-device key: Key algorithm: sha256(contentByteArray).
contentByteArray=deviceSecret.getByte()+0x2c+hexToByte(mac)+0x2c+hexToByte(random)
            

The following list describes the differences between per-product keys and per-device keys.

• Per-product key: The system uses the product key (productSecret) to generate the encryption key for local communication during provisioning. You only need to provide the ProductKey.
• Per-device key: The system uses the device key (deviceSecret) to generate the encryption key for local communication during provisioning. You must provide both the ProductKey and the DeviceName.

Response parameters

Examples

• Request example

  {
      "id": "1509086454180",
      "version": "1.0",
      "request": {
          "apiVer": "1.0.2",
          "iotToken": "token"
      },
      "params": {
          "deviceInfoForCipher": {
              "deviceName": "xxxx",
             "productKey": "xxxx",
              "productId": "001e7",
              "cipherType": 3, 
              "random": "00000000000000000000000000000000",
              "params": {
                  "mac":"xxx"
              }
          }
      }
  }     

• Successful response example

  {
      "code": 200,
      "data": "xxxx",
      "message": "success"
  }

Add a sub-device to a gateway

Description

Request parameters

Response parameters

There are no specific response parameters for this operation.

Examples

• Request example

  {
      "id": "1509086454180",
      "version": "1.0",
      "request": {
          "apiVer": "1.0.2",
          "iotToken": "token"
      },
      "params": {
          "iotId": "xxxxxxxxxxxxxx",
          "productKey": "xxxxxxxxx", 
          "time": 60                   
      }
  }             

• Successful response example

  {
      "id":"xxx",
      "code":200,
      "message":"success",
      "data":null
  }

Remove a sub-device from the network topology

Description

Request parameters

Response parameters

There are no specific response parameters for this operation.

Examples

• Request example

  {
      "id": "1509086454180",
      "version": "1.0",
      "request": {
          "apiVer": "1.0.2",
          "iotToken": "token"
      },
      "params": {
          "iotId": "xxxxxxxxxxxxxx",
          "subIotId": "xxxxxxxxx"                
      }
  }                    

• Successful response example

  {
      "id":"xxx",
      "code":200,
      "message":"success",
      "data":null
  }