IoT Explorer Topology Relationship Management-Device Development Guide-Help & Documentation-Tencent Cloud

Feature Overview
For devices of the gateway type, they can bind and unbind their subdevices through data communication with the cloud. To implement such functionality, the following two topics need to be leveraged:
Data upstream Topic (for publishing): $gateway/operation/${productid}/${devicename}
Data downstream Topic (for subscription): $gateway/operation/result/${productid}/${devicename}
Binding Device
Devices of the gateway type can use the data upstream Topic to request adding the topological relationship between them and their subdevices to implement binding sub-devices. After successful request, the cloud returns the binding result information of the subdevice through the data downstream Topic.
Data format of the gateway binding sub-device request:
{
  "type": "bind",
  "payload": {
    "devices": [
      {
        "product_id": "CFC******AG7",
        "device_name": "subdeviceaaaa",
        "signature": "signature",
        "random": 121213,
        "timestamp": 1589786839,
        "signmethod": "hmacsha256",
        "authtype": "psk"
      }
    ]
  }
}
﻿
Response data format for binding sub-device by gateway:
{
  "type": "bind",
  "payload": {
    "devices": [
      {
        "product_id": "CFC******AG7",
        "device_name": "subaaa",
        "result": -1
      }
    ]
  }
}
﻿
Request Parameter Description:
Field
Type
Description
type
String
Gateway Message Type. The value for binding sub-device is: bind.
payload.devices
Array
The list of sub-devices that should be bound.
product_id
String
Subdevice Product ID.
device_name
String
Subdevice name.
signature
String
Sub-device binding signature string. Signature algorithm:
1. Signature original string, concatenate the product ID, device name, random number, and timestamp: text=${product_id}${device_name};${random};${timestamp}
2. Use the device Psk key or the Sha1 abstract of the certificate for signing: base64_encode(hmac_Sha1(device_secret, text))
random
Int
Random number.
timestamp
Int
Timestamp, in seconds.
signmethod
String
Signature algorithm. Support hmacsha1, hmacsha256.
authtype
String
Signature type.
psk: Signing using device psk.
certificate: Signing using the device public key certificate.
Response Parameter Description:
Field
Type
Description
type
String
Gateway Message Type. The value for binding sub-device is: bind.
payload.devices
Array
List of sub-devices that should be bound.
product_id
String
Subdevice Product ID.
device_name
String
Subdevice name.
result
Int
Sub-device binding result. See Error Code in the table below.
Unbinding Device
Devices of the gateway type can use the data upstream Topic to request unbinding the topological relationship between them and their sub-devices. After successful request, the cloud returns the unbinding information of the sub-devices through the data downstream Topic.
Request data format for unbinding sub-device by gateway:
{
  "type": "unbind",
  "payload": {
    "devices": [
      {
        "product_id": "CFC******AG7",
        "device_name": "subaaa"
      }
    ]
  }
}
﻿
Response data format for gateway unbinding sub-device:
{
  "type": "unbind",
  "payload": {
    "devices": [
      {
        "product_id": "CFC******AG7",
        "device_name": "subaaa",
        "result": -1
      }
    ]
  }
}
﻿
Request Parameter Description:
Field
Type
Description
type
String
Gateway Message Type. The value for unbinding sub-device is: unbind.
payload.devices
Array
The list of sub-devices that need to be unbound.
product_id
String
Subdevice Product ID.
device_name
String
Subdevice name.
Response Parameter Description:
Field
Type
Description
type
String
Gateway Message Type. The value for unbinding sub-device is: unbind.
payload.devices
Array
The list of sub-devices that need to be unbound.
product_id
String
Subdevice Product ID.
device_name
String
Subdevice name.
result
Int
Sub-device binding result. See Error Code in the table below.
Enable the Search State of the Notification Gateway
When the application side mini program or app needs to enter a certain sub-device binding process, the platform will notify the Notification Gateway to enable and disable the sub-device search feature. The protocol is as follows:
Data upstream Topic (for publishing): $gateway/operation/${productid}/${devicename}
Data downstream Topic (for subscription): $gateway/operation/result/${productid}/${devicename}
Data Format Delivered by the Platform
{
    "type": "search_devices",
    "payload": {
    "status": 0 //0-off 1-on
    }
}
Request Parameter Description:
Field
Type
Description
type
String
Gateway Message Type. Notification Gateway enables search state, value is: search_devices.
status
Int
Gateway search state:
0: Disable.
1: Enable.
Data Format of Gateway Reply
{
    "type": "search_devices",
    "payload": {
    "status": 0, //0-off 1-on
    "result": 0
    }
}
Field
Type
Description
type
String
Gateway Message Type. Notification Gateway enables search state, value is: search_devices.
status
Int
Gateway search state:
0: Off.
1: Enable.
result
Int
Gateway Response Handling Result
0: Success.
1: Failure.
Topology Relationship Query
Devices of the gateway type can use this Topic for an upstream request to query the topological relationship of subdevices.
Gateway query sub-device topology relationship request data format:
{
    "type": "describe_sub_devices"
}
﻿
Request parameter description:
Parameter
Type
Description
type
String
Gateway Message Type. The value for querying sub-devices is: describe_sub_devices.
Gateway query sub-device topology relationship response data format:
{
  "type": "describe_sub_devices",
  "payload": {
    "devices": [
      {
        "product_id": "XKFA****LX",
        "device_name": "2OGDy7Ws8mG****YUe"
      },
      {
        "product_id": "XKFA****LX",
        "device_name": "5gcEHg3Yuvm****2p8"
      },
      {
        "product_id": "XKFA****LX",
        "device_name": "hmIjq0gEFcf****F5X"
      },
      {
        "product_id": "XKFA****LX",
        "device_name": "x9pVpmdRmET****mkM"
      },
      {
        "product_id": "XKFA****LX",
        "device_name": "zmHv6o6n4G3****Bgh"
      }
    ]
  }
}
﻿
Response Parameter Description:
Parameter
Type
Description
type
String
Gateway Message Type. The value for querying sub-devices is: describe_sub_devices.
payload.devices
Array
The list of sub-devices bound to the gateway.
product_id
String
Subdevice Product ID.
device_name
String
Subdevice name.
Topology Change
Devices of the gateway type can subscribe to the platform through this data downlink Topic to get topology changes of subdevices.
When a sub-device is bound or unbound, the gateway will receive topology changes of the sub-device. The data format is as follows:
{
  "type": "change",
  "payload": {
  "status": 0,  //0-unbind 1-bind
  "devices": [
      {
        "product_id": "CFCS****G7",
        "device_name": "****ev",
      }
    ]
  }
}
﻿
Request Parameter Description:
Parameter
Type
Description
type
String
Gateway Message Type. Topology change value is: change.
status
Int
Topology change status. 
0: Unbind.
1: Bind.
payload.devices
Array
The list of sub-devices bound to the gateway.
product_id
String
Subdevice Product ID.
device_name
String
Subdevice name.
Gateway response, data format as follows:
{
  "type": "change",
  "result": 0
}
﻿
Response Parameter Description:
Parameter
Type
Description
type
String
Gateway Message Type. Topology change value is: change.
result
Int
Gateway Response Handling Result.
Error Codes
Error Code
Description
0
Succeeded.
-1
Gateway device not bound to subdevice.
-2
System error. Subdevice online or offline failure.
801
Request parameter error.
802
Invalid device name or device does not exist.
803
Signature verification failed.
804
The signature method is not supported.
805
The signed request has expired.
806
The device has been bound.
807
Non-standard equipment cannot be bound.
808
The operation is not allowed.
809
Repeat binding.
810
Unsupported subdevice.
﻿

Field	Type	Description
type	String	Gateway Message Type. The value for binding sub-device is: `bind`.
payload.devices	Array	The list of sub-devices that should be bound.
product_id	String	Subdevice Product ID.
device_name	String	Subdevice name.
signature	String	Sub-device binding signature string. Signature algorithm: 1. Signature original string, concatenate the product ID, device name, random number, and timestamp: text=${product_id}${device_name};${random};${timestamp} 2. Use the device Psk key or the Sha1 abstract of the certificate for signing: `base64_encode(hmac_Sha1(device_secret, text))`
random	Int	Random number.
timestamp	Int	Timestamp, in seconds.
signmethod	String	Signature algorithm. Support hmacsha1, hmacsha256.
authtype	String	Signature type. psk: Signing using device psk. certificate: Signing using the device public key certificate.

Parameter	Type	Description
type	String	Gateway Message Type. The value for querying sub-devices is: `describe_sub_devices`.

Error Code	Description
0	Succeeded.
-1	Gateway device not bound to subdevice.
-2	System error. Subdevice online or offline failure.
801	Request parameter error.
802	Invalid device name or device does not exist.
803	Signature verification failed.
804	The signature method is not supported.
805	The signed request has expired.
806	The device has been bound.
807	Non-standard equipment cannot be bound.
808	The operation is not allowed.
809	Repeat binding.
810	Unsupported subdevice.

Topology Relationship Management

On this page:

Feature Overview

Binding Device

Unbinding Device

Enable the Search State of the Notification Gateway

Topology Relationship Query

Topology Change

Error Codes