Add Topological Relationships for Sub-device


An edge can publish a message to this topic to add the topological relationship between the edge and a sub-device.


Upstream

  • Request TOPIC: /sys/{productKey}/{deviceKey}/thing/topo/add
  • Reply TOPIC: /sys/{productKey}/{deviceKey}/thing/topo/add_reply

Note

The productKey and deviceKey in the TOPIC are the credentials of the edge device.

Sample Request Format

{
  "id": "123",
  "version": "1.0",
  "params": [
    {
      "deviceKey": "yourDeviceKey",
      "productKey": "yourProductKey",
      "sign": "theSignature",
      "signmethod": "hmacSha1",
      "timestamp": "1524448722000",
      "clientId": "theSubDeviceId"
    }
  ],
  "method": "thing.topo.add"
}

Sample Response Format

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

Request Parameter Description

Parameter Type Mandatory/Optional Description
id String Optional The message ID. It is a reserved parameter that is reserved for future use.
version String Mandatory The version of the protocol. The current version is 1.0.
params Array Mandatory The parameters used for adding topological relationships.
deviceKey String Mandatory The device key of the sub-device.
productKey String Mandatory The product key of the sub-device.
sign String Mandatory The signature of the sub-device.
signmethod String Mandatory The signing method. The supported method is hmacSha1.
timestamp String Mandatory The timestamp.
clientId String Mandatory The identifier of the sub-device. The value can be its productKey or deviceKey.
method String Mandatory The request method.


To generate sign, you need to use every key-value pair in the params parameter except sign and signmethod. The steps are as follows.

  1. Concatenate every key-value pair except sign and signmethod in alphabetical order in the form of “key+value”“key+value”“key+value”.

    For example, a concatenated string as follows should be generated from the previous request based on the request’s params: clientIdtheSubDeviceIddeviceKeyyourDeviceKeyproductKeyyourProductKeytimestamp1524448722000

  2. Add the device’s device secret to the end of the concatenated string from the previous step. Use the algorithm specified by signmethod to calculate the string that includes the device secret. Capitalize all letters in the result to get the sign.

    For example, if the device secret is xyz123, the value forsign can be generated using the below:

    sign=uppercase(hmacsha1(clientIdtheSubDeviceIddeviceKeyyourDeviceKeyproductKeyyourProductKeytimestamp1524448722000xyz123))


Response Parameter Description

Parameter Type Mandatory/Optional Description
code Integer Mandatory The return code. “200” indicates that the requested operation is executed successfully.

Return Code

Return Code Error Message Explanation
1255 add topo failure, [details] Part or all of the sub-devices cannot be added to the gateway device. To troubleshoot the problem, you must read the details of this return code. [1]
[1]

Details of this return code can be categorized into the following:

  • The device that you wish add the sub-devices to is not a gateway device.
  • The sub-device does not exist.
  • The number of sub-devices under this gateway has reached the maximum number allowed.
  • The sub-devices to be added include a gateway device.
  • One or multiple sub-devices has already been added to other gateway devices.