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