Sub-device online and offline status-IoT Platform (Deprecated)(IoT)-阿里云帮助中心

You can bring sub-devices online or offline individually or in batches. Before bringing a sub-device online, you must register its identity on the IoT Platform and establish a topology between the sub-device and the gateway. When a sub-device comes online, the IoT Platform verifies its identity based on the topology to determine whether the sub-device can use the gateway channel.

Note

Messages for bringing sub-devices online or offline, including in batches, support only Quality of Service (QoS) 0.
A gateway can support a maximum of 2,000 online sub-devices at one time. After this limit is reached, new requests to bring sub-devices online are rejected.
A single batch request to bring sub-devices online or offline cannot contain more than 50 sub-devices.
A batch request to bring sub-devices online or offline either succeeds for all devices or fails for all devices. If the request fails, the data parameter in the response contains information about the specific devices.

Bring a sub-device online

Uplink data:

Request topic: /ext/session/${productKey}/${deviceName}/combine/login
Response topic: /ext/session/${productKey}/${deviceName}/combine/login_reply

Note Because sub-devices communicate with the IoT Platform through the gateway channel, the topics listed are for the gateway device. Replace the ${productKey} and ${deviceName} variables in the topics with the corresponding information for the gateway device.

Alink request data format:

{
  "id": "123",
  "params": {
    "productKey": "al12345****",
    "deviceName": "device1234",
    "clientId": "al12345****&device1234",
    "timestamp": "1581417203000",
    "signMethod": "hmacmd5",
    "sign": "9B9C732412A4F84B981E1AB97CAB****",
    "cleanSession": "true"
  }
}

Note In the message body, the values of the productKey and deviceName parameters are the corresponding information for the sub-device.

Table 1. Request parameters
Parameter	Type	Description
id	String	The message ID. A string-type number from 0 to 4294967295. Each message ID must be unique for the current device.
params	Object	The request parameters. For details about the specific parameters, see the params table below.

Table 2. params
Parameter	Type	Description
deviceName	String	The device name of the sub-device.
productKey	String	The ProductKey of the product to which the sub-device belongs.
sign	String	The signature of the sub-device. The signing method is the same as that for directly connected devices. Signing method: Sort all parameters submitted to the server (except for sign, signMethod, and cleanSession) in alphabetical order. Then, concatenate the parameters and their values in sequence without any separators. Use the algorithm specified by signMethod and the device's DeviceSecret to calculate the signature for the content to be signed. The result of the calculation is the value of sign. The following example shows how to calculate the value of sign: `hmac_md5(deviceSecret, clientIdal12345**&device1234deviceNamedevice1234productKeyal12345**timestamp1581417203000)`
signMethod	String	The signing method. Supported methods are hmacSha1, hmacSha256, hmacMd5, and Sha256.
timestamp	String	A timestamp in milliseconds.
clientId	String	The device-side identifier. It can be `productKey&deviceName`.
cleanSession	String	If the value is true, all messages from when the sub-device was offline are cleared. This means all unreceived QoS 1 messages are purged. If the value is false, messages from when the sub-device was offline are not cleared.

Alink response data format:

{
  "id":"123",
  "code":200,
  "message":"success"
  "data":{
      "deviceName": "device1234",
      "productKey": "al12345****"
    }
}

Table 3. Response parameters
Parameter	Type	Description
id	String	The message ID. A string-type number from 0 to 4294967295. Each message ID must be unique for the current device.
code	Integer	The result code. 200 indicates success.
message	String	Information about the result.
data	Object	Information about the sub-device that is returned when the request succeeds or fails. For details about the specific parameters, see the data table below.

Table 4. data
Parameter	Type	Description
deviceName	String	The device name of the sub-device.
productKey	String	The ProductKey of the product to which the sub-device belongs.

Error messages:

Error code	Error message	Description
460	request parameter error	The request parameters are invalid.
429	rate limit, too many subDeviceOnline msg in one minute	Authentication requests for a single device are too frequent and have been rate-limited.
428	too many subdevices under gateway	Too many sub-devices are online under the gateway.
6401	topo relation not exist	No topology exists between the gateway and the sub-device.
6100	device not found	The sub-device does not exist.
521	device deleted	The sub-device has been deleted.
522	device forbidden	The sub-device has been disabled.
6287	invalid sign	The sub-device password or signature is incorrect.

Bring sub-devices online in a batch

Important You can bring a maximum of 50 sub-devices online in a single request.

Uplink data:

Request topic: /ext/session/${productKey}/${deviceName}/combine/batch_login
Response topic: /ext/session/${productKey}/${deviceName}/combine/batch_login_reply

Alink request data 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 In the message body, the values of the productKey and deviceName parameters are the corresponding information for the sub-device.

Table 5. Request parameters
Parameter	Type	Description
id	String	The message ID. A string-type number from 0 to 4294967295. Each message ID must be unique for the current device.
params	Object	The request parameters. The deviceList parameter contains a list of authentication parameters for the sub-devices to bring online. For details about the specific parameters, see the deviceList table below.

Table 6. deviceList

Alink response data format:

{
  "id":"123",
  "code":"200",
  "message":"success",
  "data":[{
      "productKey": "al12345****",
      "deviceName": "device1234"
    },{
      "deviceName": "device4321",
      "productKey": "al12345****"
    }]
}

Table 3. Response parameters
Parameter	Type	Description
id	String	The message ID. A string-type number from 0 to 4294967295. Each message ID must be unique for the current device.
code	Integer	The result code. 200 indicates success.
message	String	Information about the result.
data	Object	Information about the sub-device that is returned when the request succeeds or fails. For details about the specific parameters, see the data table below.

Table 4. data
Parameter	Type	Description
deviceName	String	The device name of the sub-device.
productKey	String	The ProductKey of the product to which the sub-device belongs.

Error messages:

Error code	Error message	Description
460	request parameter error	The request parameters are invalid.
429	rate limit, too many subDeviceOnline msg in one minute	Authentication requests for a single device are too frequent and have been rate-limited.
428	too many subdevices under gateway	Too many sub-devices are online under the gateway.
6401	topo relation not exist	No topology exists between the gateway and the sub-device.
6100	device not found	The sub-device does not exist.
521	device deleted	The sub-device has been deleted.
522	device forbidden	The sub-device has been disabled.
6287	invalid sign	The sub-device password or signature is incorrect.

Take a sub-device offline

Uplink data:

Request topic: /ext/session/${productKey}/${deviceName}/combine/logout
Response topic: /ext/session/${productKey}/${deviceName}/combine/logout_reply

Alink request data format:

{
  "id": "123",
  "params": {
    "productKey": "al12345****",
    "deviceName": "device1234"
  }
}

Note In the message body, the values of the productKey and deviceName parameters are the corresponding information for the sub-device.

Table 7. Request parameters
Parameter	Type	Description
id	String	The message ID. A string-type number from 0 to 4294967295. Each message ID must be unique for the current device.
params	Object	The request parameters, which contain information about the sub-device to take offline.

Table 8. params
Parameter	Type	Description
deviceName	String	The device name of the sub-device.
productKey	String	The ProductKey of the product to which the sub-device belongs.

Alink response data format:

{
  "id": "123",
  "code": 200,
  "message": "success",
  "data": {
      "deviceName": "device1234",
      "productKey": "al12345****"
    }
}

Table 9. Response parameters
Parameter	Type	Description
id	String	The message ID. A string-type number from 0 to 4294967295. Each message ID must be unique for the current device.
code	Integer	The result code. 200 indicates success.
message	String	Information about the result.
data	Object	When the request succeeds or fails, information about the sub-device that was taken offline is returned. For details about the specific parameters, see the data table below.

Table 10. data
Parameter	Type	Description
deviceName	String	The device name of the sub-device.
productKey	String	The ProductKey of the product to which the sub-device belongs.

Error messages:

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

Take sub-devices offline in a batch

Important You can take a maximum of 50 sub-devices offline in a single request.

Uplink data:

Request topic: /ext/session/${productKey}/${deviceName}/combine/batch_logout
Response topic: /ext/session/${productKey}/${deviceName}/combine/batch_logout_reply

Alink request data format:

{
  "id": "123",
  "params":[{
            "productKey": "al12345****",
            "deviceName": "device1234"
          },{
            "productKey": "al12345****",
            "deviceName": "device4321"
      }]
}

Note In the message body, the values of the productKey and deviceName parameters are the corresponding information for the sub-device.

Table 7. Request parameters
Parameter	Type	Description
id	String	The message ID. A string-type number from 0 to 4294967295. Each message ID must be unique for the current device.
params	Object	The request parameters, which contain information about the sub-device to take offline.

Table 8. params
Parameter	Type	Description
deviceName	String	The device name of the sub-device.
productKey	String	The ProductKey of the product to which the sub-device belongs.

Alink response data format:

{
  "id":"123",
  "code":"200",
  “message":"success",
  "data":[{
      "productKey": "al12345****",
      "deviceName": "device1234"
    },{
      "deviceName": "device4321",
      "productKey": "al12345****"
    }]
}

Table 9. Response parameters
Parameter	Type	Description
id	String	The message ID. A string-type number from 0 to 4294967295. Each message ID must be unique for the current device.
code	Integer	The result code. 200 indicates success.
message	String	Information about the result.
data	Object	When the request succeeds or fails, information about the sub-device that was taken offline is returned. For details about the specific parameters, see the data table below.

Table 10. data
Parameter	Type	Description
deviceName	String	The device name of the sub-device.
productKey	String	The ProductKey of the product to which the sub-device belongs.

Error messages:

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

References

For information about how to configure sub-device access, see Device identity registration.

For descriptions of error codes and their solutions, see Error codes received by devices.