<\/div>\n
Notes:<\/strong><\/p>\n\n- No additional dependencies required<\/li>\n
- Installation size: approximately 150 MB<\/li>\n
- Automatic update notifications available<\/li>\n<\/ul>\n
<\/p>\n
macOS Installation<\/strong><\/h3>\n\n- Download the
.dmg<\/code> file from the release page<\/li>\n- Open the
.dmg<\/code> file<\/li>\n- Drag MQTT Explorer to the Applications folder<\/li>\n
- Launch the application from the Applications folder<\/li>\n
- If prompted, confirm the security dialog for unsigned developer<\/li>\n<\/ol>\n
<\/div>\n
macOS Security Note:<\/strong> If you encounter a security warning, navigate to System Preferences \u2192 Security \u2192 “Open Anyway”<\/p>\n <\/p>\n
Linux Installation for Ubuntu\/Debian (AppImage)<\/strong><\/h3>\n\n- Download the .AppImage file:
wget https:\/\/github.com\/thomasnordquist\/MQTT-Explorer\/releases\/download\/0.4.0-beta\/MQTT-Explorer-0.4.0-beta.AppImage<\/code><\/li>\n- Make it executable:
chmod +x MQTT-Explorer-0.4.0-beta.AppImage<\/code><\/li>\n- Launch:
.\/MQTT-Explorer-0.4.0-beta.AppImage<\/code><\/li>\n<\/ol>\n <\/p>\n
Connecting to an MQTT Broker<\/strong><\/h2>\nEstablishing the initial connection to an MQTT broker is the critical first step for using MQTT Explorer. The tool supports various authentication methods and connection types.<\/p>\n
![\"MQTT](\"https:\/\/i-flow.io\/wp-content\/uploads\/2026\/02\/MQTT-Explorer-Verbindungskonfiguration-300x180.png\" "\\"MQTT")
<\/div>\n
<\/div>\n
Basic Connection Configuration<\/strong><\/h3>\nStep-by-Step Guide:<\/strong><\/p>\n\n- Open Connection Dialog:<\/strong> On first launch, the connection dialog opens automatically. Later, access it via “Connections” \u2192 “New Connection”<\/li>\n
- Assign Connection Name:<\/strong> Choose a descriptive name (e.g., “Local Test Broker” or “Production-UNS-Plant01”)<\/li>\n
- Configure Broker Address:<\/strong>\n
\n- Protocol:<\/strong>
mqtt:\/\/<\/code> (default) or mqtts:\/\/<\/code> (TLS)<\/li>\n- Host:<\/strong> IP address or hostname of the broker (e.g.,
192.168.1.100<\/code> or mqtt.example.com<\/code>)<\/li>\n- Port:<\/strong> Default is 1883 (unencrypted) or 8883 (TLS)<\/li>\n<\/ul>\n<\/li>\n
- Client ID (optional):<\/strong> Leave blank for automatic generation, or specify a custom ID for persistent sessions<\/li>\n<\/ol>\n
<\/div>\n
Configuration Example:<\/strong><\/p>\n\n- Name:
Production-Broker Plant 01<\/code><\/li>\n- Protocol:
mqtt:\/\/<\/code><\/li>\n- Host:
10.50.10.100<\/code><\/li>\n- Port:
1883<\/code><\/li>\n- Client ID:
mqtt-explorer-monitoring<\/code><\/li>\n<\/ul>\n <\/p>\n
Configuring Authentication<\/strong><\/h3>\n\n- Username\/Password Authentication<\/strong>\n
\n- Enable “Enable authentication”<\/li>\n
- Enter username and password<\/li>\n
- Save the connection<\/li>\n<\/ul>\n<\/li>\n
- TLS\/SSL Connection:<\/strong> TLS encryption is recommended for production industrial environments:\n
\n- Select
mqtts:\/\/<\/code> as protocol<\/li>\n- Change port to 8883<\/li>\n
- Under “Advanced” \u2192 “TLS\/SSL Configuration”:\n
\n- CA Certificate:<\/strong> Upload broker’s root certificate<\/li>\n
- Client Certificate (optional):<\/strong> Client certificate for mutual authentication<\/li>\n
- Private Key (optional):<\/strong> Private key of the client certificate<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<\/li>\n<\/ol>\n
<\/p>\n
Advanced Settings<\/strong><\/h3>\n\n- Auto connect:<\/strong> Automatic connection on startup<\/li>\n
- Clean session:<\/strong> When disabled, subscriptions are stored persistently<\/li>\n
- Keep alive interval:<\/strong> Heartbeat interval (default: 60 seconds)<\/li>\n
- QoS for subscriptions:<\/strong> Quality of Service level (QoS 0, QoS 1, or QoS 2)<\/li>\n<\/ul>\n
<\/p>\n
Testing the Connection<\/strong><\/h3>\n\n- Click “Connect”<\/li>\n
- Successful connection is indicated by “Connected” status<\/li>\n
- The topic hierarchy loads in the left panel<\/li>\n<\/ol>\n
<\/p>\n
Monitoring and Visualizing MQTT Messages<\/strong><\/h2>\nAfter establishing a successful connection, MQTT Explorer provides multiple views for monitoring message flow.<\/p>\n
<\/div>\n
The MQTT Explorer User Interface<\/strong><\/h3>\nMQTT Explorer is organized into three main areas:<\/p>\n
1. Topic Tree (left panel):<\/strong><\/p>\n\n- Hierarchical representation of all topics<\/li>\n
- Color coding by activity (green = active, gray = inactive)<\/li>\n
- Expandable\/collapsible hierarchy levels<\/li>\n
- Message count per topic<\/li>\n<\/ul>\n
2. Message Detail Panel (right panel):<\/strong><\/p>\n\n- Current payload of the selected topic<\/li>\n
- Timestamp of the last message<\/li>\n
- QoS level and Retain flag<\/li>\n
- Message history with chronological sequence<\/li>\n<\/ul>\n
3. Statistics Panel (bottom):<\/strong><\/p>\n\n- Total number of received messages<\/li>\n
- Messages per second<\/li>\n
- Number of active topics<\/li>\n<\/ul>\n
<\/p>\n
Subscribing to and Filtering Topics<\/strong><\/h3>\nMQTT Explorer subscribes to #<\/code> (all topics) by default. For focused monitoring, you can define specific topic filters:<\/p>\n\n- Click “Advanced” \u2192 “Subscribe to specific topics”<\/li>\n
- Enter topic filters:\n
\nplant01\/area01\/#<\/code> – All topics below plant01\/area01<\/li>\n+\/temperature<\/code> – Temperature topics at the second hierarchy level<\/li>\nplant01\/area01\/+\/machine01\/#<\/code> – Specific machine, all sub-topics<\/li>\n<\/ul>\n<\/li>\n<\/ol>\n<\/div>\n
Best Practice for Industrial Systems:<\/strong> Avoid #<\/code> subscriptions on production brokers with high message volumes. Subscribe specifically to relevant topic areas to prevent performance issues.<\/p>\n <\/p>\n
Payload Inspection<\/strong><\/h3>\nMQTT Explorer automatically detects payload formats and displays them accordingly:<\/p>\n
\n- JSON Payloads:<\/strong>
{\"timestamp\": \"2025-01-15T14:23:00Z\", \"machine_id\": \"robot01\", \"temperature\": 87.3, \"unit\": \"celsius\", \"status\": \"running\"}<\/code><\/li>\n- Plaintext Payloads:<\/strong>
87.3<\/code><\/li>\n- Binary Payloads:<\/strong>\n
\n- Hex representation<\/li>\n
- ASCII side view<\/li>\n
- Byte count<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n
<\/p>\n
Using Message History<\/strong><\/h3>\nMQTT Explorer stores message history for each topic:<\/p>\n
\n- Timestamp of each received message<\/li>\n
- Traceable payload changes<\/li>\n
- Ideal for debugging intermittent issues<\/li>\n
- History size configurable (Advanced Settings)<\/li>\n<\/ul>\n
<\/p>\n
Identifying Retained Messages<\/strong><\/h3>\nMessages with the retain flag set are specially marked:<\/p>\n
\n- Retain symbol next to topic name<\/li>\n
- Important for Unified Namespace (UNS) architectures: Retained messages provide the Last Known Good Value<\/li>\n<\/ul>\n
<\/p>\n
Publishing and Testing Messages<\/strong><\/h3>\n\n- Select “Publish” in the upper area<\/li>\n
- Enter the target topic:
plant01\/area01\/line01\/testmachine\/setpoint<\/code><\/li>\n- Select QoS level (QoS 0, QoS 1, or QoS 2)<\/li>\n
- Optional: Enable “Retain” for persistent messages<\/li>\n
- Enter the payload:
{\"target_temperature\": 85.0, \"unit\": \"celsius\"}<\/code><\/li>\n- Click “Publish”<\/li>\n<\/ol>\n
<\/p>\n
Troubleshooting Common Issues<\/strong><\/h2>\n<\/div>\n
Issue 1: Connection to Broker Fails<\/strong><\/h3>\nTypical symptoms include error messages like “Connection refused” or “Timeout”. In MQTT Explorer, the status remains permanently at “Connecting…” without establishing a successful connection. Solutions:<\/p>\n
\n- Verify Broker Reachability:<\/strong>
ping <broker-ip><\/code> or telnet <broker-ip> 1883<\/code><\/li>\n- Check Firewall Rules:<\/strong>\n
\n- Port 1883 (TCP) for mqtt:\/\/<\/li>\n
- Port 8883 (TCP) for mqtts:\/\/<\/li>\n
- Windows: Windows Defender Firewall<\/li>\n
- Linux: iptables or ufw<\/li>\n<\/ul>\n<\/li>\n
- Validate Broker Status:<\/strong>
sudo systemctl status mosquitto<\/code> or sudo tail -f \/var\/log\/mosquitto\/mosquitto.log<\/code><\/li>\n- Validate Credentials:<\/strong>\n
\n- Username\/password correct?<\/li>\n
- TLS certificates valid and not expired?<\/li>\n<\/ul>\n<\/li>\n<\/ol>\n
<\/p>\n
Issue 2: No Topics Displayed<\/strong><\/h3>\n