1. User Properties

    Click the New button to come to the New Client page, first we need to select the MQTT version 5.0, so you can see the bottom of the card to configure User Properties, the card is a key-value pair can be configured input box, you can click the upper right corner of the Add button to add User Properties configuration, click the Delete button at the end of each line to delete the configuration, and finally enter the required configuration Finally, you can enter the name and content of the property to be configured. After a successful connection, the MQTT server will be able to obtain the content of the client's User Properties.


    In addition to the configuration of user properties when connecting on the client side, this release also supports the configuration of user properties when publishing messages. When creating a new connection to an MQTT 5.0 client, we can see a Meta button in the bottom right corner of the publish message area, click on it to bring up a card for configuring the properties at publish time, and we can see the user properties configuration at the top of the card.


  2. Request Response

    Click the Meta button, enter a Response Topic: /ack/1 in the input box, enter a comparison data: light, and subscribe to a /ack/1 in the currently connected client.


  3. Content Type and Payload Format Indicator

    Click the Meta button, enter the Content Type in the input box, click Set Payload Format Indicator value, and then publish the message.


  4. Subscription identifier and subscription options

    We open the pop-up box for the Subscription topic, below which you can set the Subscription Identifier and the subscription options that contain No Local, Retain as Published and Retain Handling. The user can specify a numeric subscription identifier in the subscription message and return this identifier when the message is distributed. Clients can establish a mapping of subscription identifiers to message handlers to direct messages to the corresponding message handler via the subscription identifier when a PUBLISH message is received, and can configure these subscription options to change the behavior of the server.



Click the settings button at the bottom of the left menu bar, or use shortcut. macOS users can use the command +, shortcut, and other users can use the control +, shortcut to jump to the settings page. Currently, language selection is supported, whether to automatically check for updates, Set to sync OS theme or manually select a theme is enabled and also data backup and recovery functions in advanced settings.


Data management

The advanced settings include data backup and recovery functions. Users can choose two import and export ways, or through the upper right menu in the connection page, or in the advanced bar in the settings page.

In the settings page, you can choose to click the data backup and data recovery buttons in the advanced functions at the bottom. When selecting data backup, all connection data will be exported, including all received and sent messages. When selecting data recovery, after selecting the path of the imported file, the data can be recovered after confirmation. The file format supports JSON, XML, CSV and Excel.



After the v1.4.2 version, MQTT X has added a script editing function. In this function, users can write custom scripts (JavaScript) to perform custom conversions on sent and received Payload. With the timing sending function, realize the automated test function for the simulation data report.

Note: This feature is test feature in the beta stage

Click the script button in the menu bar on the left to enter the script editing page. In this page, users can write JavaScript code in the code editor at the top. There is only one execute API globally, and the user needs write a script function that receives a value parameter, which is Payload, and the function can be customized to modify the value, and finally the function can be executed by passing it as a parameter to the execute custom-written functions.

There is also an input and output box below. 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 With Plaintext, it is convenient for users to debug custom-written script functions in advance. After completing the test, you can click the Save button in the upper right corner and enter the name of the script to save the script. After saving, you can go to the connection page for use. The saved script can also be edited and deleted.

In the connection page, click the drop-down menu in the upper right corner, select Use script, in the pop-up window, select the pre-saved script you need to use, and then select the script to be applied, including: Published, Received, and All. After the selection is completed, select the data format to be sent or received according to the data type, and use the message sending and receiving normally. At this time, if the expected effect is seen, a script function is completed. If the user needs to cancel the script, you can click the red Stop script button in the top status bar to stop using the script.

This function is scalable and flexible, and requires users to cooperate with actual needs to use it.


The script usage examples can be viewed in the /docs/script-example folder. Currently, two built-in scripts are provided, timestamp conversion and temperature and humidity data simulation. If you have a better and more practical script in your use, you can submit your code here, so that more people can use it.


After v1.5.0, MQTT X has introduced a logging function to facilitate users to debug connections and report errors. In a production environment, the log system displays 3 levels of information:

  • INFO is used to prompt user operation information
  • WARN generates a warning of unsafe/potential risks
  • ERROR produces a failed error

By default, the log will be written to the log file:

  • Linux: ~/.config/MQTTX/logs/log
  • macOS: ~/Library/Application Support/MQTTX/logs/log
  • Windows: %USERPROFILE%\AppData\Roaming\MQTTX\logs\log

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



  1. Connection operation

    By clicking the action bar button at the top, you can quickly disconnect, delete the current connection, import and export of current data, timed message and bytes statistics etc.


  2. Message processing

    Through the All,Received, Published buttons in the upper right corner of the message bar, you can filter out all messages, received messages and published messages.

    Click the action bar button at the top and select the Search item, or use the shortcut key. macOS users can use the command + f shortcut and Other users can use the control + f shortcut to open the Topic search function, the fuzzy query of topics and payload is supported.

    Click on the action bar button at the top and select the Clear History item, you can quickly clear the messages sent and received by the current connection.


  3. Check update

    Click the i button at the bottom left to enter the About page to learn about the version information of MQTT X and related information of EMQX . Click Check for Updates to check if there are newer versions.


  4. Max reconnection times

    Below the automatic check update, there is a setting for the maximum number of reconnections, which can be set as an integer. When the 'broker' is disconnected or the connection is unavailable, the connection will be completely disconnected if the number of reconnections exceeds this setting value.

  5. Multi-window

    In the connection list, right-click and select New window to create a new window for the connection. In the new window, you can also connect, subscribe to topics, publish and receive messages, etc. If there is a connection between multiple connections created, or you need to view messages received at the same time, you can create multiple view windows and view them at the same time. After v1.4.1, users can also click the window button at the top to quickly create a new window.



  6. Bytes statistics

    In the drop-down menu in the upper right corner, you can click on the Bytes statistics item, MQTT X will automatically subscribe to the system topic, and can display the simple Bytes statistics chart, version and uptime of the MQTT Broker on the page.

    By default, only MQTT clients on localhost is allowed to subscribe to the $ SYS topic. Please refer to build-in ACL to modify the ACL rules for publish and subscription.


  7. Timed message

    In the drop-down menu in the upper right corner, you can click the Timed message item to set the sending frequency in seconds. After the setting is completed, manually send a message, and the message will be automatically sent according to the set sending frequency.


  8. Auto scroll

    New control for automatic scrolling of the message list when receiving and publish messages has been added to the settings. You can turn on the Auto Scroll feature in the settings page. Turning off the auto-scroll feature can improve performance when sending and receiving messages in part.