设备连接上云¶

本文介绍如何通过 MQTT 协议建立从设备到 EnOS 云端的连接。

支持的 MQTT 版本：

如果你使用基于证书的双向认证，在端口 18883 上使用 MQTT v3.1.1。
如果你使用基于密钥的单向认证，在端口 11883 上使用 MQTT v3.1.1。

直接使用 MQTT 协议¶

你可以直接使用 MQTT 协议将设备连接到 EnOS 云端。设备的 CONNECT 数据包中包含以下值：

mqttClientId: {clientId}|securemode={secureMode},signmethod=sha256,timestamp={timeStamp}|
mqttUsername: {deviceKey}&{productKey}
mqttPassword: toUpperCase(sha256({content}{deviceSecret})) 用于静态激活 或 toUpperCase(sha256({content}{productSecret})) 用于动态激活

其中：

mqttClientId 部分: 由下列字段按照前述方式拼接而成：
- clientId: 变量，必填项。可指定使用 MAC 地址或设备序列号。不可超过 64 字符。
- securemode: 必填项。表示所使用的安全模式。
  - 使用静态激活认证方式的设备，securemode=2
  - 使用动态激活认证方式的设备，securemode=3
- signmethod: 必填项，当前支持 sha256。表示使用 SHA256 签名算法。
- timestamp: 变量，必填项。表示当前的时间的 UNIX 时间戳，单位为毫秒。
  
  例如，mqttClientId 所需的各字段如下所示：
  - clientId=001A3FF14CC6
  - securemode=2，即采用静态激活模式
  - signmethod=sha256
  - timestamp=1575286479512
  则 mqttClientId= 001A3FF14CC6|securemode=2,signmethod=sha256,timestamp=1575286479512|
mqttUsername 部分: 由 deviceKey、 “&”、 productKey 三个要素拼接而成：
- deviceKey ：变量，设备的 device key。如何获取设备的 device key，参见获取设备三元组信息。
- productKey：变量，设备的 product key。如何获取设备的 product key，参见获取设备三元组信息。
例如，某设备的 deviceKey 为 abcdefg，productKey 为 1234567。则此处的 mqttUsername 为 abcdefg&1234567。
mqttPassword 部分: 静态激活的设备，由 content 与 deviceSecret 拼接而成；动态激活的设备，由 content 与 productSecret 拼接而成。然后将拼接得来的字符串用 SHA256 算法计算出新的字符串，再将新的字符串的字母全部转换成大写字母。
- content：按照 clientId，deviceKey，productKey，timestamp 的顺序，将字段名称和值串联组合。
  
  例如：设备的参数值如下所示
  - clientId = id123456
  - deviceKey = dK987654
  - productKey = pK11111
  - timestamp = 1234567890
  则 content= clientIdid123456deviceKeydK987654productKeypK11111timestamp1234567890
- deviceSecret：设备的 device secret。如何获取设备的 device secret，参见获取设备三元组信息。
- productSecret：设备的 product secret。如何获取设备的 product secret，参见查看产品信息。
deviceSecret 或 productSecret 的值应该附加到 content 中，中间不能包含任何空格或符号。

静态激活¶

静态激活认证过程中，productKey、deviceKey、和 deviceSecret 都已经在设备尝试认证并登录 EnOS 之前，配置在了设备端，在 EnOS 中，这三个信息合称为设备三元组。如何获取设备的三元组，参见获取设备三元组信息。

对于静态激活认证方式：

mqttPassword: toUpperCase(sha256({content}{deviceSecret}))

备注

timestamp 的值必须和 mqttClientId 部分的 timestamp 保持一致。

举例说明，当参数如下设定：

clientId=123456
deviceKey=test
productKey=654321
timestamp=1548753362502
deviceSecret=abcdefg

此时，mqttClientId 为：

123456|securemode=2,signmethod=sha256,timestamp=1548753362502|

mqttUsername 为：

test&654321

mqttPassword 为：

mqttPassword = toUpperCase(sha256(clientId123456deviceKeytestproductKey654321timestamp1548753362502abcdefg))

由上述参数及其值拼接而成的字符串将通过 SHA256 算法计算出新的字符串，新字符串的字母将全部转换成大写字母，再用于静态激活认证。

动态激活¶

要使用动态激活认证方式，需确保已为设备关联的产品打开 动态激活 开关。参见编辑产品基本信息和标签。

对于动态激活认证方式：

mqttPassword: toUpperCase(sha256({content}{productSecret}))

备注

timestamp 的值必须和 mqttClientId 部分的 timestamp 保持一致。

举例说明，当参数如下设定：

clientId=123
deviceKey=test
productKey=123
timestamp=1524448722000
productSecret=abcdefg

此时，mqttPassword 为：

mqttPassword = toUpperCase(sha256(clientId123deviceKeytestproductKey123timestamp1524448722000abcdefg))

在动态激活认证过程中，productKey、productSecret、和 deviceKey 已经预先配置在了设备当中。当设备尝试认证并登录 EnOS 时，设备会发送带有 productKey、productSecret 和 deviceKey 的请求以获取 deviceSecret。如果设备通过认证，设备需要订阅以下 topic 来获得 deviceSecret：

/ext/session/{productKey}/{deviceKey}/thing/activate/info

EnOS 会在发送给设备的响应中，包含 deviceSecret，举例如下：

{
    "id": "1",
    "version": "1.0",
    "method": "thing.activate.info",
    "params":{
        "assetId": "12344",
        "productKey": "1234556554",
        "deviceKey": "deviceKey1234",
        "deviceSecret": "yourDeviceSecret"
    }
}

设备在后续的接入 EnOS 的过程中，使用 productKey、deviceKey、及 deviceSecret 以认证。认证过程与静态激活认证相同。