本文介绍使用MQTT Broker代理方式将模拟设备接入物联网平台。MQTT Broker是MQTT消息代理，用于接收和转发来自客户端的消息。客户端需要连接到MQTT Broker才能与其他客户端进行通信。

🌍 说明

平台使用MQTT Broker接入时需要用户自行搭建或使用云上MQTT Broker服务。本文档使用EMQ X做示例说明。

需要注意的是使用MQTT Broker接入的设备，很难对设备身份进行验证。

应用场景

1. 设备无法直接接入IOT平台的设备，如某些厂商生产的设备仅推送消息至厂商搭建MQTT Broker服务中心。
2. 各设备之间需要订阅对方发送的topic（MQTT直连无法转发客户端发送的topic）。

前提条件

1. 安装部署MQTT Broker，参考EMQX部署
2. 下载MQTT X
3. 下载JetLinks官方协议

操作步骤

创建产品

登录JetLinks平台，物联网->设备管理->产品->新增，填写产品基础信息。

配置设备接入方式

创建网络组件

登录JetLinks物联网平台，选择物联网->运维管理->网络组件，创建MQTT客户端网络组件。

本文网络组件公网地址使用本机IP地址，网络组件端口配置请根据自身实际情况修改，配置内容可参考网络组件的说明

MQTT客户端网络组件填写参数说明

参数	说明
远程地址	emqx启动所在服务的IP地址，如果在本机启动则可填写127.0.0.1
远程端口	emqx启动的服务端口
clientId	连接到emqx的客户端Id，可任意配置
用户名	连接到emqx时需要的用户名
密码	连接到emqx时需要的密码
最大消息长度	单次收发消息的最大长度，单位：字节

💡 注意

集群模式下MQTT Broker接入应使用独立配置。更多说明参考网络组件集群模式的选择。

需要注意的是使用独立配置时，多个节点内的clientId参数仍不能相同，并且消息订阅时应配置订阅前缀，具体参考MQTT Broker共享订阅。

上传消息协议

选择物联网->运维管理->协议管理，跟随引导创建协议。当前文档使用官方协议，点击下载。

🌏 说明

上传协议失败请查看协议常见问题。

配置网关信息

物联网->运维管理->设备接入网关，创建MQTT Broker类型的接入网关，并选择以上步骤创建的网络组件与协议。

🌏 说明    

网关创建完成后，可在EMQ X客户端中的Subscriptions菜单中查看订阅列表是否存在网络组件配置的ClientID的数据，若存在说明平台已创建客户端并成功连接至MQTT Broker。

物联网->设备管理->产品->设备接入，选择接入方式为MQTT Broker类型的设备接入网关，并启用产品。

配置物模型

1. 点击上一步创建的产品查看详情，选择物模型Tab。
2. 配置物模型属性temperature，如下图所示。

创建设备

1. 物联网->设备管理->选择设备->新增，填写设备基础信息并确定保存。

1. 启用设备。

使用MQTTX模拟设备接入

MQTT X 是一款开源的 MQTT 桌面测试客户端，支持Windows、Mac和Linux操作系统，可用于验证设备是否可与物联网平台正常连接，并通过Topic订阅和发布消息。本文以Windows系统下MQTTX为例，介绍设备使用MQTT协议模拟设备接入物联网平台。

配置MQTT X接入参数

1. 下载并安装MQTT X软件。MQTT X软件安装和使用说明，请参见MQTT X。本文操作以MQTTX-Setup-1.9.1-x64.exe版本为例演示具体操作。由于第三方软件不定期更新，建议您以实际页面为准。
2. 打开MQTT X选择新建连接。

1. 配置连接参数，连接到EMQX服务。

💡 注意

MQTTX模拟器内的Client ID不能与平台内MQTT Broker网络组件内clientId设置一致，如果Broker发现已经存在一个相同Client ID的连接，它将终止当前的连接请求，使另一个连接上线（即两个客户端会互相顶替）。

连接参数说明

参数	说明
Name	自定义名称
Client ID	连接到EMQX的客户端Id。可自定义填写任意字符串
Host	填写启动EMQX服务的IPv4地址
Port	EMQX启动的服务端口

设备上下线

🌍 说明

由于MQTT Broker接入是平台开启客户端订阅MQTT服务内的Topic处理消息来管理设备生命周期，以此方式接入时平台无法感知设备真实的连接状态。平台以收到DeviceMessage（非DeviceOfflineMessage）类型消息将设备状态修改为在线（默认永久在线），以收到DeviceOfflineMessage消息将设备离线。

保持设备在线【推荐】

1. 在自定义协议包解码出消息时，可通过在消息中添加头keepOnline来进行设置。

//设置让会话强制在线
message.addHeader(Headers.keepOnline, true);
//设置超时时间（可选,默认10分钟），如果超过这个时间没有收到任何消息则认为离线。
message.addHeader(Headers.keepOnlineTimeoutSeconds, 600);

💡 注意

如果服务重启，将不会保持在线状态！

1. 上报任意报文时将保持在线消息头内容添加至正文内（该方案仅限于使用官方协议解析，其他结构报文体仍须自行封装消息头）

{
  "timestamp":1601196762389, //毫秒时间戳
  "messageId":"随机消息ID",
  "deviceId":"设备ID",
  "headers":{
    "productId":"产品ID",
    "deviceName":"子设备名称",
  	"keepOnlineTimeoutSeconds":600, //单位:秒
    "keepOnline":true
  }
}

订阅Broker服务系统Topic处理

🌍 说明

使用EMQ X搭建的MQTT Broker服务可以订阅其系统消息，参考EMQX客户端上下线文档，在协议包内订阅上下线相关的主题并将其封装为对应的DeviceOnlineMessage/DeviceOfflineMessage返回给平台。

非EMQX请查阅其官网是否提供设备上下线主题，自行在协议包内订阅即可。

需要注意的是EMQX默认拒绝所有连接订阅$SYS/开头的主题。需要修改ACL（权限控制列表）文件，具体参考ACL文件

如下图：

设备属性上报

推送物模型属性消息到EMQ X。实现平台设备上线与消息接收。

推送设备上报属性topic格式和报文参考：JetLinks官方协议-上报设备属性。

Topic:/{productId}/{deviceId}/properties/report

消息正文：

{
	"deviceId":"设备ID",
	"properties":{"temperature":36.8}
}

进入平台设备详情界面，查看属性列表，可以看到上报的温度属性值。

读取设备属性

1. 在MQTTX中点击订阅添加按钮。

1. 添加订阅设备读取属性topic：/+/+/properties/read。格式参考：JetLinks官方协议-读取设备属性

1. 在设备详情页面点击获取最新属性值

1. 在MQTTX中接收到平台下发的读取属性消息

读取设备属性回复

1. 在MQTTX中回复读取设备最新属性的消息，注意回复的消息中messageId要与下发的messageId相同

Topic: /{productId}/{deviceId}/properties/read/reply

{
  "messageId":"与下行消息中的messageId相同",
  "properties":{"temperature":40.0}, //key与设备模型中定义的属性id一致
  "deviceId":"设备ID",
  "success":true
}

1. 在平台查看MQTTX模拟设备回复的温度属性

---

上一篇：HTTP协议设备接入

下一篇：MQTT Broker接入