Connecting Sub-devices to EnOS Cloud in Batch¶

UpStream

Request TOPIC: /ext/session/{productKey}/{deviceKey}/combine/login/batch
Reply TOPIC: /ext/session/{productKey}/{deviceKey}/combine/login/batch_reply

Before You Start¶

Create the sub-device instances on EnOS Cloud.
Add the instances as sub-devices to a gateway device instance.

Sample Request Format¶

{
    "id":"1",
    "params":{
        "clientId":"Lx5Q1X6M",
        "subDevices":[
            {
                "sign":"c14fc21231e6c44849683ccfb7a2089895a278b37a30c33ccb58d3b8690d16e1",
                "deviceKey":"xGKFwfkEXz",
                "productKey":"x4jwTsoz"
            },
            {
                "sign":"1fbf0cd0903a9405d567fe5909a1aae75012df5465211db367c7666c0ae33bf2",
                "deviceKey":"cS9MdVJwO9",
                "productKey":"x4jwTsoz"
            },
            {
                "sign":"480869163c85777c9fcb9fe53340fb13d38ef19e644df82927fcd2393b3819c4",
                "deviceKey":"viWaBURIDm",
                "productKey":"x4jwTsoz"
            }
        ],
        "signMethod":"sha256",
        "timestamp":"1564988853275"
    },
    "version":"1.1",
    "method":"combine.login.batch"
}

Sample Response Format¶

a) All sub-devices logged in successfully¶

{
    "id":"1",
    "code":200,
    "data":{
        "loginedSubDevices":[
            {
                "assetId":"LhBLfxpG",
                "deviceKey":"cS9MdVJwO9",
                "productKey":"x4jwTsoz"
            },
            {
                "assetId":"kAHwVbyl",
                "deviceKey":"viWaBURIDm",
                "productKey":"x4jwTsoz"
            },
            {
                "assetId":"AkHJvoqN",
                "deviceKey":"xGKFwfkEXz",
                "productKey":"x4jwTsoz"
            }
        ],
        "failedSubDevices":[]
    },
    "message":""
}

b) Some of the sub-devices failed to log in¶

{
    "id":"1",
    "code":723,
    "data":{
        "loginedSubDevices":[
            {
                "assetId":"LhBLfxpG",
                "deviceKey":"cS9MdVJwO9",
                "productKey":"x4jwTsoz"
            },
            {
                "assetId":"kAHwVbyl",
                "deviceKey":"viWaBURIDm",
                "productKey":"x4jwTsoz"
            }
        ],
        "failedSubDevices":[
            {
                "deviceKey":"xGKFwfkEXz",
                "productKey":"x4jwTsoz"
            }
        ]
    },
    "message":"x4jwTsoz&xGKFwfkEXz has error: Device is disable;"
}

c) Invalid request format¶

{
    "id":"1",
    "code":1220,
    "data":{
        "loginedSubDevices":[],
        "failedSubDevices":[]
    },
    "message":"payload format error, ..."
}

Handling the Response¶

When the return code code is 723, loggedinSubDevices lists the sub-devices that successfully logged in and failedSubDevices lists those that failed to log in.

When the code is 1220 or if there is an internal server error, no sub-devices will be listed for loggedinSubDevices and failedSubDevices.

The following is a sample on how to handle a reply.

if (code == 200) {
  // All sub-devices logged in successfully.
} else {
  if (loginedSubDevices.isEmpty() && failedSubDevices.isEmpty()) {
    // Invalid format or internal server error
  } else {
    if (loginedSubDevices.isNotEmpty()) {
      // Sub-devices that logged in
    }
    if (failedSubDevices.isNotEmpty()) {
      // Sub-devices that failed to log in
    }
  }
}

Request Parameter Description¶

Parameter	Type	Mandatory/Optional	Description
id	Long	Optional	The message ID. It is a reserved parameter that is reserved for future use.
params	Struct	Mandatory	The parameters used for connecting the sub-device to EnOS Cloud.
deviceKey	String	Mandatory	The device key of the sub-device.
productKey	String	Mandatory	The product key of the sub-device.
version	String	Mandatory	The version No.
method	String	Mandatory	The request method.
sign	String	Mandatory	The signature of the sub-device. Sub-devices use the same signature rules as the gateway device.
signmethod	String	Mandatory	The signing method. The supported method is hmacSha1.
timestamp	String	Mandatory	The timestamp.
clientId	String	Mandatory	The identifier of the device. The value can be its productKey or deviceName.

Note

A gateway device can have a maximum of 200 online sub-devices at the same time. Subsequent new sub-devices will be declined to go online.

Response Parameter Description¶

Parameter	Type	Mandatory/Optional	Description
message	String	Mandatory	The response message.
code	Integer	Mandatory	The return code. “200” indicates that the request operation is executed successfully.
data	JSON	Mandatory	The detailed returned information in JSON format.
loginedSubDevices	Array	Mandatory	The devices that successfully logged in.
failedSubDevices	Array	Mandatory	The devices that failed to log in.

Return Code¶

Return Code	Error Message	Explanation
705	Failed to query device, this device does not exist	The sub-device does not exist.
723	Device is disabled	The sub-device is disabled.
770	Dynamic activate is not allowed	Dynamic activation is not allowed for this product.
771	Sub device cannot connect to mqtt broker directly	Sub-devices cannot be directly connected to EnOS Cloud.
740	Sub device does not belong to the gateway	The device is not a sub-device of this gateway.
742	Sign check failed	Hash signature verification failed.
746	The device must login by ssl	Certificate-based authentication is required for this product.