前言

程序员总是不想写枯燥的文档，本文就以Get Started的方式，阐述一下需要用到的几个Http API。

Get Started

登录服务器

MQTT客户端与服务器交互流程分为：连接、订阅、心跳、发送/接收数据；

• 连接参数：
  ip: 39.108.146.50
  port: 1883
  （有些SDK的参数可能会封装为：mqtt://39.108.146.50:1883）

那么，

如何得到一个MQTT客户端（设备）登陆凭证呢？

按前文所述，通过微信获得一个用户secret_key，该secret_key用于http交互的认证，保存好，并保密好；文章连接：https://www.jianshu.com/p/e1818b2d36d8

注册API

POST：http://39.108.146.50:8081/matrix_mq/v1/device
Headers:
Content-Type: application/json
x-matrix-secret-key: <secret_key> （包含<>整体替换为你拿到的secret_key）
Body:
{
"mac" : "xxxxx",
"passcode": "xxxxxx"
}
Respose Status: 201

POSTMAN 示例：

image.png image.png

• MQTT CONNECT参数
  client_id: <mac>
  username: <mac>
  password: <passcode>
  keepalive: 60-600，单位秒，根据需要选择，建议>300。
  同样的，上述尖括号内容替换真实值，下图是使用工具连接成功的状态：

image.png

登录成功之后，设备需要订阅主题来接收控制指令

• MQTT SUBSCRIBE参数
  topic: "n/<mac>/0/0"，用于透传指令
  qos: 0
  如图：

  
  image.png

如何给这个MQTT客户端（设备）发送指令

控制API

POST：http://39.108.146.50:8081/matrix_mq/v1/device
Headers:
Content-Type: application/json
x-matrix-secret-key: <secret_key> （包含<>整体替换为你拿到的secret_key）
Body:
{
"mac" : "xxxxx",
"payload": <base64 String> (发送指令的二进制数据，经过base64加密后的字符串)
}
Respose Status: 201

效果如图：

image.png

客户端收到数据：

image.png

数据解析为Hex：

image.png

客户端心跳

在此不再赘述。

设备上报数据

• MQTT PUBLISH参数
  topic: s/<mac>/0/0，用于透传指令
  payload: 透传的二进制数据

服务器会将设备的上线，下线，上报状态这一系列的动作，封装成事件数据，通知给已经订阅该设备的第三方服务。

如何订阅这个MQTT客户端（设备）的事件

订阅API

POST：http://39.108.146.50:8081/matrix_mq/v1/subscribe
Headers:
Content-Type: application/json
x-matrix-secret-key: <secret_key> （包含<>整体替换为你拿到的secret_key）
Body:
{
"url" : "http://xxxxx", （第三方服务回调url）
"auth_key": "xxxxxx" , (第三方http服务认证参数)
"events": [] （订阅事件列表）
}
Respose Status: 201

如图参考：

image.png

事件类型

• online
  客户端上线触发，数据内容如下：
  {
  "event_type": "online",
  "mac": <mac string>,
  "timestamp": <时间戳，double>,
  "ip": <ip string>,
  "payload": <payload, 客户端登录参数>
  }

• offline
  客户端下线触发，数据内容如下：
  {
  "event_type": "offline",
  "mac": <mac string>,
  "timestamp": <时间戳，double>,
  "ip": <ip string>,
  "payload": <payload, 客户端心跳统计信息、离线原因>
  }

• reonline
  客户端在服务器心跳过期之前，再次上线触发，一般发生在客户端未使用MQTT DISCONNECT，或断电，断网导致的断开链接后，立即再次上线的场景。
  数据内容如下：
  {
  "event_type": "offline",
  "mac": <mac string>,
  "timestamp": <时间戳，double>,
  "ip": <ip string>,
  "payload": <payload, 客户端心跳统计信息、离线原因>
  }

• data_changed
  客户端上报数据触发，数据内容如下：
  {
  "event_type": "data_changed",
  "mac": <mac string>,
  "timestamp": <时间戳，double>,
  "ip": <ip string>,
  "payload": <payload, Base64Str>
  }