Skip to content

Commit

Permalink
Create drafts for Get Started
Browse files Browse the repository at this point in the history
  • Loading branch information
Meggielqk authored and ysfscream committed Aug 18, 2023
1 parent 737e73b commit 6d9a1db
Show file tree
Hide file tree
Showing 32 changed files with 707 additions and 0 deletions.
23 changes: 23 additions & 0 deletions docs/desktop/en/advanced/advanced-setting.md
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.
89 changes: 89 additions & 0 deletions docs/desktop/en/downloading-and-installation.md
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)
25 changes: 25 additions & 0 deletions docs/desktop/en/introduction.md
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.
Binary file added docs/desktop/en/quick-start/assets/publish.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/desktop/en/quick-start/assets/receive.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
101 changes: 101 additions & 0 deletions docs/desktop/en/quick-start/get-started.md
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.
82 changes: 82 additions & 0 deletions docs/desktop/en/use-desktop/connect.md
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.
Loading

0 comments on commit 6d9a1db

Please sign in to comment.