开始使用
在安装完成后，即可在终端直接运行 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 -lm
# 发布指定大小的随机载荷
mqttx pub -t 'hello' -h 'broker.emqx.io' -p 1883 --payload-size 1KB
性能测试
# 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
对于每个命令，您都可以使用 --help 选项来获取更多信息。
对于运行中的命令（如 conn、sub），只需输入 Ctrl+C 即可断开连接并退出。
参数介绍
mqttx --help
| 参数 | 描述 |
|---|---|
| -v, --version | 输出当前 MQTTX CLI 的版本号 |
| -h, --help | 展示 mqttx 命令的帮助信息 |
| 命令 | 描述 |
|---|---|
| check | 检查更新 |
| init | 初始化配置文件 |
| conn | 创建一个连接并连接到 MQTT Broker |
| pub | 向主题发布一条消息 |
| sub | 订阅一个或多个主题 |
| bench | MQTT 性能测试 |
| simulate | MQTT 模拟器 |
连接
mqttx conn --help
| 参数 | 描述 |
|---|---|
| -V, --mqtt-version <5.0/3.1.1/3.1> | MQTT 版本，默认为 5.0 |
| -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 的密码 |
| -am, --authentication-method <METHOD> | 认证方法，支持 SCRAM-SHA-1、SCRAM-SHA-256、SCRAM-SHA-512 |
| -l, --protocol <PROTO> | 连接时的协议，支持 mqtt、mqtts、ws、wss，默认为 mqtt |
| --path <PATH> | websocket 的路径，默认为 /mqtt |
| -wh, --ws-headers <WSHEADERS...> | WebSocket 选项的 headers（仅适用于 MQTT over WebSocket 连接，例如 -wh "Authorization: Bearer token"） |
| --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 | 客户端向服务器请求问题信息 |
| -so, --save-options [PATH] | 将参数保存到本地配置文件中，文件支持 json 和 yaml 格式，默认路径为 ./mqttx-cli-options.json |
| -lo, --load-options [PATH] | 从本地配置文件加载参数，文件支持 json 和 yaml 格式，默认路径为 ./mqttx-cli-options.json |
| --debug | 启用 MQTT.js 的调试模式 (默认值: false) |
| --help | 展示 conn 命令的帮助信息 |
订阅
mqttx sub --help
| 参数 | 描述 |
|---|---|
| -V, --mqtt-version <5.0/3.1.1/3.1> | MQTT 版本，默认为 5.0 |
| -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 的密码 |
| -am, --authentication-method <METHOD> | 认证方法，支持 SCRAM-SHA-1、SCRAM-SHA-256、SCRAM-SHA-512 |
| -l, --protocol <PROTO> | 连接时的协议，支持 mqtt、mqtts、ws、wss，默认为 mqtt |
| --path <PATH> | websocket 的路径，默认为 /mqtt |
| -wh, --ws-headers <WSHEADERS...> | WebSocket 选项的 headers（仅适用于 MQTT over WebSocket 连接，例如 -wh "Authorization: Bearer token"） |
| -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、binary、cbor 和 msgpack |
| -v, --verbose | 打开详细模式以显示接收到的 MQTT 数据包 |
| --output-mode <default/clean> | 选择默认或简洁模式，简洁模式会输出完整的数据包，允许用户使用 jq 这类工具自由管理输出 |
| --file-save <PATH> | 将接收到的消息保存为文件 |
| --file-write <PATH> | 将接收到的消息持续写入指定文件 |
| --delimiter [CHARACTER] | 在每条消息的末尾添加一个分隔符，默认为 "\n" |
| -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"） |
| -so, --save-options [PATH] | 将参数保存到本地配置文件中，文件支持 json 和 yaml 格式，默认路径为 ./mqttx-cli-options.json |
| -lo, --load-options [PATH] | 从本地配置文件加载参数，文件支持 json 和 yaml 格式，默认路径为 ./mqttx-cli-options.json |
| --help | 展示 sub 命令的帮助信息 |
| -Pp, --protobuf-path <PATH> | 定义 Protocol Buffers（protobuf）消息格式的 .proto 文件路径 |
| -Pmn, --protobuf-message-name <NAME> | Protobuf 消息类型的名称（必须存在于 .proto 文件中） |
| -Ap, --avsc-path <PATH> | 定义 AVRO 解码模式的 .avsc 文件路径 |
| --debug | 启用 MQTT.js 的调试模式 (默认值: false) |
注意： 如果你订阅的主题带有
$前缀，例如共享订阅如$share/test/test，你需要在"$share/test/test"周围添加引号。在 shell 中，$share会被识别为一个变量，导致订阅失败。
发布
mqttx pub --help
| 参数 | 描述 |
|---|---|
| -V, --mqtt-version <5.0/3.1.1/3.1> | MQTT 版本，默认为 5.0 |
| -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 消息 |
| -S, --payload-size <SIZE> | 生成指定大小的随机载荷（如 1KB、512B、2MB）；如果存在 -m、-s、-M 或 --file-read 参数则忽略此选项 |
| -r, --retain | 设置发送消息为 Retain 消息，默认为 false |
| -s, --stdin | 从 stdin 中读取信息体 |
| -M, --multiline | 可以通过多行发布多条消息 |
| -lm, --line-mode | 进入交互模式按行发送消息（等同于 -s -M） |
| --file-read <PATH> | 从文件中读取信息 |
| -u, --username <USER> | 连接到 MQTT Broker 的用户名 |
| -P, --password <PASS> | 连接到 MQTT Broker 的密码 |
| -am, --authentication-method <METHOD> | 认证方法，支持 SCRAM-SHA-1、SCRAM-SHA-256、SCRAM-SHA-512 |
| -f, --format <TYPE> | 输入消息的格式类型，支持 base64、json、hex、binary、cbor 和 msgpack |
| -l, --protocol <PROTO> | 连接时的协议，支持 mqtt、mqtts、ws、wss，默认为 mqtt |
| --path <PATH> | websocket 的路径，默认为 /mqtt |
| -wh, --ws-headers <WSHEADERS...> | WebSocket 选项的 headers（仅适用于 MQTT over WebSocket 连接，例如 -wh "Authorization: Bearer token"） |
| --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"） |
| -so, --save-options [PATH] | 将参数保存到本地配置文件中，文件支持 json 和 yaml 格式，默认路径为 ./mqttx-cli-options.json |
| -lo, --load-options [PATH] | 从本地配置文件加载参数，文件支持 json 和 yaml 格式，默认路径为 ./mqttx-cli-options.json |
| --help | 展示 pub 命令的帮助信息 |
| -Pp, --protobuf-path <PATH> | 定义 Protocol Buffers（protobufv消息格式的 .proto 文件路径 |
| -Pmn, --protobuf-message-name <NAME> | Protobuf 消息类型的名称（必须存在于 .proto 文件中） |
| -Ap, --avsc-path <PATH> | 定义 AVRO 编码模式的 .avsc 文件路径 |
| --debug | 启用 MQTT.js 的调试模式 (默认值: false) |
配置文件
配置文件存储各种设置的默认值，为 MQTTX CLI 提供简化和可定制的体验，初始化创建后将会存放在用户的主目录下，路径为 $HOME/.mqttx-cli/config。
功能
default:
- output
- text: 默认模式，提供简洁的关键信息输出。
- log: 显示带有日期和时间戳的详细日志输出。
mqtt:
- protocol: 默认是
mqtt， 支持的选项包括mqtt,mqtts,ws,wss。 - host: 默认是
localhost。 - port: 默认是
1883。 - max_reconnect_times: 默认是
10。 - username: 默认是空。
- password: 默认是空。
default 部分的 output 设置控制 CLI 的输出显示。用户可以根据需求选择不同的模式。如果希望集成到某些日志脚本中，推荐使用 log 模式。
在 mqtt 部分，如果命令行中没有提供这些参数，将使用配置文件中的配置项。
max_reconnect_times 控制重连次数，达到设定次数后自动关闭连接，避免无限重连。注意：这是一个 MQTTX 的配置，不属于 MQTT 协议中的配置。
如果配置项如 username 和 password 不需要配置，可以将其从配置文件中省略。
初始化配置
配置文件默认不提供，需要手动创建或更新配置文件，请运行 init 命令。这将提示你输入所需的配置信息：
mqttx init
? Select MQTTX CLI output mode Text
? Select the default MQTT protocol MQTT
? Enter the default MQTT broker host broker.emqx.io
? Enter the default MQTT port 1883
? Enter the maximum reconnect times for MQTT connection 5
? Enter the default username for MQTT connection authentication admin
? Enter the default password for MQTT connection authentication ******
Configuration file created/updated at /Users/.mqttx-cli/config
配置文件示例
[default]
output = text
[mqtt]
host = broker.emqx.io
port = 1883
protocol = mqtt
max_reconnect_times = 5
username = admin
password = public
CLI 输出示例
- log
mqttx conn [5/24/2024] [11:26:17 AM] › … Connecting... [5/24/2024] [11:26:17 AM] › ✔ Connected - text
mqttx conn ✔ Connected
性能测试
性能测试命令与普通命令参数基本相同，以下仅列出新增或有变化的参数。
连接性能测试
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 (索引) 占位符 |
| -S, --payload-size <SIZE> | 生成指定大小的随机载荷（如 1KB、512B、2MB） |
| -v, --verbose | 打印发送出的历史消息数量与消息速率 |
| --file-read <PATH> | 从文件中读取消息体 |
| --split [CHARACTER] | 通过指定的字符将单个文件中的输入消息进行分割，默认为 "\n" |
典型压测场景
连接量测试
以每 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 参数。
自定义脚本
示例：
注意：模拟文件需要使用 CommonJS 规范。
/**
* 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 | 模拟生成天气站数据 |
如果未指定发布主题，内置场景默认使用以下主题格式：
mqttx/simulate/%sc/%c
其中 %sc 会替换为场景名称，%c 会替换为客户端 ID。例如，当运行 tesla 场景时，消息会发布到类似 mqttx/simulate/tesla/<客户端ID> 的主题。
要接收特定场景的所有消息，可以使用通配符订阅：
# 订阅 tesla 场景的所有消息
mqttx sub -t 'mqttx/simulate/tesla/#'
# 订阅所有场景的所有消息
mqttx sub -t 'mqttx/simulate/#'
列表
list 命令提供了可用资源的概览。
目前，该命令仅支持列出内置的场景。
mqttx list --help
| 参数 | 描述 |
|---|---|
| -sc, --scenarios | 列出内置的场景 |
配置选项管理
Note: 请注意，该功能是原来的「配置」功能，从 v1.10.0 版本后，更名为「配置选项管理」，之前的
-–config和-–save命令更新为了-–load-options和-–save-options。
MQTTX CLI 支持导入和导出配置选项，使用户可以将命令参数保存到本地选项文件以供将来使用。选项文件支持 json 和 yaml 格式，默认路径为 ./mqttx-cli-options.json。
连接（conn）、发布（pub）、订阅（sub）、基准测试（benchmark）和模拟（simulate）命令的参数都支持保存和导入。以下是导出和导入 conn 命令选项的示例：
导出选项
# 保存到默认路径
mqttx conn --save-options
# 保存到指定路径
mqttx conn --save-options ../custom/mqttx-cli-options.json
# 保存到指定路径并指定格式为 yaml
mqttx conn --save-options ../custom/mqttx-cli-options.yaml
导入选项
# 从默认路径导入选项
mqttx conn --load-options
# 从指定路径导入选项
mqttx conn --load-options ../custom/mqttx-cli-options.json
# 从指定路径导入选项并指定格式为 yaml
mqttx conn --load-options ../custom/mqttx-cli-options.yaml
消息大小
MQTTX CLI 支持消息大小显示和生成功能，方便进行消息大小测试和监控。
消息大小显示
订阅命令会自动显示接收消息的大小：
mqttx sub -t topic
# 输出示例：
# topic: test, qos: 0, size: 10B
# Hello World
消息大小生成
使用 --payload-size 参数可以生成指定大小的随机载荷：
# 生成 1KB 的随机载荷
mqttx pub -t test --payload-size 1KB
# 支持的格式：B（字节）、KB、MB、GB
mqttx pub -t test --payload-size 512B
mqttx pub -t test --payload-size 2.5MB
# 性能测试中使用指定大小载荷
mqttx bench pub -c 100 -t test --payload-size 1KB
注意： 如果同时指定了
-m、-s、-M或--file-read参数，则会忽略--payload-size参数。生成的载荷大小不能超过 MQTT 协议规定的最大值（256MB），同时建议检查 MQTT Broker 的配置以确认支持的最大消息大小。
数据管道
MQTTX CLI 提供了灵活的数据管道处理能力，支持多种数据处理方式。可以简单快速地处理接收和发布的 MQTT 数据，而无需编写复杂的代码。
数据的接收与处理
使用 clean 模式配合 jq 工具，可以简单快速地处理 MQTT 数据，例如，要订阅并提取 MQTT 数据包的 payload 或重组数据：
- 提取消息的 payload 内容：
mqttx sub -t topic --output-mode clean | jq '.payload'
- 提取消息的完整信息（主题、payload、保留标志和用户属性）：
mqttx sub -t topic --output-mode clean | jq '{
topic,
payload,
retain: .packet.retain,
userProperties: .packet.properties.userProperties
}'
这个两个简单的示例展示了如何使用 MQTTX CLI 和 jq 工具的功能，来自定义构建，采集和高效的处理 IoT 数据。
数据的获取与发布
MQTTX CLI 可通过 --stdin (简写为 -s) 参数接收管道输入数据，支持从多种输入源获取数据并发布到 MQTT 服务器。这种灵活的数据输入方式使得发布操作更加便捷，例如：
- 使用
echo快速发布数据
echo "hello world" | mqttx pub -t "test" -s
- 使用
cat命令从文件获取数据并发布
cat message.txt | mqttx pub -t "test" -s
- 使用重定向读取文件数据
mqttx pub -t "test" -s < message.txt
- 交互式多行输入模式
mqttx pub -t "topic" -s -M
hello # 输入将立即发送
world # 每行输入都会作为独立消息
<Ctrl+C> # 按 Ctrl+C 结束输入
注意：
-s -M组合与--line-mode效果相同，后者是更简洁的写法。
通过管道发布数据时，你可以选择不同的处理模式：
- 准备测试数据
echo -e "line1\nline2\nline3" > message.txt
- 整体发布模式，将所有内容作为一条消息发送：
cat message.txt | mqttx pub -t "test" -s
# 发送一条完整消息：
# line1
# line2
# line3
- 逐行发布模式，使用 -M 参数将每行作为独立消息发送：
cat message.txt | mqttx pub -t "test" -s -M
# 发送多条独立消息：
# 消息1: line1
# 消息2: line2
# 消息3: line3
使用管道获取数据并发布的方式简单直观，特别适合快速的数据发布场景。如果需要更复杂的数据分割和处理能力，可以考虑使用文件读写功能 --split 参数来实现更灵活的控制。
注意：不同操作系统下管道命令的语法可能不同，请根据您的操作系统选择合适的命令格式。
文件读写
MQTTX CLI 提供了文件读取和写入功能，可以无缝地通过 MQTT 处理消息有效载荷作为文件输入和输出，从而增强了数据工作流中集成和自动化的便利性。
文件读取
使用以下命令，你可以从文件读取消息：
mqttx pub -t topic --file-read path/to/file
Note: 请注意，由于 MQTT 协议的限制，发送的文件大小不能超过 256MB。在发送文件之前，请确保你已经检查了 MQTT Broker 的默认 payload size。
文件写入
要将接收到的消息写入文件，可以使用：
mqttx sub -t topic --file-write path/to/file
--file-write 选项会将每条消息追加到文件中，每条消息默认通过换行符 (\n) 进行分隔，非常适合用于日志记录或累积文本数据。如果你希望改变分隔符，可以使用 --delimiter 选项。例如，--delimiter ',' 将使每条消息以逗号进行分隔。
对于文件传输，以及将消息保存为单独的文件，可以使用：
mqttx sub -t topic --file-save path/to/file
现有的文件将自动重新编号并保存，以防止覆盖。
请勿同时使用 --file-write 和 --file-save。
文件格式
您可以指定发送或保存文件时使用的文件格式,如果没有指定，默认为纯文本（utf-8）格式。
mqttx pub -t topic --file-read path/to/file --format type
mqttx sub -t topic --file-save path/to/file --format type
目前，我们支持以下数据格式输出到文件：
- json
- base64
- hex
- binary
- cbor
- msgpack
注意：msgpack 和 cbor 是两种常见的二进制序列化格式，它们在数据压缩和传输效率上通常优于 JSON，特别是在处理大量数据或进行网络传输时，能够显著减少数据大小和传输时间。因此，当使用 msgpack 或 cbor 格式时，消息的输入输出格式都将使用 JSON 格式。
当用户传输了后缀名在以下格式中的文件，且没有指定 --format 参数时，会自动识别文件格式为 binary 。如果传输的文件不在以下格式中，且需要以二进制格式传输需要手动指定 --format binary 参数。
| 扩展名 | 文件格式 | 描述 |
|---|---|---|
.png, .jpg, .jpeg, .gif, .bmp, .ico, .tif, .tiff | 图像 | 图片和图形的常用图像文件格式 |
.mp4, .avi, .mov, .mkv, .flv, .wmv, .mpeg, .3gp | 视频 | 电影和视频剪辑的标准视频文件格式 |
.mp3, .wav, .flac, .aac, .ogg, .wma, .m4a, .m4p | 音频 | 音乐和声音录制的音频文件格式 |
.zip, .gz, .rar, .tar, .7z, .bz2, .xz, .jar | 压缩文件 | 用于归档和数据压缩的压缩文件格式 |
.bin, .exe, .dll, .so, .dmg, .iso, .img | 二进制文件 | 可执行文件、系统库和磁盘映像的二进制文件格式 |
.pdf, .epub | 文档 | 文档和电子书的二进制格式 |
.netp, .pcap, .pcapng, .cap | 网络数据 | 网络抓包和协议分析的数据格式 |
.dmp, .trace | 调试数据 | 内存转储和跟踪文件格式 |
.db, .sqlite, .mdb, .frm, .myd, .myi | 数据库 | 各类数据库文件和表结构格式 |
.dat, .raw, .log, .blob | 通用数据 | 通用二进制数据和日志文件格式 |
.hex, .rom, .fw | 系统数据 | 系统固件和 ROM 镜像格式 |
.pkt, .mpack | 消息数据 | 数据包和 MessagePack 格式 |
.parquet, .orc | 列式存储 | 大数据分析的列式存储格式 |
检查更新
使用 check 命令可以检查 MQTTX CLI 的最新版本。该命令会提示是否有新版本可用，并提供下载链接。
用法
运行以下命令以检查更新：
mqttx check
示例输出
如果有新版本可用，将显示如下消息：
A new version of MQTTX CLI is available: 1.9.8 → 1.9.10
https://github.com/emqx/MQTTX/releases/tag/v1.9.10
可以从 MQTTX 下载页面 或 GitHub 发布页面 手动下载最新版本。下载后，替换当前版本以保持更新。