After a sub-device is registered in IoT Platform, a gateway needs to submit the topology 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 topology 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 topology is deleted, 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 topology does not exist. 2. The verification failed.

Add topologies for sub-devices

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

Upstream data

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

Alink request format

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

Alink response 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 of the protocol. Set this parameter to 1.0.
params List The list of request parameters.
deviceName String The name of the sub-device.
productKey String The key 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 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 product key and device name based on the following syntax: productKey&deviceName.
method String The request method. Valid value: 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 response code. A value of 200 indicates that the call was successful.
data Object The information returned if the call was successful. For more information about the parameters, see the following data table.
Table 1. data
Parameter Type Description
deviceName String The name of the sub-device.
productKey String The key of the product to which the sub-device belongs.

Error codes

Error 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.

Delete topologies of sub-devices

You can use a topic to send a request for deleting a topology between a gateway and sub-device. If the topology is deleted, the information of the sub-device is returned.

Upstream data

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

Alink request format

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

Alink response 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 of the protocol. Set this parameter to 1.0.
params List The request parameters.
deviceName String The name of the sub-device.
productKey String The key of the product to which the sub-device belongs.
method String The request method. Valid value: 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 response code. A value of 200 indicates that the call was successful.
data Object The information returned if the call was successful. For more information about the parameters, see the following data table.
Table 2. data
Parameter Type Description
deviceName String The name of the sub-device.
productKey String The key of the product to which the sub-device belongs.

Error codes

Error 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 topologies of sub-devices

Upstream data

  • 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 topology between a gateway and sub-device.

Alink request format

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

Alink response 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 of the protocol. Set this parameter to 1.0.
params Object The request parameters. You can leave the parameters empty.
method String The request method. Valid value: thing.topo.add.

Response parameters

Parameter Type Description
id String Valid values: 0 to 4294967295. Each message ID must be unique for the device.
code Integer The response code. A value of 200 indicates that the call was successful.
data Object The information returned if the call was successful.
deviceName String The name of the sub-device.
productKey String The key of the product to which the sub-device belongs.

Error codes

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

Submit a list of new discovered devices

Upstream data

  • Request topic: /sys/{productKey}/{deviceName}/thing/list/found
  • Response topic: /sys/{productKey}/{deviceName}/_thing/diag/post_reply

In certain scenarios, a gateway can discover new sub-devices. The gateway submits information of 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.

Alink request format

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

Alink response 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 of the protocol. Set this parameter to 1.0.
params Object The request parameters. You can leave the parameters empty.
method String The request method. Valid value: thing.list.found.
deviceName String The name of the sub-device.
productKey String The key 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 response code. A value of 200 indicates that the call was successful.
data Object The information returned if the call was successful.

Error message

Error code 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 name of the sub-device is invalid. The sub-device name must be 4 to 32 characters in length and can contain letters, digits, hyphens (-), at signs (@), periods (.), and colons (:).

Notify gateways to add topologies for sub-devices

Downstream data

  • 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 topology for a sub-device. This applies after the gateway discovers new sub-devices and submits 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.

Alink request format

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

Alink response 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 of the protocol. Set this parameter to 1.0.
params Object The request parameters. You can leave the parameters empty.
method String The request method. Valid value: thing.topo.add.notify.
deviceName String The name of the sub-device.
productKey String The key 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 response code. A value of 200 indicates that the call was successful.
data Object The information returned if the call was successful.

Notify gateways of topology changes

Sub-devices can notify gateways of topology changes.

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

Operation Description Notification method
Add sub-devices to gateways Add topologies between gateways and sub-devices. Notify gateways.
Delete sub-devices Delete topologies between sub-devices and gateways.
Disable sub-devices Disable sub-devices and the topologies between the sub-devices and gateways.
Enable sub-devices Enable sub-devices and restore the topologies between the sub-devices and gateways.

Alink format of downstream data

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

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 of the protocol. Set this parameter to 1.0.
method String The request method. Valid value: thing.topo.change.
params Object The request parameters, including the status and sublist parameters.
status Integer The status of the topology.
  • 0: The topology is created.
  • 1: The topology is deleted.
  • 2: The topology is enabled.
  • 8: The topology is disabled.
deviceName String The name of the sub-device.
productKey String The key of the product to which the sub-device belongs.

Alink response format

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