Quick Start

Connect to your first MQTT broker and start exploring in minutes

Get Started in Minutes

This guide will walk you through connecting to an MQTT broker and exploring your first messages.

1. Launch MQTT Explorer

   Open the application or navigate to your browser deployment.

2. Create a connection

   Click + New Connection or select an existing connection from the list.

3. Configure and connect

   Enter your broker details and click Connect.

4. Explore topics

   Browse the topic tree, inspect messages, and publish your own.

Quick Connection Example

Try connecting to a public test broker to explore MQTT Explorer’s features:

Test Broker: Mosquitto

The Eclipse Mosquitto project provides a free public test broker:

Connection Settings

Name: Test Mosquitto
Host: test.mosquitto.org
Port: 1883
Protocol: mqtt
Username: (none)
Password: (none)
Encryption: Disabled

Subscriptions:
  - Topic: #
    QoS: 0
  - Topic: $SYS/#
    QoS: 0

Default Subscriptions

MQTT Explorer automatically subscribes to:

• # - All topics (wildcard)
• $SYS/# - Broker system information

You can modify these in Advanced Settings.

Connection Setup

Basic Connection

1. Open Connection Dialog

   Click + Create Connection in the sidebar

2. Enter Basic Details

   name · string · required

   A friendly name for this connection (e.g., “Production Broker”, “Home Assistant”)

   host · string · required

   Broker hostname or IP address (e.g., test.mosquitto.org, 192.168.1.100)

   port · number · default: "1883"

   MQTT port (default: 1883 for plain, 8883 for TLS, 80/443 for WebSocket)

   protocol · string · default: "mqtt"

   Connection protocol:

   • mqtt - Standard MQTT over TCP
   • ws - MQTT over WebSocket
3. Configure Authentication (Optional)

   If your broker requires authentication:

   username · string

   MQTT username

   password · string

   MQTT password

   Many public test brokers don’t require authentication. For production brokers, always use authentication and encryption.

4. Connect

   Click Connect to establish the connection.

   Once connected, you’ll see:

   • Topic tree in the left sidebar
   • Connection status indicator (green)
   • Real-time message count

Working With Topics

Viewing Topics

Once connected, topics appear in a hierarchical tree structure:

📁 home
  📁 livingroom
    📄 temperature: 22.5
    📄 humidity: 45
  📁 bedroom
    📄 temperature: 20.1
    📄 humidity: 50
📁 $SYS
  📁 broker
    📄 version: mosquitto 2.0.15
    📄 uptime: 3600 seconds

Topic Structure:

• 📁 Folder icon = Topic level (branch)
• 📄 Document icon = Topic with message (leaf)
• Bold = Recently updated topic
• Color coding = Message age (newer = brighter)

Inspecting Messages

Click any topic to view:

Value

The current message payload:

• Raw: Plain text view
• JSON: Formatted JSON with syntax highlighting
• Hex: Hexadecimal view for binary data

History

All messages received for this topic:

• Timestamp
• Payload value
• QoS level
• Retain flag

History is stored in memory. Clear history with Clear History button.

Stats

Statistics for this topic:

• Total messages received
• First seen timestamp
• Last update timestamp
• Update frequency

Chart

For numeric values, visualize as a time-series chart:

• Line graph of values over time
• Zoom and pan controls
• Export data to CSV

Enable chart view for sensor data, metrics, or any numeric MQTT topics.

Publishing Messages

Publish Your First Message

1. Select Topic

   Click any topic in the tree, or manually enter a topic in the Publish panel.

2. Enter Message Details

   In the Publish panel (usually at the bottom):

   topic · string · required

   Topic to publish to (e.g., home/livingroom/light/command)

   payload · string · required

   Message payload (text, JSON, or binary)

   qos · number · default: "0"

   Quality of Service level:

   • 0 - At most once (fire and forget)
   • 1 - At least once (acknowledged)
   • 2 - Exactly once (assured delivery)

   retain · boolean · default: "false"

   Retain flag - if enabled, broker stores message and sends to new subscribers

3. Publish

   Click Publish to send the message.

   If subscribed to the topic, you’ll see your message appear immediately in the topic tree.

Example: Publish JSON

{
  "device": "sensor-01",
  "temperature": 22.5,
  "humidity": 45,
  "timestamp": "2026-03-05T12:00:00Z"
}

Publish to topic: home/livingroom/sensor

MQTT Explorer automatically validates and formats JSON payloads. Invalid JSON is highlighted with error details.

Advanced Settings

Client ID

MQTT Explorer generates a unique client ID automatically:

mqtt-explorer-a1b2c3d4

You can customize this in Advanced Connection Settings.

Unique Client IDs

Each MQTT client must have a unique client ID. If two clients connect with the same ID, the broker will disconnect the first client.

Custom Subscriptions

Modify the default subscriptions in Advanced Settings:

Examples:

# Subscribe to specific device
sensor/bedroom/+

# Multiple levels wildcard
home/#

# Specific topics only
home/livingroom/temperature
home/bedroom/humidity

# Exclude system topics
# (remove $SYS/# subscription)

Wildcard Characters:

• + - Single level wildcard (e.g., home/+/temperature)
• # - Multi-level wildcard (e.g., home/#)

WebSocket Connections

For brokers that support MQTT over WebSocket:

Protocol: ws
Port: 80 (or 443 for wss)
Basepath: /mqtt (if required)

Common WebSocket Paths:

• HiveMQ: /mqtt
• Mosquitto: / (default)
• AWS IoT: /mqtt
• Azure IoT Hub: /$iothub/websocket

WebSocket connections are useful when:

• MQTT port (1883) is blocked by firewall
• Connecting from browser environments
• Using cloud MQTT services

TLS/SSL Encryption

For secure connections with encryption:

1. Enable Encryption

   Check Enable TLS/SSL in connection settings

2. Update Port

   Change port to 8883 (standard MQTT/TLS port)

3. Certificate Validation

   Enable certificate validation for production brokers.

   Disable only for:

   • Testing with self-signed certificates
   • Development environments

   Security Risk: Disabling certificate validation removes protection against man-in-the-middle attacks. Use only for testing.

4. Upload Certificates (Optional)

   For self-signed certificates or client authentication:

   • CA Certificate: Broker’s Certificate Authority
   • Client Certificate: Your client certificate
   • Client Key: Private key for client certificate

   Desktop App

   Click Select File to browse for certificate files from your filesystem.

   Browser/Docker

   Click Upload to upload certificate files (max 16MB). Certificates are stored server-side.

Real-World Examples

Home Assistant

Connect to Home Assistant’s built-in MQTT broker:

Host: homeassistant.local
Port: 1883
Username: mqtt_user
Password: your_password
Protocol: mqtt

Subscriptions:
  - homeassistant/#
  - $SYS/#

AWS IoT Core

Host: your-endpoint.iot.us-east-1.amazonaws.com
Port: 8883
Protocol: mqtt
Encryption: Enabled
Cert Validation: Enabled

Certificates:
  - CA: AmazonRootCA1.pem
  - Client Cert: device-certificate.pem.crt
  - Client Key: private.pem.key

HiveMQ Cloud

Host: your-cluster.s1.eu.hivemq.cloud
Port: 8883
Username: your_username
Password: your_password
Protocol: mqtt
Encryption: Enabled

Local Mosquitto (Docker)

Host: localhost (or 172.17.0.1 from another container)
Port: 1883
Username: mosquitto
Password: mosquitto
Protocol: mqtt

Next Steps

Topic Visualization

Learn about the hierarchical topic tree and filtering

Message Publishing

Master message publishing with QoS and retain flags

TLS/SSL Setup

Configure secure encrypted connections

Protocol Decoders

Decode Protobuf and Sparkplug B messages

Troubleshooting

Connection Refused

Possible causes:

• Broker is not running
• Wrong host or port
• Firewall blocking connection
• Network connectivity issues

Solutions:

1. Verify broker is running: netstat -an | grep 1883
2. Test connectivity: telnet broker-host 1883
3. Check firewall rules
4. Try a public test broker first

Authentication Failed

Solutions:

1. Verify username and password
2. Check broker access control list (ACL)
3. Confirm authentication is required
4. Check broker logs for details

No Topics Appearing

Possible causes:

• No messages published yet
• Subscription filters too restrictive
• ACL restricts topic access

Solutions:

1. Publish a test message
2. Check subscription patterns
3. Verify ACL permissions on broker
4. Check broker logs

TLS/SSL Connection Failed

Solutions:

1. Verify port is 8883 (not 1883)
2. Check certificate validation setting
3. Upload CA certificate for self-signed certs
4. Verify broker TLS configuration
5. Check certificate expiration dates

Need More Help?

Report issues or ask questions on GitHub