MQTTX Documentation

File: README.md Copy Chapter

MQTTX is a cross-platform MQTT 5.0 client tool open sourced by EMQ, which can run on macOS, Linux and Windows, and supports formatting MQTT payload.

MQTTX simplifies test operation with the help of a familiar, chat-like interface. It’s easy and quick to create multiple, simultaneous online MQTT client connections, and can test the connection, publishing, and subscription functions of MQTT/TCP, MQTT/TLS, MQTT/WebSocket as well as other MQTT protocol features.

MQTT stands for MQ Telemetry Transport. It is a publish/subscribe, extremely simple and lightweight messaging protocol, designed for constrained devices and low-bandwidth, high-latency or unreliable networks.

Preview Copy Chapter

Installation Copy Chapter

Currently available for download from these app stores

macOS App Store Copy Section

Homebrew Copy Section

The macOS users can install MQTTX using brew cask

brew install --cask mqttx

Linux Copy Section

Released Packages Copy Section

Download from GitHub Releases and install it.

Alternative, you can download here.

Usage Copy Chapter

See our documentation or manual for details.

1. Get MQTT Broker Ready.

   • If you do not need to deploy the MQTT Broker locally, you can use the public MQTT 5.0 Broker provided by EMQX Cloud for testing:

     shell Copy

     Broker IP: broker.emqx.io
     Broker TCP Port: 1883
     Broker SSL Port: 8883

   • To run MQTT Broker locally, EMQX is recommended: An Open-Source, Cloud-Native, Distributed MQTT Broker for IoT.

2. Connection configuration. Click the + button in the left menu bar and fill in the corresponding required fields in the form.

3. After the connection information is configured, click the Connect button in the upper right corner to create a connection and connect to MQTT Broker.

4. After the MQTT is connected successfully, you can perform MQTT publish and subscription tests.

Better Together with EMQX Copy Chapter

MQTTX is designed to connect to test MQTT Brokers such as EMQX, The one-click connection and simple graphical interface make it easy to connect to EMQX or EMQX Cloud to debug and explore functional features.

Sign up EMQX Cloud for 14 days free trial

Download EMQX locally right now

Get Involved Copy Chapter

• Follow @EMQTech on Twitter.
• If you have a specific question, check out our discussion forums.
• For general discussions, join us on the official Discord team.
• Keep updated on EMQX YouTube by subscribing.

Develop Copy Chapter

Recommended version for Node environment:

• v18.*.*

# Clone
git clone [email protected]:emqx/MQTTX.git

# Install dependencies
cd MQTTX
yarn install

# Compiles and hot-reloads for development
yarn run electron:serve

# Compiles and minifies for production
yarn run electron:build

After the building is successful, the corresponding installation file for the successful build ing will appear in the dist_electron directory.

If you need to package it as an installation package for an independent operating system, please refer to the following command:

# For Windows
yarn run electron:build-win

# For Linux
yarn run electron:build-linux

# For macOS
yarn run electron:build-mac

Contributing Copy Chapter

Please make sure to read the Contributing Guide before making a pull request.

Technology Stack Copy Chapter

• Electron
• Vue + Element
• TypeScript
• TypeORM
• SQLite
• MQTT.js

Resources Copy Chapter

• MQTT Programming

  A series of blogs to help developers get started quickly with MQTT in PHP, Node.js, Python, Golang, and other programming languages.

• MQTT SDKs

  We have selected popular MQTT client SDKs in various programming languages and provided code examples to help you quickly understand the use of MQTT clients.

License Copy Chapter

Apache License 2.0, see LICENSE.

File: cli/README.md Copy Chapter

MQTTX CLI

MQTTX CLI is an open source MQTT 5.0 CLI Client and MQTTX on the command line. Designed to help develop and debug MQTT services and applications faster without the need to use a graphical interface.

MQTT stands for MQ Telemetry Transport. It is a publish/subscribe, extremely simple and lightweight messaging protocol, designed for constrained devices and low-bandwidth, high-latency or unreliable networks.

Preview Copy Chapter

Documentation Copy Chapter

Explore the full range of features and learn how to get the most out of MQTTX CLI with our comprehensive MQTTX CLI Documentation.

Installation Copy Chapter

Get started by downloading MQTTX CLI from the MQTTX Downloads Page. Installation instructions are provided for different platforms to ensure a smooth setup.

Quickstart Copy Chapter

Once you've installed MQTTX CLI, you can immediately begin exploring its capabilities. Start with these basic commands:

• Connect to a Broker

  shell Copy

  mqttx conn -h 'broker.emqx.io' -p 1883 -u 'admin' -P 'public'

• Subscribe to a Topic

  shell Copy

  mqttx sub -t 'hello' -h 'broker.emqx.io' -p 1883

• Publish a Message

  shell Copy

  mqttx pub -t 'hello' -h 'broker.emqx.io' -p 1883 -m 'from MQTTX CLI'

For additional information on usage and advanced features, please consult our Getting Started Guide.

Better Together with EMQX Copy Chapter

MQTTX is designed to connect to test MQTT Brokers such as EMQX, The one-click connection and simple graphical interface make it easy to connect to EMQX or EMQX Cloud to debug and explore functional features.

Sign up EMQX Cloud for 14 days free trial

Download EMQX locally right now

Get Involved Copy Chapter

• Follow @EMQTech on Twitter.
• If you have a specific question, check out our discussion forums.
• For general discussions, join us on the official Discord team.
• Keep updated on EMQX YouTube by subscribing.

Develop Copy Chapter

Recommended version for Node environment:

• v18.*.*

# Clone
git clone [email protected]:emqx/MQTTX.git

# Install dependencies
cd MQTTX/cli
yarn install

# Compiles and hot-reloads for development
yarn run dev

# Compiles and minifies for production
yarn run build

After a successful build, the corresponding file for the successful build will appear in the dist directory and will need to be used in a Node.js environment.

If you need to package a binary executable, please refer to the following command.

# Install pkg lib
npm install pkg -g

# Build binary
pkg package.json

After a successful build, you will see the binary executable for each system in the release directory.

Contributing Copy Chapter

Please make sure to read the Contributing Guide before making a pull request.

Technology Stack Copy Chapter

• TypeScript
• Node.js
• pkg
• MQTT.js

License Copy Chapter

Apache License 2.0, see LICENSE.

File: cli/README-CN.md Copy Chapter

MQTTX 命令行工具

English | 简体中文

MQTTX CLI 是一款开源的 MQTT 5.0 命令行客户端工具，也是命令行上的 MQTTX，旨在帮助开发者在不需要使用图形化界面的基础上，也能更快的开发和调试 MQTT 服务与应用。

MQTT 全称为 Message Queuing Telemetry Transport（消息队列遥测传输）是一种基于 发布/订阅 范式的“轻量级”消息协议，旨在用于受限设备和低带宽，高延迟或不可靠的网络，由 IBM 发布。

功能预览 Copy Chapter

文档 Copy Chapter

关于介绍、安装和使用，请参阅 MQTTX CLI 文档，下面是一个快速入门指南。

安装 Copy Chapter

macOS Copy Section

下载二进制文件并快速安装最新的 MQTTX CLI 稳定版到 macOS 系统上。

注意：请注意区分当前系统环境的 CPU 架构

Intel Chip

curl -LO https://www.emqx.com/zh/downloads/MQTTX/v1.9.3/mqttx-cli-macos-x64
sudo install ./mqttx-cli-macos-x64 /usr/local/bin/mqttx

Apple Silicon

curl -LO https://www.emqx.com/zh/downloads/MQTTX/v1.9.3/mqttx-cli-macos-arm64
sudo install ./mqttx-cli-macos-arm64 /usr/local/bin/mqttx

Homebrew

brew install emqx/mqttx/mqttx-cli

Linux Copy Section

下载二进制文件并快速安装最新的 MQTTX CLI 稳定版到 Linux 系统上。

注意：请注意区分当前系统环境的 CPU 架构

x86-64

curl -LO https://www.emqx.com/zh/downloads/MQTTX/v1.9.3/mqttx-cli-linux-x64
sudo install ./mqttx-cli-linux-x64 /usr/local/bin/mqttx

ARM64

curl -LO https://www.emqx.com/zh/downloads/MQTTX/v1.9.3/mqttx-cli-linux-arm64
sudo install ./mqttx-cli-linux-arm64 /usr/local/bin/mqttx

Windows Copy Section

Windows 用户请到 MQTTX 的发布页面内，找到对应的系统架构的 exe 包，手动下载后使用

NPM Copy Section

npm install mqttx-cli -g

Docker Copy Section

docker pull emqx/mqttx-cli

docker run -it --rm emqx/mqttx-cli

其它平台 Copy Section

从 MQTTX 的发布页面内，下载对应的二进制文件。

使用 Copy Chapter

在安装完成后，可在终端直接运行 mqttx 命令：

快速使用 Copy Section

Connect

mqttx conn -h 'broker.emqx.io' -p 1883 -u 'admin' -P 'public'

Subscribe

mqttx sub -t 'hello' -h 'broker.emqx.io' -p 1883

Publish

# Publish a single message
mqttx pub -t 'hello' -h 'broker.emqx.io' -p 1883 -m 'from MQTTX CLI'

# Publish multiple messages (multiline)
mqttx pub -t 'hello' -h 'broker.emqx.io' -p 1883 -s -M

Benchmark

# Connect Benchmark
mqttx bench conn -c 5000

# Subscribe Benchmark
mqttx bench sub -c 5000 -t bench/%i

# Publish Benchmark
mqttx bench pub -c 5000 -t bench/%i

Simulate

# Specify a local scenario and start the simulation
mqttx simulate -sc tesla -c 10

# Specify a scenario file and start the simulation
mqttx simulate -f <scenario file path> -c 10

# List the built-in scenarios
mqttx ls -sc

参数介绍 Copy Section

mqttx --help

连接 Copy Section

mqttx conn --help

订阅 Copy Section

mqttx sub --help

发布 Copy Section

mqttx pub --help

性能测试 Copy Section

性能测试命令与普通命令参数基本相同，以下仅列出新增或有变化的参数。

连接性能测试

mqttx bench conn --help

订阅性能测试

mqttx bench sub --help

发布性能测试

mqttx bench pub --help

模拟器 Copy Section

用于模拟特定场景下 MQTT 发布消息操作。

模拟器命令与发布性能测试参数基本相同，以下仅列出新增或有变化的参数。

mqttx simulate --help

--scenario 与 --file 参数必须指定一个，如果同时指定，优先使用 --file 参数。

自定义物联网数据模拟脚本示例：

/**
 * MQTTX 场景文件示例
 * 
 * 此脚本生成随机的温度和湿度数据。
 */
function generator (faker, options) {
  return {
    // 如果没有返回主题，则使用命令行参数中的主题。
    // 主题格式：'mqttx/simulate/myScenario/' + clientId,
    message: JSON.stringify({
      temp: faker.number.int({ min: 20, max: 80 }),  // 在 20 到 80 之间生成随机温度。
      hum: faker.number.int({ min: 40, max: 90 }),   // 在 40 到 90 之间生成随机湿度。
    })
  }
}
// 导出场景模块
module.exports = {
  name: 'myScenario',  // 场景名称
  generator,          // 生成器函数
}

对于更多示例和详细的编辑指南，请参考 MQTTX GitHub 仓库中的脚本示例，或查看如何使用 faker.js 来生成各种类型的随机数据。

列表 Copy Section

list 命令提供了可用资源的概览。

目前，该命令仅支持列出内置的场景。

mqttx list --help

内置场景

可以使用 --scenarios 选项来显示内置场景的列表。

mqttx list --scenarios

这个命令会输出一个表格，显示每个内置场景的名称和描述。如果想在模拟命令中使用其中一个，只需在 --scenario 选项中指定场景名称：

mqttx simulate --scenario <SCENARIO>

未来，list 命令将添加更多选项和功能。敬请期待！

与 EMQX 更好的合作 Copy Chapter

MQTTX 为连接测试 EMQX 等 MQTT 消息服务器而生，一键式的连接方式和简洁的图形界面可以帮助您快速连接到 EMQX 或 EMQX Cloud 调试并探索其功能特性。

注册 EMQX Cloud 可以享受 14 天免费试用

现在就本地下载并安装 EMQX

社区 Copy Chapter

• 访问 EMQ 问答社区 以获取帮助，也可以分享您的想法或项目。
• 添加小助手微信号 emqmkt，加入 EMQ 微信技术交流群。
• 加入我们的 Discord，参于实时讨论。
• 关注我们的 bilibili，获取最新物联网技术分享。
• 关注我们的 微博 或 Twitter，获取 EMQ 最新资讯。

开发 Copy Chapter

Node 环境的推荐版本:

• v18.*.*

# 克隆项目
git clone [email protected]:emqx/MQTTX.git

# 安装依赖
cd MQTTX/cli
yarn install

# 编译和热重载以进行开发
yarn run dev

# 编译和压缩以构建生产版本
yarn run build

构建成功后，会在 dist 目录里出现构建成功的相应的文件，需要在 Node.js 环境中使用。

如果需要打包一个二进制可执行文件，请参考以下命令：

# 全局安装 pkg
npm install pkg -g

# 构建二进制可执行文件
pkg package.json

构建成功后，在 release 目录里可以看到对应各系统的二进制可执行文件了。

贡献 Copy Chapter

请确保在发出 PR 请求前， 已经仔细阅读过了贡献指南

技术栈 Copy Chapter

• TypeScript
• Node.js
• pkg
• MQTT.js

License Copy Chapter

Apache License 2.0, see LICENSE.

File: docs/desktop/zh/advanced/advanced-setting.md Copy Chapter

Create a Connection with Advanced and MQTT 5.0 Settings

When you create a new connection, you can configure the advanced settings and settings for MQTT 5.0 features.

Configure Advanced Settings Copy Chapter

In the Advanced section, you can configure the MQTT protocol-related features.

The default value of the MQTT Version is 5.0 and you can configure the MQTT 5.0 specific features such as Session Expiry Interval, Receive Maximum, and Topic Alias Maximum (optional). You can also select other MQTT protocol versions from the drop-down list. Other optional values are 3.1 and 3.1.1.

For detailed information on the advanced settings, see [Advanced].

Configure Last Will and Testament Copy Chapter

In the Last Will and Testament section, you can configure options for will messages.

The Last-Will-QoS and Last-Will-Retain fields are preset with 0 and False, respectively. Input the Last-Will-Topic and Last-Will-Payload values to complete the Will Message configuration.

After completing the configuration, click the Connect button in the upper right corner to swiftly create a connection and connect to the MQTT Broker.

File: docs/desktop/zh/quick-start/get-started.md Copy Chapter

快速开始

本页面指导您快速开始使用 MQTTX 桌面版连接 MQTT 代理服务器并体验基本的发布和订阅操作。

准备 MQTT 服务器 Copy Chapter

在开始之前，您需要准备一个 MQTT 服务器。您可以选择以下任一 MQTT 服务器或在线 MQTT 服务。

公共 MQTT 服务器 Copy Section

为了快速测试，您可以使用免费的在线公共 MQTT 代理而无需进行本地部署。这是 EMQX 的在线公共版本。

Broker address: broker.emqx.io
Broker TCP port: 1883
Broker SSL port: 8883

全托管云原生 MQTT 消息服务 Copy Section

EMQX 提供全托管的云原生 MQTT 消息服务，能够通过可靠、实时的物联网数据传输、处理和集成，连接大量的物联网设备。您可以在几分钟内创建一个 MQTT 服务。

14 天免费试用

自行部署 MQTT 服务器 Copy Section

如果您想在本地运行 MQTT 服务器，我们建议使用 EMQX。这是一款云原生分布式物联网 MQTT 消息服务器，能帮助您实时可靠地连接、转移和处理业务数据。

开始并运行 EMQX 的最简单方法是使用 Docker。您可以按照以下步骤下载和安装。

1. 下载并启动最新版本的 EMQX，请在执行以下命令之前确保已安装并运行 Docker。

   bash Copy

   docker run -d --name emqx -p 1883:1883 -p 8083:8083 -p 8084:8084 -p 8883:8883 -p 18083:18083 emqx/emqx-enterprise:latest

2. 启动您的 Web 浏览器，输入 http://localhost:18083/（localhost 可以替换为您的 IP 地址）在地址栏中访问 EMQX Dashboard，您可以在此连接客户端或查看运行状态。

   默认用户名和密码：admin 和 public

您还可以通过 下载软件包 安装 EMQX。

连接到 MQTT 服务器 Copy Chapter

本节演示了如何使用 MQTTX 桌面版通过最简单的设置连接到公共的 MQTT 服务器。想要了解其他高级设置，参阅使用通用设置建立客户端连接，使用高级设置建立客户端连接 和 MQTT 5.0 功能设置。

1. 启动您的 MQTT 服务器和 MQTTX 桌面端。您可以通过以下3种方式之一在 MQTTX 中创建新的客户端连接：

   • 在左侧导航菜单中点击 + 图标。

   • 在主面板上点击 + 新建连接 按钮。

   • 在连接面板上点击 + -> 新建连接。

2. 在基础区域输入 MQTT 服务器的连接信息。要尝试快速连接，您只需为新建的连接输入名称，例如 emqx_test，并将其他连接选项保留为默认设置。

   • 如果您使用的是自行部署的 MQTT 服务器，您可以将服务器地址替换为实际的 IP 地址，例如 127.0.0.1。

   ::: tip

   关于基础部分中的选项的详细信息，请查看使用基础设置创建连接。

   :::

3. 点击右上角的连接。至此，您已经建立了一个名为 emqx_test 的 MQTT 客户端连接。

订阅与发布 Copy Chapter

本节演示了如何使用 MQTTX 桌面版发布和订阅 MQTT 消息。

1. 点击主面板中的 + 添加订阅。在弹出窗口中， 在 Topic 文本框中输入 test，并保留其他选项为默认设置。点击确定。客户端连接现在订阅了 test 主题。

   ::: tip

   作为简单的演示，不建议使用默认主题 testtopic/#，否则如果您连接到公共 MQTT 代理服务器，您会不断收到消息。

   :::

2. 按照连接到 MQTT 代理服务器中的步骤，创建一个新的 MQTT 客户端连接，名称为 Publisher。

3. 在连接面板中，确保选择了客户端连接 Publisher。在右下角的发布区域中，输入 test 作为主题，并保留消息 payload 和其他选项为默认设置。

   点击发送按钮，连接 emqx_test 上出现一个数字，表示收到了一条新消息。

4. 在连接面板中选择 emqx_test 连接。 您可以查看 Publisher 发送的消息。

File: docs/desktop/zh/use-desktop/connect.md Copy Chapter

Create Connection with General Settings

When you create a new connection, in the General section of the New pane, you can configure the information of the broker you connect to, the client authentication information, and SSL/TLS options.

Broker Information Copy Chapter

The broker information contains must-fill fields. The Client ID, Host, and Port are already filled with default values. You can modify them based on the actual broker information.

• Name: Enter a connection, for example emqx_test.

• Client ID: It is the one and only identification of a client connection and can be automatically generated by clicking the refresh button next to the field.

• Host: Select the protocol to be used for the connection. Select mqtt:// or ws://. If an SSL/TLS encrypted connection is used, you need to select mqtts:// or wss://. The host IP address is set to broker.emqx.io by default, indicating you will connect to the public broker. If you are working with your own EMQX, replace it with the actual IP.

  • Path: Define the path for the WebSocket connection when ws:// or wss:// is selected as the protocol. It is used to find the correct endpoint on the server; default: /mqtt.

• Port: Enter the port corresponding to the selected protocol.

  Protocol	Port
  mqtt:// or wss://	1883
  mqtts:// or wss://	8883

User Authentication Copy Chapter

If your broker has enabled user user authentication, you need to enter the information in the Username and Password fields.

SSL/TLS Copy Chapter

You can establish a secured connection between MQTTX and the broker by enabling the SSL/TLS option.

• SSL/TLS: Enable or disable the SSL/TLS connection using the toggle switch; Disabled by default.

  • SSL Secure: You can enable or disable the client verification on the certificate chain and hostname of the server on which the broker is deployed during the connection. When disabled, no verification is performed, allowing connections to be established with unverified servers.

    ::: tip

    Scenarios for disabling the SSL Secure:

    1. Development Environment: During development, for testing and debugging purposes, you can turn off the SSL secure switch to connect to unverified servers.

    2. Internal Network: In trusted internal networks without external access risk, consider turning off the SSL secure switch to simplify certificate management.

    However, disabling SSL Secure reduces security. In production environments or when communicating with external networks, it is recommended to enable the feature to ensure secure communications.

    :::

  • CA signed server: Verify the server through the Certificate Authority (CA) signed certificate.

  • Self signed: Verify the server through self-signed certificates. When selected, you need to configure the certificates. For a one-way authentication, only your CA File needs to be selected. For two-way authentication, you also need to configure the Client Certificate File and Client key file.

    • CA File: Select the CA file by clicking the folder icon.
    • Client Certificate File: Select the client certificate file by clicking the folder icon.
    • Client key file: Select the file by clicking the folder icon for two-way authentication.

Configure Advanced Settings Copy Chapter

In the Advanced section, you can configure the MQTT protocol-related features.

The default value of the MQTT Version is 5.0 and you can configure the MQTT 5.0 specific features such as Session Expiry Interval, Receive Maximum, and Topic Alias Maximum (optional). You can also select other MQTT protocol versions from the drop-down list. Other optional values are 3.1 and 3.1.1.

For detailed information on the advanced settings, see [Advanced].

Configure Last Will and Testament Copy Chapter

In the Last Will and Testament section, you can configure options for will messages.

The Last-Will-QoS and Last-Will-Retain fields are preset with 0 and False, respectively. Input the Last-Will-Topic and Last-Will-Payload values to complete the Will Message configuration.

After completing the configuration, click the Connect button in the upper right corner to swiftly create a connection and connect to the MQTT Broker.

File: docs/desktop/zh/use-desktop/pub-sub.md Copy Chapter

Publish and Subscribe

Main Interface Copy Chapter

Upon successful connection, you'll access the main interface of the connection. Click the fold button next to the connection name at the top to expand and display the basic configuration information. This feature is handy for swiftly modifying several common connection configurations. Note that modifications require a disconnect, then a re-connect to take effect. After each successful connection, the panel will automatically fold up. In the disconnected state, you can click the configuration button on the right to modify more connection configurations.

Add Subscription Copy Chapter

Click the New Subscription button in the lower left corner to swiftly add a Topic. Each Topic can be marked with a color, which can be randomly generated or chosen via the color selector. The rightmost button at the top of the subscription list can hide the subscription list to make more room on the page. After completion, click on the subscribed Topic items in the subscription list for message filtering. The message view will only display the message content subscribed to the current topic. Click again to cancel the filter; You can also directly click other subscribed Topic items to view the corresponding message content. By clicking on the topic name, you can quickly copy the current topic information. When you need to send a message to this topic, you can quickly paste it into the topic input box of the message bar to modify it, and you can quickly complete the operation.

When adding Topic, you can set an alias for each Topic. This option is optional. When the subscription is set and added, the Topic in the subscription list will be displayed as an alias, and hovering over the Topic item will also display the original value of the Topic. This is very helpful when multiple Topics that need to be monitored are too long to distinguish the specific meaning of Topic.

We open the dialog of the subscription topic, in the Topic input box, enter multiple Topics and use comma (,) to split, click to confirm the success of the subscription, we can see that the subscription list contains multiple Topics. for the use of the client layer alias function can also support the simultaneous setting of multiple Topics, the same use of comma separation (,).

Subscribed Topics support Edit/Disable/Enable functions, right click on the subscribed Topic list item, in the context menu we can quickly choose to edit, disable or enable the operation. When subscribing to too many Topics, sometimes not all the Topic messages you want to receive, in order to avoid subscribing to the same Topic again, the disable function is provided, if you want to receive messages from the Topic again, just enable it again.

Publish and Receiving Messages Copy Chapter

After the Topic is successfully subscribed, you can test the sending and receiving of messages. Fill in the Topic information you just subscribed to in the lower right corner of the page. You can select the values of QoS, Retain, input payload, and click the send button on the far right to send a message to the Topic you just subscribed. After sending successfully, you can immediately receive the message just sent. Note that in the message box, the right column is the sent message, and the left column is the received message. macOS users can use the command + enter shortcut to quickly send messages, and other users can use the control + enter shortcut to do that.

Through the payload option in the message bar, the messages can quickly be converted into multiple formats, such as Base64, Hex,JSON and Plaintext.

So far, the testing of an MQTT message is completed.

File: docs/desktop/zh/downloading-and-installation.md Copy Chapter

Installation

You can download and install MQTTX from several sources:

1. MQTTX Official Website Download Page provides direct access to download and installation.

2. EMQ Official Website Download Page also hosts MQTTX for download and installation.

3. Alternatively, you can select your preferred version from the GitHub Releases page.

If you're experiencing slow network speed or latency issues when downloading from GitHub, we recommend using the MQTTX official homepage or the EMQ official download page instead.

For additional released versions, you can visit our More Downloads page. Select and install the version that best suits your needs.

Note: We strongly recommend downloading the latest version whenever possible to ensure the best user experience.

macOS Copy Chapter

We offer two distinct versions of the MQTTX installer for macOS users, one for Intel Chip and another for Apple Silicon. Please select the version that is compatible with your current hardware configuration.

Alternatively, you can download MQTTX from Apple's Mac App Store.

NOTE: Currently, due to the App Store review process, the version on the App Store is limited to version 1.6.0. We are working to resolve this issue and will continue to update the version accordingly.

When it comes to installing MQTTX, we recommend downloading the dmg format installation package. Alternatively, you can download the mac.zip compressed file which can be decompressed and used quickly.

Note: Please be aware that for certain macOS system versions, specifically 10.15.2, there may be issues opening the zip compressed file after decompression. As a result, we advise users to prioritize downloading the dmg file.

For macOS users who prefer using the command line, MQTTX can also be installed via brew cask:

brew install --cask mqttx

Windows Copy Chapter

For Windows users, we provide installation packages for 32-bit, 64-bit, and ARM64 architectures. Please choose the version compatible with your current hardware.

We recommend Windows users to download the latest exe file. Once downloaded, you can follow the Setup instructions for installation.

Linux Copy Chapter

For Linux users, we provide installation packages for x86 64-bit and ARM64 architectures. Please select the version that matches your current hardware.

Linux users can directly visit Flathub to download and install MQTTX:

Alternatively, use the flatpak command to quickly install and start MQTTX:

Install:

flatpak install flathub com.emqx.MQTTX

Run:

flatpak run com.emqx.MQTTX

For those who prefer manual installation, download the latest AppImage, deb, or rpm files according to your specific Linux operating system.

Ubuntu Copy Chapter

For Ubuntu Snap Store users, currently, only the x86 64-bit installer is available.

Ubuntu users typically use snap files for installation. The snap format installers can be downloaded from the Snap Store:

Alternatively, execute the following command to install MQTTX using the snap file:

sudo snap install mqttx

For manual installation, download the latest version of the snap file. Here's an example:

sudo snap install Downloads/MQTTX_1.9.3_amd64.snap --dangerous

Note: When installing with snap files, you may encounter insufficient permission issues. For more details, refer to this issue: https://github.com/emqx/MQTTX/issues/109

File: docs/desktop/zh/introduction.md Copy Chapter

Introduction

MQTTX is an open-source, cross-platform MQTT 5.0 desktop client initially developed by EMQ, which can run on macOS, Linux, and Windows.

The user interface (UI) of MQTTX adopts a chat-based layout, simplifying operational logic. It enables users to establish multiple MQTT connections, thereby facilitating swift testing of MQTT/MQTTS connections, as well as message subscription and publication.

Before installing, we encourage you to visit our website or GitHub to acquaint yourself with the latest version information. The latest updates are aimed at enhancing the user experience. If you're familiar with this project, you also have the option to directly clone the source code of MQTTX, and build and use it on your own terms. During usage, if you encounter any issues, please navigate to GitHub issues to pose queries or share your thoughts. Alternatively, you can fork our project and submit your modifications as a Pull Request. We promise a thoughtful review and timely response.

Preview Copy Chapter

Main Features Copy Chapter

• User-friendly, chat box for sending/receiving MQTT messages
• Cross-platform, compatibility, runs on Windows, macOS, and Linux
• Fully compliant with MQTT 5.0, 3.1.1 and 3.1
• Customizable color schemes for different MQTT subscriptions
• Supports one-way and two-way SSL/TLS authentication
• Supports MQTT over WebSockets
• Payload Format Conversion with support for Hex, Base64, JSON, and Plaintext
• Custom scripts for MQTT Pub/Sub simulation
• Comprehensive logging capabilities
• Language support for English, Japanese, Simplified Chinese, Turkish, and Hungarian 🇨🇳 🇯🇵 🇺🇸 🇹🇷 🇭🇺
• Toggle between Light/Dark/Night mode freely

File: docs/desktop/en/advanced/advanced-setting.md Copy Chapter

Create a Connection with Advanced and MQTT 5.0 Settings

When you create a new connection, you can configure the advanced settings and settings for MQTT 5.0 features.

Configure Advanced Settings Copy Chapter

In the Advanced section, you can configure the MQTT protocol-related features.

The default value of the MQTT Version is 5.0 and you can configure the MQTT 5.0 specific features such as Session Expiry Interval, Receive Maximum, and Topic Alias Maximum (optional). You can also select other MQTT protocol versions from the drop-down list. Other optional values are 3.1 and 3.1.1.

For detailed information on the advanced settings, see [Advanced].

Configure Last Will and Testament Copy Chapter

In the Last Will and Testament section, you can configure options for will messages.

The Last-Will-QoS and Last-Will-Retain fields are preset with 0 and False, respectively. Input the Last-Will-Topic and Last-Will-Payload values to complete the Will Message configuration.

After completing the configuration, click the Connect button in the upper right corner to swiftly create a connection and connect to the MQTT Broker.