Get Device Connection Info¶

Get Device Connection Info API is used by the device to get the triple information for itself, sub-devices, or branch devices, as well as the EnOS MQTT/HTTP protocol public address. After obtaining the triple information using this API, the device can use the EnOS-provided device SDK to attempt a connection to EnOS.

Get Device Connection Info API is compatible with Bootstrap Device API, with the following differences:

API Name	Function	Scenario Sample
Get Device Connection Info	Registered devices to get the triple information, including single-channel devices, multi-channel devices, gateway devices, and sub-devices.	Registered devices get the triple information for themselves, branch devices, or sub-devices.
Bootstrap Device	Direct-connected devices to get their own triple information and register themselves if they are unregistered.	Direct-connected devices register themselves.

Prerequisites¶

Ensure the device has been allocated and activated. You can use Allocate DPS Device API to allocate and activate devices if required.

Request Format¶

POST http(s)://{dps-address}/preview/get/conn

For more information, see About Device APIs.

Request Parameters(Body)¶

Name	Required/Optional	Data Type	Description
self	Required	DeviceAuth Struct	The authentication information of the device itself.
signMethod	Optional	String	The signature algorithm. Supports `sha256` only.
sub	Optional	SubDeviceAuth Struct	The authentication information of the sub-devices or branch devices. When the `sub` is not empty, it indicates that the device is a gateway device and the `self` must refer to the authentication information of a gateway device. For common scenarios, see Scenario Samples.

DeviceAuth Struct ¶

Name	Required/Optional	Data Type	Description
sn	Required	String	Device SN that is generated by system automatically.
timestamp	Required	Long	The timestamp to generate the verification value in the `sign` parameter.
sign	Required	String	The verification value that is generated by SHA256 algorithm based on the registration group password, `sn`, and `timestamp` as inputs. You can find the registration group password in EnOS Management Console > Device Provisioning > Registration Group Management.

SubDeviceAuth Struct ¶

Name	Required/Optional	Data Type	Description
branch	Depending on the scenario, see Scenario Samples.	Integer	The channel branch number to specify the channel.
sn	Depending on the scenario, see Scenario Samples.	String	Device SN that is generated by system automatically.
timestamp	Depending on the scenario, see Scenario Samples.	Long	The timestamp to generate the verification value in the `sign` parameter.
sign	Depending on the scenario, see Scenario Samples.	String	The verification value that is generated by SHA256 algorithm based on the registration group password, `sn`, and `timestamp` as inputs. You can find the registration group password in EnOS Management Console > Device Provisioning > Registration Group Management.
createSubSnFromGw	Depending on the scenario, see Scenario Samples.	Boolean	Whether to generate a virtual sub-device SN from the gateway’s registration group when a branch number is provided. Default is `true`.

The follow table lists the usage of parameters in the SubDeviceAuth struct in some common scenarios.

Scenario	Parameter Description
A single-channel device or a gateway device need to directly connect to EnOS Cloud and the triple information of itself is required.	Leave all parameters in the SubDeviceAuth struct empty. See Sample 1.
Multiple-channel devices need to directly connect to EnOS Cloud and the triple information of a branch device is required.	Provide `branch` to specify the branch number, leave `sn`, `timestamp`, and `sign` empty, and set `createSubSnFromGw` by default. See Sample 2.
A single-channel sub-device under a gateway device need to connect to EnOS Cloud and the triple information of the sub-device is required.	Leave `branch` empty, provide `sn`, `timestamp`, and `sign` parameters as the authentication information of the sub-device, and set `createSubSnFromGw` by default. See Sample 3.
Multiple-channel sub-devices under a gateway device need to connect to EnOS Cloud and the triple information of a branch sub-device is required.	Provide `branch`, `sn`, `timestamp`, and `sign` as the authentication information of the branch sub-device, and set `createSubSnFromGw` by default. See Sample 4.

Response Parameters¶

Name	Data Type	Description
murl	String	The EnOS MQTT protocol public address for the device’s environment. Return if the SubDeviceAuth struct is empty.
hurl	String	The EnOS HTTP protocol public address for the device’s environment. Return if the SubDeviceAuth struct is empty.
pk	String	The product key in the triple information.
dk	String	The device key in the triple information.
ds	String	The device secret in the triple information.

Error Codes¶

Code	Message	Description
10000	[{sn}] not allocated	If the device is unallocated and the “Auto Activation” of the registration group is not enabled, the triplet cannot be obtained and an error message indicating the device is unallocated will be returned.

Samples¶

The following samples are based on the SubDeviceAuth Struct Scenario Samples.

Sample 1¶

When a single-channel device or a gateway device need to directly connect to EnOS Cloud and the triple information of itself is required, refer to sample 1.

Request Sample¶

url: http://{dps-address}/preview/get/conn
method: POST
requestBody:
{
    "self": {
        "sn": "selfsn",
        "timestamp": 1607073024438,
        "sign": "6b8335652c31738c415916a3b9eb5be2d2cfc3af876cc3ab1d9d2a8f73cd1a6a"
    }
}

Return Sample¶

{
    "murl": "tcp://mqtt-{address}:21883",
    "hurl": "http://http-{address}",
    "pk": "selfProductKey",
    "dk": "selfDeviceKey",
    "ds": "selfDeviceSecret"
}

Sample 2¶

When multiple-channel devices need to directly connect to EnOS Cloud and the triple information of a branch device is required, refer to sample 2.

Request Sample¶

url: http://{dps-address}/preview/get/conn
method: POST
requestBody:
{
    "signMethod":"sha256",
    "self": {
        "sn": "selfsn",
        "timestamp": 1607073024438,
        "sign": "6b8335652c31738c415916a3b9eb5be2d2cfc3af876cc3ab1d9d2a8f73cd1a6a"
    },
    "sub": {
        "branch": 2
    }
}

Return Sample¶

{
    "pk": "branchProductKey",
    "dk": "branchDeviceKey",
    "ds": "branchDeviceSecret"
}

Sample 3¶

When a single-channel sub-device under a gateway device need to connect to EnOS Cloud and the triple information of the sub-device is required, refer to sample 3.

Request Sample¶

url: http://{dps-address}/preview/get/conn
method: POST
requestBody:
{
    "signMethod":"sha256",
    "self": {
        "sn": "selfsn",
        "timestamp": 1607073024438,
        "sign": "6b8335652c31738c415916a3b9eb5be2d2cfc3af876cc3ab1d9d2a8f73cd1a6a"
    },
    "sub": {
        "sn": "subsn",
        "timestamp": 1607073024438,
        "sign": "7197763f578fdb703134a2f9ae0145cbd865a3a60ea7742b541b5bb0db793aca"
    }
}

Return Sample¶

{
    "pk": "subProductKey",
    "dk": "subDeviceKey",
    "ds": "subDeviceSecret"
}

Sample 4¶

When multiple-channel sub-devices under a gateway device need to connect to EnOS Cloud and the triple information of a branch sub-device is required, refer to sample 4.

Request Sample¶

url: http://{apigw-address}/preview/get/conn
method: POST
requestBody:
{
    "signMethod":"sha256",
    "self": {
        "sn": "selfsn",
        "timestamp": 1607073024438,
        "sign": "6b8335652c31738c415916a3b9eb5be2d2cfc3af876cc3ab1d9d2a8f73cd1a6a"
    },
    "sub": {
        "branch": 2,
        "sn": "subsn",
        "timestamp": 1607073024438,
        "sign": "7197763f578fdb703134a2f9ae0145cbd865a3a60ea7742b541b5bb0db793aca"
    }
}

Return Sample¶

{
    "pk": "subProductKey",
    "dk": "subDeviceKey",
    "ds": "subDeviceSecret"
}