MQTTX Documentation

MQTTX is an open-source, cross-platform MQTT 5.0 client tool developed by EMQ. It features a chat-like UI designed to simplify testing MQTT/MQTTS connections and publishing/subscribing to messages. It allows users to quickly create and save multiple client connections.

Key Features:

• Supported Platforms: Windows, macOS, and Linux.
• MQTT Versions: Supports MQTT v3.1.1 and MQTT v5.0.
• Security: Supports CA, self-signed certificates, and one-way/two-way SSL certificates.
• Connectivity: Supports WebSocket connections to MQTT servers.
• Payload Formats: Supports Hex, Base64, JSON, and Plaintext.
• UI Customization: Supports Light, Dark, and Night (Purple) themes, and custom color marking for subscribed topics.
• Special Features: Automatic subscription to $SYS topics with configurable levels.

MQTTX is an open-source, cross-platform MQTT client designed for macOS, Linux, and Windows. It uses a chat-based UI to simplify the process of establishing multiple MQTT connections and testing MQTT/MQTTS connections through message subscription and publication.

Key Capabilities:

• Protocol Support: Fully compliant with MQTT 5.0, 3.1.1, and 3.1.
• Security: Supports one-way and two-way SSL/TLS authentication, as well as MQTT over WebSockets.
• Payload Management: Supports payload format conversion for Hex, Base64, JSON, and Plaintext.
• Customization: Features customizable color schemes for subscriptions and Light/Dark/Night modes.
• Advanced Tools: Includes custom scripts for MQTT Pub/Sub simulation and comprehensive logging.

MQTTX Web is an open-source MQTT 5.0 browser client and online MQTT WebSocket client tool. It allows you to connect to MQTT brokers via WebSockets directly in your browser to develop and debug MQTT services without local installation.

You can access the web client at: https://mqttx.app/web-client

MQTTX Web prioritizes data privacy and security with the following data handling practices:

• Local Configuration: All configuration data is processed locally on your device and is never transmitted from the browser to external servers.
• MQTT Data: Topics and message data are associated strictly with the MQTT brokers you connect to.
• No Cloud Processing: No cloud operations or data processing are performed by MQTTX.
• Analytics: Google Tag Manager (GTM) and Google Analytics (GA) are used to collect page visit metrics, but no user privacy data is involved in this collection.

MQTTX prioritizes data privacy and security through the following practices:

• Local Configuration: All configuration data is processed locally on your machine and never leaves your browser.
• Data Isolation: Any topic and message data is solely related to the MQTT Broker you are connected to.
• No Cloud Processing: The application does not perform any cloud operations or data processing.
• Limited Analytics: Google Tag Manager (GTM) and Google Analytics (GA) are used exclusively to collect page visit metrics; no user privacy data is collected.

MQTTX Web prioritizes data privacy and security through the following principles:

• Local Processing: All configuration data is processed locally on your machine; data never leaves your browser.
• Broker Isolation: Any topic or message data is strictly limited to the MQTT Broker you are currently connected to.
• No Cloud Processing: The application does not perform any cloud-based operations or data processing.
• Analytics: Google Tag Manager (GTM) and Google Analytics (GA) are used solely to collect page view metrics. No user privacy data is collected via these tools.

To quickly test MQTT functionality without deploying a local broker, use the EMQX public broker with the following settings:

• Broker Address: broker.emqx.io
• Broker TCP Port: 1883
• Broker SSL Port: 8883

Follow these steps to test MQTT publishing and subscription:

1. Prepare a Broker:
   • Use a public broker for testing:
     • Broker IP: broker.emqx.io
     • Broker TCP Port: 1883
     • Broker SSL Port: 8883
   • Or run a local broker like EMQX.
2. Configure Connection: Click the + button in the left menu bar and fill in the required fields.
3. Connect: Click the Connect button in the upper right corner.
4. Test: Once connected, you can perform MQTT publish and subscription tests.

Use the following commands to perform basic MQTT operations via the CLI:

• Connect to a Broker: Establish a connection using host, port, username, and password.
• Subscribe to a Topic: Listen for messages on a specific topic.
• Publish a Message: Send a message to a specific topic.

Subscribing to Topics

• Click New Subscription to add a topic.
• Multiple Topics: You can subscribe to multiple topics at once by separating them with a comma (,).
• Aliases: You can set an optional alias for a topic to make long topic strings easier to identify in the list.
• Management: Right-click a topic in the list to Edit, Disable, or Enable it.
• Filtering: Click a subscribed topic in the list to filter the message view to only show messages for that topic.

Publishing Messages

• Fill in the Topic in the message bar (bottom right).
• Select QoS and Retain settings.
• Enter the payload and click the send button.
• Payload Formats: Supports Base64, Hex, JSON, and Plaintext.
• Shortcuts:
  • macOS: command + enter
  • Others: control + enter

To test message flow between clients:

Subscribing

1. In the main pane, click + New Subscription.
2. Enter a topic (e.g., test) in the Topic text box. Note: Avoid using the default testtopic/# when connected to a public broker to prevent message flooding.
3. Click Confirm.

Publishing

1. Create a second connection (e.g., named Publisher) and connect to the same broker.
2. Select the Publisher connection in the Connections pane.
3. In the publishing area (lower right corner), enter the topic (e.g., test) and your message payload.
4. Click the send button.
5. Switch back to your subscriber connection (e.g., emqx_test) to view the received message.

To develop the MQTTX CLI, ensure you are using Node.js version v18.*.*. Follow these steps to set up your environment, install dependencies, and run the project in development mode or build it for production.

Development Workflow

1. Clone the repository.
2. Install dependencies using yarn within the cli directory.
3. Use yarn run dev for compilation with hot-reloading.
4. Use yarn run build to compile and compress the production version. The output will be located in the dist directory.