DesktopCLIWeb

Getting Started

Preparing the MQTT Broker

Public MQTT Broker

For a quick test that doesn't require local MQTT Broker deployment, you can use the online public version of EMQX;

Broker address: broker.emqx.io
Broker TCP port: 1883
Broker SSL port: 8883

Fully Managed MQTT Cloud

EMQX Cloud is a fully managed, cloud-native MQTT Messaging Service for IoT that allows you to create an MQTT Broker instantly in just a few minutes.

Sign up for a 14-day free trial of EMQX Cloud

No credit card required.

Self-managed MQTT Broker

If you plan on running an MQTT Broker locally, we recommend EMQX. EMQX Broker is a cloud-native, distributed MQTT Broker for IoT, powering event streaming for IoT devices at massive scale.

Download EMQX now

To install EMQX using Docker:

docker run -d --name emqx -p 1883:1883 -p 8083:8083 -p 8883:8883 -p 8084:8084 -p 18083:18083 emqx/emqx

Connect

Once your broker is ready, click + in the left sidebar or New Connection to open the connection form.

When no connections are saved, the welcome page offers three shortcuts:

  • New Connection: Open the connection form, or press Cmd/Ctrl + N.
  • Try public broker: Create a connection named broker.emqx.io to broker.emqx.io:1883 and connect immediately.
  • Import Data: Import JSON, YAML, CSV, XML, or Excel files. The app reloads after a successful import.

MQTTX empty connection page

mqttx-create

Configure the following fields on the connection form.

  1. Broker Information
    Client ID, Host, and Port have default values. Set them to match your broker.
    • Name: Enter a connection name, such as emqx_test.
    • Client ID: A unique identifier for the connection. Click the refresh button to generate one.
    • Host: Choose mqtt:// or ws://, or mqtts:// or wss:// for TLS. The default hostname is the public broker broker.emqx.io; replace it with your broker's hostname or IP address when needed.
      • Path: For WebSocket connections, enter the server's endpoint path; the default is /mqtt.
    • Port: Use the port configured for the selected protocol. EMQX defaults are listed below; your broker may use different ports.
      ProtocolDefault EMQX port
      mqtt://1883
      mqtts://8883
      ws://8083
      wss://8084

    mqttx-brokerinfo
  2. User Authentication Information
    If the broker requires user authentication, enter Username and Password.
    mqttx-user
  3. SSL/TLS
    Enable SSL/TLS to encrypt the connection between MQTTX and the broker.
    • SSL/TLS: Enable or disable TLS; off by default.
    • SSL Secure: Verify the server certificate chain and hostname. Turning it off skips both checks. You can temporarily disable it when testing untrusted certificates in development or a trusted internal network; keep it enabled in production and for external connections.
    • CA signed server certificate: Verify the server using a trusted CA.
    • CA or Self-signed certificates: Supply your own certificates. One-way authentication requires CA File; two-way authentication also requires Client Certificate File and Client key file. Use the folder icon beside each field to select the file.

    mqttx-certs
  4. Advanced Configuration
    In Advanced, set the connection timeout, Keep Alive, Clean Session or Clean Start, automatic reconnection, and MQTT version.
  5. MQTT 5.0
    MQTT Version defaults to 5.0; 3.1 and 3.1.1 are also available. With MQTT 5.0, you can set optional properties such as Session Expiry Interval, Receive Maximum, and Topic Alias Maximum.
    mqttx-v5
  6. Will Message
    In Last Will and Testament, configure the message that the broker publishes if the client disconnects unexpectedly.
    Last-Will-QoS defaults to 0 and Last-Will-Retain to False. Enter Last-Will-Topic and Last-Will-Payload to complete the configuration.
    mqttx-willmessage

Click Connect in the upper right corner to create the connection and connect to the broker.

Subscribe and Publish

Main Interface

After connecting, expand the panel next to the connection name to view or edit basic settings. Disconnect before changing settings, then reconnect to apply them. The panel collapses after each successful connection. While disconnected, use the configuration button on the right for all connection settings.

mqttx-main

Add Subscription

Click New Subscription in the lower left corner and enter a Topic. Choose a color or use a randomly generated one. The button at the top right of the subscription list hides the list.

Click a subscription to filter messages; click it again to clear the filter, or select another subscription to change the filter. Click the topic name to copy it, then paste it into the publish area's topic field when needed.

mqttx-topic

Optionally, set a topic alias when adding a subscription. The list displays the alias, while hovering shows the original topic. Aliases help distinguish long topic names.

mqttx-topic-alias

To add multiple topics at once, separate them with commas in the subscription dialog. Use commas to separate their aliases too.

mqttx-multi-topics

Right-click a subscription to Edit, Disable, or Enable it. Disable a subscription to stop receiving its messages temporarily; enable it to resume without entering the topic again.

mqttx-edit-topic

While disconnected, you can delete or disable subscriptions if Clean Session (MQTT 3.x) or Clean Start (MQTT 5.0) is enabled. MQTTX blocks these changes for persistent sessions: Clean Session disabled, or Clean Start disabled with a Session Expiry Interval greater than 0. The broker retains those subscriptions. Adding or editing a subscription still requires a connection.

Publish and Receiving Messages

In the publish area, enter a subscribed topic, choose QoS and Retain, enter the payload, and click Send. Sent messages appear on the right and received messages on the left. A message published to a subscribed topic appears in both. Press Cmd + Enter on macOS or Ctrl + Enter on other systems to publish.

mqttx-message

Choose Base64, Hex, JSON, Plaintext, CBOR, or MsgPack in the publish area's payload selector. Use the format selector above the message list to decode received messages.

Note: CBOR and MsgPack are efficient binary formats that can reduce payload size compared with JSON. Both use JSON for input and output.

For Protobuf and Avro encoding and decoding, open Script > Schema.

Use the arrows in the publish area to browse previously published payloads. Right-click a message to copy its payload or topic.

Each connection saves its own publish area (Topic, QoS, Retain, Payload, and format) and publish history. A connection with no saved publish area opens with its most recent sent message. Upgrading copies the previously shared history to each connection. In the topic history drop-down, use an entry's delete icon to remove only that entry.

So far, the testing of an MQTT message is completed.

On This Page