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.

Important Up to 30 sub-devices can be added at a time.

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/${productKey}/${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

ParameterTypeDescription
idStringThe ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
versionStringThe version number of the protocol. Set the value to 1.0.
sysObjectThe 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.
ackIntegerThe 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: IoT Platform needs to return response data.
  • 0: IoT Platform does not need to return response data.
Important For more information about the parameter, see Examples on how to use a TSL model.

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

paramsListThe request parameters.
deviceNameStringThe DeviceName of the sub-device.
productKeyStringThe ProductKey of the product to which the sub-device belongs.
signString

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)
signmethodStringThe signature algorithm. The supported algorithms are HMACSHA1, HMACSHA256, HMACMD5, and SHA256.
timestampStringThe timestamp.
clientIdStringOptional. 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.
methodStringThe request method. Set the value to thing.topo.add.

Response parameters

ParameterTypeDescription
idStringThe ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for a device.
codeIntegerThe status code. The value 200 indicates that the request is successful.
dataObjectThe returned sub-device information in the case of a successful request. For more information about the parameters, see the following table.
Table 1. data
ParameterTypeDescription
deviceNameStringThe DeviceName of the sub-device.
productKeyStringThe ProductKey of the product to which the sub-device belongs.

Error messages

HTTP status codeError messageDescription
460request parameter errorThe error message returned because the request parameters are invalid.
6402topo relation cannot add by selfThe error message returned because a device cannot be added as a sub-device of itself.
401request auth errorThe 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.

Important Up to 30 sub-devices can be deleted at a time.

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/${productKey}/${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

ParameterTypeDescription
idStringThe ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
versionStringThe version number of the protocol. Set the value to 1.0.
sysObjectThe 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.
ackIntegerThe 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: IoT Platform needs to return response data.
  • 0: IoT Platform does not need to return response data.
Important For more information about the parameter, see Examples on how to use a TSL model.

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

paramsListThe request parameters.
deviceNameStringThe DeviceName of the sub-device.
productKeyStringThe ProductKey of the product to which the sub-device belongs.
methodStringThe request method. Set the value to thing.topo.delete.

Response parameters

ParameterTypeDescription
idStringThe ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for a device.
codeIntegerThe status code. The value 200 indicates that the request is successful.
dataObjectThe returned sub-device information in the case of a successful request. For more information about the parameters, see the following table.
Table 2. data
ParameterTypeDescription
deviceNameStringThe DeviceName of the sub-device.
productKeyStringThe ProductKey of the product to which the sub-device belongs.

Error messages

HTTP status codeError messageDescription
460request parameter errorThe error message returned because the request parameters are invalid.
6100device not foundThe error message returned because the 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/${productKey}/${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

ParameterTypeDescription
idStringThe ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
versionStringThe version number of the protocol. Set the value to 1.0.
sysObjectThe 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.
ackIntegerThe 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: IoT Platform needs to return response data.
  • 0: IoT Platform does not need to return response data.
Important For more information about the parameter, see Examples on how to use a TSL model.

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

paramsObjectThe request parameters. You can leave the parameters empty.
methodStringThe request method. Set the value to thing.topo.get.

Response parameters

ParameterTypeDescription
idStringThe ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for a device.
codeIntegerThe status code. The value 200 indicates that the request is successful.
dataObjectThe response data in the case of a successful request.
deviceNameStringThe DeviceName of the sub-device.
productKeyStringThe ProductKey of the product to which the sub-device belongs.

Error messages

HTTP status codeError messageDescription
460request parameter errorThe error message returned because the request parameters are invalid.

Submit newly discovered 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/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

ParameterTypeDescription
idStringThe ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
versionStringThe version number of the protocol. Set the value to 1.0.
sysObjectThe 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.
ackIntegerThe 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: IoT Platform needs to return response data.
  • 0: IoT Platform does not need to return response data.
Important For more information about the parameter, see Examples on how to use a TSL model.

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

paramsObjectThe request parameters. You can leave the parameters empty.
methodStringThe request method. Set the value to thing.list.found.
deviceNameStringThe DeviceName of the sub-device.
productKeyStringThe ProductKey of the product to which the sub-device belongs.

Response parameters

ParameterTypeDescription
idStringThe ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for a device.
codeIntegerThe status code. The value 200 indicates that the request is successful.
dataObjectThe response data in the case of a successful request.

Error messages

HTTP status codeError messageDescription
460request parameter errorThe error message returned because the request parameters are invalid.
6250product not foundThe error message returned because the product to which the sub-device belongs does not exist.
6280devicename not meet specsThe 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

ParameterTypeDescription
idString

The message ID that is generated by IoT Platform. Valid values: 0 to 4294967295. Each message ID must be unique for the device.

versionStringThe version number of the protocol. Set the value to 1.0.
paramsObjectThe request parameters. You can leave the parameters empty.
methodStringThe request method. Set the value to thing.topo.add.notify.
deviceNameStringThe DeviceName of the sub-device.
productKeyStringThe ProductKey of the product to which the sub-device belongs.

Response parameters

ParameterTypeDescription
idStringThe ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for a device.
codeIntegerThe status code. The value 200 indicates that the request is successful.
dataObjectThe 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

OperationBehaviornotification method
Add sub-devices to gateways.Add topological relationships between gateways and sub-devices. Notify gateways.
Delete sub-devices.Delete 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

ParameterTypeDescription
idString

The message ID that is generated by IoT Platform. Valid values: 0 to 4294967295. Each message ID must be unique for the device.

versionStringThe version number of the protocol. Set the value to 1.0.
methodStringThe request method. Set the value to thing.topo.change.
paramsObjectThe 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.
statusIntegerThe 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.
deviceNameStringThe DeviceName of the sub-device.
productKeyStringThe ProductKey of the product to which the sub-device belongs.

Sample response in the Alink JSON format:

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