Connection Setup

Learn how to configure and manage MQTT broker connections in MQTT Explorer

MQTT Explorer provides a comprehensive connection setup interface that supports various MQTT broker configurations, from simple local connections to secure cloud deployments.

Quick Start

1. Open Connection Dialog

   Launch MQTT Explorer and you’ll see the connection setup dialog. Click the ”+” button to create a new connection profile.

2. Configure Basic Settings

   Enter your broker details:

   • Name: A friendly name for this connection (e.g., “Home Assistant”)
   • Host: Your MQTT broker hostname or IP address
   • Port: MQTT broker port (default: 1883 for non-encrypted, 8883 for TLS)
   • Protocol: Choose between mqtt:// (standard) or ws:// (WebSocket)
3. Connect

   Click the “Connect” button to establish a connection to your broker.

Connection Parameters

Basic Configuration

name · string · required

A descriptive name for your connection profile. This helps you identify different brokers when managing multiple connections.

Example: "Production MQTT Broker", "Home Assistant", "IoT Devices"

protocol · string · default: "mqtt"

The connection protocol to use:

• mqtt: Standard MQTT protocol (TCP-based)
• ws: WebSocket-based MQTT (required for browser mode)

Browser mode automatically uses WebSocket (ws:// or wss://) connections since browsers cannot make direct TCP connections.

host · string · required

The hostname or IP address of your MQTT broker.

Examples:

• localhost - Local broker
• 192.168.1.100 - LAN broker
• mqtt.example.com - Remote broker
• mqtt.eclipseprojects.io - Public test broker

port · number · default: "1883"

The TCP port your MQTT broker listens on.

Common ports:

• 1883 - Standard MQTT (non-encrypted)
• 8883 - MQTT over TLS/SSL
• 8080 - WebSocket (ws://)
• 8443 - WebSocket over TLS (wss://)

basePath · string

Required when using WebSocket protocol (ws://). Specifies the path component of the WebSocket URL.

Default: ws when protocol is set to WebSocket

Examples:

• ws → connects to ws://broker.example.com:8080/ws
• mqtt → connects to ws://broker.example.com:8080/mqtt
• Empty for standard MQTT protocol

TLS/SSL Configuration

encryption · boolean · default: false

Enable TLS/SSL encryption for secure communication with your broker.

When enabled:

• Uses encrypted connection (port 8883 typically)
• Protects credentials and message data in transit
• Required for production deployments

certValidation · boolean · default: true

Validate the broker’s TLS certificate against trusted certificate authorities.

Disabling certificate validation makes your connection vulnerable to man-in-the-middle attacks. Only disable for testing with self-signed certificates, and use proper certificate management in production.

When disabled, you can connect to brokers with:

• Self-signed certificates
• Expired certificates
• Certificate hostname mismatches

Connection Profiles

MQTT Explorer allows you to save multiple connection profiles for quick access to different brokers.

Creating a Profile

1. Click the ”+” button in the connection dialog
2. Enter your broker details
3. Click Save to persist the connection profile
4. The profile is stored locally and will be available in future sessions

Managing Profiles

Switch Profiles

Select a different profile from the list on the left side of the connection dialog. Each profile retains its own settings.

Edit Profile

Select a profile and modify any settings. Click Save to update the profile with your changes.

Delete Profile

Select a profile and click the Delete button. You’ll be prompted to confirm the deletion.

Duplicate Profile

Create a new profile based on an existing one by copying the connection details and modifying them as needed.

Default Profiles

MQTT Explorer includes pre-configured profiles for public test brokers:

mqtt.eclipseprojects.io

A public MQTT broker provided by the Eclipse Foundation.

• Host: mqtt.eclipseprojects.io
• Port: 1883
• Protocol: mqtt
• Authentication: None required
• Use case: Testing and learning MQTT

This is a public broker. Never send sensitive data or use it for production applications.

test.mosquitto.org

A public test MQTT broker by Eclipse Mosquitto.

• Host: test.mosquitto.org
• Port: 1883
• Protocol: mqtt
• Authentication: None required
• Use case: Testing and learning MQTT

This broker supports multiple ports for testing different configurations (TLS, WebSockets, etc.).

Auto-Connect (Server Mode)

When running MQTT Explorer in browser/server mode, you can configure automatic connection using environment variables.

# Basic auto-connect
export MQTT_AUTO_CONNECT_HOST=mqtt.example.com
export MQTT_AUTO_CONNECT_PORT=1883

# With authentication
export MQTT_AUTO_CONNECT_USERNAME=myuser
export MQTT_AUTO_CONNECT_PASSWORD=mypassword

# With custom protocol and client ID
export MQTT_AUTO_CONNECT_PROTOCOL=mqtt
export MQTT_AUTO_CONNECT_CLIENT_ID=mqtt-explorer-server

# Start server
node dist/src/server.js

When MQTT_AUTO_CONNECT_HOST is set, MQTT Explorer will automatically connect to the specified broker on startup.

See the Environment Variables guide for complete configuration options.

Client ID

clientId · string

A unique identifier for this MQTT client connection.

Default: Auto-generated as mqtt-explorer-[random]

The client ID is used by the broker to:

• Identify your connection in broker logs
• Manage persistent sessions
• Prevent duplicate connections

If two clients connect with the same client ID, the broker will disconnect the first client. Use unique client IDs for each connection.

When to Customize Client ID

• Persistent sessions: Use a consistent client ID to maintain subscriptions across reconnections
• Debugging: Use descriptive client IDs to identify connections in broker logs
• Multiple instances: Ensure each instance has a unique client ID to prevent conflicts

Keyboard Shortcuts

The connection dialog supports several keyboard shortcuts for quick navigation:

• Enter: Connect to the selected profile
• Escape: Disconnect from the current connection
• Ctrl+S / Cmd+S: Save the current profile

Connection States

MQTT Explorer displays the current connection state:

1. Disconnected

   Not connected to any broker. The Connect button is enabled.

2. Connecting

   Connection attempt in progress. You can click the button again to cancel.

3. Connected

   Successfully connected to the broker. The main interface shows the topic tree.

4. Error

   Connection failed. Check your settings and broker availability.

Troubleshooting

Connection refused

Causes:

• Broker is not running
• Firewall blocking the connection
• Incorrect host or port

Solutions:

• Verify the broker is running: mosquitto -v
• Check firewall rules allow the port
• Confirm host and port are correct
• Try connecting from command line: mosquitto_sub -h host -p port -t #

Connection timeout

Causes:

• Broker is unreachable
• Network connectivity issues
• Broker is overwhelmed

Solutions:

• Verify network connectivity: ping broker.example.com
• Check if broker is responding: telnet broker.example.com 1883
• Try a different network or VPN connection

Authentication failed

Causes:

• Incorrect username or password
• Broker requires authentication but none provided
• User doesn’t have connection permissions

Solutions:

• Verify credentials are correct
• Check broker logs for authentication errors
• Ensure user has ACL permissions to connect
• See Authentication guide for details

TLS/SSL errors

Causes:

• Certificate validation failure
• Self-signed certificate without proper configuration
• TLS version mismatch

Solutions:

• For self-signed certificates, disable certificate validation (testing only)
• Install proper CA certificates
• Check TLS version compatibility
• See TLS/SSL guide for detailed configuration

WebSocket connection fails

Causes:

• Incorrect basePath
• Broker doesn’t support WebSocket
• CORS issues in browser mode

Solutions:

• Verify broker has WebSocket listener configured
• Check basePath matches broker configuration
• Ensure broker allows CORS for your domain (browser mode)
• Try standard MQTT protocol instead

Best Practices

Use Descriptive Names

Name your connection profiles clearly to distinguish between different brokers and environments (e.g., “Production”, “Staging”, “Local Dev”).

Enable TLS in Production

Always use TLS/SSL encryption for production deployments to protect credentials and message data.

Test with Public Brokers

Use public test brokers to learn MQTT and verify your setup before connecting to production brokers.

Unique Client IDs

Use unique client IDs for each connection to prevent conflicts and make debugging easier.

Next Steps

Authentication

Learn how to configure username/password authentication and access control.

TLS/SSL Configuration

Set up encrypted connections with certificates for secure communication.

Advanced Settings

Configure custom subscriptions, QoS levels, and advanced MQTT options.

Environment Variables

Configure MQTT Explorer using environment variables for server deployments.