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}/2.4.0/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}/2.4.0/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}/2.4.0/get/conn
method: POST
requestBody:
{
"signMethod":"sha256",
"self": {
"sn": "selfsn",
"timestamp": 1607073024438,
"sign": "6b8335652c31738c415916a3b9eb5be2d2cfc3af876cc3ab1d9d2a8f73cd1a6a"
},
"sub": {
"branch": 2
}
}
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}/2.4.0/get/conn
method: POST
requestBody:
{
"signMethod":"sha256",
"self": {
"sn": "selfsn",
"timestamp": 1607073024438,
"sign": "6b8335652c31738c415916a3b9eb5be2d2cfc3af876cc3ab1d9d2a8f73cd1a6a"
},
"sub": {
"sn": "subsn",
"timestamp": 1607073024438,
"sign": "7197763f578fdb703134a2f9ae0145cbd865a3a60ea7742b541b5bb0db793aca"
}
}
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}/2.4.0/get/conn
method: POST
requestBody:
{
"signMethod":"sha256",
"self": {
"sn": "selfsn",
"timestamp": 1607073024438,
"sign": "6b8335652c31738c415916a3b9eb5be2d2cfc3af876cc3ab1d9d2a8f73cd1a6a"
},
"sub": {
"branch": 2,
"sn": "subsn",
"timestamp": 1607073024438,
"sign": "7197763f578fdb703134a2f9ae0145cbd865a3a60ea7742b541b5bb0db793aca"
}
}