Connect Sub-devices to EnOS™ Cloud¶

Before a sub-device comes online, ensure that:

The sub-device identity is registered in EnOS Cloud.
The topology relationship is added in Edge.

The cloud will verify the sub-device identity based on the topology relationship to confirm that the sub-device has the ability to use the gateway channel before bringing it online.

Upstream

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

The productKey and deviceKey in above Topics belong to the gateway device.

Sample Request Format¶

{
    "id": "123",
    "params": {
        "productKey": "theSubProductKey",
        "deviceKey": "theSubDeviceKey",
        "clientId": "theSubDeviceId",
        "timestamp": "1524448722000",
        "signMethod": "hmacmd5",
        "sign": "theSignature",
        "cleanSession": "true"
    },
    "method":"combine.login"
}

Sample Response Format¶

{
  "id":"123",
  "code":200,
  "message":"success",
  "data": {
    "assetId": "t5CM9W2b",
    "productKey": "123",
    "deviceKey": "test"
  }
}

Request Parameter Description¶

Parameter	Type	Mandatory/Optional	Description
id	String	Optional	The message ID. It is a reserved parameter that is reserved for future use.
params	Map	Mandatory	The parameters used for connecting 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
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.
signmethod	String	Mandatory	The signing method. The supported method is hmacSha1.
timestamp	String	Mandatory	The timestamp.
clientId	String	Mandatory	The identifier of the sub-device. The value can be its `productKey` or `deviceName`.
cleanSession	String	Mandatory	Supported value: True. Offline information (information that has not been received by QoS 1) will be cleared for all sub-devices.

To generate sign, you need to use every key-value pair in the params parameter except sign and signmethod. The steps are as follows.

Concatenate every key-value pair except sign and signmethod in alphabetical order in the form of “key+value””key+value””key+value”.

For example, a concatenated string as follows should be generated from the previous request based on the request’s params: clientIdtheSubDeviceIddeviceKeyyourDeviceKeyproductKeyyourProductKeytimestamp1524448722000
Add the device’s device secret to the end of the concatenated string from the previous step. Use the algorithm specified by signmethod to calculate the string that includes the device secret. Capitalize all letters in the result to get the sign.

For example, if the device secret is xyz123, the value forsign can be generated using the below:

sign=uppercase(hmacsha1(clientIdtheSubDeviceIddeviceKeyyourDeviceKeyproductKeyyourProductKeytimestamp1524448722000xyz123))

Response Parameter Description¶

:widths: auto :header-rows: 1¶
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	Optional	The detailed returned information in JSON format.

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.