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 theproductKey, deviceKey, and deviceSecret is provided to activate the device, the value is 2.
  - For dynamic authentication, where the productKey, productSecret, and deviceKey is provided to activate the device, the value is 3.
- 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=id123456
- securemode=2 for static authentication
- sighmethod=sha256
- timestamp=1234567890
The mqttCliendId in this case would be: clientIdid123456|securemode=2,signmethod=sha256,timestamp=1234567890|
mqttUsername: It is a concatenation of deviceKey, “&”, and productKey.
- 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 the productKey is 1234567, the mqttUsername in this case would be abcdefg&1234567.
mqttPassword: For static authentication, it is a string concatenated by content and deviceSecret. For dynamic authentication, it is a string concatenated by content and productSecret. 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 the clientId and its value, the deviceKey and its value, the productKey and its value, and the timestamp 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 = id123456
  - deviceKey = dK987654
  - productKey = pK11111
  - timestamp = 1234567890
  The content in this case would be clientIdid123456deviceKeydK987654productKeypK11111timestamp1234567890
- 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 or productSecret should be appended to content 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.