Manage topological relationships

Add topological relationships for sub-devices

You can use a topic to send a request for adding a topological relationship between a gateway and sub-device. If the topological relationship is added, the information about the sub-device is returned.

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

• Request topic: /sys/{productKey}/{deviceName}/thing/topo/add
• Response topic: /sys/{gw_productKey}/{gw_deviceName}/thing/topo/add_reply

Sample request in the Alink JSON format:

{
  "id": "123",
  "version": "1.0",
  "sys":{
      "ack":0
  },
  "params": [
    {
      "deviceName": "deviceName1234",
      "productKey": "1234556554",
      "sign": "xxxxxx",
      "signmethod": "hmacSha1",
      "timestamp": "1524448722000",
      "clientId": "xxxxxx"
    }
  ],
  "method": "thing.topo.add"
}

Sample response in the Alink JSON format:

{
  "id": "123",
  "code": 200,
  "data": [
    {
      "deviceName": "deviceName1234",
      "productKey": "1234556554"
    }
  ]
}

Request parameters

sign= hmac_md5(deviceSecret, clientId123deviceNametestproductKey123timestamp1524448722000)

Response parameters

Error messages:

Remove topological relationships of sub-devices

You can use a topic to send a request for removing a topological relationship between a gateway and sub-device. If the topological relationship is removed, the information about the sub-device is returned.

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

• Request topic: /sys/{productKey}/{deviceName}/thing/topo/delete
• Response topic: /sys/{gw_productKey}/{gw_deviceName}/thing/topo/delete_reply

Sample request in the Alink JSON format:

{
  "id": "123",
  "version": "1.0",
  "sys":{
      "ack":0
  },
  "params": [
    {
      "deviceName": "deviceName1234",
      "productKey": "1234556554"
    }
  ],
  "method": "thing.topo.delete"
}

Sample response in the Alink JSON format:

{
  "id": "123",
  "code": 200,
  "data": [
    {
      "deviceName": "deviceName1234",
      "productKey": "1234556554"
    }
  ]
}

Request parameters

Response parameters

Error messages:

Query topological relationships of sub-devices

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

• Request topic: /sys/{productKey}/{deviceName}/thing/topo/get
• Response topic: /sys/{gw_productKey}/{gw_deviceName}/thing/topo/get_reply

You can use a topic to send a request for querying a topological relationship between a gateway and sub-device.

Sample request in the Alink JSON format:

{
  "id": "123",
  "version": "1.0",
  "sys":{
      "ack":0
  },
  "params": {},
  "method": "thing.topo.get"
}

Sample response in the Alink JSON format:

{
  "id": "123",
  "code": 200,
  "data": [
    {
      "deviceName": "deviceName1234",
      "productKey": "1234556554"
    }
  ]
}

Request parameters

Response parameters

Error messages:

Submit newly discovered devices

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

• Request topic: /sys/{productKey}/{deviceName}/thing/list/found
• Response topic: /sys/{productKey}/{deviceName}/thing/list/found_reply

In specific scenarios, a gateway can discover new sub-devices. The gateway reports the information about new sub-devices to IoT Platform. IoT Platform forwards the information to third-party applications, and the third-party applications choose the sub-devices to connect to the gateway.

Sample request in the Alink JSON format:

{
  "id": "123",
  "version": "1.0",
  "sys":{
      "ack":0
  },
  "params": [
    {
      "deviceName": "deviceName1234",
      "productKey": "1234556554"
    }
  ],
  "method": "thing.list.found"
}

Sample response in the Alink JSON format:

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

Request parameters

Response parameters

Error messages:

Notify gateways to add topological relationships for sub-devices

The following topic is used when IoT Platform sends requests to a sub-device and the sub-device sends responses to IoT Platform:

• Request topic: /sys/{productKey}/{deviceName}/thing/topo/add/notify
• Response topic: /sys/{productKey}/{deviceName}/thing/topo/add/notify_reply

IoT Platform can use a topic to notify a gateway to add a topological relationship for a sub-device. This applies after the gateway discovers new sub-devices and reports sub-device information to IoT Platform. IoT Platform can subscribe to the following data forwarding topic to receive the response from the gateway: /{productKey}/{deviceName}/thing/downlink/reply/message.

Sample request in the Alink JSON format:

{
  "id": "123",
  "version": "1.0",
  "params": [
    {
      "deviceName": "deviceName1234",
      "productKey": "1234556554"
    }
  ],
  "method": "thing.topo.add.notify"
}

Sample response in the Alink JSON format:

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

Request parameters

Response parameters

Notify gateways of changes of topological relationships

IoT Platform notifies gateways of changes of topological relationships.

Gateways need to subscribe to the following topic: /sys/{productKey}/{deviceName}/thing/topo/change

Sample request in the Alink JSON format:

{
    "id":"123",
    "version":"1.0",
    "params":{
        "status":0, // 0-add 1-remove 2-resume disabling 8-disable
        "subList":[{
            "productKey":"a1hRrzD****",
            "deviceName":"abcd"
        }]
    }, 
  "method":"thing.topo.change"  
}

Request parameters

Sample response in the Alink JSON format:

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