Advanced

MQTT 5.0

Clean Start and Session Expiry Interval

MQTT 5.0 introduces two features, Clean Start and Session Expiry Interval, which provide more flexibility compared to the Clean Session in MQTT 3.1.1.

In MQTTX, if Clean Start is enabled, it needs to be paired with a set Session Expiry Interval to take effect. By default, if Clean Start is disabled, the Session Expiry Interval is set to never expire and can be modified as needed. However, if the Session Expiry Interval is disabled, the system automatically sets the Session Expiry Interval to 0, meaning that as soon as the connection is disconnected, the session ends immediately.

User Properties

To begin configuring User Properties, navigate to the New Client page by clicking on the New button. Firstly, ensure that the MQTT version selected is 5.0.

You will then notice a card at the bottom of the page specifically for User Properties configuration. This card displays a configurable input box for key-value pairs. To add User Properties, click on the Add button found at the upper right corner of the card. You may also delete configurations by clicking on the Delete button at the end of each line.

To finalize your configuration, enter the necessary key-value pairs, including the name and the corresponding content of the property. Upon establishing a successful connection, the MQTT server will then access the content of the client's User Properties.

Note: User properties configuration is not only available when initiating a client connection. You can also configure user properties when publishing messages. When establishing a new connection with an MQTT 5.0 client, you'll notice a Meta button at the bottom right of the publish message area. Clicking this button will reveal a card that allows you to configure properties at the time of publishing. The user properties configuration can be found at the top of this card.

Request Response

To configure a Request Response, click the Meta button and input a Response Topic, such as /ack/1, in the provided field. Next, input comparison data (for example, "light"), and subscribe to /ack/1 with the currently connected client.

Content-Type and Payload Format Indicator

Setting the Content-Type and Payload Format Indicator requires a few steps. Start by clicking the Meta button, then enter the Content-Type in the input field. Following this, select Set Payload Format Indicator value, and finally, publish the message.

Subscription Identifier and Options

To access the Subscription Identifier and Subscription Options, open the pop-up box for the Subscription topic. Here, you can set the Subscription Identifier and configure Subscription Options which include No Local, Retain as Published, and Retain Handling.

Users can specify a numeric subscription identifier in the subscription message. This identifier will be returned when the message is distributed. By establishing a mapping of subscription identifiers to message handlers, clients can direct messages to the appropriate message handler via the subscription identifier when a PUBLISH message is received. The server's behavior can be adjusted through the configuration of these subscription options.

Settings

The settings can be accessed by clicking the button located at the bottom of the left menu bar or by using a shortcut. macOS users can use command +, while other users can use control +,. The settings page includes several options categorized into General, Appearance, and Advanced sections.

General

The General settings allow for basic operational customizations of MQTTX. Here, you can select your preferred language, enable or disable automatic updates, enable multi-topic subscriptions, and set the maximum number of reconnection attempts to maintain connection continuity under unstable network conditions.

Appearance

The Appearance settings allow you to customize the look of your MQTTX interface. You can choose from three themes: Light, Dark, and Night. Alternatively, there is also an option to synchronize the MQTTX theme with your operating system for a consistent user experience.

Install MQTTX CLI

From v1.10.1 onwards, the MQTTX desktop client supports a one-click installation of the MQTTX CLI tool. Users only need to click the install button to automate the entire setup process through a user-friendly graphical interface, avoiding manual downloads and configurations. This feature ensures that the latest version of the MQTTX CLI is easily accessible, enhancing usability in various operational environments.

Installation Steps:

1. Navigate to the settings page, find the MQTTX CLI section, and click the install button.
2. Alternatively, select the 'Install MQTTX CLI' option from the top menu.

Once clicked, the client automatically downloads and installs the required package for your system. You might need to enter a password to grant installation permissions. After installation, the mqttx command is ready to use from any command-line window.

Note: For Windows users, after clicking install, you need to manually download the MQTTX CLI executable file and use it in the corresponding directory.

Advanced (Data Management)

In the Advanced settings, you find more specific customization options, including data backup, recovery, and history clearing.

For data backup, all connection data, including all received and sent messages, are exported, ensuring the safety of your connection information and message history. During data recovery, you'll select the path of the file to import. Once you've confirmed the file path, your data is restored. Supported file formats for these operations include JSON, XML, CSV, Excel, and YAML.

If necessary, you can clear your history to manage your data usage or protect your privacy.

Script

Function

This feature allows users to write customized function code according to specific needs or scenarios, freely adjusting and transforming the content and format of the Payload for more refined data management and processing. If combined with the timing sending function, it can realize automation testing of simulated data reports, etc.

Examples of custom functions can be found in the scripts-example/function folder. If you have better and more practical scripts in use, you can submit your code here so that more people can use it.

JavaScript

Click the Script button in the left menu to enter the script editing page. In the Function page, users can write JavaScript code in the code editor at the top. There is only one global execute API, users need to write a custom function that accepts a value parameter, which is the Payload. The function can customize and modify value, and finally execute the custom function through execute.

There is also an Input and Output box below, where you can enter the expected input value. Click the Test button on the right to view the execution result in the Output box. The format of the input value includes JSON and Plaintext, which is convenient for users to debug the custom function in advance. After testing, you can click the Save button in the upper right corner, enter the custom function name and save the custom function. After saving, it can be used on the connection page, and the saved custom functions can also be edited and deleted.

The default JavaScript function example is as follows:

/**
* @description: Default script
* @param {any} value - Payload
* @param {string} msgType - Message type, the value is 'received' or 'publish'
* @param {number} index - The index of the message, only valid when the script is used to publish messages and enable timed messages
* @return {any} - Payload after script processing
*/
function handlePayload(value, msgType, index) {
  return value.msg
}
execute(handlePayload)

Schema

This feature allows users to write custom Schema files according to actual needs to encode and decode the sent and received Payload. In specific applications, users can write specific encoding and decoding rules according to data characteristics or specific application scenarios. This process is similar to designing a specific "language" for Payload and defining the translation rules of this "language" by writing encoding and decoding files. In this way, whether sending or receiving Payload, you can encode or decode according to these rules to ensure the correct understanding and effective transmission of data.

Examples of Schema can be found in the scripts-example/schema folder. If you have better and more practical encoding and decoding in use, you can submit your code here so that more people can use it.

Protocol Buffers

Click the Script button in the left menu to enter the script editing page. On the Schema page, users can write proto files in the code editor at the top.

There is also an Input and Output box below, where you can enter the expected input value. After entering the name of the defined message type, click the Test button on the right to view the execution result in the Output box. The format of the input value includes JSON, Plaintext, Base64, and Hex, which is convenient for users to debug the custom Schema in advance. After inputting JSON or JSON strings encoded with Base64 and Hex, and testing is completed, click the Save button in the upper right corner, enter the Schema name and save the Schema. After saving, it can be used on the connection page, and the saved Schema can also be edited and deleted.

The default Protocol Buffers Schema file example is as follows:

syntax = "proto3";

message Person {
  int32 id = 1;
  string name = 2;
}

Workflow

If the user uses both the custom function and Schema features of the script, MQTTX will use an efficient script workflow, covering both the publishing and subscribing stages.

In the publishing stage, the script workflow first calls custom functions to process the input data. The messages generated after these custom functions are displayed. Subsequently, the processed messages are encoded using the Schema.

In the subscription stage, the script workflow first receives the incoming encoded messages. After receiving the messages, the Schema is immediately called to decode. The decoded messages are sent to the custom functions for processing. After processing, the processed messages are displayed.

This script workflow design allows users to flexibly process data during publishing and subscribing stages, and ensures the safety and integrity of messages during transmission.

Usage

1. Navigate to the connection page, click the drop-down menu in the upper right corner of the page. In the drop-down menu, select the Run Script option.
   
2. This will pop up a script window, choose from which script should be applied, options include publish, receive and all. Then, select the custom function or Schema you want to use.
   
3. If you see a script usage hint on the message card of publishing or subscribing, it means the script function has been successfully invoked.
   
4. If you need to stop using the script, you can click the red Stop Script button in the top status bar, which will stop the script.
   

Logs

Starting with version v1.5.0, MQTTX has introduced a log function to help users debug connections and report errors. In a production environment, the log system displays information at three levels:

• INFO provides feedback on user operational information.
• WARN issues warnings about unsafe actions or potential risks.
• ERROR generates an error message when a failure occurs.

By default, logs are written to the log file at the following locations depending on your operating system:

OS	Log File Path
Linux	~/.config/MQTTX/logs/log
macOS	~/Library/Application Support/MQTTX/logs/log
Windows	%USERPROFILE%\AppData\Roaming\MQTTX\logs\log

Each time MQTTX is closed, the current log file is renamed according to the timestamp in the format [YY]-[MM]-[DD]T[hh]:[mm].log.

Others

Connection Operations

By clicking the action bar button at the top, you can quickly perform various connection operations such as disconnecting, deleting the current connection, importing and exporting data, and managing timed messages and byte statistics.

Message Processing

You can filter messages by selecting the "All", "Received", or "Published" buttons in the upper right corner of the message bar.

Click the action bar button at the top and choose the "Search" option, or use the shortcut. macOS users can use the command + f shortcut, while other users can use the control + f shortcut to open the topic search function, which allows for fuzzy queries of topics and payloads.

Click the action bar button at the top and select the "Clear History" option to quickly clear the sent and received messages of the current connection.

Check for Updates

Click the "i" button at the bottom left to access the "About" page, where you can find information about the version of MQTTX and related information about EMQX. Click "Check for Updates" to check if there are newer versions available.

Multi-Window

In the connection list, you can right-click and select "New Window" to create a new window for the connection. In the new window, you can establish connections, subscribe to topics, publish and receive messages, and perform other operations. If you have multiple connections or need to view received messages simultaneously, you can create multiple view windows and display them side by side. Starting from v1.4.1, users can also click the window button at the top to quickly create a new window.

Bytes Statistics

By clicking the "Bytes Statistics" option in the drop-down menu in the upper right corner, MQTTX will automatically subscribe to the system topic and display a simple chart showing the byte statistics, version, and uptime of the MQTT Broker on the page.

By default, only MQTT clients on the localhost can subscribe to the $SYS topic. Please refer to the built-in ACL to modify the ACL rules for publishing and subscribing.

Timed Messages

In the drop-down menu in the upper right corner, you can select the "Timed Message" option to set the sending frequency in seconds. After the setting is completed, manually send a message, and MQTTX will automatically send the message according to the specified frequency.