MQTTX-Tutorial: Broker mit Desktop-Client und CLI testen

MQTTX ist ein Open-Source-MQTT-Client von EMQ in drei Varianten: eine Desktop-App (Windows, macOS, Linux), ein Kommandozeilen-Tool namens mqttx und eine Browser-Version. Er spricht MQTT 3.1, 3.1.1 und 5.0 über TCP, TLS, WebSocket und Secure WebSocket und funktioniert mit jedem konformen Broker — nicht nur mit EMQX.

Dieses Tutorial geht die Teile durch, die Entwickler beim Testen eines Brokers wirklich brauchen: Verbindungen einrichten, MQTT-5-Properties prüfen, Payloads mit Scripts umwandeln und die CLI für automatisiertes Pub/Sub, simulierte Geräte und Lasttests mit mqttx bench einsetzen.

MQTTX installieren

Prüfe die CLI mit mqttx --version. Wenn du nur kurz im Browser testen willst, ohne etwas zu installieren, erledigt der Online-MQTT-Client dieser Seite die Pub/Sub-Grundlagen über WebSocket.

Die Desktop-App: Verbindungen wie in Produktion

Klicke auf New Connection und fülle die Felder genau so aus, wie deine Geräte sie verwenden — ein Test, der von der Produktion abweicht, beweist nichts.

Unter Advanced findest du Keep-Alive, Connect-Timeout, Auto-Reconnect und für MQTT 5 die CONNECT-Properties: Session Expiry Interval, Receive Maximum, Maximum Packet Size, Topic Alias Maximum und User Properties. Der Abschnitt Last Will konfiguriert Will-Topic, Payload, QoS, Retain-Flag und Will Delay Interval — praktisch, um die Zustellung des Last Will zu testen.

Schlägt eine Verbindung fehl, steht der Fehler im Verbindungslog. MQTT-5-Broker liefern einen Reason Code; füge ihn in die Reason-Code-Suche ein, um zu sehen, was er bedeutet.

Abonnieren und publizieren

Lege mit New Subscription ein Abo mit einem Topic-Filter wie testmqtt/mqttx/# an. Jedes Abo bekommt eine Farbe, und eingehende Nachrichten werden in der Farbe des passenden Abos eingefärbt — so siehst du überlappende Wildcards am schnellsten. Unsicher, ob ein Filter greift? Probiere ihn im Topic Matcher aus.

Unten im Fenster sitzt das Publish-Feld: Topic, QoS, Retain-Flag und Payload. Die Auswahl des Payload-Typs (Plaintext, JSON, Base64, Hex und je nach Version weitere) steuert, wie du die ausgehende Nachricht eingibst und wie eingehende Payloads dekodiert werden. Der JSON-Modus validiert und formatiert, wodurch kaputte Telemetrie sofort auffällt.

Für MQTT 5 klickst du auf das Properties-Symbol neben dem Publish-Feld und setzt:

• Content Type und Payload Format Indicator
• Message Expiry Interval
• Topic Alias
• Response Topic und Correlation Data für Request/Response
• User Properties als Schlüssel/Wert-Paare

Empfangene Nachrichten zeigen ihre Properties in der Nachrichtenblase, sodass du prüfen kannst, ob der Broker sie weitergeleitet hat. Damit ist MQTTX eine praktische manuelle Ergänzung zum Testen von MQTT-5-Features.

Scripts und zeitgesteuerte Nachrichten

Mit der Funktion Script schreibst du eine kleine JavaScript-Funktion, die einen Payload vor dem Publizieren oder nach dem Empfang umwandelt. Das klassische Beispiel simuliert einen Sensor:

/**
 * Ersetzt Temperatur und Luftfeuchte bei jedem Publish durch Zufallswerte.
 * @param value der im Publish-Feld eingegebene Payload, z. B. {}
 */
function handlePayload(value) {
  let data = value;
  if (typeof value === 'string') {
    data = JSON.parse(value);
  }
  data.temperature = Math.round(Math.random() * 400) / 10;
  data.humidity = Math.floor(Math.random() * 100);
  return JSON.stringify(data, null, 2);
}

execute(handlePayload);

Speichere das Script, wende es auf die Verbindung an (gesendete, empfangene oder beide Nachrichtenarten) und kombiniere es mit Timed Message, um alle paar Sekunden zu publizieren. Schon hast du ein Fake-Gerät, ohne einen kompletten Client zu schreiben. Die Script-API hat sich zwischen Releases geändert — schau dir die mitgelieferten Beispiele deiner Version an, falls execute nicht erkannt wird.

Die mqttx-CLI

Bei wiederholbaren Tests spielt MQTTX in der CLI seine Stärken aus. Vier Subcommands decken fast alles ab: conn, sub, pub und bench.

mqttx conn -h broker.connectmq.com -p 1883 \
  -u "$MQTT_USER" -P "$MQTT_PASS" -i testmqtt-cli-check

mqttx sub -h broker.connectmq.com -p 1883 \
  -t 'testmqtt/mqttx/#' -q 1 -v

mqttx pub -h broker.connectmq.com -p 1883 \
  -t 'testmqtt/mqttx/sensor-1' -q 1 -r \
  -m '{"temperature":21.5}'

-v gibt das Topic neben jedem Payload aus — unverzichtbar bei Wildcards. Weitere Optionen, die du brauchen wirst:

Hier derselbe Publish über Secure WebSocket — so würde es eine Browser-App machen:

mqttx pub -h broker.connectmq.com -p 8084 -l wss --path /mqtt \
  -u "$MQTT_USER" -P "$MQTT_PASS" \
  -t 'testmqtt/mqttx/ws' -m 'hello over wss'

mqttx pub --help zeigt die vollständige Liste; zwischen Releases kommen gelegentlich Flags hinzu oder werden umbenannt.

Simulierte Geräte

mqttx simulate publiziert realistische Daten aus eingebauten Szenarien oder deiner eigenen Script-Datei. Liste die in deiner Version verfügbaren Szenarien mit mqttx ls --scenarios auf und starte eines:

mqttx simulate -sc tesla -c 10 \
  -h broker.connectmq.com -p 1883 \
  -t 'testmqtt/mqttx/sim/%c'

%c wird zur Client ID expandiert, sodass jedes simulierte Gerät ein eigenes Topic bekommt. Abonniere testmqtt/mqttx/sim/# in einem zweiten Terminal, um den Datenstrom zu sehen.

Lasttests mit mqttx bench

mqttx bench führt Verbindungs-, Publish- und Subscribe-Benchmarks aus einem einzigen Prozess aus:

mqttx bench conn -c 500 -i 10 \
  -h broker.connectmq.com -p 1883 -u "$MQTT_USER" -P "$MQTT_PASS"

mqttx bench sub -c 50 -t 'testmqtt/bench/%i' -q 1 \
  -h broker.connectmq.com -p 1883

mqttx bench pub -c 50 -im 100 -t 'testmqtt/bench/%i' -q 1 \
  -h broker.connectmq.com -p 1883 -m '{"v":1}'

%i ist der Client-Index, Publisher 7 spricht also mit Subscriber 7. Die Ausgabe zeigt verbundene Clients und die Nachrichtenrate pro Sekunde; bleibt die Empfangsrate in Terminal 1 unter der Senderate in Terminal 2, ist irgendetwas zwischen Clients und Broker ausgelastet. Wie du diese Zahlen liest und welche schwereren Tools es gibt, steht in Lasttests für MQTT-Broker.

Desktop oder CLI?

• Desktop, wenn du erkundest: Payload-Formate vergleichen, mehrere Abos beobachten, MQTT-5-Properties von Hand ausprobieren.
• CLI, wenn du wiederholst: Shell-Scripts, CI-Pipelines, Server, die du per SSH erreichst, und alles, was in einen Bug-Report soll.
• Keins von beiden, wenn du Assertions brauchst. MQTTX zeigt Nachrichten an, lässt aber keinen Build fehlschlagen. Für automatisierte Prüfungen packst du mqttx in ein Script, das die Ausgabe prüft, oder schreibst Tests mit einer Client-Bibliothek — siehe MQTT-Tests in GitHub Actions.

Einen Vergleich von MQTTX mit MQTT Explorer, der HiveMQ-CLI und weiteren Tools findest du unter MQTT-Desktop-Clients im Vergleich.

MQTTX-Nachrichten im Browser beobachten

MQTTX deckt den ganzen Ablauf vom Herumklicken bis zum automatisierten Benchmark mit einem Tool und einem Satz Verbindungseinstellungen ab. Speichere eine Verbindung pro Umgebung, leg deine CLI-Befehle neben der Firmware ins Repository, und du kannst jedes Broker-Problem in einer Minute reproduzieren.

Häufig gestellte Fragen