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
  • Only quality of service (QoS) 0 messages can be delivered between sub-devices and IoT Platform.
  • 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 a batch cannot exceed 50.
  • If a request to connect or disconnect multiple sub-devices is successful, all the sub-devices are connected or disconnected as expected. If the request fails, all sub-devices fail to be connected or fail to be disconnected, and the data response parameter contains the 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 are related to gateways. Replace the ${productKey} and ${deviceName} variables in the topics with the information about 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 values of the productKey and deviceName parameters in the message body with the corresponding information about 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 the signature procedure 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. Valid values: 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 is disconnected are cleared.
  • If this parameter is set to false, all messages that are not received when the sub-device is 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 is successful 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 Remarks
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 number of authentication requests that are sent from the device exceeds the limit. The device is throttled.
428 too many subdevices under gateway The error message returned because the number of sub-devices that are connected exceeds the limit.
6401 topo relation not exist The error message returned because topological relationships between the gateway and the sub-device do not 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

Important You can connect a maximum of 50 sub-devices to IoT Platform at time.

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 are related to gateways. Replace the ${productKey} and ${deviceName} variables in the topics with the information about 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 values of the productKey and deviceName parameters in the message body with the corresponding information about 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 the signature procedure 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. Valid values: 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 is disconnected are cleared.
  • If this parameter is set to false, all messages that are not received when the sub-device is 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 is successful 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 Remarks
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 number of authentication requests that are sent from the device exceeds the limit. The device is throttled.
428 too many subdevices under gateway The error message returned because the number of sub-devices that are connected exceeds the limit.
6401 topo relation not exist The error message returned because topological relationships between the gateway and the sub-device do not 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 are related to gateways. Replace the ${productKey} and ${deviceName} variables in the topics with the information about the gateway.

Sample request in the Alink JSON format:

{
  "id": "123",
  "params": {
    "productKey": "al12345****",
    "deviceName": "device1234"
  }
}
Note Replace the values of the productKey and deviceName parameters in the message body with the corresponding information about 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 Remarks
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 multiple sub-devices in batches

Important You can disconnect a maximum of 50 sub-devices from IoT Platform at a time.

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 are related to gateways. Replace the ${productKey} and ${deviceName} variables in the topics with the information about the gateway.

Sample request in the Alink JSON format:

{
  "id": "123",
  "params":[{
            "productKey": "al12345****",
            "deviceName": "device1234"
          },{
            "productKey": "al12345****",
            "deviceName": "device4321"
      }]
}
Note Replace the values of the productKey and deviceName parameters in the message body with the corresponding information about 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.