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:
Example:
|
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. |
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. |
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.
|
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":{}
}