-
Notifications
You must be signed in to change notification settings - Fork 450
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
32 changed files
with
707 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,23 @@ | ||
# 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]. <!--To do: add links later--> | ||
|
||
<img src="./assets/connection-advanced.png" alt="connection-advanced" style="zoom:40%;" /> | ||
|
||
## 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. | ||
|
||
![mqttx-willmessage](/images/mqttx-willmessage.png) | ||
|
||
After completing the configuration, click the `Connect` button in the upper right corner to swiftly create a connection and connect to the MQTT Broker. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,89 @@ | ||
# 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. | ||
|
||
[![Download on the Mac App Store](/images/app-store-download.svg)](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: | ||
|
||
<a href='https://flathub.org/apps/details/com.emqx.MQTTX'><img style="height: 56px;width: 170px;" alt='Download on Flathub' src='https://flathub.org/assets/badges/flathub-badge-en.png'/></a> | ||
|
||
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: | ||
|
||
<a href="https://snapcraft.io/mqttx"> | ||
<img alt="Get it from the Snap Store" src="https://snapcraft.io/static/images/badges/en/snap-store-black.svg" /> | ||
</a> | ||
|
||
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) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,25 @@ | ||
# 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 | ||
|
||
![mqttx-gif](/images/mqttx-gif.gif) | ||
|
||
## 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 |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,101 @@ | ||
# Get Started | ||
|
||
This page guides you to quickly start using the MQTTX Desktop to connect to MQTT broker and experience the basic publishing and subscribing operations. | ||
|
||
## Prepare MQTT Broker | ||
|
||
Before you get started, you need to prepare an MQTT Broker. You can choose either of the following brokers or an online MQTT service. | ||
|
||
### Public MQTT Broker | ||
|
||
For a quick test, you can use the free online [public MQTT Broker](https://www.emqx.com/en/mqtt/public-mqtt5-broker) without local deployment. It is an online public version of EMQX. | ||
|
||
```shell | ||
Broker address: broker.emqx.io | ||
Broker TCP port: 1883 | ||
Broker SSL port: 8883 | ||
``` | ||
|
||
### Fully-Managed MQTT Cloud | ||
|
||
You can also try the EMQX Cloud which is a fully managed, cloud-native MQTT Messaging Service for IoT. The EMQX Cloud allows you to create an MQTT Broker instantly in just a few minutes. | ||
|
||
[Sign up for a 14-day free trial of EMQX Cloud](https://www.emqx.com/en/try?product=cloud) | ||
|
||
*No credit card is required*. | ||
|
||
### Self-Managed MQTT Broker | ||
|
||
If you want to run an MQTT Broker locally, you are recommended to use [EMQX](https://www.emqx.com/en/products/emqx). It is the world’s most scalable and reliable MQTT messaging platform that can help you to connect, move and process your business data reliably in real time. | ||
|
||
The easiest way to start and run EMQX is using Docker. Follow the steps below for download and installation. | ||
|
||
1. To download and start the latest version of EMQX, enter the command below. | ||
|
||
Ensure [Docker](https://www.docker.com/) is installed and running before you execute this command. | ||
|
||
```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. Start your web browser and enter `http://localhost:18083/` ( `localhost` can be substituted with your IP address) in the address bar to access the [EMQX Dashboard](https://docs.emqx.com/en/enterprise/v5.1/dashboard/introduction.html), from where you can connect to your clients or check the running status. | ||
|
||
Default user name and password: `admin` and `public` | ||
|
||
You can also install EMQX with a [download package](https://www.emqx.com/en/try?product=enterprise). | ||
|
||
## Connect to MQTT Broker | ||
|
||
This section demonstrates how to use the MQTTX Desktop to connect to the public MQTT broker with the most simple settings requested. For advanced and other settings, see [Configure General Settings], [Configure Advanced Settings] and [MQTT 5.0]. <!-- Add links later--> | ||
|
||
1. Start your MQTT Broker and MQTTX Desktop. You can create a new client connection in either of the following 3 ways: | ||
|
||
- Click the **+** icon in the left navigation menu. | ||
|
||
- Click the **+ New Connection** button on the main pane. | ||
|
||
- Click **+** -> **New Connection** in the **Connections** pane. | ||
|
||
<img src="/Users/emqx/Documents/MQTTX/docs/desktop/en/quick-start/assets/new-connection.png" alt="new-connection" style="zoom:40%;" /> | ||
|
||
2. Enter the connection information of the MQTT broker in the **General** pane. To try a quick connection, you can just enter the name of the new connection, for example, `emqx_test,` and leave other options as default. | ||
|
||
- If you are using a self-managed MQTT broker, you can replace the hostname with the actual IP, such as `127.0.0.1`. | ||
|
||
::: tip | ||
|
||
For detailed information about the options in the **General** section, see [Create Connection with Generals Settings](../use-desktop/connect.md). | ||
|
||
::: | ||
|
||
<img src="./assets/mqttx-brokerinfo.png" alt="mqttx-brokerinfo" style="zoom:40%;" /> | ||
|
||
3. Click **Connect** at the upper right corner and now you have established an MQTT client connection named `emqx_test`. | ||
|
||
<img src="./assets/mqttx-connected.png" alt="mqttx-connected" style="zoom:40%;" /> | ||
|
||
## Subscribe and Publish | ||
|
||
This section demonstrates how to use the MQTTX Desktop to publish and subscribe to MQTT messages. | ||
|
||
1. Click **+ New Subscription** in the main pane. On the pop-up window, enter `test` in the **Topic** text box and leave other options as default. Click **Confirm**. The client connection now subscribes to the `test` topic. | ||
|
||
::: tip | ||
|
||
For a simple demonstration, it is not recommend to use the default topic `testtopic/#`, otherwise you will keep receiving messages if you are connected to the public MQTT broker. | ||
|
||
::: | ||
|
||
<img src="./assets/new-subscribe.png" alt="new-subscribe" style="zoom:40%;" /> | ||
|
||
2. Create a new MQTT client connection with the name as `Publisher` by following the steps in [Connect to MQTT Broker](#connect-to-mqtt-broker). | ||
|
||
3. In the **Connections** pane, make sure that the client connection `Publisher` is selected. In the publishing area at the lower right corner, enter `test` as the topic and leave the message payload and other options as default. | ||
|
||
Click the send button and a number appears on the connection `emqx_test`, indicating that a new message is received. | ||
|
||
<img src="./assets/publish.png" alt="publish" style="zoom:40%;" /> | ||
|
||
4. Click the connection `emqx_test` in the **Connections** pane. You can view the received message from `Publisher`. | ||
|
||
<img src="./assets/receive.png" alt="receive" style="zoom:50%;" /> |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,82 @@ | ||
# 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 | | ||
|
||
<img src="./assets/mqttx-brokerinfo.png" alt="mqttx-brokerinfo" style="zoom:40%;" /> | ||
|
||
## User Authentication | ||
|
||
If your broker has enabled user user authentication, you need to enter the information in the **Username** and **Password** fields. | ||
|
||
<img src="./assets/mqttx-user.png" alt="mqttx-user" style="zoom:40%;" /> | ||
|
||
## 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. | ||
|
||
<!--To do: update the screenshot--> | ||
|
||
<img src="./assets/mqttx-certs.png" alt="mqttx-certs" style="zoom:40%;" /> | ||
|
||
## 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]. <!--To do: add links later--> | ||
|
||
<img src="./assets/connection-advanced.png" alt="connection-advanced" style="zoom:40%;" /> | ||
|
||
## 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. | ||
|
||
![mqttx-willmessage](/images/mqttx-willmessage.png) | ||
|
||
After completing the configuration, click the `Connect` button in the upper right corner to swiftly create a connection and connect to the MQTT Broker. |
Oops, something went wrong.