本文档以MQTT.fx为例，介绍使用第三方软件以MQTT协议接入物联网平台。MQTT.fx是一款基于Eclipse Paho，使用Java语言编写的MQTT客户端工具。支持通过Topic订阅和发布消息。

创建协议

自定义消息协议创建，请参考消息协议定义。

例
i. 选择 设备接入—>协议管理—> 点击新建协议按钮
新建协议导航
ii. 输入型号名称
iii. 选择型号类型为 jar
iv. 输入类名org.jetlinks.demo.protocol.DemoProtocolSupportProvider
v. 上传jar包demo-protocol-1.0.jar， 请检出demo-protocol自行打包。
vi. 点击保存，完成协议新增。

创建完成信息展示

新建型号协议

创建产品

完整的产品创建，请参考添加设备型号。

例
i.下载型号文件配置JSON
ii. 选择 设备管理—>产品—> 点击导入配置按钮
导入型号导航
iii. 选择配置JSON文件
::: tip 注意：
上传文件需要将standalone/src/main/resources/application.yml中的static-location修改为
http://后台服务ip:8848/upload，参考协议上传问题
:::
iv.型号导入完成效果如下图
未发布型号
v.点击上图中未发布链接完成型号发布，导航栏中发布状态变为已发布代表发布成功。
已发布型号

创建成功的型号信息展示

i. 点击导航栏中编辑链接查看型号基本信息
ii. 点击弹出框中设备定义板块查看型号设备定义
iii. 点击属性定义、事件定义对应操作下的编辑按钮查看更详细的型号信息
属性定义参数：
型号信息1
功能定义参数：
型号信息2
事件定义参数：
型号信息3

创建设备

自定义创建设备，请参考添加设备。

例
i. 下载设备Excel文件设备Excel
ii. 选择 设备管理—>设备—> 其他批量操作—>批量导入设备
导入设备导航
iii. 选择需要导入的产品,点击文件上传
选择型号
iv. 选择设备Excel文件
v. 设备导入完成效果如下图
未激活的设备
vi. 点击上图中激活链接完成设备激活，状态栏中发布状态变为离线代表设备激活成功。
已激活的设备

创建成功的设备信息展示

i. 设备基本信息
设备基本信息
ii. 设备运行状态信息
设备运行状态信息
iii. 设备日志
设备日志

创建网关配置

参照启动设备网关服务
例

  • 创建MQTT服务网络组件
  • 创建MQTT服务设备网关

MQTT服务组件配置
MQTT服务组件配置
::: tip 注意：
此处使用的端口为1889，docker启动时没有默认开启，使用docker启动jetlinks时请映射1889端口或者使用1883端口。
:::
MQTT服务设备网关
MQTT服务设备网关

使用MQTT.fx接入

1.下载并安装MQTT.fx软件。请访问MQTT.fx官网。
2.打开MQTT.fx软件，单击设置图标。
mqttfx首页
3.设置连接参数。
::: tip 注意
设置参数时，请确保参数值中或参数值的前后均没有空格。
:::
i. 设置基本信息
mqtt基本信息设置

| 参数 | 说明 | | —- | —- |

| Profile Name | 输入您的自定义名称。 |

| Profile Type | 选择为MQTT Broker。 |

MQTT Broker Profile Settings

| 参数 | 说明 | | —- | —- |

| Broker Address | 连接域名。本地连接可直接填写 127.0.0.1,如为远程连接，请填写远程连接地址 |

| Broker Port | 设置为1889 |

| Client ID | 设备Id。本文档中为演示设备test001 |

General栏目下的设置项可保持系统默认，也可以根据您的具体需求设置。
ii. 单击User Credentials，设置User Name和Password。

在消息协议未定义前,username,password可以填写任意字符,但是不能留空。

mqtt用户名名密码设置

| 参数 | 说明 | | —- | —- |

| User Name | 由消息协议定义中决定User Name值（消息协议未定义时可填写任意值） |

| Password | 由消息协议定义中决定Password值 （消息协议未定义时可填写任意值） |

4.设置完成后，单击右下角的OK。

设备消息

设备连接上平台，并进行一些基本的事件收发、属性读取操作。

设备上下线

单击 Mqtt fx 中Connect进行连接
mqtt连接
平台中设备状态变为上线即为连接成功
设备上线
在设备日志模块可以看到设备上线日志
设备上线日志
单击 Mqtt fx 中Disconnect断开连接
mqtt连接
平台中设备状态变为离线即为断开连接成功
设备离线
在设备日志模块可以看到设备离线日志
设备离线日志

读取设备属性

::: tip 注意
第2步中回复平台属性值需要在第1步平台发送订阅以后的十秒钟内完成，否则平台会视为该次操作超时，导致读取属性值失败。
:::
1.平台告知设备（MQTT.fx）需要设备返回设备属性
在MQTT.fx上订阅消息，订阅物联网平台下发设备返回属性的Topic
i. 在MQTT.fx上，单击Subscribe。
ii. 输入平台获取设备属性会发送给网关的topic/read-property
iii. 单击Subscribe，订阅这个topic
订阅topic
iv. 平台发送订阅操作
单击设备页面中test001设备对应的查看链接
选择弹出框中运行状态板块
单击属性刷新
平台属性订阅操作
v. 订阅topic: /read-property对应的消息
订阅topic
::: tip 注意:
复制好订阅该topic收到的消息中的messageId。此messageId将作为回复与平台设备属性的凭据之一
:::
2.设备（MQTT.fx）回复平台设备属性值
在MQTT.fx上发送消息，发送平台所需要的设备属性值。
i. 在MQTT.fx上，单击 Publish。
ii. 输入一个回复平台属性值消息Topic和要发送的消息内容，单击Publish，向平台推送该消息。
回复设备属性

| 参数 | 说明 | | —- | —- |

| messageId | 第一步订阅平台topic“/read-property”所收到的messageId值 |

| deviceId | 设备Id |

| timestamp | 当前时间戳 |

| success | 成功标识 |

| properties | 设备属性值对象。例如： { “threshold”:”50”} |

该文档所使用的回复内容

  1. {
  2.     "messageId":"第一步订阅平台topic“/read-property”所收到的messageId值",
  3.     "deviceId":"test001",
  4.     "timestamp":1583809148000,
  5.     "success":true,
  6.     "properties":{
  7.       "temperature":36.5
  8.      }
  9. }

iii. 平台收到Mqtt.fx推送的属性值
平台收到属性值
iv. 读取设备属性回复的日志
设备属性读取日志

获取设备属性值完整演示

获取设备属性值

设备事件上报

MQTT.fx 推送设备事件消息到平台
以火灾报警事件为例。
1.在MQTT.fx上，单击 Publish。
2.输入事件上报Topic和要发送的事件内容，单击Publish按钮，向平台推送该事件消息。
设备事件上报
该文档使用的topic: /fire_alarm
该文档所使用的回复内容

  1. {
  2.    "deviceId":"test001",
  3.     "pname":"智能温控",
  4.     "aid":105,
  5.     "a_name":"未来科技城",
  6.     "b_name":"C2 栋",
  7.     "l_name":"12-05-201",
  8.     "timestamp":"2019-11-06 16:28:50",
  9.     "alarm_type":1,
  10.     "alarm_describe":"火灾报警",
  11.     "event_id":1,
  12.     "event_count":1
  13. }

| 参数 | 说明 | | —- | —- |

| deviceId | 设备Id |

| pname | 产品名称 |

| aid | 区域Id |

| a_name | 区域名称 |

| b_name | 建筑名称 |

| l_name | 位置名称 |

| timestamp | 上报时间 |

| alarm_type | 报警类型 |

| alarm_describe | 报警描述 |

| event_id | 事件 ID |

| event_count | 该事件上报次数 |

3.事件上报设备日志
事件上报设备日志
4.事件上报内容
事件上报内容
事件上报内容1

地理位置上报

  1. 物模型中添加地理位置。通过属性定义添加地理位置类型属性。

添加地理位置属性

  1. 在设备产品详情页面点击应用配置按钮。
    应用配置
  1. 使用mqtt.fx连接到平台，设备上线后推送地理位置消息到平台， 此处使用topic为/report-property。

推送地理位置消息
此处使用的报文为：

  1. {
  2.     "deviceId":"test001",
  3.     "properties":{
  4.       "geo-test": "36.523,102.321"
  5.      }
  6. }

::: tip 注意：
上报geo地理位置类型数据有三种格式，一是字符串以逗号分隔，如："36.523,102.321";
二是数组类型，如:[36.523,102.321];
三是map类型，如：{"lat":36.523,"lon":102.321}。
:::

  1. 上报成功后将在设备的运行状态中显示。

地理位置展示
也可查看上报历史消息。
地理位置历史记录
::: tip 注意：
物模型中的标签也可创建geo类型，但不可通过标签上报地理位置信息，只能通过属性上报。
地理位置标签将主要运用在地图查询中。
:::