MQTT Tutorial auf Deutsch: Der komplette Einstieg in MQTT für Anfänger

Dieses MQTT Tutorial bringt Sie in einem Durchgang von null zu einem funktionierenden Publish/Subscribe-Setup. Sie lernen die wenigen Konzepte kennen, auf denen MQTT beruht, und führen dann jeden Schritt real gegen den kostenlosen öffentlichen MQTT-Broker broker.connectmq.com aus, über die Kommandozeile, mit Python und im Browser. Am Ende wissen Sie, wie Sie Topics entwerfen, eine QoS-Stufe wählen, Retained Messages und Last Will einsetzen und wann der Umstieg auf einen privaten Broker fällig ist.

Was ist MQTT und warum lohnt es sich, es zu lernen?

MQTT ist ein schlankes Publish/Subscribe-Messaging-Protokoll, das auf TCP aufsetzt. Es wurde für unzuverlässige Netzwerke und kleine Geräte entwickelt und ist deshalb heute die Standardsprache des IoT: Sensoren, Gateways, SPS-Adapter, mobile Apps und Backend-Services sprechen es gleichermaßen. Die aktuellen Versionen sind MQTT 3.1.1 und MQTT 5.0, beide von OASIS standardisiert (der vollständige Text ist auf mqtt.org veröffentlicht).

Drei Eigenschaften erklären seine Beliebtheit:

• Minimaler Overhead. Der feste Header eines Pakets kann nur zwei Bytes groß sein, daher funktioniert MQTT auch über Mobilfunk, Satellit und überlastetes WLAN.
• Entkopplung. Publisher kommunizieren nie direkt mit Subscribern. Sie müssen die IP-Adressen der anderen nicht kennen und nicht einmal gleichzeitig online sein.
• Push statt Polling. Sobald ein Client abonniert hat, kommen Daten in dem Moment an, in dem sie veröffentlicht werden. Es gibt keine Abfrageschleife, die Akku und Bandbreite verbraucht.

Wenn Sie sich vor dem Praxisteil den Paketfluss genauer ansehen möchten, lesen Sie wie MQTT unter der Haube funktioniert. Ansonsten machen Sie einfach weiter: Die folgenden Konzepte reichen aus, um echte Systeme zu bauen.

Die Kernkonzepte in fünf Minuten

Broker

Der Broker ist der Server in der Mitte. Jeder Client öffnet eine langlebige TCP-Verbindung zu ihm, und der Broker leitet jede veröffentlichte Nachricht an alle Clients weiter, deren Abonnement passt. Außerdem verwaltet er Sessions, speichert Retained Messages und löst Last-Will-Nachrichten aus. Eine ausführliche Erklärung, was ein MQTT Broker leistet und worin er sich von einer Message Queue unterscheidet, finden Sie in unserem eigenen Leitfaden.

Clients

Alles, was sich mit dem Broker verbindet, ist ein Client: ein ESP32, ein Python-Skript, ein Node-RED-Flow, ein Dashboard im Browser. Ein Client kann veröffentlichen, abonnieren oder beides. Jede Verbindung trägt eine Client ID, anhand derer der Broker die Session identifiziert. Zwei Clients mit derselben ID werfen sich gegenseitig hinaus, deshalb sollte sie immer eindeutig sein.

Topics

Ein Topic ist ein UTF-8-String mit durch Schrägstriche getrennten Ebenen, zum Beispiel factory1/line2/press3/temperature. Topics werden nicht vorab angelegt; sie existieren in dem Moment, in dem jemand darauf veröffentlicht. Ein gutes Topic-Design ist die wichtigste Einzelentscheidung in einem MQTT-Projekt, deshalb behandeln wir es ausführlich in MQTT Topic-Namenskonventionen.

Publish und Subscribe

Ein Publisher sendet eine Nachricht an ein Topic. Ein Subscriber meldet Interesse an einem Topic-Filter an. Der Broker bringt beides zusammen. Das ist das Publish/Subscribe-Modell, und genau das ermöglicht es Ihnen, ein neues Dashboard oder einen neuen Datenbank-Writer hinzuzufügen, ohne ein einziges Gerät anzufassen.

Wildcards

Subscriber können zwei Wildcards verwenden:

• + passt auf genau eine Ebene: factory1/+/press3/temperature
• # passt auf alle verbleibenden Ebenen und muss am Ende stehen: factory1/#

Publisher dürfen niemals Wildcards verwenden. Die vollständigen Abgleichsregeln, inklusive Sonderfällen rund um $SYS-Topics, finden Sie in unserem Leitfaden zu MQTT Wildcards.

Schritt 1: Einen Broker für dieses MQTT Tutorial wählen

Sie brauchen einen Broker, mit dem Sie sprechen können. Eine lokale Installation funktioniert, bringt aber schon in der ersten Stunde Firewall-, Port- und Dienstverwaltung mit sich. Der schnellste Weg ist ein öffentlicher MQTT-Broker. In diesem Tutorial verwenden wir broker.connectmq.com, den kostenlosen öffentlichen MQTT-Broker von ConnectMQ, der für Tests und Prototypen gedacht ist, nicht für Produktionsdaten. Er akzeptiert anonyme Verbindungen auf allen Standard-Ports:

Regeln, die Sie vor dem Start kennen sollten:

1. Verwenden Sie bei jeder Verbindung eine nicht leere, eindeutige Client ID.
2. Stellen Sie allen Topics ein Präfix voran, das sonst niemand verwendet, etwa connectmq/demo/<random-id>/. Wählen Sie Ihre zufällige ID jetzt, zum Beispiel a7k2q9.
3. Alles auf dem öffentlichen MQTT-Broker ist für jeden lesbar. Veröffentlichen Sie niemals Passwörter, personenbezogene Daten oder andere sensible Inhalte.
4. Der öffentliche MQTT-Broker hat Limits: 64 KB pro Nachricht, 10 Nachrichten pro Sekunde pro Client, 10 Abonnements pro Client, bis zu 8 Topic-Ebenen und Sessions, die nach spätestens 30 Minuten ablaufen. Zum Lernen ist das großzügig, für den Produktivbetrieb aber bewusst zu knapp.

Wenn Sie verstehen möchten, warum es diese vier Ports gibt und welchen Sie hinter einer Firmen-Firewall wählen sollten, lesen Sie MQTT Ports erklärt.

Schritt 2: Ihr erstes Publish und Subscribe über die Kommandozeile

Die Mosquitto-Kommandozeilen-Clients sind der einfachste Weg, MQTT in Aktion zu sehen. Installieren Sie sie über Ihren Paketmanager:

# Debian / Ubuntu / Raspberry Pi OS
sudo apt install mosquitto-clients

# macOS (Homebrew)
brew install mosquitto

Unter Windows enthält der Installer des Mosquitto-Projekts mosquitto_pub.exe und mosquitto_sub.exe.

Öffnen Sie ein Terminal und abonnieren Sie alles unter Ihrem Präfix. Das Flag -v gibt das Topic neben jedem Payload aus:

mosquitto_sub -h broker.connectmq.com -p 1883 -i sub-a7k2q9 \
  -t "connectmq/demo/a7k2q9/#" -v

Öffnen Sie ein zweites Terminal und veröffentlichen Sie:

mosquitto_pub -h broker.connectmq.com -p 1883 -i pub-a7k2q9 \
  -t "connectmq/demo/a7k2q9/room1/temperature" -m "21.5"

Das erste Terminal gibt sofort connectmq/demo/a7k2q9/room1/temperature 21.5 aus. Das ist der gesamte MQTT-Kreislauf: verbinden, abonnieren, veröffentlichen, empfangen.

Probieren Sie nun den verschlüsselten Port. Da broker.connectmq.com ein Let's-Encrypt-Zertifikat verwendet, kann Ihr System-CA-Bundle es verifizieren:

mosquitto_pub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -i pub-tls-a7k2q9 -t "connectmq/demo/a7k2q9/room1/humidity" -m "48"

Unter macOS oder Windows verweisen Sie mit --cafile auf eine CA-Bundle-Datei, statt --capath zu verwenden.

Schritt 3: QoS, Retained Messages und Last Will

Diese drei Funktionen unterscheiden MQTT von einem einfachen Socket. Probieren Sie jede davon jetzt aus.

Quality of Service

Jede Veröffentlichung und jedes Abonnement trägt eine QoS-Stufe:

Die effektive QoS für einen Subscriber ist der niedrigere Wert aus Publish-QoS und Subscription-QoS. Veröffentlichen Sie mit -q 1 und abonnieren Sie mit -q 1, um eine bestätigte Zustellung zu sehen. Unser Leitfaden zur Wahl zwischen QoS 0, 1 und 2 erläutert die Abwägungen anhand echter Fehlerszenarien.

Retained Messages

Eine Retained Message speichert der Broker als „letzten bekannten Wert“ eines Topics und liefert sie sofort an jeden neuen Subscriber aus. Veröffentlichen Sie eine:

mosquitto_pub -h broker.connectmq.com -p 1883 -i pub-a7k2q9 -r \
  -t "connectmq/demo/a7k2q9/room1/setpoint" -m "22"

Starten Sie nun einen neuen Subscriber. Er erhält sofort 22, obwohl seit seiner Verbindung nichts veröffentlicht wurde. Um eine Retained Message zu löschen, veröffentlichen Sie einen leeren Payload mit Retain-Flag: -r -n. Weitere Muster, auch dazu, wann Retained Messages für Verwirrung sorgen, finden Sie unter MQTT Retained Messages.

Last Will and Testament

Beim Verbindungsaufbau kann ein Client eine „Will“-Nachricht registrieren. Verschwindet der Client ohne sauberes Disconnect (Stromausfall, Netzabbruch, Absturz), veröffentlicht der Broker den Will in seinem Namen. Kombiniert mit einer Retained-Nachricht „online“ erhalten Sie eine zuverlässige Präsenzerkennung für Geräte:

mosquitto_sub -h broker.connectmq.com -p 1883 -i dev-a7k2q9 \
  -t "connectmq/demo/a7k2q9/room1/cmd" \
  --will-topic "connectmq/demo/a7k2q9/room1/status" \
  --will-payload "offline" --will-retain --will-qos 1 -k 10

Beenden Sie diesen Prozess über die Schließen-Schaltfläche Ihres Terminals (nicht mit Strg+C, das bei manchen Builds noch ein sauberes Disconnect sendet) und beobachten Sie, wie nach etwa anderthalb Keep-Alive-Intervallen offline bei Ihrem Wildcard-Subscriber ankommt.

Schritt 4: Dasselbe MQTT Tutorial in Python

Die Kommandozeile eignet sich hervorragend zum Erkunden; echte Projekte verwenden eine Bibliothek. Installieren Sie paho-mqtt 2.x:

pip install "paho-mqtt>=2.0"

Dieses Skript verbindet sich per MQTT 5, abonniert sein eigenes Befehls-Topic, veröffentlicht alle fünf Sekunden einen Messwert und meldet seine Präsenz mit einem Retained-Status plus Last Will:

import json
import random
import time
import uuid

import paho.mqtt.client as mqtt

BROKER = "broker.connectmq.com"
PREFIX = "connectmq/demo/a7k2q9"
CLIENT_ID = f"tutorial-py-{uuid.uuid4().hex[:8]}"


def on_connect(client, userdata, flags, reason_code, properties):
    if reason_code.is_failure:
        print(f"Connect failed: {reason_code}")
        return
    print("Connected as", CLIENT_ID)
    client.publish(f"{PREFIX}/room1/status", "online", qos=1, retain=True)
    client.subscribe(f"{PREFIX}/room1/cmd", qos=1)


def on_message(client, userdata, msg):
    print(f"Command on {msg.topic}: {msg.payload.decode()}")


def on_disconnect(client, userdata, flags, reason_code, properties):
    print(f"Disconnected: {reason_code}")


client = mqtt.Client(
    mqtt.CallbackAPIVersion.VERSION2,
    client_id=CLIENT_ID,
    protocol=mqtt.MQTTv5,
)
client.will_set(f"{PREFIX}/room1/status", "offline", qos=1, retain=True)
client.on_connect = on_connect
client.on_message = on_message
client.on_disconnect = on_disconnect

client.tls_set()  # Let's-Encrypt-Zertifikat mit den System-CAs prüfen
client.connect(BROKER, 8883, keepalive=30)
client.loop_start()

try:
    while True:
        reading = {"temperature": round(random.uniform(19, 24), 2), "ts": int(time.time())}
        client.publish(f"{PREFIX}/room1/telemetry", json.dumps(reading), qos=1)
        time.sleep(5)
except KeyboardInterrupt:
    client.publish(f"{PREFIX}/room1/status", "offline", qos=1, retain=True).wait_for_publish()
    client.disconnect()
    client.loop_stop()

Lassen Sie Ihr mosquitto_sub-Terminal laufen, und Sie sehen die Telemetrie eintreffen. Senden Sie mit mosquitto_pub -t "connectmq/demo/a7k2q9/room1/cmd" -m "reboot" einen Befehl zurück, und das Skript gibt ihn aus. Beachten Sie die Besonderheiten von paho 2.x: CallbackAPIVersion.VERSION2 ist Pflicht, und die Callbacks erhalten die Argumente reason_code und properties. Das Vermischen mit alten 1.x-Beispielen ist hier die häufigste Fehlerquelle.

Schritt 5: MQTT im Browser mit WebSocket

Browser können keine rohen TCP-Sockets öffnen, daher sprechen sie MQTT über WebSocket. Speichern Sie Folgendes als index.html und öffnen Sie es in einem beliebigen modernen Browser:

// Laden Sie MQTT.js zuerst per CDN in Ihrem HTML:
// <script src="https://unpkg.com/mqtt@5.10.1/dist/mqtt.min.js"></script>

const clientId = "tutorial-web-" + Math.random().toString(16).slice(2, 10);
const prefix = "connectmq/demo/a7k2q9";

const client = mqtt.connect("wss://broker.connectmq.com:8084/mqtt", {
  clientId,
  protocolVersion: 5,
  clean: true,
  reconnectPeriod: 2000,
});

client.on("connect", () => {
  console.log("Connected", clientId);
  client.subscribe(`${prefix}/#`, { qos: 1 });
  client.publish(`${prefix}/room1/cmd`, "hello from the browser", { qos: 1 });
});

client.on("message", (topic, payload) => {
  console.log(topic, payload.toString());
});

client.on("error", (err) => console.error("MQTT error", err.message));

Öffnen Sie die Entwicklerkonsole, und Sie sehen die Python-Telemetrie, den gespeicherten Sollwert und Status sowie Ihren eigenen Befehl als Echo. Port 8084 mit dem Pfad /mqtt ist der richtige für HTTPS-Seiten, weil Browser unsichere WebSocket-Verbindungen aus sicheren Origins blockieren. Unser Leitfaden zu MQTT über WebSocket behandelt Proxys, Frameworks und Authentifizierung im Browser.

Topics und Payloads skalierbar gestalten

Sobald Nachrichten fließen, entscheidet das Design darüber, ob das System wartbar bleibt. Einige Regeln, die sich in der Praxis bewähren:

1. Vom Allgemeinen zum Speziellen. site/area/line/device/measurement ermöglicht es, eine ganze Linie mit einer einzigen Wildcard zu abonnieren.
2. Nicht mit einem Schrägstrich beginnen. /factory/line1 erzeugt eine leere erste Ebene, die jeden Filter verkompliziert.
3. Bezeichner stabil halten. Verwenden Sie Geräte-IDs, keine sprechenden Namen, die sich ändern werden.
4. Daten und Befehle trennen. .../telemetry, .../status und .../cmd sollten eigene Topics sein, damit sich Berechtigungen und QoS unterscheiden können.
5. Ein Payload-Format festlegen. JSON ist lesbar und leicht zu debuggen; Binärformate wie Protobuf sparen Bandbreite auf eingeschränkten Verbindungen. Was auch immer Sie wählen: Fügen Sie einen Zeitstempel und Einheiten hinzu.
6. Nicht ein Topic pro Messwert. Zehn Werte jede Sekunde auf zehn Topics zu veröffentlichen, vervielfacht den Paket-Overhead; ein kleines JSON-Objekt ist meist besser.

Für industrielle Systeme hat sich eine an ISA-95 ausgerichtete Hierarchie (Unternehmen, Standort, Bereich, Linie, Zelle) als gängige Konvention etabliert. Sie bildet die Grundlage eines Unified Namespace (UNS), in dem diese Ebenen zur Topic-Struktur auf dem Broker werden, etwa acme/werk-stuttgart/montage/linie-1/zelle-3/temperatur. Das Muster wird in Sparkplug B und der Unified Namespace erklärt wird.

Typische Anfängerfehler und wie Sie sie beheben

Vom Tutorial zum Produktivbetrieb

Ein öffentlicher MQTT-Broker ist ideal zum Lernen und für nichts anderes. Bevor echte Geräte live gehen, brauchen Sie private Zugangsdaten, TLS überall, Isolation von anderen Nutzern und Limits, die zu Ihrer Geräteflotte passen. Sie können einen eigenen Broker betreiben, sind dann aber selbst für Patches, Zertifikate, Monitoring und Kapazitätsplanung verantwortlich. Ein verwalteter MQTT-Broker verlagert diese Arbeit zum Anbieter.

Mit ConnectMQ ist der Umstieg vor allem eine Konfigurationsänderung. Registrieren Sie sich, wählen Sie einen Plan, erstellen Sie einen Broker, und das Portal liefert Ihnen einen generierten Benutzernamen, ein Passwort und eine Client ID. Derselbe Code aus diesem Tutorial funktioniert, sobald Sie die Zugangsdaten ergänzen:

client = mqtt.Client(
    mqtt.CallbackAPIVersion.VERSION2,
    client_id="YOUR_CLIENT_ID",
    protocol=mqtt.MQTTv5,
)
client.username_pw_set("YOUR_USERNAME", "YOUR_PASSWORD")
client.tls_set()
client.connect("broker.connectmq.com", 8883, keepalive=30)

Das Portal enthält außerdem einen MQTT-Client im Browser und einen Live-Topic-Explorer, sodass Sie jeden Schritt dieses Tutorials auf Ihrem privaten Broker wiederholen können, ohne etwas zu installieren. Um Bereitstellungsoptionen zu vergleichen, von einer geteilten Serverless-Stufe bis zu einem Dedicated-Cluster oder Ihrem eigenen Cloud-Konto, lesen Sie unseren Leitfaden zur Wahl eines Cloud-MQTT-Brokers. Arbeiten Sie danach die MQTT Security Best Practices durch, bevor Sie das erste Gerät im Feld anbinden.

Ihr Lernpfad nach diesem Tutorial

Starten Sie mit ConnectMQ

Sie haben gerade jede zentrale MQTT-Funktion auf einem öffentlichen MQTT-Broker genutzt. Wenn Sie bereit für private Topics und echte Geräte sind, erstellen Sie einen kostenlosen Broker unter app.connectmq.com. Der kostenlose Serverless-Plan benötigt keine Kreditkarte, unterstützt MQTT 3.1.1 und 5.0 über TCP, TLS und WebSocket und bietet bis zu 25 Verbindungen für Ihr erstes Projekt. Ihre ConnectMQ-Zugangsdaten lassen sich direkt in den obigen Code einsetzen.

Häufig gestellte Fragen

Ist MQTT schwer zu lernen?

Nein. Das Kernmodell besteht nur aus Clients, einem Broker, Topics und Publish/Subscribe, und Ihre erste Nachricht senden Sie mit der CLI in weniger als fünf Minuten. Die Tiefe kommt später mit Sessions, QoS-Abwägungen und Topic-Design.

Muss ich für dieses MQTT Tutorial einen Broker installieren?

Nein. Jeder Schritt läuft gegen broker.connectmq.com, der anonyme Verbindungen akzeptiert. Sie benötigen nur die Mosquitto-Client-Tools, Python oder einen Browser.

Sollte ich MQTT 3.1.1 oder MQTT 5 lernen?

Lernen Sie die Konzepte einmal; sie sind in beiden Versionen gleich. Verwenden Sie MQTT 5 für neue Projekte, denn es bringt Reason Codes, Message Expiry, Shared Subscriptions und User Properties mit und bleibt kompatibel mit Brokern, die beide Versionen unterstützen.

Ist der öffentliche MQTT-Broker sicher für echte Daten?

Nein. Alles auf dem öffentlichen MQTT-Broker kann von jedem gelesen werden, nutzen Sie ihn daher nur für Tests und Demos. Echte Daten gehören auf einen privaten Broker mit Zugangsdaten und TLS.

Was sollte ich nach diesem Tutorial bauen?

Binden Sie einen echten Sensor mit einem ESP32 oder Raspberry Pi an, speichern Sie Messwerte mit einem kleinen Subscriber-Skript in einer Datenbank und bauen Sie ein Dashboard über WebSocket. Jeder dieser Schritte nutzt genau das, was Sie hier gelernt haben.