diff --git a/cli/README.md b/cli/README.md index 90c279311..b955fc891 100644 --- a/cli/README.md +++ b/cli/README.md @@ -3,13 +3,18 @@ # MQTTX CLI [![GitHub Release](https://img.shields.io/github/release/emqx/mqttx?color=brightgreen)](https://github.com/emqx/mqttx/releases) +![platforms](https://img.shields.io/badge/platforms-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey) ![build packages](https://github.com/emqx/MQTTX/workflows/build%20packages/badge.svg) -[![Total Downloads](https://img.shields.io/github/downloads/emqx/mqttx/total.svg)](https://github.com/emqx/mqttx/releases) -[![Docker](https://img.shields.io/docker/pulls/emqx/mqttx-cli)](https://hub.docker.com/r/emqx/mqttx-cli) -[![Slack](https://img.shields.io/badge/Slack-EMQX-39AE85?logo=slack)](https://slack-invite.emqx.io/) [![Discord](https://img.shields.io/discord/931086341838622751?label=Discord&logo=discord)](https://discord.gg/xYGf3fQnES) + +[![GitHub Downloads](https://img.shields.io/github/downloads/emqx/MQTTX/total?label=GitHub%20Downloads)](https://mqttx.app/downloads) +[![Docker Web Pulls](https://img.shields.io/docker/pulls/emqx/mqttx-web?label=Docker%20Web%20Pulls)](https://hub.docker.com/r/emqx/mqttx-web) +[![Docker CLI Pulls](https://img.shields.io/docker/pulls/emqx/mqttx-cli?label=Docker%20CLI%20Pulls)](https://hub.docker.com/r/emqx/mqttx-cli) + [![Community](https://img.shields.io/badge/Community-MQTTX-yellow?logo=github)](https://github.com/emqx/MQTTX/discussions) +[![Slack](https://img.shields.io/badge/Slack-EMQX-39AE85?logo=slack)](https://slack-invite.emqx.io/) +[![Discord](https://img.shields.io/discord/931086341838622751?label=Discord&logo=discord)](https://discord.gg/xYGf3fQnES) [![YouTube](https://img.shields.io/badge/Subscribe-EMQ-FF0000?logo=youtube)](https://www.youtube.com/channel/UC5FjR77ErAxvZENEWzQaO5Q) -[![Twitter](https://img.shields.io/badge/Follow-EMQ-1DA1F2?logo=twitter)](https://twitter.com/EMQTech) +[![Twitter Follows](https://img.shields.io/twitter/follow/EMQTech?label=Twitter%20Follows)](https://twitter.com/EMQTech) --- @@ -23,445 +28,35 @@ ## Documentation -For introduction, installation, and usage, see the [MQTTX CLI documentation](https://mqttx.app/docs/cli). Below is a quick start guide. +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 -### macOS - -To install the latest MQTTX CLI stable release on **macOS** using **binary download**. - -> **Note**: Please note CPU architecture of the current system environment - -#### Intel Chip - -```shell -curl -LO https://www.emqx.com/en/downloads/MQTTX/v1.9.8/mqttx-cli-macos-x64 -sudo install ./mqttx-cli-macos-x64 /usr/local/bin/mqttx -``` - -#### Apple Silicon - -```shell -curl -LO https://www.emqx.com/en/downloads/MQTTX/v1.9.8/mqttx-cli-macos-arm64 -sudo install ./mqttx-cli-macos-arm64 /usr/local/bin/mqttx -``` - -#### Homebrew - -```shell -brew install emqx/mqttx/mqttx-cli -``` - -### Linux - -To install the latest MQTTX CLI stable release on **Linux** using **binary download**. - -> **Note**: Please note CPU architecture of the current system environment - -#### x86-64 - -```shell -curl -LO https://www.emqx.com/en/downloads/MQTTX/v1.9.8/mqttx-cli-linux-x64 -sudo install ./mqttx-cli-linux-x64 /usr/local/bin/mqttx -``` - -#### ARM64 - -```shell -curl -LO https://www.emqx.com/en/downloads/MQTTX/v1.9.8/mqttx-cli-linux-arm64 -sudo install ./mqttx-cli-linux-arm64 /usr/local/bin/mqttx -``` - -### Windows - -Windows users should go to the MQTTX [release page](https://github.com/emqx/MQTTX/releases) and find the `exe` package for the corresponding system architecture, download it manually and execute. - -### NPM - -```shell -npm install mqttx-cli -g -``` - -### Docker - -```shell -docker pull emqx/mqttx-cli - -docker run -it --rm emqx/mqttx-cli -``` - -### Other platforms - -Download packaged binaries from the [MQTTX releases page](https://github.com/emqx/MQTTX/releases). - -## Usage - -After installing it, run `mqttx` on the terminal - -### Quickstart - -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 +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. -# Subscribe Benchmark -mqttx bench sub -c 5000 -t bench/%i +## Quickstart -# Publish Benchmark -mqttx bench pub -c 5000 -t bench/%i -``` - -Simulate - -```bash -# Specify a built-in 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 -``` - -### Help - -```shell -mqttx --help -``` - -| Options | Description | -| ------------- | ------------------------- | -| -v, --version | Output the version number | -| -h, --help | Display help for command | - -| Command | Description | -| ------- | ---------------------------------------------- | -| check | Check for updates | -| conn | Create a connection and connect to MQTT Broker | -| pub | Publish a message to a topic | -| sub | Subscribes to one or multiple topics | -| bench | MQTT Benchmark in performance testing | -| simulate | Simulate publishing scenario-specific MQTT messages | - -### Connect - -```shell -mqttx conn --help -``` - -| Options | Description | -| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | -| -V, --mqtt-version <5/3.1.1/3.1> | the MQTT version (default: 5) | -| -h, --hostname | the broker host (default: "localhost") | -| -p, --port | the broker port | -| -i, --client-id | the client id | -| --no-clean | set the clean session flag to false (default: true) | -| -k, --keepalive | send a ping every SEC seconds (default: 30) | -| -u, --username | the username | -| -P, --password | the password | -| -l, --protocol | the protocol to use, mqtt, mqtts, ws, or wss (default: mqtt) | -| --path | the path of websocket (default: /mqtt) | -| --key | path to the key file | -| --cert | path to the cert file | -| --ca | path to the ca certificate | -| --insecure | do not verify the server certificate | -| --alpn | set one or multiple ALPN (Application Layer Protocol Negotiation) protocols | -| -rp, --reconnect-period | interval between two reconnections, disable auto reconnect by setting to 0 (default: 1000ms) | -| --maximum-reconnect-times | the maximum reconnect times (default: 10) | -| -up, --user-properties | the user properties of MQTT 5.0 (e.g. -up "name: mqttx cli") | -| -Wt, --will-topic | the will topic | -| -Wm, --will-message | the will message | -| -Wq, --will-qos <0/1/2> | the will qos | -| -Wr, --will-retain | send a will retained message (default: false) | -| -Wd, --will-delay-interval | the will delay interval in seconds | -| -Wpf, --will-payload-format-indicator | will message is UTF-8 encoded character data or not | -| -We, --will-message-expiry-interval | lifetime of the will message in seconds | -| -Wct, --will-content-type | description of the will message’s content | -| -Wrt, --will-response-topic | topic name for a response message | -| -Wcd, --will-correlation-data | correlation data for the response message | -| -Wup, --will-user-properties | the user properties of will message | -| -se, --session-expiry-interval | the session expiry interval in seconds | -| --rcv-max, --receive-maximum | the receive maximum value | -| --maximum-packet-size | the maximum packet size the client is willing to accept | -| --topic-alias-maximum | the topic alias maximum value | -| --req-response-info | the client requests response information from the server | -| --no-req-problem-info | the client requests problem information from the server | -| --save \[PATH\] | save the parameters to the local configuration file, which supports json and yaml format, default path is `./mqttx-cli-config.json` | -| --config \[PATH\] | load the parameters from the local configuration file, which supports json and yaml format, default path is `./mqttx-cli-config.json` | -| --debug | Enable debug mode for MQTT.js (default: false) | -| --help | display help for conn command | - -### Subscribe - -```shell -mqttx sub --help -``` - -| Options | Description | -| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | -| -V, --mqtt-version <5/3.1.1/3.1> | the MQTT version (default: 5) | -| -h, --hostname | the broker host (default: "localhost") | -| -p, --port | the broker port | -| -i, --client-id | the client id | -| -q, --qos <0/1/2> | the QoS of the message (default: 0) | -| --no-clean | set the clean session flag to false (default: true) | -| -t, --topic | the message topic | -| -k, --keepalive | send a ping every SEC seconds (default: 30) | -| -u, --username | the username | -| -P, --password | the password | -| -l, --protocol | the protocol to use, mqtt, mqtts, ws, or wss (default: mqtt) | -| --path | the path of websocket (default: /mqtt) | -| -nl, --no_local | the no local MQTT 5.0 flag | -| -rap, --retain-as-published | the retain as published MQTT 5.0 flag | -| -rh, --retain-handling <0/1/2> | the retain handling MQTT 5.0 | -| --key | path to the key file | -| --cert | path to the cert file | -| --ca | path to the ca certificate | -| --insecure | do not verify the server certificate | -| --alpn | set one or multiple ALPN (Application Layer Protocol Negotiation) protocols | -| -rp, --reconnect-period | interval between two reconnections, disable auto reconnect by setting to 0 (default: 1000ms) | -| --maximum-reconnect-times | the maximum reconnect times (default: 10) | -| -up, --user-properties | the user properties of MQTT 5.0 (e.g. -up "name: mqttx cli") | -| -f, --format | format the message body, support base64, json, hex | -| -v, --verbose | print the topic before the message | -| --output-mode | choose between the default and clean mode, which outputs the complete MQTT packet data, allowing users to pipe the output as they wish | -| -Wt, --will-topic | the will topic | -| -Wm, --will-message | the will message | -| -Wq, --will-qos <0/1/2> | the will qos | -| -Wr, --will-retain | send a will retained message (default: false) | -| -Wd, --will-delay-interval | the will delay interval in seconds | -| -Wpf, --will-payload-format-indicator | will message is UTF-8 encoded character data or not | -| -We, --will-message-expiry-interval | lifetime of the will message in seconds | -| -Wct, --will-content-type | description of the will message’s content | -| -Wrt, --will-response-topic | topic name for a response message | -| -Wcd, --will-correlation-data | correlation data for the response message | -| -Wup, --will-user-properties | the user properties of will message | -| -se, --session-expiry-interval | the session expiry interval in seconds | -| -si, --subscription-identifier | the identifier of the subscription | -| --rcv-max, --receive-maximum | the receive maximum value | -| --maximum-packet-size | the maximum packet size the client is willing to accept | -| --topic-alias-maximum | the topic alias maximum value | -| --req-response-info | the client requests response information from the server | -| --no-req-problem-info | the client requests problem information from the server | -| -Cup, --conn-user-properties | the connect user properties of MQTT 5.0 (e.g. -Cup "name: mqttx cli") | -| --save \[PATH\] | save the parameters to the local configuration file, which supports json and yaml format, default path is `./mqttx-cli-config.json` | -| --config \[PATH\] | load the parameters from the local configuration file, which supports json and yaml format, default path is `./mqttx-cli-config.json` | -| --help | display help for sub command | -| -Pp, --protobuf-path | the path to the .proto file that defines the message format for Protocol Buffers (protobuf) | -| -Pmn, --protobuf-message-name | the name of the protobuf message type (must exist in the .proto file) | -| --debug | Enable debug mode for MQTT.js (default: false) | - -### Publish - -```shell -mqttx pub --help -``` - -| Options | Description | -| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | -| -V, --mqtt-version <5/3.1.1/3.1> | the MQTT version (default: 5) | -| -h, --hostname | the broker host (default: "localhost") | -| -p, --port | the broker port | -| -i, --client-id | the client id | -| -q, --qos <0/1/2> | the QoS of the message (default: 0) | -| --no-clean | set the clean session flag to false (default: true) | -| -t, --topic | the message topic | -| -m, --message | the message body (default: "Hello From MQTTX CLI") | -| -r, --retain | send a retained message (default: false) | -| -s, --stdin | read the message body from stdin | -| -M, --multiline | read lines from stdin as multiple messages | -| -u, --username | the username | -| -P, --password | the password | -| -f, --format | the format type of the input message, support base64, json, hex | -| -l, --protocol | the protocol to use, mqtt, mqtts, ws, or wss (default: mqtt) | -| --path | the path of websocket (default: /mqtt) | -| --key | path to the key file | -| --cert | path to the cert file | -| --ca | path to the ca certificate | -| --insecure | do not verify the server certificate | -| --alpn | set one or multiple ALPN (Application Layer Protocol Negotiation) protocols | -| -rp, --reconnect-period | interval between two reconnections, disable auto reconnect by setting to 0 (default: 1000ms) | -| --maximum-reconnect-times | the maximum reconnect times (default: 10) | -| -up, --user-properties | the user properties of MQTT 5.0 (e.g. -up "name: mqttx cli") | -| -pf, --payload-format-indicator | the payload format indicator of the publish message | -| -e, --message-expiry-interval | the lifetime of the publish message in seconds | -| -ta, --topic-alias | value that is used to identify the topic instead of using the topic name | -| -rt, --response-topic | string which is used as the topic name for a response message | -| -cd, --correlation-data | used by the sender of the request message to identify which request the response message is for when it is received | -| -si, --subscription-identifier | the identifier of the subscription | -| -ct, --content-type | a description of the content of the publish message | -| -Wt, --will-topic | the will topic | -| -Wm, --will-message | the will message | -| -Wq, --will-qos <0/1/2> | the will qos | -| -Wr, --will-retain | send a will retained message (default: false) | -| -Wd, --will-delay-interval | the will delay interval in seconds | -| -Wpf, --will-payload-format-indicator | will message is UTF-8 encoded character data or not | -| -We, --will-message-expiry-interval | lifetime of the will message in seconds | -| -Wct, --will-content-type | description of the will message’s content | -| -Wrt, --will-response-topic | topic name for a response message | -| -Wcd, --will-correlation-data | correlation data for the response message | -| -Wup, --will-user-properties | the user properties of will message | -| -se, --session-expiry-interval | the session expiry interval in seconds | -| --rcv-max, --receive-maximum | the receive maximum value | -| --maximum-packet-size | the maximum packet size the client is willing to accept | -| --topic-alias-maximum | the topic alias maximum value | -| --req-response-info | the client requests response information from the server | -| --no-req-problem-info | the client requests problem information from the server | -| -Cup, --conn-user-properties | the connect user properties of MQTT 5.0 (e.g. -Cup "name: mqttx cli") | -| --save \[PATH\] | save the parameters to the local configuration file, which supports json and yaml format, default path is `./mqttx-cli-config.json` | -| --config \[PATH\] | load the parameters from the local configuration file, which supports json and yaml format, default path is `./mqttx-cli-config.json` | -| --help | display help for pub command | -| -Pp, --protobuf-path | the path to the .proto file that defines the message format for Protocol Buffers (protobuf) | -| -Pmn, --protobuf-message-name | the name of the protobuf message type (must exist in the .proto file) | -| --debug | Enable debug mode for MQTT.js (default: false) | - -### Benchmark - -The bench command is used to test the performance of the broker. It has basically the same as the normal command options, the following will only list the new or changed options. - -#### Connect Benchmark - -```shell -mqttx bench conn --help -``` - -| Options | Description | -| ----------------------------- | ---------------------------------------------------- | -| -c, --count | the number of connections (default: 1000) | -| -i, --interval | interval of connecting to the broker (default: 10ms) | -| -I, --client-id | the client id, support %i (index) variable | +Once you've installed MQTTX CLI, you can immediately begin exploring its capabilities. Start with these basic commands: -#### Subscribe Benchmark +- **Connect to a Broker** -```shell -mqttx bench sub --help -``` - -| Options | Description | -| ----------------------------- | ------------------------------------------------------------------------------ | -| -c, --count | the number of connections (default: 1000) | -| -i, --interval | interval of connecting to the broker (default: 10ms) | -| -I, --client-id | the client id, support %i (index) variable | -| -t, --topic | the message topic, support %u (username), %c (client id), %i (index) variables | -| -v, --verbose | print history received messages and rate | - -#### Publish Benchmark - -```shell -mqttx bench pub --help -``` - -| Options | Description | -| -------------------------------------- | ------------------------------------------------------------------------------ | -| -c, --count | the number of connections (default: 1000) | -| -i, --interval | interval of connecting to the broker (default: 10ms) | -| -im, --interval-message | interval of publishing message to the broker (default: 1000ms) | -| -I, --client-id | the client id, support %i (index) variable | -| -t, --topic | the message topic, support %u (username), %c (client id), %i (index) variables | -| -v, --verbose | print history received messages and rate | -| ~~-s, --stdin~~ | ~~read the message body from stdin~~ | -| ~~-M, --multiline~~ | ~~read lines from stdin as multiple messages~~ | + ```shell + mqttx conn -h 'broker.emqx.io' -p 1883 -u 'admin' -P 'public' + ``` -### Simulate - -For simulating MQTT publish message in specific scenarios. - -It has basically the same as the [Publish Benchmark](#publish-benchmark) command options, the following will only list the new or changed options. - -```shell -mqttx simulate --help -``` - -| Options | Description | -| ----------------------------- | -------------------------------- | -| -sc, --scenario | the name of the built-in scenario to simulate | -| -f, --file | file path of a local custom scenario script | -| -t, --topic | the message topic, optional, supports variables such as %u (username), %c (client id), %i (index), %sc (scenario). Default topic format is `mqttx/simulate/%sc/%c` | - -One of the `--scenario` and `--file` parameters must be specified, and if both are specified, the `--file` parameter is preferred. - -Custom IoT Data Simulation Script Example:: - -```js -/** - * MQTTX Scenario file example - * - * This script generates random temperature and humidity data. - */ -function generator (faker, options) { - return { - // If no topic is returned, use the topic in the command line parameters. - // Topic format: 'mqttx/simulate/myScenario/' + clientId, - message: JSON.stringify({ - temp: faker.datatype.number({ min: 20, max: 80 }), // Generate a random temperature between 20 and 80. - hum: faker.datatype.number({ min: 40, max: 90 }), // Generate a random humidity between 40 and 90. - }) - } -} -// Export the scenario module -module.exports = { - name: 'myScenario', // Name of the scenario - generator, // Generator function -} -``` +- **Subscribe to a Topic** -For more examples and detailed editing guides, please refer to the [scripts-example](https://github.com/emqx/MQTTX/tree/main/scripts-example/IoT-data-scenarios) in the MQTTX GitHub repository, or see how to use [faker.js](https://fakerjs.dev/) to generate various types of random data. + ```shell + mqttx sub -t 'hello' -h 'broker.emqx.io' -p 1883 + ``` -### List +- **Publish a Message** -The `list` command provides an overview of available resources. - -> Currently, it supports listing built-in scenarios. - -```shell -mqttx list --help -``` - -| Options | Description | -| ----------------------------- | -------------------------------- | -| -sc, --scenarios | list the built-in scenarios | - -#### Built-in Scenarios - -You can use the `--scenarios` option to display a list of built-in scenarios. - -```shell -mqttx list --scenarios -``` - -This command will output a table that shows the name and description of each built-in scenario. If you want to use one of them in the simulate command, simply specify the scenario name in the `--scenario` option: - -```shell -mqttx simulate --scenario -``` + ```shell + mqttx pub -t 'hello' -h 'broker.emqx.io' -p 1883 -m 'from MQTTX CLI' + ``` -More options and features will be added to the `list` command in the future. Stay tuned! +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 diff --git a/web/README.md b/web/README.md index 6e6f6c3a2..25b3fb007 100644 --- a/web/README.md +++ b/web/README.md @@ -3,13 +3,18 @@ # MQTTX Web [![GitHub Release](https://img.shields.io/github/release/emqx/mqttx?color=brightgreen)](https://github.com/emqx/mqttx/releases) +![platforms](https://img.shields.io/badge/platforms-Browser-lightgrey) ![build packages](https://github.com/emqx/MQTTX/workflows/build%20packages/badge.svg) -[![Total Downloads](https://img.shields.io/github/downloads/emqx/mqttx/total.svg)](https://github.com/emqx/mqttx/releases) -[![Docker](https://img.shields.io/docker/pulls/emqx/mqttx-web)](https://hub.docker.com/r/emqx/mqttx-web) -[![Slack](https://img.shields.io/badge/Slack-EMQX-39AE85?logo=slack)](https://slack-invite.emqx.io/) [![Discord](https://img.shields.io/discord/931086341838622751?label=Discord&logo=discord)](https://discord.gg/xYGf3fQnES) + +[![GitHub Downloads](https://img.shields.io/github/downloads/emqx/MQTTX/total?label=GitHub%20Downloads)](https://mqttx.app/downloads) +[![Docker Web Pulls](https://img.shields.io/docker/pulls/emqx/mqttx-web?label=Docker%20Web%20Pulls)](https://hub.docker.com/r/emqx/mqttx-web) +[![Docker CLI Pulls](https://img.shields.io/docker/pulls/emqx/mqttx-cli?label=Docker%20CLI%20Pulls)](https://hub.docker.com/r/emqx/mqttx-cli) + [![Community](https://img.shields.io/badge/Community-MQTTX-yellow?logo=github)](https://github.com/emqx/MQTTX/discussions) +[![Slack](https://img.shields.io/badge/Slack-EMQX-39AE85?logo=slack)](https://slack-invite.emqx.io/) +[![Discord](https://img.shields.io/discord/931086341838622751?label=Discord&logo=discord)](https://discord.gg/xYGf3fQnES) [![YouTube](https://img.shields.io/badge/Subscribe-EMQ-FF0000?logo=youtube)](https://www.youtube.com/channel/UC5FjR77ErAxvZENEWzQaO5Q) -[![Twitter](https://img.shields.io/badge/Follow-EMQ-1DA1F2?logo=twitter)](https://twitter.com/EMQTech) +[![Twitter Follows](https://img.shields.io/twitter/follow/EMQTech?label=Twitter%20Follows)](https://twitter.com/EMQTech) ---