You can connect or disconnect sub-devices separately or in batches. Before you connect a sub-device, you must register the sub-device in IoT Platform to establish a topological relationship between the sub-device and the gateway. When the sub-device is connected, IoT Platform verifies the identity of the sub-device based on the topological relationship to determine whether the sub-device can access the gateway.

Note
  • The message delivery between sub-devices and IoT Platform supports QoS 0 rather than QoS 1.
  • The number of sub-devices that are connected to IoT Platform cannot exceed 2,000 for a gateway. If the number of connected sub-devices reaches 2,000, IoT Platform rejects all subsequent connection requests.
  • The number of sub-devices that are connected or disconnected in one batch cannot exceed 50.
  • If a request to connect or disconnect multiple sub-devices succeeds, all the sub-devices are connected or disconnected as requested. If the request fails, all the sub-devices fail to be connected or disconnected, and the data response parameter contains the detailed device information.

Connect a sub-device to IoT Platform

Upstream data:

  • Request topic: /ext/session/${productKey}/${deviceName}/combine/login
  • Response topic: /ext/session/${productKey}/${deviceName}/combine/login_reply
Note Sub-devices use the gateway to communicate with IoT Platform. The preceding topics belong to the gateway. Replace the ${productKey} and ${deviceName} variables in the topics with the information of the gateway.

Sample request in the Alink JSON format:

{
  "id": "123",
  "params": {
    "productKey": "al12345****",
    "deviceName": "device1234",
    "clientId": "al12345****&device1234",
    "timestamp": "1581417203000",
    "signMethod": "hmacmd5",
    "sign": "9B9C732412A4F84B981E1AB97CAB****",
    "cleanSession": "true"
  }
}
Note Replace the productKey and deviceName parameters in the message body with the information of the sub-device.
Table 1. 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.
params Object The request parameters. For more information, see the following params table.
Table 2. params
Parameter Type Description
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 of the sub-device. The signature procedure of the sub-device is the same as that of a directly connected device.

Procedure:

  1. Sort all parameters that are submitted to the server in alphabetical order and concatenate the parameters and values. No concatenation symbol is required to separate these parameters and values. The sign, signMethod, and cleanSession parameters must be excluded.
  2. Use the algorithm that is specified by the signMethod parameter and the value of the DeviceSecret parameter to calculate the signature.

    Use the calculation result as the value of the sign parameter.

Example of how the value of the sign parameter is calculated: 

hmac_md5(deviceSecret, clientIdal12345****&device1234deviceNamedevice1234productKeyal12345****timestamp1581417203000)
signMethod String The signature algorithm. The supported algorithms are HMACSHA1, HMACSHA256, HMACMD5, and SHA256.
timestamp String The value is a timestamp in milliseconds.
clientId String The ID 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.
cleanSession String
  • If this parameter is set to true, all QoS 1 messages that are not received when the sub-device was disconnected are cleared.
  • If this parameter is set to false, all messages that are not received when the sub-device was disconnected are retained.

Sample response in the Alink JSON format:

{
  "id":"123",
  "code":200,
  "message":"success"
  "data":{
      "deviceName": "device1234",
      "productKey": "al12345****"
    }
}
Table 3. Response parameters
Parameter Type Description
id String The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for a device.
code Integer The status code. The value 200 indicates that the request is successful.
message String The response message.
data Object The sub-device information that is returned regardless of whether the request succeeds or fails. For more information, see the following data table.
Table 4. 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 messages:

Error code Error message Description
460 request parameter error The error message returned because the request parameters are invalid.
429 rate limit, too many subDeviceOnline msg in one minute The error message returned because the system cannot process this number of authentication requests from the device. The device is throttled.
428 too many subdevices under gateway The error message returned because the number of sub-devices that are connected at the same time exceeds the limit.
6401 topo relation not exist The error message returned because no topological relationships between the gateway and the sub-device exist.
6100 device not found The error message returned because the sub-device does not exist.
521 device deleted The error message returned because the sub-device is deleted.
522 device forbidden The error message returned because the sub-device is disabled.
6287 invalid sign The error message returned because the password or signature of the sub-device is invalid.

Connect sub-devices in batches

Upstream data:

  • Request topic: /ext/session/${productKey}/${deviceName}/combine/login
  • Response topic: /ext/session/${productKey}/${deviceName}/combine/batch_login_reply
Note Sub-devices use the gateway to communicate with IoT Platform. The preceding topics belong to the gateway. Replace the ${productKey} and ${deviceName} variables in the topics with the information of the gateway.

Sample request in the Alink JSON format:

{
  "id": "123",
  "params":{ 
     "deviceList":[{
        "productKey": "al12345****", 
        "deviceName": "device1234",
        "clientId": "al12345****&device1234",
        "timestamp": "1581417203000", 
        "cleanSession": "false",
        "signMethod": "hmacmd5",
        "sign": "9B9C732412A4F84B981E1AB97CAB****",
     }, {
        "productKey": "al12345****", 
        "deviceName": "device4321",
        "clientId": "al12345****&device4321",
        "timestamp": "1581417203000", 
        "cleanSession": "true",
        "signMethod": "hmacmd5",
        "sign": "9B9C732412A4F84B981E1AB97CAB****",
     }]
  }
}
Note Replace the productKey and deviceName parameters in the message body with the information of the sub-device.
Table 5. 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.
params Object The request parameters. The deviceList parameter includes the parameters required to authenticate sub-devices that you want to connect. For more information, see the following deviceList table.
Table 6. deviceList
Parameter Type Description
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 of the sub-device. The signature procedure of the sub-device is the same as that of a directly connected device.

Procedure:

  1. Sort all parameters that are submitted to the server in alphabetical order and concatenate the parameters and values. No concatenation symbol is required to separate these parameters and values. The sign, signMethod, and cleanSession parameters must be excluded.
  2. Use the algorithm that is specified by the signMethod parameter and the value of the DeviceSecret parameter to calculate the signature.

    Use the calculation result as the value of the sign parameter.

Example of how the value of the sign parameter is calculated: 

hmac_md5(deviceSecret, clientIdal12345****&device1234deviceNamedevice1234productKeyal12345****timestamp1581417203000)
signMethod String The signature algorithm. The supported algorithms are HMACSHA1, HMACSHA256, HMACMD5, and SHA256.
timestamp String The value is a timestamp in milliseconds.
clientId String The ID 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.
cleanSession String
  • If this parameter is set to true, all QoS 1 messages that are not received when the sub-device was disconnected are cleared.
  • If this parameter is set to false, all messages that are not received when the sub-device was disconnected are retained.

Sample response in the Alink JSON format:

{
  "id":"123",
  "code":"200",
  "message":"success",
  "data":[{
      "productKey": "al12345****",
      "deviceName": "device1234"
    },{
      "deviceName": "device4321",
      "productKey": "al12345****"
    }]
}
Table 7. Response parameters
Parameter Type Description
id String The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for a device.
code Integer The status code. The value 200 indicates that the request is successful.
message String The response message.
data Object The sub-device information that is returned regardless of whether the request succeeds or fails. For more information, see the following data table.
Table 8. 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 messages:

Error code Error message Description
460 request parameter error The error message returned because the request parameters are invalid.
429 rate limit, too many subDeviceOnline msg in one minute The error message returned because the system cannot process this number of authentication requests from the device. The device is throttled.
428 too many subdevices under gateway The error message returned because the number of sub-devices that are connected at the same time exceeds the limit.
6401 topo relation not exist The error message returned because no topological relationships between the gateway and the sub-device exist.
6100 device not found The error message returned because the sub-device does not exist.
521 device deleted The error message returned because the sub-device is deleted.
522 device forbidden The error message returned because the sub-device is disabled.
6287 invalid sign The error message returned because the password or signature of the sub-device is invalid.

Disconnect a sub-device from IoT Platform

Upstream data:

  • Request topic: /ext/session/${productKey}/${deviceName}/combine/logout
  • Response topic: /ext/session/${productKey}/${deviceName}/combine/logout_reply
Note Sub-devices use the gateway to communicate with IoT Platform. The preceding topics belong to the gateway. Replace the ${productKey} and ${deviceName} variables in the topics with the information of the gateway.

Sample request in the Alink JSON format:

{
  "id": "123",
  "params": {
    "productKey": "al12345****",
    "deviceName": "device1234"
  }
}
Note Replace the productKey and deviceName parameters in the message body with the information of the sub-device.
Table 9. 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.
params Object The request parameters. These parameters specify the information about the sub-device that you want to disconnect.
Table 10. params
Parameter Type Description
deviceName String The name of the sub-device.
productKey String The key of the product to which the sub-device belongs.

Sample response in the Alink JSON format:

{
  "id": "123",
  "code": 200,
  "message": "success",
  "data": {
      "deviceName": "device1234",
      "productKey": "al12345****"
    }
}
Table 11. Response parameters
Parameter Type Description
id String The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for a device.
code Integer The status code. The value 200 indicates that the request is successful.
message String The response message.
data Object The sub-device information that is returned regardless of whether the request succeeds or fails. For more information, see the following data table.
Table 12. 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 messages:

Error code Error message Description
460 request parameter error The error message returned because the request parameters are invalid.
520 device no session The error message returned because the sub-device session does not exist.

Disconnect sub-devices in batches

Upstream data:

  • Request topic: /ext/session/${productKey}/${deviceName}/combine/batch_logout
  • Response topic: /ext/session/${productKey}/${deviceName}/combine/batch_logout_reply
Note Sub-devices use the gateway to communicate with IoT Platform. The preceding topics belong to the gateway. Replace the ${productKey} and ${deviceName} variables in the topics with the information of the gateway.

Sample request in the Alink JSON format:

{
  "id": "123",
  "params":[{
            "productKey": "al12345****",
            "deviceName": "device1234"
          },{
            "productKey": "al12345****",
            "deviceName": "device4321"
      }]
}
Note Replace the productKey and deviceName parameters in the message body with the information of the sub-device.
Table 13. 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.
params Object The request parameters. These parameters specify the information about the sub-device that you want to disconnect.
Table 14. params
Parameter Type Description
deviceName String The name of the sub-device.
productKey String The key of the product to which the sub-device belongs.

Sample response in the Alink JSON format:

{
  "id":"123",
  "code":"200",
  "message":"success",
  "data":[{
      "productKey": "al12345****"
      "deviceName": "device1234"
    },{
      "deviceName": "device4321",
      "productKey": "al12345****"
    }]
}
Table 15. Response parameters
Parameter Type Description
id String The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for a device.
code Integer The status code. The value 200 indicates that the request is successful.
message String The response message.
data Object The sub-device information that is returned regardless of whether the request succeeds or fails. For more information, see the following data table.
Table 16. 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 messages:

Error code Error message Description
460 request parameter error The error message returned because the request parameters are invalid.
520 device no session The error message returned because the sub-device session does not exist.

References

For more information about how to connect sub-devices to IoT Platform, see Register devices.

For more information about error codes and solutions, see Error codes for devices.