Establishing Connection with EnOS™ Cloud using the MQTT Protocol¶
This section shows how to establish the connection from devices to EnOS Cloud through the MQTT protocol.
The supported MQTT version:
MQTT v3.1.1 on port 11883 if you use the secret-based one-way authentication.
MQTT v3.1.1 over SSL/TLS on port 18883 if you use the certificate-based two-way authentication.
Using the MQTT Protocol¶
You can connect devices to the EnOS Cloud directly by using the MQTT protocol. Include the following values in the CONNECT packet of the device.
mqttClientId: {clientId}|securemode={secureMode}, signmethod=sha256,timestamp={timeStamp}|
mqttUsername: {deviceKey}&{productKey}
mqttPassword: toUpperCase(sha256({content}{deviceSecret}/{productSecret}))
mqttClientId:
clientId
: Required. The identifier of the device, which can be the MAC address or device serial number. It must contain no more than 64 characters.securemode
: Required. Indicates the secure mode that has been used.For static authentication, where the
productKey
,deviceKey
, anddeviceSecret
is provided to activate the device, the value is2
.For dynamic authentication, where the
productKey
,productSecret
, anddeviceKey
is provided to activate the device, the value is3
.
signmethod
: Required. Indicates the signing method. “sha256” means the SHA256 signature algorithm is used.timestamp
: Required. Indicates the UNIX timestamp of the current time in milliseconds.
For example, if the following parameter values are used for mqttClientId,
clientId
=id123456securemode
=2 for static authenticationsighmethod
=sha256timestamp
=1234567890
The mqttClientId in this case would be:
id123456|securemode=2,signmethod=sha256,timestamp=1234567890|
mqttUsername: It is a concatenation of
deviceKey
, “&”, andproductKey
.deviceKey
: Device key of a product. You can find it in the EnOS Management Console after you register the device.productKey
: Product key of a product. You can find it in the EnOS Management Console after you register the device.
For example, if the
deviceKey
is abcdefg and theproductKey
is 1234567, themqttUsername
in this case would beabcdefg&1234567
.mqttPassword: For static authentication, it is a string concatenated by
content
anddeviceSecret
. For dynamic authentication, it is a string concatenated bycontent
andproductSecret
. Use the SHA256 algorithm to generate a new string from this concatenation and turn the new string into upper case letters.content
: It is concatenated by theclientId
and its value, thedeviceKey
and its value, theproductKey
and its value, and thetimestamp
and its value. The parameter names must be sorted in alphabetical order and concatenated without concatenation symbols.For example, if the following parameter values are used for
content
,clientId
= id123456deviceKey
= dK987654productKey
= pK11111timestamp
= 1234567890
The
content
in this case would beclientIdid123456deviceKeydK987654productKeypK11111timestamp1234567890
deviceSecret
: The device secret of a device. You can find it in the EnOS Management Console.productSecret
: The product secret of a device. You can find it in the EnOS Management Console.The value of the
deviceSecret
orproductSecret
should be appended tocontent
without any space or symbols.
Static Authentication¶
In secret-per-device authentication, the productKey
, deviceKey
, and deviceSecret
are configured in the device before the device tries to get authenticated and log in to EnOS. You can obtain a device’s productKey
, deviceKey
, and deviceSecret
from the EnOS Management Console after you have created the device in Device Management > Device Assets.
For secret-per-device authentication:
mqttPassword: toUpperCase(sha256({content}{deviceSecret}))
Note
The value of timestamp must be same as the timestamp in the mqttClientId segment.
Therefore, if the following parameter values are used for mqttPassword,
clientId
=123456
deviceKey
=test
productKey
=654321
timestamp
=1548753362502
deviceSecret
=abcdefg
The mqttClientId in this case would be:
123456|securemode=2,signmethod=sha256,timestamp=1548753362502|
The mqttUsername in this case would be:
test&654321
The mqttPassword in this case would be:
mqttPassword = toUpperCase(sha256(clientId123456deviceKeytestproductKey654321timestamp1548753362502abcdefg))
Dynamic Authentication¶
To enable secret-per-product authentication, you must first toggle the Enable Dynamic Activation switch to on for your product at the Product Details page in Device Management > Products.
For secret-per-product authentication:
mqttPassword: toUpperCase(sha256({content}{productSecret}))
Note
The value of timestamp must be same as the timestamp in the mqttClientId segment.
Therefore, if the following parameter values are used for mqttPassword,
clientId
=123
,deviceKey
=test
,productKey
=123
,timestamp
=1524448722000
,productSecret
=abcdefg
.
The mqttPassword in this case would be:
mqttPassword = toUpperCase(sha256(clientId123deviceKeytestproductKey123timestamp1524448722000abcdefg))
In secret-per-product authentication, the productKey
, productSecret
, and deviceKey
are configured in the device in advance. When the device tries to get authenticated and log in to EnOS, it first sends a request containing the productKey
, productSecret
, and deviceKey
in exchange for the deviceSecret
. If the device passes authentication, it then subscribes to the following topic to obtain the deviceSecret
.
/ext/session/{productKey}/{deviceKey}/thing/activate/info
The deviceSecret
is sent back as a JSON file in the following format.
{
"id": "1",
"version": "1.0",
"method": "thing.activate.info",
"params":{
"assetId": "12344",
"productKey": "1234556554",
"deviceKey": "deviceKey1234",
"deviceSecret": "yourDeviceSecret"
}
}
The device can then use the deviceSecret
together with the productKey
and deviceKey
for future authentication and login.