高级进阶

MQTT 5

Clean Start 和会话过期间隔

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

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

用户属性

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

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

请求响应

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

内容类型和载荷格式

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

订阅标识符和订阅选项

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

设置

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

通用

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

外观

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

高级（数据管理）

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

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

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

脚本

自定义函数

此功能允许用户根据特定的需求或场景，编写自定义的函数代码，自由地对 Payload 的内容和格式进行调整和转化，实现更为精细化的数据管理和处理。如果同时配合定时发送功能，可以实现模拟数据报告的自动化测试等功能。

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

使用 JavaScript

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

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

默认 JavaScript 函数示例如下：

/**
* @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)

编解码

此功能允许用户根据实际需求编写自定义的编解码文件，来对发送和接收的 Payload 进行编解码。在具体应用中，用户可以根据数据特性或特定的应用场景，编写特定的编解码规则。这个过程类似于为 Payload 设计一种特定的“语言”，并通过编写编解码文件来定义这种“语言”的翻译规则。这样，无论是发送还是接收 Payload，都可以根据这些规则来进行编码或解码，确保数据的正确理解和有效传输。

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

使用 Protocol Buffers

点击左侧菜单栏中的 脚本 按钮进入脚本编辑页面。在 编解码页面中，用户可以在顶部的代码编辑器中编写 proto 文件。

下方还有一个 输入 和 输出 框，可以输入预期的输入值。输入定义的消息类型的名字之后，点击右侧的 测试 按钮可以在 输出 框中查看执行结果。输入值的格式包括 JSON 、 Plaintext 、Base64 和 Hex，方便用户提前调试自定义的编解码。输入 JSON 或者经过 Base64 和 Hex 编码后的 JSON 字符串，测试完成后，可以点击右上角的 保存 按钮，输入编解码名称保存编解码。保存后即可到连接页面使用，已保存的编解码也可以编辑和删除。

默认 Protocol Buffers 编解码文件示例如下：

syntax = "proto3";

message Person {
  int32 id = 1;
  string name = 2;
}

工作流

如果用户同时使用了脚本的自定义函数功能和编解码功能，MQTTX 将使用一种高效的脚本工作流，涵盖了发布和订阅两个阶段。

在发布阶段，脚本工作流首先调用自定义函数来处理输入数据。经过这些自定义函数处理后，产生的消息将被显示出来。随后，将使用编解码对处理后的消息进行编码。

在订阅阶段，脚本工作流首先接收传入的编码消息。接收到消息后，编解码立即被调用以进行解码。解码后的消息会送入自定义函数进行处理。处理完成后，处理过的消息将被显示出来。

这种的脚本工作流设计允许用户灵活地在发布和订阅阶段处理数据，并保证了消息在传输过程中的安全和完整性。

使用指南

1. 导航到连接页面，点击页面右上角的下拉菜单。在下拉菜单中，选择 运行脚本 选项。
   
2. 这将会弹出一个脚本窗口，从中选择选择脚本要应用的位置，选项包括发布、接收和全部。然后，选择需要使用的自定义函数或者编解码。
   
3. 如果您看到在发布或者订阅的消息卡片上看到脚本使用提示，那么说明脚本功能已经被成功调用。
   
4. 如果您需要取消使用脚本，可以点击顶部状态栏中红色的 停止脚本 按钮，这将停止使用脚本。
   

日志

从 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。

其他

连接操作

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

消息处理

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

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

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

检查更新

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

多窗口

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

流量统计

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

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

定时消息

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