入门

MQTT 基础知识

MQTT是一种轻量级的发布-订阅消息协议，可能使其最适合各种物联网设备。您可以在此处找到有关 MQTT 的更多信息。
睿珀物联网平台服务器节点充当 MQTT 代理，支持 QoS 级别 0（最多一次）和 1（至少一次）和一组可配置主题。

客户端库设置

您可以在 Web 上找到大量的 MQTT 客户端软件。本文中的示例将基于 mqttx。

MQTT 连接

我们将在本文中使用访问令牌设备凭据，稍后将它们称为$ACCESS_TOKEN。应用程序需要使用包含$ACCESS_TOKEN的用户名发送 MQTT CONNECT 消息。
连接序列期间可能的返回码及其原因：

  • 0x00 已连接- 成功连接到 物联网平台 MQTT 服务器。
  • 0x04 连接被拒绝，用户名或密码错误- 用户名为空。
  • 0x05 连接被拒绝，未授权- 用户名包含无效的$ACCESS_TOKEN。

另一种身份验证选项是使用X.509 证书或基本 MQTT 凭据- 客户端 ID、用户名和密码的组合。

键值格式

默认情况下，物联网平台 支持 JSON 中的键值内容。键始终是字符串，而值可以是字符串、布尔值、双精度、长整型或 JSON。例如：

  1. {
  2.     "stringKey":"value1",
  3.     "booleanKey":true,
  4.     "doubleKey":42,
  5.     "longKey":73,
  6.     "jsonKey":{
  7.         "someNumber":42,
  8.         "someArray":[1,2,3],
  9.         "someNestedObject":{
  10.             "key":"value"
  11.         }
  12.     }
  13. }

但是，也可以通过Protocol Buffers发送数据。有关详细信息，请参阅设备配置文件文章中的MQTT 传输类型配置部分。
也可以使用自定义二进制格式或一些序列化框架。有关详细信息，请参阅协议自定义。

MQTT 传输类型

MQTT 传输类型启用高级 MQTT 传输设置。现在，您可以为分别对应于遥测上传 API和属性更新 API的时间序列数据和属性更新指定自定义 MQTT 主题过滤器 。

遥测上传 API

为了将遥测数据发布到 物联网平台服务器节点，请将 PUBLISH 消息发送到以下主题：

v1/devices/me/telemetry

支持的最简单的数据格式是：

  1. {"key1":"value1", "key2":"value2"}

要么

  1. [{"key1":"value1"}, {"key2":"value2"}]

请注意，在这种情况下，服务器端时间戳将分配给上传的数据！
如果您的设备能够获取客户端时间戳，您可以使用以下格式：

  1. [
  2.     {
  3.         "ts":1451649600512,
  4.         "values":{
  5.             "key1":"value1",
  6.             "key2":"value2"
  7.         }
  8.     },
  9.     {
  10.         "ts":1451649600512,
  11.         "values":{
  12.             "key1":"value1",
  13.             "key2":"value2"
  14.         }
  15.     }
  16. ]

属性API

物联网平台属性API能够使设备具备如下功能：

  • 将客户端设备属性上传到服务端
  • 从服务端请求客户端和共享属性
  • 从服务端订阅共享属性
  • 通过服务端发布客户端属性

    通过服务端发布客户端属性

    通过服务端发布客户端属性必须PUBLISH消息到下面主题：
    1. v1/devices/me/attributes
    支持的数据格式：
    1. {
    2. "attribute1": "value1",
    3. "attribute2": true,
    4. "attribute3": 42.0,
    5. "attribute4": 73,
    6. "attribute5": {
    7.   "someNumber": 42,
    8.   "someArray": [1,2,3],
    9.   "someNestedObject": {"key": "value"}
    10. }
    11. }
    示例：
    image.png
    物联网平台可以通过设备详情的客户端属性查看：
    image.png

    通过服务端获取属性值

    通过服务端获取客户端属性或共享属性必须PUBLISH消息到下面主题:
v1/devices/me/attributes/request/$request_id

其中$request_id表示整数的请求标识符。
在发送带有请求的PUBLISH消息之前客户端需要订阅下面主题：

v1/devices/me/attributes/response/+

示例：
步骤一：设置订阅主题
image.png
步骤二：发布获取属性值主题
$request_id设置为1，保证整数的不重复性。
注意事项：需要设置一个空JSON格式数据
image.png
步骤三：订阅主题收到客户端属性
image.png

通过服务端订阅属性

通过服务端订阅共享属性必须SUBSCRIBE消息到下面主题：

  1. v1/devices/me/attributes

如果服务端组件（例如REST API或规则链）更改了共享属性时客户端就会收到对应属性值：

  1. {
  2.     "key1": "value1"
  3. }

示例：
步骤一：订阅共享属性主题
image.png
步骤二：平台更改共享属性
平台可点击新增功能更改属性值
image.png
image.png
订阅主题接收到响应
image.png

RPC API（远程指令下发）

服务端RPC

客户端订阅服务端RPC命令必须SUBSCRIBE消息发送下面主题：

v1/devices/me/rpc/request/+

订阅后客户端会收到一条命令作为对相应主题的PUBLISH命令：

v1/devices/me/rpc/request/+

$request_id表示请求的整型标识符。
客户端PUBLISH下面主题进行响应：

v1/devices/me/rpc/request/+

示例：
步骤一：客户端订阅服务端RPC命令
image.png
步骤二：通过平台API进行远程指令下发
通过账户/密码登录获取访问token
示例地址：
【POST】http://iot.relaper.com/api/auth/login
示例数据：

  1. {
  2.  "username": "edgex@qq.com",
  3.  "password": "123456"
  4. }

image.png
远程控制下发
注意事项：远程控制下发是双向的，当客户端响应成功，接口才会提示成功，否则提示为超时未响应。
示例地址：【POST】http://iot.relaper.com/api/plugins/rpc/twoway/**{{deviceId}}**
Header设置：增加token凭证
key：X-Authorization
value（Bearer后携带1个空格）：”Bearer “ + 登录获取的token
示例token：
Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiI5MjQzOTI1NjZAcXEuY29tIiwic2NvcGVzIjpbIlRFTkFOVF9BRE1JTiJdLCJ1c2VySWQiOiIxZWExMDgxMC05MDJkLTExZWItOWRiMS0zNzM4NzFmMDFjN2IiLCJmaXJzdE5hbWUiOiLkuo7lvLoiLCJsYXN0TmFtZSI6IueOiyIsImVuYWJsZWQiOnRydWUsImlzUHVibGljIjpmYWxzZSwidGVuYW50SWQiOiIwZGE0NDZkMC05MDJkLTExZWItOWRiMS0zNzM4NzFmMDFjN2IiLCJjdXN0b21lcklkIjoiMTM4MTQwMDAtMWRkMi0xMWIyLTgwODAtODA4MDgwODA4MDgwIiwiaXNzIjoidGhpbmdzYm9hcmQuaW8iLCJpYXQiOjE2NDAxMzQ3ODgsImV4cCI6MTY0MDE0Mzc4OH0.jA0sc0Elpkjft9KHK6RE2AZmiK-d9UuMiJmJY-owRnIAi1zDWvq7Jg-2iYbLpgmmW6xIKYjBIuSioQIh9mHByA
示例数据：

  1. {
  2.     "method": "SET",
  3.   "service": "",
  4.   "uri": "",
  5.     "params": {
  6.             "LED":"false"
  7.     }
  8. }

请求地址{{deviceId}}通过物联网平台获取：
点击设备详情，复制设备ID获取
image.png
image.png
image.png
步骤三：客户端PUBLISH主题进行响应
订阅收到对应远程指令
image.png
客户端响应
image.png

认领设备

为了启动认领设备，向以下主题发送 PUBLISH 消息：

v1/devices/me/claim

支持的数据格式为：

  1. {"secretKey":"value", "durationMs":60000}

请注意，上述字段是可选的。如果未指定secretKey，则使用空字符串作为默认值。如果没有指定durationMs ，则使用系统参数device.claim.duration（在文件/etc/relaperiot/conf/relaperiot.yml 中）。

设备配置

为了启动设备配置，请将 Provisioning 请求发送到以下主题：

/provision

此外，您应该将username或clientId设置为provision。
支持的数据格式为：

  1. {"deviceName":"DEVICE_NAME", "provisionDeviceKey":"u7piawkboq8v32dmcmpp","provisionDeviceSecret":"jpmwdn8ptlswmf4m29bw"}