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}/dev/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}/dev/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}/dev/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}/dev/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}/dev/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"
}