开始使用
在安装完成后，即可在终端直接运行 mqttx 命令。
快速使用
连接
mqttx conn -h 'broker.emqx.io' -p 1883 -u 'admin' -P 'public'
订阅
mqttx sub -t 'hello' -h 'broker.emqx.io' -p 1883
发布
# 发布单个消息
mqttx pub -t 'hello' -h 'broker.emqx.io' -p 1883 -m '来自MQTTX CLI的消息'
# 发布多个消息（多行）
mqttx pub -t 'hello' -h 'broker.emqx.io' -p 1883 -s -M
性能测试
# 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
数据模拟器
# 指定一个本地内置的场景并开始模拟
mqttx simulate -sc tesla -c 10
# 指定一个场景文件并开始模拟
mqttx simulate -f <scenario file path> -c 10
# 列出内置模拟数据的场景
mqttx ls -sc
版本检查
mqttx check
参数介绍
mqttx --help
| 参数 | 描述 |
|---|---|
| -v, --version | 输出当前 MQTTX CLI 的版本号 |
| -h, --help | 展示 mqttx 命令的帮助信息 |
| 命令 | 描述 |
|---|---|
| check | 检查更新 |
| conn | 创建一个连接并连接到 MQTT Broker |
| pub | 向主题发布一条消息 |
| sub | 订阅一个或多个主题 |
| bench | MQTT 性能测试 |
| simulate | MQTT 模拟器 |
连接
mqttx conn --help
| 参数 | 描述 |
|---|---|
| -V, --mqtt-version <5/3.1.1/3.1> | MQTT 版本，默认为 5 |
| -h, --hostname <HOST> | MQTT Broker 的 Host 地址，默认为 localhost |
| -p, --port <PORT> | MQTT Broker 的端口号 |
| -i, --client-id <ID> | 客户端 ID |
| --no-clean | 取消 clean session 标志位，默认为 true |
| -k, --keepalive <SEC> | MQTT 的 Keep Alive，默认为 30 |
| -u, --username <USER> | 连接到 MQTT Broker 的用户名 |
| -P, --password <PASS> | 连接到 MQTT Broker 的密码 |
| -l, --protocol <PROTO> | 连接时的协议，支持 mqtt、mqtts、ws、wss，默认为 mqtt |
| --path <PATH> | websocket 的路径，默认为 /mqtt |
| --key <PATH> | key 文件的路径 |
| --cert <PATH> | cert 文件的路径 |
| --ca | ca 证书的文件路径 |
| --insecure | 取消服务器的证书校验 |
| --alpn <PROTO...> | 设置一个或多个 ALPN（应用层协议协商）协议 |
| -rp, --reconnect-period <MILLISECONDS> | 自动重连的间隔时间，通过设置为 0 来禁用自动重连，默认为 1000ms |
| --maximum-reconnect-times <NUMBER> | 最大重连次数，默认为 10 次 |
| -up, --user-properties <USERPROPERTIES...> | MQTT 5.0 用户属性，例如：-up "name: mqttx cli" |
| -Wt, --will-topic <TOPIC> | 遗嘱消息的 Topic |
| -Wm, --will-message <BODY> | 遗嘱消息的 Payload |
| -Wq, --will-qos <0/1/2> | 遗嘱消息的 QoS |
| -Wr, --will-retain | 发送的遗嘱消息为保留消息，默认为 false |
| -Wd, --will-delay-interval <SECONDS> | 遗嘱消息延迟间隔，单位为秒 |
| -Wpf, --will-payload-format-indicator | 遗嘱消息是否为 UTF-8 编码的字符数据 |
| -We, --will-message-expiry-interval <SECONDS> | 遗嘱信息的有效期，单位为秒 |
| -Wct, --will-content-type <CONTENTTYPE> | 遗嘱消息内容的描述 |
| -Wrt, --will-response-topic <TOPIC> | 响应信息的主题名称 |
| -Wcd, --will-correlation-data <DATA> | 响应信息的关联数据 |
| -Wup, --will-user-properties <USERPROPERTIES...> | 遗嘱消息的自定义用户属性 |
| -se, --session-expiry-interval <SECONDS> | 会话过期间隔，单位为秒 |
| --rcv-max, --receive-maximum <NUMBER> | 接收消息的最大值 |
| --maximum-packet-size <NUMBER> | 客户端愿意接受的最大数据包大小 |
| --topic-alias-maximum <NUMBER> | 主题别名的最大值 |
| --req-response-info | 客户端要求服务器提供的响应信息 |
| --no-req-problem-info | 客户端向服务器请求问题信息 |
| --save [PATH] | 将参数保存到本地配置文件中，文件支持 json 和 yaml 格式，默认路径为 ./mqttx-cli-config.json |
| --config [PATH] | 从本地配置文件加载参数，文件支持 json 和 yaml 格式，默认路径为 ./mqttx-cli-config.json |
| --debug | 启用 MQTT.js 的调试模式 (默认值: false) |
| --help | 展示 conn 命令的帮助信息 |
订阅
mqttx sub --help
| 参数 | 描述 |
|---|---|
| -V, --mqtt-version <5/3.1.1/3.1> | MQTT 版本，默认为 5 |
| -h, --hostname <HOST> | MQTT Broker 的 Host 地址，默认为 localhost |
| -p, --port <PORT> | MQTT Broker 的端口号 |
| -i, --client-id <ID> | 客户端 ID |
| -q, --qos <0/1/2> | 消息的 QoS，默认为 0 |
| --no-clean | 取消 clean session 标志位，默认为 true |
| -t, --topic <TOPIC> | 需要订阅的 Topic |
| -k, --keepalive <SEC> | MQTT 的 Keep Alive，默认为 30 |
| -u, --username <USER> | 连接到 MQTT Broker 的用户名 |
| -P, --password <PASS> | 连接到 MQTT Broker 的密码 |
| -l, --protocol <PROTO> | 连接时的协议，支持 mqtt、mqtts、ws、wss，默认为 mqtt |
| --path <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 <PATH> | key 文件的路径 |
| --cert <PATH> | cert 文件的路径 |
| --ca | ca 证书的文件路径 |
| --insecure | 取消服务器的证书校验 |
| --alpn <PROTO...> | 设置一个或多个 ALPN（应用层协议协商）协议 |
| -rp, --reconnect-period <MILLISECONDS> | 自动重连的间隔时间，通过设置为 0 来禁用自动重连，默认为 1000ms |
| --maximum-reconnect-times <NUMBER> | 最大重连次数，默认为 10 次 |
| -up, --user-properties <USERPROPERTIES...> | MQTT 5.0 用户属性，例如：-up "name: mqttx cli" |
| -f, --format <TYPE> | 格式化 Payload，支持 base64、json、hex 和 cbor |
| -v, --verbose | 打开详细模式以显示接收到的 MQTT 数据包 |
| --output-mode <default/clean> | 选择默认或简洁模式，简洁模式会输出完整的数据包，允许用户使用 jq 这类工具自由管理输出 |
| -Wt, --will-topic <TOPIC> | 遗嘱消息的 Topic |
| -Wm, --will-message <BODY> | 遗嘱消息的 Payload |
| -Wq, --will-qos <0/1/2> | 遗嘱消息的 QoS |
| -Wr, --will-retain | 发送的遗嘱消息为保留消息，默认为 false |
| -Wd, --will-delay-interval <SECONDS> | 遗嘱消息延迟间隔，单位为秒 |
| -Wpf, --will-payload-format-indicator | 遗嘱消息是否为 UTF-8 编码的字符数据 |
| -We, --will-message-expiry-interval <SECONDS> | 遗嘱信息的有效期，单位为秒 |
| -Wct, --will-content-type <CONTENTTYPE> | 遗嘱消息内容的描述 |
| -Wrt, --will-response-topic <TOPIC> | 响应信息的主题名称 |
| -Wcd, --will-correlation-data <DATA> | 响应信息的关联数据 |
| -Wup, --will-user-properties <USERPROPERTIES...> | 遗嘱消息的自定义用户属性 |
| -se, --session-expiry-interval <SECONDS> | 会话过期间隔，单位为秒 |
| -si, --subscription-identifier <NUMBER> | 订阅标识符 |
| --rcv-max, --receive-maximum <NUMBER> | 接收消息的最大值 |
| --maximum-packet-size <NUMBER> | 客户端愿意接受的最大数据包大小 |
| --topic-alias-maximum <NUMBER> | 主题别名的最大值 |
| --req-response-info | 客户端要求服务器提供的响应信息 |
| --no-req-problem-info | 客户端向服务器请求问题信息 |
| -Cup, --conn-user-properties <USERPROPERTIES...> | 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 <PATH> | 定义 Protocol Buffers（protobuf）消息格式的 .proto 文件路径 |
| -Pmn, --protobuf-message-name <NAME> | Protobuf 消息类型的名称（必须存在于 .proto 文件中） |
| --debug | 启用 MQTT.js 的调试模式 (默认值: false) |
注意： 如果你订阅的主题带有
$前缀，例如共享订阅如$share/test/test，你需要在"$share/test/test"周围添加引号。在 shell 中，$share会被识别为一个变量，导致订阅失败。
发布
mqttx pub --help
| 参数 | 描述 |
|---|---|
| -V, --mqtt-version <5/3.1.1/3.1> | MQTT 版本，默认为 5 |
| -h, --hostname <HOST> | MQTT Broker 的 Host 地址，默认为 localhost |
| -p, --port <PORT> | MQTT Broker 的端口号 |
| -i, --client-id <ID> | 客户端 ID |
| -q, --qos <0/1/2> | 消息的 QoS，默认为 0 |
| -t, --topic <TOPIC> | 需要发布的 Topic |
| -m, --message<MSG> | 需要发布的 Payload 消息 |
| -r, --retain | 设置发送消息为 Retain 消息，默认为 fasle |
| -s, --stdin | 从 stdin 中读取信息体 |
| -M, --multiline | 可以通过多行发布多条消息 |
| -u, --username <USER> | 连接到 MQTT Broker 的用户名 |
| -P, --password <PASS> | 连接到 MQTT Broker 的密码 |
| -f, --format <TYPE> | 输入消息的格式类型，支持 base64、json 和 hex 和 cbor |
| -l, --protocol <PROTO> | 连接时的协议，支持 mqtt、mqtts、ws、wss，默认为 mqtt |
| --path <PATH> | websocket 的路径，默认为 /mqtt |
| --key <PATH> | key 文件的路径 |
| --cert <PATH> | cert 文件的路径 |
| --ca | ca 证书的文件路径 |
| --insecure | 取消服务器的证书校验 |
| --alpn <PROTO...> | 设置一个或多个 ALPN（应用层协议协商）协议 |
| -rp, --reconnect-period <MILLISECONDS> | 自动重连的间隔时间，通过设置为 0 来禁用自动重连，默认为 1000ms |
| --maximum-reconnect-times <NUMBER> | 最大重连次数，默认为 10 次 |
| -up, --user-properties <USERPROPERTIES...> | MQTT 5.0 用户属性，例如：-up "name: mqttx cli" |
| -pf, --payload-format-indicator | 发布信息的有效载荷格式指标 |
| -e, --message-expiry-interval <NUMBER> | 发布信息的有效期，单位为秒 |
| -ta, --topic-alias <NUMBER> | 主题别名，识别主题的值，而不是使用主题名称 |
| -rt, --response-topic <TOPIC> | 作为响应信息的主题名称 |
| -cd, --correlation-data <DATA> | 请求信息的发送者在收到响应信息时用来识别是哪个请求的对比数据 |
| -si, --subscription-identifier <NUMBER> | 订阅标识符 |
| -ct, --content-type <TYPE> | 对发布信息内容的描述 |
| -Wt, --will-topic <TOPIC> | 遗嘱消息的 Topic |
| -Wm, --will-message <BODY> | 遗嘱消息的 Payload |
| -Wq, --will-qos <0/1/2> | 遗嘱消息的 QoS |
| -Wr, --will-retain | 发送的遗嘱消息为保留消息，默认为 false |
| -Wd, --will-delay-interval <SECONDS> | 遗嘱消息延迟间隔，单位为秒 |
| -Wpf, --will-payload-format-indicator | 遗嘱消息是否为 UTF-8 编码的字符数据 |
| -We, --will-message-expiry-interval <SECONDS> | 遗嘱信息的有效期，单位为秒 |
| -Wct, --will-content-type <CONTENTTYPE> | 遗嘱消息内容的描述 |
| -Wrt, --will-response-topic <TOPIC> | 响应信息的主题名称 |
| -Wcd, --will-correlation-data <DATA> | 响应信息的关联数据 |
| -Wup, --will-user-properties <USERPROPERTIES...> | 遗嘱消息的自定义用户属性 |
| -se, --session-expiry-interval <SECONDS> | 会话过期间隔，单位为秒 |
| --rcv-max, --receive-maximum <NUMBER> | 接收消息的最大值 |
| --maximum-packet-size <NUMBER> | 客户端愿意接受的最大数据包大小 |
| --topic-alias-maximum <NUMBER> | 主题别名的最大值 |
| --req-response-info | 客户端要求服务器提供的响应信息 |
| --no-req-problem-info | 客户端向服务器请求问题信息 |
| -Cup, --conn-user-properties <USERPROPERTIES...> | 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 <PATH> | 定义 Protocol Buffers（protobufv消息格式的 .proto 文件路径 |
| -Pmn, --protobuf-message-name <NAME> | Protobuf 消息类型的名称（必须存在于 .proto 文件中） |
| --debug | 启用 MQTT.js 的调试模式 (默认值: false) |
性能测试
性能测试命令与普通命令参数基本相同，以下仅列出新增或有变化的参数。
连接性能测试
mqttx bench conn --help
| 参数 | 描述 |
|---|---|
| -c, --count <NUMBER> | 连接数量，默认为 1000 |
| -i, --interval <MILLISECONDS> | 创建连接的间隔时间，默认为 10ms |
| -I, --client-id <ID> | 客户端 ID，支持 %i (索引) 占位符 |
订阅性能测试
mqttx bench sub --help
| 参数 | 描述 |
|---|---|
| -c, --count <NUMBER> | 连接数量，默认为 1000 |
| -i, --interval <MILLISECONDS> | 创建连接的间隔时间，单位为毫秒，默认为 10ms |
| -I, --client-id <ID> | 客户端 ID，支持 %i (索引) 占位符 |
| -t, --topic <TOPIC...> | 需要订阅的 Topic, 支持 %u (用户名), %c (客户端 ID), %i (索引) 占位符 |
| -v, --verbose | 打印接收到的历史消息数量与消息速率 |
发布性能测试
mqttx bench pub --help
| 参数 | 描述 |
|---|---|
| -c, --count <NUMBER> | 连接数量，默认为 1000 |
| -i, --interval <MILLISECONDS> | 创建连接的间隔时间，单位为毫秒，默认为 10ms |
| -im, --message-interval <MILLISECONDS> | 发布消息的间隔时间，单位为毫秒，默认为 1000ms |
| -L, --limit <NUMBER> | 发布的消息数量，0 表示无限制，默认为 0 |
| -I, --client-id <ID> | 客户端 ID，支持 %i (索引) 占位符 |
| -t, --topic <TOPIC...> | 需要订阅的 Topic, 支持 %u (用户名), %c (客户端 ID), %i (索引) 占位符 |
| -v, --verbose | 打印发送出的历史消息数量与消息速率 |
典型压测场景
连接量测试
以每 10ms 创建一个连接的速率，创建 10000 个连接，客户端 ID 为 mqttx-bench-%i：
mqttx bench conn -c 10000 -i 10 -I "mqttx-bench-%i"
如果您使用的是 EMQX，在所有连接建立完成后，可以通过 dashboard 或执行 ./bin/emqx_ctl listeners 查看 EMQX 中连接数的信息：
tcp:default
listen_on : :1883
acceptors : 16
proxy_protocol : false
running : true
current_conn : 10000
max_conns : 1024000
吞吐测试
启动 500 个订阅客户端，订阅主题 mqttx/bench/t：
mqttx bench sub -c 500 -t mqttx/bench/t
然后启动 20 个发布客户端，向主题 mqttx/bench/t 发布消息，消息速率为每秒 10 条，消息内容为 mqttx bench test：
mqttx bench pub -c 20 -im 100 -t mqttx/bench/t -m "mqttx bench test"
回到订阅客户端，可以看到接收消息总数和实时消息速率，类似于：
Received total: 10989500, rate: 100000/s
模拟器
用于模拟特定场景下 MQTT 发布消息操作。
模拟器命令与发布性能测试参数基本相同，以下仅列出新增或有变化的参数
mqttx simulate --help
| 参数 | 描述 |
|---|---|
| -sc, --scenario <SCENARIO> | 模拟内置场景的名称 |
| -f, --file <SCENARIO FILE PATH> | 本地自定义场景脚本的文件路径 |
| -t, --topic <TOPIC...> | 需要发布的消息主题, 可选, 支持 %u (用户名), %c (客户端 ID), %i (索引) 占位符, %sc (场景) 占位符, 默认为 mqttx/simulate/%sc/%c |
--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, // 生成器函数
}
假设我们将上述 JavaScript 代码保存为 tempAndHum.js 文件，然后我们可以使用以下命令来模拟生成 10 条 MQTT 消息：
mqttx simulate --file ./tempAndHum.js -c 10
对于更多示例和详细的编辑指南，请参考 MQTTX GitHub 仓库中的脚本示例，或查看如何使用 faker.js 来生成各种类型的随机数据。
注意： 自 v1.9.10 起，所有模拟脚本已更新为使用 faker.js 的 v8 或更高版本。如果您的脚本仍然基于 faker.js 的旧版本，为确保兼容性和正常使用，请参照 faker.js 官方的升级指南 更新您的代码。
内置场景
MQTTX CLI 内置了一些常用的场景，可以通过 --scenario 参数指定，例如：
mqttx simulate --scenario tesla
可以使用 ls 命令列出所有的内置场景：
mqttx ls --scenarios
这个命令会输出一个表格，显示每个内置场景的名称和描述。如果你想在 simulate 命令中使用其中一个，只需在 --scenario 选项中指定场景名称：
mqttx simulate --scenario <场景名称>
内置场景列表：
| 场景名称 | 描述 |
|---|---|
| tesla | 模拟特斯拉车辆数据 |
| IEM | 模拟工业能源监控数据 |
| smart_home | 模拟生成智能家居数据 |
| weather | 模拟生成天气站数据 |
列表
list 命令提供了可用资源的概览。
目前，该命令仅支持列出内置的场景。
mqttx list --help
| 参数 | 描述 |
|---|---|
| -sc, --scenarios | 列出内置的场景 |
使用配置文件
MQTTX CLI 支持配置的导入与导出，用户能够将命令参数保存到本地配置文件中，以便于下次使用。
配置文件支持 json 和 yaml 格式，默认路径为 ./mqttx-cli-config.json。
这里以 conn 命令为例，演示如何导出、导入配置：
导出配置
# 保存到默认路径
mqttx conn --save
# 保存到指定路径
mqttx conn --save ../custom/mqttx-cli.json
# 保存到指定路径，并指定格式为 yaml
mqttx conn --save ../custom/mqttx-cli.yaml
导入配置
# 从默认路径导入配置
mqttx conn --config
# 从指定路径导入配置
mqttx conn --config ../custom/mqttx-cli.json
# 从指定路径导入格式为 yaml 的配置
mqttx conn --config ../custom/mqttx-cli.yaml
数据管道
MQTTX CLI 提供了一种简单的方式来管理和管道化 MQTT 数据，其 clean 模式与 jq 工具的配合使用，可以简单快速地处理 MQTT 数据，而无需编写复杂的代码。
例如，要订阅并提取 MQTT 数据包的 payload 或重组数据：
mqttx sub -t topic --output-mode clean | jq '.payload'
mqttx sub -t topic --output-mode clean | jq '{topic, payload, retain: .packet.retain, userProperties: .packet.properties.userProperties}'
这个示例清晰直观地展示了如何充分利用 MQTTX CLI、jq 以及其他工具的功能，来快速高效地构建，采集和处理 IoT 数据。