After a sub-device is registered in IoT Platform, a gateway needs to report the topological relationship between the sub-device and gateway to connect the sub-device to IoT Platform.

When a sub-device connects to IoT Platform, IoT Platform verifies its identity and the topological relationship between the sub-device and the gateway. If the verification is successful, IoT Platform establishes a logical connection with the sub-device and associates the logical connection with the physical connection of the gateway. The communication protocol between the sub-device and IoT Platform is the same as that between a directly connected device and IoT Platform. Gateway information is not required in the communication protocol.

If the topological relationship is removed, the sub-device cannot connect to IoT Platform by using the gateway. The following errors may occur if you connect the sub-device to IoT Platform: 1. The topological relationship does not exist. 2. The verification failed.

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

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 list of request parameters.
deviceName String The DeviceName of the sub-device.
productKey String The ProductKey of the product to which the sub-device belongs.
sign String

The signature.

Signature method:

  1. Sort all parameters that are submitted to the server, excluding the sign and signMethod parameters, in alphabetical order, and splice the parameters and values in sequence without using splicing symbols.
  2. Use the algorithm that is specified by the signMethod parameter and the value of the DeviceSecret parameter to calculate the signature.
Example:
sign= hmac_md5(deviceSecret, clientId123deviceNametestproductKey123timestamp1524448722000)
signmethod String The signature algorithm. The supported algorithms are HMACSHA1, HMACSHA256, HMACMD5, and SHA256.
timestamp String The timestamp.
clientId String Optional. The on-premises identifier of the device. You can set this parameter to a value that combines the ProductKey and DeviceName based on the following syntax: productKey&deviceName.
method String The request method. Set the value to thing.topo.add.

Response 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.
code Integer The status code that indicates the result. A value of 200 indicates a successful request.
data Object The returned sub-device information in the case of a successful request. For more information about the parameters, see the following table.
Table 1. data
Parameter Type Description
deviceName String The DeviceName of the sub-device.
productKey String The ProductKey of the product to which the sub-device belongs.

Error messages:

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 message returned because a device cannot be added as a sub-device of itself.
401 request auth error The error message returned because the signature failed to be verified.

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

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 list of request parameters.
deviceName String The DeviceName of the sub-device.
productKey String The ProductKey of the product to which the sub-device belongs.
method String The request method. Set the value to thing.topo.delete.

Response 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.
code Integer The status code that indicates the result. A value of 200 indicates a successful request.
data Object The returned sub-device information in the case of a successful request. For more information about the parameters, see the following table.
Table 2. data
Parameter Type Description
deviceName String The DeviceName of the sub-device.
productKey String The ProductKey of the product to which the sub-device belongs.

Error messages:

HTTP status code Error message Description
460 request parameter error The error message returned because the request parameters are invalid.
6100 device not found The error message returned because the specified sub-device does not exist.

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

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 Object The request parameters. You can leave the parameters empty.
method String The request method. Set the value to thing.topo.get.

Response 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.
code Integer The status code that indicates the result. A value of 200 indicates a successful request.
data Object The response data in the case of a successful request.
deviceName String The DeviceName of the sub-device.
productKey String The ProductKey of the product to which the sub-device belongs.

Error messages:

HTTP status code Error message Description
460 request parameter error The error message returned because the request parameters are invalid.

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

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 Object The request parameters. You can leave the parameters empty.
method String The request method. Set the value to thing.list.found.
deviceName String The DeviceName of the sub-device.
productKey String The ProductKey of the product to which the sub-device belongs.

Response 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.
code Integer The status code that indicates the result. A value of 200 indicates a successful request.
data Object The response data in the case of a successful request.

Error messages:

HTTP status code Error message Description
460 request parameter error The error message returned because the request parameters are invalid.
6250 product not found The error message returned because the product to which the sub-device belongs does not exist.
6280 devicename not meet specs The error message returned because the DeviceName of the sub-device reported by the gateway is invalid.

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

Parameter Type Description
id String

The message ID that is generated by IoT Platform. 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.
params Object The request parameters. You can leave the parameters empty.
method String The request method. Set the value to thing.topo.add.notify.
deviceName String The DeviceName of the sub-device.
productKey String The ProductKey of the product to which the sub-device belongs.

Response 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.
code Integer The status code that indicates the result. A value of 200 indicates a successful request.
data Object The response data in the case of a successful request.

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

Operation Behavior Notification method
Add sub-devices to gateways. Add topological relationships between gateways and sub-devices. Notify gateways.
Remove sub-devices. Remove topological relationships between sub-devices and gateways.
Disable sub-devices. Disable sub-devices and the topological relationships between the sub-devices and gateways.
Enable sub-devices Enable sub-devices and restore the topological relationships between the sub-devices and gateways.

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

Parameter Type Description
id String

The message ID that is generated by IoT Platform. 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.
method String The request method. Set the value to thing.topo.change.
params Object The request parameters, including the status and subList parameters. The status parameter specifies the status of the topological relationship. The subList parameter specifies the list of sub-devices.
status Integer The status of the topological relationship.
  • 0: The topological relationship is added.
  • 1: The topological relationship is removed.
  • 2: The topological relationship is enabled.
  • 8: The topological relationship is disabled.
deviceName String The DeviceName of the sub-device.
productKey String The ProductKey of the product to which the sub-device belongs.

Sample response in the Alink JSON format:

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