Before a sub-device goes online, you need to register the sub-device in IoT Platform to establish a topology between the sub-device and the gateway. IoT platform verifies the identity of the sub-device that needs to go online based on the topology to determine whether the sub-device can access the gateway.

Note The message delivery between sub-devices and IoT Platform only supports QoS 0 and does not support QoS 1.

Sub-devices go online

Note The number of sub-devices that are online at the same time cannot exceed 1,500 for a gateway. If the number of online sub-devices exceeds 1,500, IoT Platform rejects all new connection requests.

Upload data

  • Request topic: /ext/session/${productKey}/${deviceName}/combine/login
  • Response topic: /ext/session/{gw_productKey}/{gw_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 topic with the corresponding information of the gateway.

Alink request format

{
  "id": "123",
  "params": {
    "productKey": "al123455655",
    "deviceName": "device1234",
    "clientId": "al123455655&device1234",
    "timestamp": "1581417203000",
    "signMethod": "hmacmd5",
    "sign": "9B9C732412A4F84B981E1AB97CAB****",
    "cleanSession": "true"
  }
}
Note Replace the productKey and deviceName parameters in the message body with the corresponding 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 about specific parameters, 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 method of the sub-device is the same as that of a device that is directly connected to IoT Platform.

Signature method:

  1. Sort all parameters that are submitted to the server (excluding the sign, signMethod, and cleanSession 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.

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

Example of calculating the value of thesign parameter:

hmac_md5(deviceSecret, clientIdal123455655&device1234deviceNamedevice1234productKeyal123455655timestamp1581417203000)
signMethod String The signature algorithm. The supported algorithms are HMACSHA1, HMACSHA256, HMACMD5, and SHA256.
timestamp String The timestamp. Unit: 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 offline are cleared.
  • If this parameter is set to false, all messages that are sent when the sub-device was offline are retained.

Alink response format

{
  "id":"123",
  "code":200,
  "message":"success"
  "data":{
      "deviceName": "device1234",
      "productKey": "al123455655"
    }
}
Table 3. 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.
message String The returned information.
data Object The information returned if the call was successful. For more information about the parameters, 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 codes

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 authentication requests from the device are throttled due to an excessive frequency.
428 too many subdevices under gateway The error message returned because the number of sub-devices that are online at the same time exceeds the limit.
6401 topo relation not exist The error message returned because the topology between the gateway and the sub-device does not exist.
6100 device not found The error message returned because the specified sub-device does not exist.
521 device deleted The error message returned because the sub-device has been deleted.
522 device forbidden The error message returned because the specified sub-device has been disabled.
6287 invalid sign The error message returned because the password or signature of the sub-device is invalid.

Sub-devices go offline

Upload data

  • Request topic: /ext/session/${productKey}/${deviceName}/combine/login
  • Response topic: /ext/session/{gw_productKey}/{gw_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 topic with the corresponding information of the gateway.

Alink request format

{
  "id": 123,
  "params": {
    "productKey": "al123455655",
    "deviceName": "device1234"
  }
}
Note Replace the productKey and deviceName parameters in the message body with the corresponding 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. These parameters specify the information of the sub-device that needs to go offline.
Table 6. 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.

Alink response format

{
  "id": "123",
  "code": 200,
  "message": "success",
  "data": {
      "deviceName": "device1234",
      "productKey": "al123455655"
    }
}
Table 7. Response parameters
Field 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.
message String The returned information.
data Object The sub-device information returned if the call is successful. For more information about specific parameters, 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 codes

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 the sub-device session does not exist.

For more information about how to connect sub-devices to IoT Platform, see Device identity registration. For more information about error codes, see Error codes for device SDKs.