1.0 MQTT

1.1 MQTT基础

MQTT是一种轻量级的发布-订阅消息传递协议，它可能最适合各种物联网设备，物联网平台服务器支持QoS级别0（最多一次）和QoS级别1（至少一次）以及一组预定义主题的MQTT代理。

1.2 MQTT网关设备

网关是物联网平台中的一种特殊类型的设备，能够充当连接到不同外部设备和平台之间的桥梁。
网关API提供了使用单个MQTT连接在多个设备和平台之间交换数据的功能。
网关还充当物联网平台设备，并且可以利用现有的MQTT设备API来报告统计信息，接收配置更新等等。

1.3 网关与子设备的拓扑关系

image.png

1.4 MQTT连接

我们将在本文中使用令牌凭据对进行设备访问，这些凭证稍后将称为$ACCESS_TOKEN应用程序需要发送用户名包含$ACCESS_TOKEN的MQTT CONNECT消息。

连接状态码说明：
0x00 连接成功 - 成功连接
0x04 连接失败 - 用户名或密码错误。
0x05 连接未授权 - -用户名包含无效的 $ACCESS_TOKEN。

1.5 MQTT客户端

你可以在网上找到大量的MQTT客户端库或者模拟软件，本文中的示例将基于mqttfx客户端模拟软件进行演示
网关与子设备接入 - 图2

1.6 物联网平台创建网关

网关示例设备已提前创建好，ACCESS_TOKEN已实际准备为准。
步骤一：创建网关设备，勾选图中所示选项
image.png
image.png
步骤二：获取MQTT连接凭证
通过设备详情，点击赋值访问令牌，获取ACCESS_TOKEN
image.png

1.7 mqttfx创建连接

设置MQTT基本属性
Broker Address：iot.relaper.com
Broker Port：9001
User Name（Access Token）：使用实际设备凭证
网关与子设备接入 - 图6

1.8 Key-value格式

物联网平台支持以JSON格式的key-value字符串，值可以是string、bool、float、long或者二进制格式的序列化字符串。
例如：

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

2.0 子设备上线API

通知设备已连接到网关，需要发布到下面主题：

  1. v1/gateway/connect

支持数据格式是：

  1. {
  2.     "device": "Device A"
  3. }

Device A 代表你的设备名称。
收到后物联网平台将查找或创建具有指定名称的设备。
物联网平台还将向该网关发布有关特定设备的新属性更新和RPC命令的消息。
注意事项：后续操作要保证设备是处于上线状态！！！
示例：
image.png

3.0 子设备下线API

通知设备已与网关断开连接，需要发布到下面主题：

  1. v1/gateway/disconnect

支持数据格式是：

  1. {
  2.     "device": "Device A"
  3. }

Device A 代表你的设备名称。
一旦收到物联网平台将不再将此特定设备的更新发布到此网关。
示例：
image.png

4.0 遥测上传API

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

  1. v1/gateway/telemetry

支持数据格式是：

  1. {
  2.   "Device A": [
  3.     {
  4.       "ts": 1483228800000,
  5.       "values": {
  6.         "temperature": 42,
  7.         "humidity": 80
  8.       }
  9.     },
  10.     {
  11.       "ts": 1483228801000,
  12.       "values": {
  13.         "temperature": 43,
  14.         "humidity": 82
  15.       }
  16.     }
  17.   ],
  18.   "Device B": [
  19.     {
  20.       "ts": 1483228800000,
  21.       "values": {
  22.         "temperature": 42,
  23.         "humidity": 80
  24.       }
  25.     }
  26.   ]
  27. }

其中Device A和Device B是你的设备名称，“temperature和humidity”是遥测键，ts是unix时间戳（以毫秒为单位）。
示例：

4.1 操作步骤演示

步骤一：遥测数据上传
同时上传Device A和Device B子设备的遥测数据。
image.png
步骤二：平台可通过设备详情查看遥测数据
image.png
image.png

5.0 属性API

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

  • 将客户端设备属性上载到服务器
  • 从服务器请求客户端和共享设备属性
  • 从服务器订阅 共享设备属性

    5.1 将属性更新发布到服务器

    为了将客户端设备属性发布到物联网平台，请将PUBLISH消息发送到以下主题：
    1. v1/gateway/attributes
    支持的数据格式：
    1. {
    2.   "Device A": {
    3.       "attribute1": "value1",
    4.       "attribute2": 42
    5.   },
    6.   "Device B": {
    7.       "attribute1": "value1",
    8.       "attribute2": 42
    9.   }
    10. }
    其中Device A和Device B是你的设备名称，attribute1和attribute2是属性键。

    5.1.1 操作步骤演示

    步骤一：属性更新发布到服务器
    image.png
    步骤二：平台可通过设备详情查看属性数据
    image.png

    5.2 从服务器请求属性值

    为了向物联网平台请求客户端或共享设备属性，请将PUBLISH消息发送到以下主题：
    1. v1/gateway/attributes/request
    支持的数据格式：
    1. {
    2.   "id": $request_id,
    3.   "device": "Device A",
    4.   "client": true,
    5.   "key": "attribute1"
    6. }
    其中 $request_id 是您的整数请求标识符，Device A是你的设备名称，client标识客户端或共享属性范围，而key是属性键。
    在发送带有请求的PUBLISH消息之前，客户端需要订阅一下主题：
    1. v1/gateway/attributes/response
    消息结果格式如下：
    1. {
    2.   "id": $request_id,
    3.   "device": "Device A",
    4.   "value": "value1"
    5. }

    5.2.1 操作步骤演示

    步骤一：设置订阅主题
    image.png
    步骤二：发布获取属性值主题
    $request_id设置为1，保证整数的不重复性。
    image.png
    订阅主题接收到响应
    image.png

    5.3 从服务器订阅属性更新

    为了订阅共享设备属性更改，请发送SUBSCRIBE消息到以下主题
    1. v1/gateway/attributes
    消息结果格式如下：
    1. {
    2.   "device": "Device A",
    3.   "data": {
    4.       "attribute1": "value1",
    5.       "attribute2": 42
    6.   }
    7. }

    5.3.1 操作步骤演示

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

    6.0 RPC API（远程指令下发）

    6.1 服务器端RPC

    为了从服务器订阅RPC命令，请将SUBSCRIBE消息发送到以下主题：
    1. v1/gateway/rpc
    订阅后，响应的消息格式：
    注意事项：订阅后，需要基于云端HTTP接口发送远程指令后，才可收到订阅消息，详细可参考操作步骤演示。
    1. {
    2.   "device": "Device A",
    3.   "data": {
    4.       "id": $request_id,
    5.       "method": "toggle_gpio",
    6.       "params": {
    7.           "pin": 1
    8.       }
    9.   }
    10. }
    设备处理完命令后，网关回复需要发布到下面主题：
    1. v1/gateway/rpc
    支持数据格式是：
    1. {
    2.   "device": "Device A",
    3.   "id": $request_id,
    4.   "data": {
    5.       "success": true
    6.   }
    7. }

$request_id是你的整数请求标识符，Device A是你的设备名称，方法是您的RPC方法method。

6.1.1 操作步骤演示

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

  1. {
  2.  "username": "test@relaper.com",
  3.  "password": "123456"
  4. }

网关与子设备接入 - 图21

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

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

请求地址{{deviceId}}通过物联网平台获取：
点击设备详情，复制设备ID获：
image.png
设置X-Authorization token凭证：
网关与子设备接入 - 图23
远程控制指令下发：
网关与子设备接入 - 图24
步骤三：客户端PUBLISH主题进行响应
image.png
响应回复成功：
image.png