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 7200 seconds (two hours).

If you need to set it to never expire, you can click the clear button on the right side of the input box; clearing the value will set the session to never expire. However, if the Session Expiry Interval is disabled, MQTTX 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.

Starting from v1.13.1, you can also set user properties when subscribing. In the new or edit subscription dialog of an MQTT 5.0 connection, add key-value pairs under User Properties, and they are sent with the SUBSCRIBE packet. Some broker features rely on this, such as the stream-offset user property used to choose the replay position when consuming EMQX MQTT Streams. Subscriptions with user properties show an icon in the subscription list; click it to view the properties.

SCRAM Enhanced Authentication

MQTT 5.0 supports SCRAM (Salted Challenge Response Authentication Mechanism) enhanced authentication. When your MQTT broker (such as EMQX) has SCRAM authentication enabled, you can select the desired authentication method from the Authentication Method dropdown in the connection configuration. MQTTX supports:

• SCRAM-SHA-1
• SCRAM-SHA-256
• SCRAM-SHA-512

Simply select your preferred SCRAM method and connect to the broker using your username and password.

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.

Enable Request Response Info in an MQTT 5.0 connection's advanced settings to request Response Information in CONNACK. If returned, the connection header shows Response Information and a copy button, even when its settings are collapsed. Click a long value to view it in full. The value comes from the broker; MQTTX does not generate it. It is hidden for MQTT 3.x connections and after disconnecting.

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. Settings that belong to MQTTX Agent, such as enabling it, choosing a model provider and configuring MCP servers, are described in MQTTX Agent.

General

The General settings allow for basic operational customizations of MQTTX:

• Language: choose the interface language.
• Auto check update: check for new versions automatically.
• Auto resubscribe: resubscribe to all locally saved subscriptions after connecting.
• Multi topics subscribe: subscribe to multiple topics at once, separated by commas.
• Max reconnect times: set the maximum number of reconnection attempts to maintain connection continuity under unstable network conditions.
• Max payload display size: payloads at or above this size are collapsed in the message list (minimum 16 KB, default 512 KB, maximum 2 MB).

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.

JSON Highlighting highlights received JSON payloads in real time. Turn it off if you experience performance issues.

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.

Backup and restore

In Settings > Advanced, choose Data Backup to export connection settings and sent and received messages as JSON, YAML, XML, CSV, or Excel. Choose Data Recovery to import a backup; connections remain disconnected after recovery.

JSON preserves nested and empty connection groups, ordering, and each connection's group. A single-connection JSON export includes its ancestor groups. Other formats keep their existing connection or message layouts without groups.

{
  "id": "collection-id",
  "name": "Production",
  "isCollection": true,
  "parentId": null,
  "orderId": 0
}

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

The Advanced section also includes:

• Log level: choose how much detail is written to the log. See Logs.
• Topic whitespace detection: highlight whitespace in topics to help prevent publish/subscribe mismatches.
• Enable GPU Acceleration: render the interface with graphics hardware for smoother operation and lower CPU usage. Changing this option requires restarting MQTTX. If you see screen lag, artifacts, or other display issues, check that your graphics driver is up to date, or turn this option off.
• Decompress GZIP messages: decompress received GZIP payloads automatically. See GZIP Decompression.

Ignore QoS 0 Message

In the settings, you can choose to enable or disable the feature to ignore QoS 0 messages. QoS 0 (Quality of Service level 0) messages are the most basic form of message delivery, offering no guarantee of delivery and no retries. For certain application scenarios, you may want to ignore these messages to reduce unnecessary network traffic or processing overhead.

Steps to Configure

1. Open the settings page.
2. Locate the "Ignore QoS 0 Message" option.
3. Toggle the switch to "On" or "Off" as desired.

Feature Description

• Enabled: MQTTX will ignore QoS 0 messages. These messages will only be displayed on the page but not stored locally, thus improving performance and reducing unnecessary storage overhead.
• Disabled: All QoS 0 messages will be received and processed normally.

Note: Previously saved QoS 0 messages will not be automatically cleared.

GZIP Decompression

Starting from v1.13.2, the Decompress GZIP messages switch in the Advanced settings decompresses received GZIP messages. It is off by default.

• A received message that starts with the gzip magic number 1f 8b is decompressed first, then decoded with the selected payload format or Schema. Messages that are not gzipped are left unchanged.
• A message that cannot be decompressed is marked with an error and keeps its original content.
• A decompressed message shows a GZIP badge next to its QoS value; hover the badge to see Automatically decompressed from GZIP.
• The badge is stored with the message, so history messages keep it after you turn the switch off or restart MQTTX.

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 select Protobuf from the dropdown box at the top, then write the proto file in the code editor.

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;
}

Using Avro Schema

Click the Script button in the left menu to enter the script editing page. On the Schema page, users can select Avro from the dropdown box at the top, then write the avsc file in the code editor.

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 encoding and decoding execution result in the Output box. The usage method is essentially the same as with Protobuf.

An example of using an Avro schema file is as follows:

{
  "type": "record",
  "name": "Person",
  "fields": [
    { "name": "id", "type": "int" },
    { "name": "name", "type": "string" }
  ]
}

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. In the schema selection box, choose the schema you want to use. Currently, Protobuf and Avro schemas are supported.
   
4. If you see a script usage prompt on the publish or subscribe message card, it indicates that the script function has been successfully invoked.
   
5. 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 four levels:

• DEBUG provides detailed debugging information, including MQTT.js packet details, to assist in troubleshooting.
• 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.

You can change the log level in the Advanced section of the settings page.

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

Each time MQTTX is closed, the current log file is renamed according to the timestamp in the format YYYY-MM-DDThh-mm-ss.log (UTC).

Viewer

Starting from v1.11.0, MQTTX introduces the Viewer feature, providing MQTT data visualization capabilities to help users better understand and monitor message flows.

Topic Tree (Beta)

The Topic Tree displays MQTT topics and messages in a hierarchical structure, allowing users to clearly understand the relationships between topics and the flow of messages.

Note: The Topic Tree feature is currently in Beta and may have incomplete or unstable functionality.

The Topic Tree feature is in the Viewer menu under the New Connection section. To use it, create a connection and subscribe to relevant topics. Once the subscribed topics receive messages, the Topic Tree will update automatically.

The page has a search box, an operation button area, a topic tree display area, and a details panel on the right. In the operation area, you can one-click to expand/collapse all nodes, view the visualized display, and clear the topic tree.

The nodes in the Topic Tree are divided into three types:

• Root node (Host node): Displays the client information receiving messages, including the client ID, Host information, connection name, and sub-topic nodes.
• Intermediate node: Contains sub-topic nodes. Clicking on it displays the current node's complete topic path and sub-topics.
• Leaf node: Displays the latest received message, including the complete topic path, reception time, Retain flag, and QoS value.

Each node name shows the number of sub-nodes and messages. Clicking the expand/collapse button before the node toggles the visibility of sub-nodes while clicking the node itself displays detailed information on the right.

Drag the divider to resize the details panel; MQTTX remembers its width. The Sub-Topics area shows the selected node's direct children, their count, and the depth below them.

Note: When you delete the corresponding connection or clear the messages in the connection, the content in the Topic Tree will also be cleared.

Visualize Topic Tree

Selecting Visualize Topic Tree from the More Operations menu displays the topic structure of the current connection graphically. This visual representation is more intuitive than the list format, making it easier to understand the distribution of topics.

You can select different Host nodes at the top of the pop-up box and adjust the default expansion level (default is 4 layers). You can adjust the depth of the view at any time using the expand/collapse button. Hovering over a node displays its topic path, message count, and sub-node count.

Note: If the data updates in real time, the visualized tree will refresh according to the current expansion level. To view deeper data changes, increase the number of expansion levels.

Synchronize Connection Data

When the topic tree receives new messages, it will be automatically synchronized to the message list on the connection page. MQTTX also supports manually synchronizing the historical message data from the connection page to the topic tree view. You can synchronize in the following two ways:

1. On the connection page:
   • Click the "Sync Topic Tree" option in the upper right corner drop-down menu
   • Select the connection to synchronize
   • The system will automatically convert the message records of the connection into a topic tree structure
   
   
2. On the topic tree page:
   • Click the "Sync Connection Data" option in the upper right corner drop-down menu
   • Select the connection to synchronize
   • View the synchronized topic tree view
   
   
   

Note:

• It is recommended to synchronize data when the connection is idle to ensure data accuracy
• The synchronized topic tree will display the latest messages for each topic

Clear Topic Tree

Selecting the Clear Topic Tree option in the More Operations menu clears the content of the Topic Tree for the current connection.

Dashboard

Use Dashboard to display MQTT message fields as numeric readings, gauges, and trend charts. This guide starts with connecting and receiving data, then covers widget configuration and checking live updates and local history.

Configure the view directly in Viewer → Dashboard; MQTTX Agent is not required. Choose a connection, topic filter, and payload field for each widget to display measurements from different sources together.

Connect and receive the data

1. Connect an MQTTX client to the broker that receives your device's messages.
2. Subscribe to the device topic or an MQTT topic filter, such as factory/+/telemetry.
3. Confirm that messages arrive in the connection's message list.

Dashboard uses the messages MQTTX receives. Choosing a topic filter for a widget does not subscribe the MQTT client to that topic.

Find the numeric fields to display in a received payload. For example:

{
  "deviceId": "line-01",
  "temperature": 24.8,
  "humidity": 56,
  "pressure": 1.02
}

set a widget's Value Field to temperature, humidity, or pressure to read that value.

Choose a useful view for each measurement

• Big Number displays a current reading, such as temperature, pressure, or a counter sent by a device.
• Gauge places a reading within a range, such as humidity from 0 to 100%.
• Line shows changes over time for inspecting trends and fluctuations during a test.

For the JSON example in the preparation steps, add a temperature Big Number, humidity Gauge, and pressure Big Number. Add a temperature Line chart to inspect changes over time.

Create a Dashboard

1. Open Viewer → Dashboard from the left sidebar.
2. Select Create Dashboard and enter a name and description.
3. Select Add Widget and choose Big Number, Line, or Gauge.
4. Configure its data source and the options available for that widget type.
5. Drag and resize the widget to arrange your view. Add other measurements as needed.

Drag the right edge of the Dashboard list to change its width. Use a Dashboard's right-click menu or ⋯ menu to edit or delete it.

Bind a widget to a message field

Configure these fields under Data Source:

Both live matching and history queries support MQTT + and # topic filters. An exact topic selects one device's readings; a filter includes messages from matching topics. A shared filter does not create a separate series for each device automatically.

Make the reading easy to interpret

Name the widget after the measurement. Configure the options available for its type, including color, decimal places, unit, range, thresholds, or line style. The editor shows Smooth Lines and Area Fill for line presentation where supported.

For the example above, give the temperature and pressure numeric widgets the units °C and bar, and set the humidity gauge range to 0–100%. A clear Line chart title, such as Temperature trend (°C), identifies the plotted measurement and its unit.

The available controls depend on the widget type. Dashboard colors follow the Light, Dark, and Night themes.

Follow incoming readings and inspect history

1. Publish a message from the device or another MQTT client to a topic matched by the widget's filter. Confirm that the message appears in the selected connection's message list.
2. Compare the widget's reading with the selected payload field. If a fallback value appears, check the JSON path and field value.
3. Publish another message with a changed value and confirm that the numeric or Gauge reading updates, or that the Line chart receives another point. If it does not update, check the active connection, broker subscription, topic filter, and selected connection.
4. Select a time range in the toolbar that includes the received messages. Compare the displayed history with the locally stored message records.

The history query uses local message records. It does not retrieve earlier broker messages that MQTTX never received. Keep the source publishing to observe ongoing live updates.

Example: ask MQTTX Agent to prepare a view

1. Configure and open MQTTX Agent, then select the Zero EMQX Skill with /.
2. Submit this request to create a temporary broker, publish sample messages, and prepare a Dashboard:

Create a temporary Zero EMQX broker, save its connection as Factory Demo, connect, and subscribe to factory/+/telemetry. Publish 12 JSON messages with deviceId and varying temperature, humidity, and pressure values to factory/line-01/telemetry, one at a time. Create a Factory Overview dashboard with the three current readings and a temperature trend chart, then open it.

3. In Ask mode, review and approve the requested actions. Confirm that Factory Demo is connected and subscribed, and that it received separate JSON messages on factory/line-01/telemetry.
4. Open Factory Overview. Compare the current readings with the latest message and choose a history range that includes the sample messages to inspect the trend.

Continue editing the Dashboard with the manual controls described above. To use another broker or data source, first connect and subscribe, then change the widgets' data-source settings.

Traffic Monitor

Starting from v1.11.1, the current bytes statistics function has been migrated to the Viewer menu and renamed Traffic Monitor. Visualizing the traffic data of the MQTT Broker helps users monitor the connection's data sending and receiving status in real-time, analyze the traffic trends and peaks, and identify potential network issues promptly, optimizing system performance and resource configuration.

There are two convenient ways to access the traffic monitor:

• Click the traffic monitor icon in the upper right corner of the connection page to enter directly
• Select Viewer -> Traffic Monitor from the left menu bar

When entering from the connection page, MQTTX will automatically subscribe to the $SYS/# system topic for you with no need to operate manually. If you are accessing directly from the menu, you need to manually subscribe to the system topic to see the monitoring data.

Note: EMQX defaults to allowing only clients on the localhost to subscribe to the $SYS topic. If you encounter subscription failures when accessing EMQX remotely, you must modify the ACL rule settings. Please refer to the built-in ACL rule description in the EMQX documentation for specific configurations.

Top Control Bar

There is a connection selector on the top. When jumping from the connection page, it will automatically select the corresponding connection, and you can switch to monitor the connection and view its connection status. On the right is the time range selector, which displays data for the past 24 hours by default.

The time selector provides time ranges such as the past 5 minutes, 30 minutes, 1 hour, 1 day, and 1 week. Clicking on them lets you switch time ranges to view monitoring data for different periods.

Accumulated Value Statistics

The card displays the latest accumulated value, and the following is a line chart indicating the growth trend of the accumulated value.

Rate Statistics

The following are the rate statistics. The card displays the latest rate information, and the following shows the current time average sending and receiving rate.

Note: The rate data is calculated based on the time interval the MQTT Broker sends the system topic. The shorter the sampling interval, the more accurate the data. You can adjust the sending interval of the system topic in the MQTT Broker configuration to obtain more accurate data.

Payload Inspector

Starting from v1.13.0, the Viewer includes a Payload Inspector for examining the messages of a single topic in detail.

Select Viewer -> Payload Inspector from the left menu bar, then choose a connection and a topic. You can filter messages by All, Received, or Published.

• Diff View: compares a message with the previous message on the same topic, highlighting what changed. Use the older and newer buttons to move through the message history, or jump back to the latest message. The topic needs at least two messages.
• JSON Tree: shows JSON payloads as a collapsible tree that you can search. Select Visualize JSON Tree to view the structure as a graph, set the expansion level, click nodes to expand or collapse them, and right-click a node to copy its subtree as JSON.

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.

Right-click a connection in the connection list to duplicate it, open it in a new window, or copy its Host or full Broker address.

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.

To clear the sent and received messages of the current connection, click the Clear History button in the toolbar at the top of the connection page. A confirmation dialog names the connection, and the messages are cleared only after you confirm.

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.

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.