高级进阶

MQTT 5

Clean Start 和会话过期间隔

MQTT 5.0 引入了 Clean Start 和会话过期间隔(Session Expiry Interval)这两项特性,相比于 MQTT 3.1.1 的清除会话(Clean Session)提供了更多的灵活性。

在 MQTTX 中使用时,如果设置了 Clean Start,为了使其生效,需要设定会话过期间隔。默认情况下,如果关闭了 Clean Start,那么会话过期间隔默认设置为永不过期,并且可以根据需要进行修改。然而,如果关闭会话过期间隔,系统会自动将会话过期间隔设置为 0,即连接一旦断开,会话立即结束。

mqttx-user-properties-connect

用户属性

点击新建按钮来到新建客户端页面,首先我们需要选择 MQTT 的版本为 5.0。这样,下方就会出现配置用户属性的卡片。卡片内包含一个可配置键值对的输入框。您可以点击右上角的添加按钮来增加用户属性配置,也可以点击每一行末尾的删除按钮删除配置。最后输入需要配置的属性名称和内容即可。连接成功后,MQTT 服务器就能获取到该客户端的用户属性内容。

mqttx-user-properties-connect

除了在客户端连接时配置用户属性外,该版本还支持在发布消息时配置用户属性。当新建连接为 MQTT 5.0 的客户端时,我们可以看到发布消息区域的右下角出现了一个 Meta 按钮。点击该按钮即可看到配置发布时属性的卡片,在卡片顶部可以配置用户属性。

mqttx-user-properties-publish

请求响应

点击 Meta 按钮,在输入框内输入一个响应主题:/ack/1,以及一个对比数据:light。然后,在当前连接客户端订阅一个 /ack/1。

mqttx-response-topic

内容类型和载荷格式

点击 Meta 按钮,在输入框内输入 Content-Type,并设置 Payload Format Indicator 的值。设置完成后,就可以发布消息了。

mqttx-content-type

订阅标识符和订阅选项

打开订阅主题的弹出框,下方可以设置 Subscription Identifier 和订阅选项,订阅选项包括 No Local、Retain as Published 和 Retain Handling。用户可以在订阅报文中指定一个数字作为订阅标识符,并在消息分发时返回此标识符。这样,客户端就能建立订阅标识符与消息处理程序的映射,当收到 PUBLISH 报文时,可以直接通过订阅标识符将消息定向至对应的消息处理程序。同时,用户还可以配置这些订阅选项来改变服务器的行为。

mqttx-sub-flag

设置

您可以通过点击左侧菜单栏底部的设置按钮或使用快捷方式来访问设置。macOS 用户可以使用 command +,,而其他用户可以使用 control +,。设置页面包括了分为通用、外观和高级三个部分的多项选项。

mqttx-settings

通用

通用设置允许您进行 MQTTX 的基本操作定制。在这里,您可以选择您喜欢的语言,启用或禁用自动更新,启用多主题订阅,并设置最大重连次数以在网络不稳定的情况下保持连接的连续性。

外观

外观设置允许您定制 MQTTX 界面的外观。您可以选择三种主题:Light,Dark 和 Night。另外,还有一个选项可以将 MQTTX 主题与您的操作系统同步,以实现一致的用户体验。

高级(数据管理)

在高级设置中,包含了数据备份,恢复和历史记录清理。

对于数据备份,包括所有接收和发送的消息的所有连接数据都会被导出,以确保您的连接信息和消息历史的安全。在数据恢复过程中,您需要选择要导入的文件的路径。一旦确认了文件路径,您的数据就会被恢复。这些操作支持的文件格式包括 JSONXMLCSVExcelYAML

如果必要,您可以清除历史记录以管理您的数据使用或保护您的隐私。

mqttx-advance

脚本

自 v1.4.2 版本开始,MQTTX 添加了脚本编辑功能。此功能允许用户编写自定义的JavaScript脚本来对发送和接收的 Payload 进行自定义转换。配合定时发送功能,可以实现模拟数据报告的自动化测试功能。

点击左侧菜单栏中的 脚本 按钮进入脚本编辑页面。在此页面中,用户可以在顶部的代码编辑器中编写 JavaScript 代码。全局只有一个 execute API,用户需要编写一个接收 value 参数的脚本函数,此参数即为 Payload,函数可以自定义修改 value,最后通过 execute 传参执行自定义函数。

下方还有一个 输入输出 框,可以输入预期的输入值,点击右侧的 测试 按钮可以在 输出 框中查看执行结果。输入值的格式包括 JSONPlaintext,方便用户提前调试自定义的脚本函数。测试完成后,可以点击右上角的 保存 按钮,输入脚本名称保存脚本。保存后即可到连接页面使用,已保存的脚本也可以编辑和删除。

在连接页面中,点击右上角的下拉菜单,选择 使用脚本,在弹出的窗口中选择需要使用的预保存脚本,然后选择脚本要应用的位置,包括发布、接收和全部。选择完成后,根据数据类型选择要发送或接收的数据格式,正常使用消息发布和接收。此时,如果看到预期的效果,一个脚本功能就完成了。如果用户需要取消脚本,可以点击顶部状态栏中红色的 停止脚本 按钮停止使用脚本。

此功能具有可扩展性和灵活性,需要用户配合实际需求使用。

mqttx-script

脚本使用示例可以在 scripts-example 文件夹中查看。如果你在使用中有更好、更实用的脚本,可以在此提交你的代码,让更多的人可以使用。

默认脚本示例如下:

/**
* @description: 默认脚本
* @param {any} value - Payload
* @param {string} msgType - 消息类型,值是 'received' 或 'publish'
* @param {number} index - 消息的索引,仅在脚本用于发布消息并启用定时消息时有效
* @return {any} - 脚本处理后的Payload
*/
function handlePayload(value, msgType, index) {
  return value.msg
}
execute(handlePayload)

日志

从 v1.5.0 版本开始,MQTTX 引入了日志功能,以帮助用户调试连接和报告错误。在生产环境中,日志系统会显示三个级别的信息:

  • INFO 用于提示用户操作信息
  • WARN 生成不安全行为或潜在风险的警告
  • ERROR 在失败时产生错误消息

默认情况下,日志将写入以下位置的日志文件,具体取决于您的操作系统:

操作系统日志文件路径
Linux~/.config/MQTTX/logs/log
macOS~/Library/Application Support/MQTTX/logs/log
Windows%USERPROFILE%\AppData\Roaming\MQTTX\logs\log

每次关闭 MQTTX 时,当前的日志文件都会根据时间戳重命名,格式为[YY]-[MM]-[DD]T[hh]:[mm].log

mqttx-log

其他

连接操作

通过点击顶部的操作栏按钮,您可以快速执行各种连接操作,如断开连接、删除当前连接、导入和导出数据,以及管理定时消息和流量统计等功能。

mqttx-connection

消息处理

您可以通过选择消息栏右上角的 "全部"、"接收" 或 "发布" 按钮来筛选消息。

点击顶部的操作栏按钮,选择 "搜索" 选项,或使用快捷键。macOS 用户可以使用 command + f 快捷键,其他用户可以使用 control + f 快捷键打开主题搜索功能,支持模糊查询主题和负载。

点击顶部的操作栏按钮,选择 "清除历史记录" 选项,可以快速清除当前连接的发送和接收消息。

mqttx-search

检查更新

点击左下角的 "i" 按钮进入 "关于" 页面,可以查看 MQTTX 的版本信息和相关的 EMQX 信息。点击 "检查更新" 按钮可以检查是否有新版本可用。

mqttx-update

多窗口

在连接列表中,右键单击并选择 "新建窗口" 可以为连接创建一个新窗口。在新窗口中,您可以建立连接、订阅主题、发布和接收消息等。如果有多个连接或需要同时查看接收到的消息,可以创建多个视图窗口并并排显示。从 v1.4.1 版本开始,用户还可以点击顶部的窗口按钮快速创建新窗口。

mqttx-window

mqttx-multi-window

流量统计

通过点击右上角的下拉菜单中的 "流量统计" 选项,MQTTX 将自动订阅系统主题,并在页面上显示一个简单的流量统计图表,显示 MQTT Broker 的版本信息和运行时间。

默认情况下,只有本地主机上的 MQTT 客户端才能订阅 $SYS 主题。请参考内置 ACL 来修改发布和订阅的 ACL 规则。

mqttx-bytes

定时消息

在右上角的下拉菜单中,您可以选择 "定时消息" 选项来设置发送频率(以秒为单位)。设置完成后,手动发送一条消息,MQTTX 将按照指定的频率自动发送该消息。

mqttx-timed-message