## File: README.md [](https://github.com/emqx/mqttx/releases) [](https://mqttx.app/downloads) [](https://hub.docker.com/r/emqx/mqttx-web) [](https://hub.docker.com/r/emqx/mqttx-cli) [](https://github.com/emqx/MQTTX/discussions) [](https://slack-invite.emqx.io/) [](https://discord.gg/xYGf3fQnES) [](https://www.youtube.com/channel/UC5FjR77ErAxvZENEWzQaO5Q) [](https://twitter.com/EMQTech) --- [MQTTX](https://mqttx.app) is a cross-platform [MQTT 5.0](https://www.emqx.com/en/blog/introduction-to-mqtt-5) client tool open sourced by [EMQ](https://www.emqx.com/en), which can run on macOS, Linux and Windows, and supports formatting MQTT payload. [MQTTX](https://mqttx.app) 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](https://www.emqx.com/en/blog/the-easiest-guide-to-getting-started-with-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 ## Installation Currently available for download from these app stores ### macOS App Store [](https://apps.apple.com/us/app/mqttx/id1514074565?mt=12) ### Homebrew The macOS users can install MQTTX using [brew cask](https://formulae.brew.sh/cask/mqttx) ```shell brew install --cask mqttx ``` ### Linux [](https://snapcraft.io/mqttx) [](https://flathub.org/apps/details/com.emqx.MQTTX) ### Released Packages Download from [GitHub Releases](https://github.com/emqx/MQTTX/releases) and install it. Alternative, you can download [here](https://www.emqx.com/downloads/MQTTX/). ## Usage See our [documentation](https://mqttx.app/docs) or [manual](./docs/manual.md) 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](https://www.emqx.com/en/mqtt/public-mqtt5-broker) provided by [EMQX Cloud](https://www.emqx.com/en/cloud) for testing: ```shell Broker IP: broker.emqx.io Broker TCP Port: 1883 Broker SSL Port: 8883 ``` - To run MQTT Broker locally, [EMQX](https://www.emqx.com/en/products/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 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](https://www.emqx.com/en/try?product=cloud) [Download EMQX locally right now](https://www.emqx.com/en/try?product=enterprise) ## Get Involved - Follow [@EMQTech on Twitter](https://twitter.com/EMQTech). - If you have a specific question, check out our [discussion forums](https://github.com/emqx/emqx/discussions). - For general discussions, join us on the [official Discord](https://discord.gg/xYGf3fQnES) team. - Keep updated on [EMQX YouTube](https://www.youtube.com/channel/UC5FjR77ErAxvZENEWzQaO5Q) by subscribing. ## Develop Recommended version for Node environment: - v18.\*.\* ``` shell # Clone git clone git@github.com: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: ```shell # For Windows yarn run electron:build-win # For Linux yarn run electron:build-linux # For macOS yarn run electron:build-mac ``` ## Contributing Please make sure to read the [Contributing Guide](https://github.com/emqx/MQTTX/blob/main/.github/CONTRIBUTING.md) before making a pull request. ## Technology Stack - [Electron](https://electronjs.org/) - [Vue](https://vuejs.org/) + [Element](https://element.eleme.io) - [TypeScript](https://www.typescriptlang.org/) - [TypeORM](https://github.com/typeorm/typeorm) - [SQLite](https://github.com/mapbox/node-sqlite3) - [MQTT.js](https://github.com/mqttjs/MQTT.js) ## Resources - [MQTT Programming](https://www.emqx.com/en/blog/category/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](https://www.emqx.com/en/mqtt-client-sdk) 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 Apache License 2.0, see [LICENSE](https://github.com/emqx/MQTTX/blob/main/LICENSE). --- ## File: cli/README.md # MQTTX CLI [](https://github.com/emqx/mqttx/releases) [](https://mqttx.app/downloads) [](https://hub.docker.com/r/emqx/mqttx-web) [](https://hub.docker.com/r/emqx/mqttx-cli) [](https://github.com/emqx/MQTTX/discussions) [](https://slack-invite.emqx.io/) [](https://discord.gg/xYGf3fQnES) [](https://www.youtube.com/channel/UC5FjR77ErAxvZENEWzQaO5Q) [](https://twitter.com/EMQTech) --- [MQTTX CLI](https://mqttx.app/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](https://www.emqx.com/en/blog/the-easiest-guide-to-getting-started-with-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 ## Documentation Explore the full range of features and learn how to get the most out of MQTTX CLI with our comprehensive [MQTTX CLI Documentation](https://mqttx.app/docs/cli). ## Installation Get started by downloading MQTTX CLI from the [MQTTX Downloads Page](https://mqttx.app/downloads). Installation instructions are provided for different platforms to ensure a smooth setup. ## Quickstart Once you've installed MQTTX CLI, you can immediately begin exploring its capabilities. Start with these basic commands: - **Connect to a Broker** ```shell mqttx conn -h 'broker.emqx.io' -p 1883 -u 'admin' -P 'public' ``` - **Subscribe to a Topic** ```shell mqttx sub -t 'hello' -h 'broker.emqx.io' -p 1883 ``` - **Publish a Message** ```shell 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](https://mqttx.app/docs/cli/get-started). ## Better Together with EMQX 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](https://www.emqx.com/en/try?product=cloud) [Download EMQX locally right now](https://www.emqx.com/en/try?product=enterprise) ## Get Involved - Follow [@EMQTech on Twitter](https://twitter.com/EMQTech). - If you have a specific question, check out our [discussion forums](https://github.com/emqx/emqx/discussions). - For general discussions, join us on the [official Discord](https://discord.gg/xYGf3fQnES) team. - Keep updated on [EMQX YouTube](https://www.youtube.com/channel/UC5FjR77ErAxvZENEWzQaO5Q) by subscribing. ## Develop Recommended version for Node environment: - v18.\*.\* ``` shell # Clone git clone git@github.com: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. ```shell # 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 Please make sure to read the [Contributing Guide](https://github.com/emqx/MQTTX/blob/main/.github/CONTRIBUTING.md) before making a pull request. ## Technology Stack - [TypeScript](https://www.typescriptlang.org/) - [Node.js](https://nodejs.org/en/) - [pkg](https://github.com/vercel/pkg) - [MQTT.js](https://github.com/mqttjs/MQTT.js) ## License Apache License 2.0, see [LICENSE](https://github.com/emqx/MQTTX/blob/main/LICENSE). --- ## File: cli/README-CN.md # MQTTX 命令行工具 [](https://github.com/emqx/mqttx/releases) [](https://github.com/emqx/mqttx/releases) [](https://hub.docker.com/r/emqx/mqttx-cli) [](https://slack-invite.emqx.io/) [](https://discord.gg/xYGf3fQnES) [](https://github.com/emqx/MQTTX/discussions) [](https://www.youtube.com/channel/UCir_r04HIsLjf2qqyZ4A8Cg) [](https://twitter.com/EMQTech) [English](https://github.com/emqx/MQTTX/blob/main/cli/README.md) | 简体中文 --- [MQTTX CLI](https://mqttx.app/zh/cli) 是一款开源的 MQTT 5.0 命令行客户端工具，也是命令行上的 MQTTX，旨在帮助开发者在不需要使用图形化界面的基础上，也能更快的开发和调试 MQTT 服务与应用。 > [MQTT](https://www.emqx.com/zh/blog/the-easiest-guide-to-getting-started-with-mqtt) 全称为 Message Queuing Telemetry Transport（消息队列遥测传输）是一种基于 发布/订阅 范式的“轻量级”消息协议，旨在用于受限设备和低带宽，高延迟或不可靠的网络，由 IBM 发布。 ## 功能预览 ## 文档 关于介绍、安装和使用，请参阅 [MQTTX CLI 文档](https://mqttx.app/zh/docs/cli)，下面是一个快速入门指南。 ## 安装 ### macOS 下载二进制文件并快速安装最新的 MQTTX CLI 稳定版到 macOS 系统上。 > **注意**：请注意区分当前系统环境的 CPU 架构 #### Intel Chip ```shell 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 ```shell 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 ```shell brew install emqx/mqttx/mqttx-cli ``` ### Linux 下载二进制文件并快速安装最新的 MQTTX CLI 稳定版到 Linux 系统上。 > **注意**：请注意区分当前系统环境的 CPU 架构 #### x86-64 ```shell 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 ```shell 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 Windows 用户请到 MQTTX 的[发布页面](https://github.com/emqx/MQTTX/releases)内，找到对应的系统架构的 `exe` 包，手动下载后使用 ### NPM ```shell npm install mqttx-cli -g ``` ### Docker ```shell docker pull emqx/mqttx-cli docker run -it --rm emqx/mqttx-cli ``` ### 其它平台 从 MQTTX 的[发布页面](https://github.com/emqx/MQTTX/releases)内，下载对应的二进制文件。 ## 使用 在安装完成后，可在终端直接运行 `mqttx` 命令： ### 快速使用 Connect ```shell mqttx conn -h 'broker.emqx.io' -p 1883 -u 'admin' -P 'public' ``` Subscribe ```shell mqttx sub -t 'hello' -h 'broker.emqx.io' -p 1883 ``` Publish ```shell # 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 ```bash # 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 ```bash # 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 -c 10 # List the built-in scenarios mqttx ls -sc ``` ### 参数介绍 ```shell mqttx --help ``` | 参数 | 描述 | | ------------- | --------------------------- | | -v, --version | 输出当前 MQTTX CLI 的版本号 | | -h, --help | 展示 mqttx 命令的帮助信息 | | 命令 | 描述 | | -------- | -------------------------------- | | check | 检查更新 | | conn | 创建一个连接并连接到 MQTT Broker | | pub | 向主题发布一条消息 | | sub | 订阅一个或多个主题 | | bench | MQTT 性能测试 | | simulate | MQTT 模拟器 | ### 连接 ```shell mqttx conn --help ``` | 参数 | 描述 | | ------------------------------------------------ | ------------------------------------------------------------------------------------------ | | -V, --mqtt-version <5.0/3.1.1/3.1> | MQTT 版本，默认为 5 | | -h, --hostname | MQTT Broker 的 Host 地址，默认为 localhost | | -p, --port | MQTT Broker 的端口号 | | -i, --client-id | 客户端 ID | | --no-clean | 取消 clean session 标志位，默认为 true | | -k, --keepalive | MQTT 的 Keep Alive，默认为 30 | | -u, --username | 连接到 MQTT Broker 的用户名 | | -P, --password | 连接到 MQTT Broker 的密码 | | -l, --protocol | 连接时的协议，支持 mqtt、mqtts、ws、wss，默认为 mqtt | | --path | websocket 的路径，默认为 /mqtt | | --key | key 文件的路径 | | --cert | cert 文件的路径 | | --ca | ca 证书的文件路径 | | --insecure | 取消服务器的证书校验 | | -rp, --reconnect-period | 自动重连的间隔时间，通过设置为 0 来禁用自动重连，默认为 1000ms | | --maximum-reconnect-times | 最大重连次数，默认为 10 | | -up, --user-properties | MQTT 5.0 用户属性，例如：-up "name: mqttx cli" | | -Wt, --will-topic | 遗嘱消息的 Topic | | -Wm, --will-message | 遗嘱消息的 Payload | | -Wq, --will-qos <0/1/2> | 遗嘱消息的 QoS | | -Wr, --will-retain | 发送的遗嘱消息为保留消息，默认为 false | | -Wd, --will-delay-interval | 遗嘱消息延迟间隔，单位为秒 | | -Wpf, --will-payload-format-indicator | 遗嘱消息是否为UTF-8编码的字符数据 | | -We, --will-message-expiry-interval | 遗嘱信息的有效期，单位为秒 | | -Wct, --will-content-type | 遗嘱消息内容的描述 | | -Wrt, --will-response-topic | 响应信息的主题名称 | | -Wcd, --will-correlation-data | 响应信息的关联数据 | | -Wup, --will-user-properties | 遗嘱消息的自定义用户属性 | | -se, --session-expiry-interval | 会话过期间隔，单位为秒 | | --rcv-max, --receive-maximum | 接收消息的最大值 | | --maximum-packet-size | 客户端愿意接受的最大数据包大小 | | --topic-alias-maximum | 主题别名的最大值 | | --req-response-info | 客户端要求服务器提供的响应信息 | | --no-req-problem-info | 客户端向服务器请求问题信息 | | --save \[PATH\] | 将参数保存到本地配置文件中，文件支持 json 和 yaml 格式，默认路径为 ./mqttx-cli-config.json | | --config \[PATH\] | 从本地配置文件加载参数，文件支持 json 和 yaml 格式，默认路径为 ./mqttx-cli-config.json | | --help | 展示 conn 命令的帮助信息 | ### 订阅 ```shell mqttx sub --help ``` | 参数 | 描述 | | ------------------------------------------------ | ------------------------------------------------------------------------------------------ | | -V, --mqtt-version <5.0/3.1.1/3.1> | MQTT 版本，默认为 5 | | -h, --hostname | MQTT Broker 的 Host 地址，默认为 localhost | | -p, --port | MQTT Broker 的端口号 | | -i, --client-id | 客户端 ID | | -q, --qos <0/1/2> | 消息的 QoS，默认为 0 | | --no-clean | 取消 clean session 标志位，默认为 true | | -t, --topic | 需要订阅的 Topic | | -k, --keepalive | MQTT 的 Keep Alive，默认为 30 | | -u, --username | 连接到 MQTT Broker 的用户名 | | -P, --password | 连接到 MQTT Broker 的密码 | | -l, --protocol | 连接时的协议，支持 mqtt、mqtts、ws、wss，默认为 mqtt | | --path | websocket 的路径，默认为 /mqtt | | -nl, --no_local | MQTT 5.0 订阅选项中的 no local 标识 | | -rap, --retain-as-published | MQTT 5.0 订阅选项中的 retain as published 标识 | | -rh, --retain-handling <0/1/2> | MQTT 5.0 订阅选项中的 retain handling 标识 | | --key | key 文件的路径 | | --cert | cert 文件的路径 | | --ca | ca 证书的文件路径 | | --insecure | 取消服务器的证书校验 | | -rp, --reconnect-period | 自动重连的间隔时间，通过设置为 0 来禁用自动重连，默认为 1000ms | | --maximum-reconnect-times | 最大重连次数，默认为 10 | | -up, --user-properties | MQTT 5.0 用户属性，例如：-up "name: mqttx cli" | | -f, --format | 消息格式化类型，支持 base64、json、hex | | -v, --verbose | 在接收到的 Payload 前显示当前 Topic | | --output-mode | 选择默认或简洁模式，简洁模式会输出完整的数据包，允许用户使用 jq 这类工具自由管理输出 | | -Wt, --will-topic | 遗嘱消息的 Topic | | -Wm, --will-message | 遗嘱消息的 Payload | | -Wq, --will-qos <0/1/2> | 遗嘱消息的 QoS | | -Wr, --will-retain | 发送的遗嘱消息为保留消息，默认为 false | | -Wd, --will-delay-interval | 遗嘱消息延迟间隔，单位为秒 | | -Wpf, --will-payload-format-indicator | 遗嘱消息是否为UTF-8编码的字符数据 | | -We, --will-message-expiry-interval | 遗嘱信息的有效期，单位为秒 | | -Wct, --will-content-type | 遗嘱消息内容的描述 | | -Wrt, --will-response-topic | 响应信息的主题名称 | | -Wcd, --will-correlation-data | 响应信息的关联数据 | | -Wup, --will-user-properties | 遗嘱消息的自定义用户属性 | | -se, --session-expiry-interval | 会话过期间隔，单位为秒 | | -si, --subscription-identifier | 订阅标识符 | | --rcv-max, --receive-maximum | 接收消息的最大值 | | --maximum-packet-size | 客户端愿意接受的最大数据包大小 | | --topic-alias-maximum | 主题别名的最大值 | | --req-response-info | 客户端要求服务器提供的响应信息 | | --no-req-problem-info | 客户端向服务器请求问题信息 | | -Cup, --conn-user-properties | MQTT 5.0 的连接用户属性（例如，-Cup "name: mqttx cli"） | | --save \[PATH\] | 将参数保存到本地配置文件中，文件支持 json 和 yaml 格式，默认路径为 ./mqttx-cli-config.json | | --config \[PATH\] | 从本地配置文件加载参数，文件支持 json 和 yaml 格式，默认路径为 ./mqttx-cli-config.json | | --help | 展示 sub 命令的帮助信息 | | -Pp, --protobuf-path | 定义 Protocol Buffers（protobuf）消息格式的 .proto 文件路径 | | -Pmn, --protobuf-message-name | Protobuf 消息类型的名称（必须存在于 .proto 文件中） | ### 发布 ```shell mqttx pub --help ``` | 参数 | 描述 | | ------------------------------------------------ | ------------------------------------------------------------------------------------------ | | -V, --mqtt-version <5.0/3.1.1/3.1> | MQTT 版本，默认为 5 | | -h, --hostname | MQTT Broker 的 Host 地址，默认为 localhost | | -p, --port | MQTT Broker 的端口号 | | -i, --client-id | 客户端 ID | | -q, --qos <0/1/2> | 消息的 QoS，默认为 0 | | --no-clean | 取消 clean session 标志位，默认为 true | | -t, --topic | 需要发布的 Topic | | -m, --message | 需要发布的 Payload 消息 | | -r, --retain | 设置发送消息为 Retain 消息，默认为 fasle | | -s, --stdin | 从 stdin 中读取信息体 | | -M, --multiline | 可以通过多行发布多条消息 | | -u, --username | 连接到 MQTT Broker 的用户名 | | -P, --password | 连接到 MQTT Broker 的密码 | | -f, --format | 输入消息的格式类型，支持 base64、json 和 hex | | -l, --protocol | 连接时的协议，支持 mqtt、mqtts、ws、wss，默认为 mqtt | | --path | websocket 的路径，默认为 /mqtt | | --key | key 文件的路径 | | --cert | cert 文件的路径 | | --ca | ca 证书的文件路径 | | --insecure | 取消服务器的证书校验 | | -rp, --reconnect-period | 自动重连的间隔时间，通过设置为 0 来禁用自动重连，默认为 1000ms | | --maximum-reconnect-times | 最大重连次数，默认为 10 | | -up, --user-properties | MQTT 5.0 用户属性，例如：-up "name: mqttx cli" | | -pf, --payload-format-indicator | 发布信息的有效载荷格式指标 | | -e, --message-expiry-interval | 发布信息的有效期，单位为秒 | | -ta, --topic-alias | 主题别名，识别主题的值，而不是使用主题名称 | | -rt, --response-topic | 作为响应信息的主题名称 | | -cd, --correlation-data | 请求信息的发送者在收到响应信息时用来识别是哪个请求的对比数据 | | -si, --subscription-identifier | 订阅标识符 | | -ct, --content-type | 对发布信息内容的描述 | | -Wt, --will-topic | 遗嘱消息的 Topic | | -Wm, --will-message | 遗嘱消息的 Payload | | -Wq, --will-qos <0/1/2> | 遗嘱消息的 QoS | | -Wr, --will-retain | 发送的遗嘱消息为保留消息，默认为 false | | -Wd, --will-delay-interval | 遗嘱消息延迟间隔，单位为秒 | | -Wpf, --will-payload-format-indicator | 遗嘱消息是否为UTF-8编码的字符数据 | | -We, --will-message-expiry-interval | 遗嘱信息的有效期，单位为秒 | | -Wct, --will-content-type | 遗嘱消息内容的描述 | | -Wrt, --will-response-topic | 响应信息的主题名称 | | -Wcd, --will-correlation-data | 响应信息的关联数据 | | -Wup, --will-user-properties | 遗嘱消息的自定义用户属性 | | -se, --session-expiry-interval | 会话过期间隔，单位为秒 | | --rcv-max, --receive-maximum | 接收消息的最大值 | | --maximum-packet-size | 客户端愿意接受的最大数据包大小 | | --topic-alias-maximum | 主题别名的最大值 | | --req-response-info | 客户端要求服务器提供的响应信息 | | --no-req-problem-info | 客户端向服务器请求问题信息 | | -Cup, --conn-user-properties | MQTT 5.0 的连接用户属性（例如，-Cup "name: mqttx cli"） | | --save \[PATH\] | 将参数保存到本地配置文件中，文件支持 json 和 yaml 格式，默认路径为 ./mqttx-cli-config.json | | --config \[PATH\] | 从本地配置文件加载参数，文件支持 json 和 yaml 格式，默认路径为 ./mqttx-cli-config.json | | --help | 展示 pub 命令的帮助信息 | | -Pp, --protobuf-path | 定义 Protocol Buffers（protobuf）消息格式的 .proto 文件路径 | | -Pmn, --protobuf-message-name | Protobuf 消息类型的名称（必须存在于 .proto 文件中） | ### 性能测试 性能测试命令与普通命令参数基本相同，以下仅列出新增或有变化的参数。 #### 连接性能测试 ```shell mqttx bench conn --help ``` | 参数 | 描述 | | ----------------------------- | -------------------------------- | | -c, --count | 连接数量，默认为 1000 | | -i, --interval | 创建连接的间隔时间，默认为 10ms | | -I, --client-id | 客户端 ID，支持 %i (索引) 占位符 | #### 订阅性能测试 ```shell mqttx bench sub --help ``` | 参数 | 描述 | | ----------------------------- | -------------------------------------------------------------------- | | -c, --count | 连接数量，默认为 1000 | | -i, --interval | 创建连接的间隔时间，单位为毫秒，默认为 10ms | | -I, --client-id | 客户端 ID，支持 %i (索引) 占位符 | | -t, --topic | 需要订阅的 Topic, 支持 %u (用户名), %c (客户端 ID), %i (索引) 占位符 | | -v, --verbose | 打印接收到的历史消息数量与消息速率 | #### 发布性能测试 ```shell mqttx bench pub --help ``` | 参数 | 描述 | | -------------------------------------- | -------------------------------------------------------------------- | | -c, --count | 连接数量，默认为 1000 | | -i, --interval | 创建连接的间隔时间，单位为毫秒，默认为 10ms | | -im, --message-interval | 发布消息的间隔时间，单位为毫秒，默认为 1000ms | | -I, --client-id | 客户端 ID，支持 %i (索引) 占位符 | | -t, --topic | 需要订阅的 Topic, 支持 %u (用户名), %c (客户端 ID), %i (索引) 占位符 | | -v, --verbose | 打印发送出的历史消息数量与消息速率 | | ~~-s, --stdin~~ | ~~从 stdin 中读取信息体~~ | | ~~-M, --multiline~~ | ~~可以通过多行发布多条消息~~ | ### 模拟器 用于模拟特定场景下 MQTT 发布消息操作。 模拟器命令与[发布性能测试](#发布性能测试)参数基本相同，以下仅列出新增或有变化的参数。 ```shell mqttx simulate --help ``` | 参数 | 描述 | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | -sc, --scenario | 模拟内置场景的名称 | | -f, --file | 本地自定义场景脚本的文件路径 | | -t, --topic | 需要发布的消息主题, 可选, 支持 %u (用户名), %c (客户端 ID), %i (索引) 占位符, %sc (场景) 占位符, 默认为 `mqttx/simulate/%sc/%c` | `--scenario` 与 `--file` 参数必须指定一个，如果同时指定，优先使用 `--file` 参数。 自定义物联网数据模拟脚本示例： ```js /** * 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 仓库中的[脚本示例](https://github.com/emqx/MQTTX/tree/main/scripts-example/IoT-data-scenarios)，或查看如何使用 [faker.js](https://fakerjs.dev/) 来生成各种类型的随机数据。 ### 列表 `list` 命令提供了可用资源的概览。 > 目前，该命令仅支持列出内置的场景。 ```shell mqttx list --help ``` | 参数 | 描述 | | ---------------- | -------------- | | -sc, --scenarios | 列出内置的场景 | #### 内置场景 可以使用 `--scenarios` 选项来显示内置场景的列表。 ```shell mqttx list --scenarios ``` 这个命令会输出一个表格，显示每个内置场景的名称和描述。如果想在模拟命令中使用其中一个，只需在 `--scenario` 选项中指定场景名称： ```shell mqttx simulate --scenario ``` 未来，`list` 命令将添加更多选项和功能。敬请期待！ ## 与 EMQX 更好的合作 MQTTX 为连接测试 EMQX 等 MQTT 消息服务器而生，一键式的连接方式和简洁的图形界面可以帮助您快速连接到 EMQX 或 EMQX Cloud 调试并探索其功能特性。 [注册 EMQX Cloud 可以享受 14 天免费试用](https://www.emqx.com/zh/try?product=cloud) [现在就本地下载并安装 EMQX](https://www.emqx.com/zh/try?product=enterprise) ## 社区 - 访问 [EMQ 问答社区](https://askemq.com/) 以获取帮助，也可以分享您的想法或项目。 - 添加小助手微信号 `emqmkt`，加入 EMQ 微信技术交流群。 - 加入我们的 [Discord](https://discord.gg/xYGf3fQnES)，参于实时讨论。 - 关注我们的 [bilibili](https://space.bilibili.com/522222081)，获取最新物联网技术分享。 - 关注我们的 [微博](https://weibo.com/emqtt) 或 [Twitter](https://twitter.com/EMQTech)，获取 EMQ 最新资讯。 ## 开发 Node 环境的推荐版本: - v18.\*.\* ```shell # 克隆项目 git clone git@github.com:emqx/MQTTX.git # 安装依赖 cd MQTTX/cli yarn install # 编译和热重载以进行开发 yarn run dev # 编译和压缩以构建生产版本 yarn run build ``` 构建成功后，会在 `dist` 目录里出现构建成功的相应的文件，需要在 Node.js 环境中使用。 如果需要打包一个二进制可执行文件，请参考以下命令： ```shell # 全局安装 pkg npm install pkg -g # 构建二进制可执行文件 pkg package.json ``` 构建成功后，在 `release` 目录里可以看到对应各系统的二进制可执行文件了。 ## 贡献 请确保在发出 PR 请求前， 已经仔细阅读过了[贡献指南](https://github.com/emqx/MQTTX/blob/main/.github/CONTRIBUTING_CN.md) ## 技术栈 - [TypeScript](https://www.typescriptlang.org/) - [Node.js](https://nodejs.org/en/) - [pkg](https://github.com/vercel/pkg) - [MQTT.js](https://github.com/mqttjs/MQTT.js) ## License Apache License 2.0, see [LICENSE](https://github.com/emqx/MQTTX/blob/main/LICENSE). --- ## File: docs/desktop/zh/advanced/advanced-setting.md # 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 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 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 # 快速开始 本页面指导您快速开始使用 MQTTX 桌面版连接 MQTT 代理服务器并体验基本的发布和订阅操作。 ## 准备 MQTT 服务器 在开始之前，您需要准备一个 MQTT 服务器。您可以选择以下任一 MQTT 服务器或在线 MQTT 服务。 ### 公共 MQTT 服务器 为了快速测试，您可以使用免费的在线[公共 MQTT 代理](https://www.emqx.com/zh/mqtt/public-mqtt5-broker)而无需进行本地部署。这是 EMQX 的在线公共版本。 ```shell Broker address: broker.emqx.io Broker TCP port: 1883 Broker SSL port: 8883 ``` ### 全托管云原生 MQTT 消息服务 EMQX 提供全托管的云原生 MQTT 消息服务，能够通过可靠、实时的物联网数据传输、处理和集成，连接大量的物联网设备。您可以在几分钟内创建一个 MQTT 服务。 [14 天免费试用](https://www.emqx.com/zh/try?product=cloud) ### 自行部署 MQTT 服务器 如果您想在本地运行 MQTT 服务器，我们建议使用 [EMQX](https://www.emqx.com/zh/products/emqx)。这是一款云原生分布式物联网 MQTT 消息服务器，能帮助您实时可靠地连接、转移和处理业务数据。 开始并运行 EMQX 的最简单方法是使用 Docker。您可以按照以下步骤下载和安装。 1. 下载并启动最新版本的 EMQX，请在执行以下命令之前确保已安装并运行 [Docker](https://www.docker.com/)。 ```bash 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](https://docs.emqx.com/zh/enterprise/v5.1/dashboard/introduction.html)，您可以在此连接客户端或查看运行状态。 默认用户名和密码：`admin` 和 `public` 您还可以通过 [下载软件包](https://www.emqx.com/zh/try?product=enterprise) 安装 EMQX。 ## 连接到 MQTT 服务器 本节演示了如何使用 MQTTX 桌面版通过最简单的设置连接到公共的 MQTT 服务器。想要了解其他高级设置，参阅[使用通用设置建立客户端连接]()，[使用高级设置建立客户端连接]() 和 [MQTT 5.0 功能设置]()。 1. 启动您的 MQTT 服务器和 MQTTX 桌面端。您可以通过以下3种方式之一在 MQTTX 中创建新的客户端连接： - 在左侧导航菜单中点击 **+** 图标。 - 在主面板上点击 **+ 新建连接** 按钮。 - 在**连接**面板上点击 **+** -> **新建连接**。 2. 在**基础**区域输入 MQTT 服务器的连接信息。要尝试快速连接，您只需为新建的连接输入名称，例如 `emqx_test`，并将其他连接选项保留为默认设置。 - 如果您使用的是自行部署的 MQTT 服务器，您可以将服务器地址替换为实际的 IP 地址，例如 `127.0.0.1`。 ::: tip 关于**基础**部分中的选项的详细信息，请查看[使用基础设置创建连接](../use-desktop/connect.md)。 ::: 3. 点击右上角的**连接**。至此，您已经建立了一个名为 `emqx_test` 的 MQTT 客户端连接。 ## 订阅与发布 本节演示了如何使用 MQTTX 桌面版发布和订阅 MQTT 消息。 1. 点击主面板中的 **+ 添加订阅**。在弹出窗口中， 在 **Topic** 文本框中输入 `test`，并保留其他选项为默认设置。点击**确定**。客户端连接现在订阅了 `test` 主题。 ::: tip 作为简单的演示，不建议使用默认主题 `testtopic/#`，否则如果您连接到公共 MQTT 代理服务器，您会不断收到消息。 ::: 2. 按照[连接到 MQTT 代理服务器](#connect-to-mqtt-broker)中的步骤，创建一个新的 MQTT 客户端连接，名称为 `Publisher`。 3. 在**连接**面板中，确保选择了客户端连接 `Publisher`。在右下角的发布区域中，输入 `test` 作为主题，并保留消息 payload 和其他选项为默认设置。 点击发送按钮，连接 `emqx_test` 上出现一个数字，表示收到了一条新消息。 4. 在**连接**面板中选择 `emqx_test` 连接。 您可以查看 `Publisher` 发送的消息。 --- ## File: docs/desktop/zh/use-desktop/connect.md # 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 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 If your broker has enabled user user authentication, you need to enter the information in the **Username** and **Password** fields. ## SSL/TLS 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 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 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 # Publish and Subscribe ## Main Interface 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 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 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 # Installation You can download and install MQTTX from several sources: 1. [MQTTX Official Website Download Page](https://mqttx.app/downloads) provides direct access to download and installation. 2. [EMQ Official Website Download Page](https://www.emqx.com/en/try?product=MQTTX) also hosts MQTTX for download and installation. 3. Alternatively, you can select your preferred version from the [GitHub Releases](https://github.com/emqx/MQTTX/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](https://www.emqx.com/en/downloads/MQTTX) 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 > 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. [](https://apps.apple.com/us/app/mqttx/id1514074565?mt=12) 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](https://formulae.brew.sh/cask/mqttx): ```shell brew install --cask mqttx ``` ## Windows > 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 > 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: [](https://flathub.org/apps/details/com.emqx.MQTTX) Alternatively, use the `flatpak` command to quickly install and start MQTTX: Install: ```shell flatpak install flathub com.emqx.MQTTX ``` Run: ```shell 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 > 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: ```shell sudo snap install mqttx ``` For manual installation, download the latest version of the `snap` file. Here's an example: ```shell 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](https://github.com/emqx/MQTTX/issues/109) --- ## File: docs/desktop/zh/introduction.md # Introduction [MQTTX](https://mqttx.app) is an open-source, cross-platform MQTT 5.0 desktop client initially developed by [EMQ](https://www.emqx.com/), which can run on macOS, Linux, and Windows. The user interface (UI) of [MQTTX](https://mqttx.app) 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](https://mqttx.app) or [GitHub](https://github.com/emqx/MQTTX) 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](https://mqttx.app), and build and use it on your own terms. During usage, if you encounter any issues, please navigate to [GitHub issues](https://github.com/emqx/MQTTX/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 ## Main Features - 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](https://www.emqx.com/en/blog/connect-to-mqtt-broker-with-websocket) - 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 # 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 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 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.