MQTT 3.1.1 vs. 5.0: Was hat sich geändert und lohnt sich das Upgrade?

MQTT 3.1.1 vs. 5.0 ist die Versionsfrage, vor der jedes Team steht, sobald ein Projekt über den Prototyp hinauswächst: Ist das neuere Protokoll die Migration wert, und können alte und neue Geräte nebeneinander existieren? Dieser Leitfaden vergleicht, wie sich die beiden Versionen auf der Leitung und in der Praxis verhalten, listet auf, welche verbreiteten Client-Bibliotheken MQTT 5 unterstützen, und liefert eine Migrations-Checkliste, mit der Sie eine gemischte Flotte Gruppe für Gruppe aktualisieren.

Ein kurzer Rückblick

MQTT 3.1.1 wurde 2014 zum OASIS-Standard und ist bis heute die am weitesten verbreitete Version. Es ist klein, stabil und wird von praktisch jeder Client-Bibliothek und jedem Gerät unterstützt. MQTT 5.0 folgte 2019 als OASIS-Standard. Es behielt das Kernmodell bei – Topics, QoS-Stufen, Retained Messages und Last Will – und ergänzte die Funktionen, die große Installationen bis dahin von Hand gebaut hatten: klarere Fehler, Expiry, Flusskontrolle, Metadaten und Lastverteilung. Eine Version 4 gab es nicht; das Protocol-Level-Byte ist bei 3.1.1 eine 4 und bei 5.0 eine 5, weshalb Bibliotheken 3.1.1 oft „Protokollversion 4“ nennen.

Die gute Nachricht für die Migration: Ein Broker kann beide Versionen gleichzeitig bedienen. Jeder Client gibt seine Version im CONNECT-Paket an, und Nachrichten fließen zwischen 3.1.1- und 5.0-Clients auf denselben Topics.

MQTT 3.1.1 vs. 5.0 im direkten Vergleich

Die Änderungen, die in der Praxis am meisten zählen

Reason Codes. Lehnt ein Broker in 3.1.1 ein Publish wegen eines Kontingents oder fehlender Berechtigung ab, sieht der Client oft nur den Verbindungsabbruch und muss raten. In MQTT 5 kann der Broker den Grund nennen, etwa 0x97 (Quota exceeded) oder 0x87 (Not authorized). Allein das verkürzt die Fehlersuche drastisch. Die Referenz zu MQTT Reason Codes listet sie alle auf.

Session- und Message-Expiry. Mit 3.1.1 lebt eine persistente Session, bis der Client zurückkehrt – das kann bedeuten, dass ein Broker Nachrichten für Geräte vorhält, die vor Monaten außer Betrieb genommen wurden. MQTT 5 erlaubt dem Client zu sagen „Behalte meine Session 10 Minuten“ und Publishern zu sagen „Dieser Befehl ist nach 30 Sekunden nutzlos“. Tipps zur Abstimmung finden Sie unter MQTT Session Expiry Interval.

Shared Subscriptions. Mehrere Instanzen eines Backend-Service können $share/workers/orders/+/new abonnieren, und der Broker verteilt die Nachrichten auf sie. Vor MQTT 5 erforderte das broker-spezifische Erweiterungen oder eine separate Queue.

User Properties und Request/Response. Metadaten wie eine Schema-Version oder eine Trace-ID können in Properties reisen, statt in jeden Payload eingepackt zu werden, und Request/Response-Abläufe erhalten ein standardisiertes Response Topic und Correlation Data.

Eine Tour Funktion für Funktion mit Beispielen bietet MQTT-5-Funktionen.

Was sich nicht ändert

Topic-Syntax und Wildcards, die drei QoS-Stufen, Retained Messages, Last Will, Keep Alive, Ports und TLS funktionieren alle wie gehabt. Payloads sind weiterhin opake Bytes. Ein 3.1.1-Subscriber empfängt Nachrichten, die ein 5.0-Client publiziert hat; er sieht lediglich die MQTT-5-Properties nicht. Genau diese Kompatibilität macht ein schrittweises Upgrade möglich.

Unterstützung in Client-Bibliotheken

Bibliotheksversionen ändern sich, prüfen Sie daher vor einer Festlegung die offizielle Dokumentation. Das Muster, das auffällt: Server- und Gateway-Bibliotheken unterstützen MQTT 5 in der Regel, während viele beliebte Mikrocontroller-Bibliotheken noch auf 3.1.1 beschränkt sind. Das ist der Hauptgrund, warum Flotten gemischt bleiben.

MQTT-5-Funktionen im Code nutzen

Dieses Python-Beispiel verbindet sich mit MQTT 5, fordert eine 10-minütige Session an, publiziert einen Befehl mit 30 Sekunden Expiry und User Properties und gibt Reason Codes aus. Es läuft gegen den öffentlichen MQTT-Broker, der beide Versionen und Session Expiry bis 30 Minuten unterstützt und für Tests, nicht für Produktionsdaten gedacht ist.

import time
import uuid

import paho.mqtt.client as mqtt
from paho.mqtt.packettypes import PacketTypes
from paho.mqtt.properties import Properties

PREFIX = f"connectmq/demo/{uuid.uuid4().hex[:8]}"

def on_connect(client, userdata, flags, reason_code, properties):
    print("CONNACK:", reason_code, "| session present:", flags.session_present)
    client.subscribe(f"{PREFIX}/cmd/#", qos=1)

def on_subscribe(client, userdata, mid, reason_code_list, properties):
    print("SUBACK:", [str(rc) for rc in reason_code_list])

def on_message(client, userdata, msg):
    props = msg.properties
    user_props = getattr(props, "UserProperty", None)
    expiry = getattr(props, "MessageExpiryInterval", None)
    print(f"{msg.topic} {msg.payload.decode()} user={user_props} expiry={expiry}")

def on_publish(client, userdata, mid, reason_code, properties):
    print("PUBACK:", reason_code)

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2,
                     client_id=f"v5-demo-{uuid.uuid4().hex[:8]}",
                     protocol=mqtt.MQTTv5)
client.on_connect = on_connect
client.on_subscribe = on_subscribe
client.on_message = on_message
client.on_publish = on_publish

connect_props = Properties(PacketTypes.CONNECT)
connect_props.SessionExpiryInterval = 600  # Session 10 Minuten behalten

client.connect("broker.connectmq.com", 1883, keepalive=30,
               clean_start=False, properties=connect_props)
client.loop_start()
time.sleep(1)

pub_props = Properties(PacketTypes.PUBLISH)
pub_props.MessageExpiryInterval = 30
pub_props.UserProperty = [("schema", "v2"), ("source", "ops-console")]
pub_props.ContentType = "application/json"

client.publish(f"{PREFIX}/cmd/pump7", '{"action":"stop"}', qos=1,
               properties=pub_props)
time.sleep(2)
client.loop_stop()
client.disconnect()

Um die Interoperabilität zu sehen, starten Sie in einem anderen Terminal einen 3.1.1-Subscriber auf demselben Topic. Er empfängt den Payload, aber nicht die Properties.

mosquitto_sub -h broker.connectmq.com -p 1883 -V mqttv311 \
  -i v311-check-$RANDOM -t "connectmq/demo/+/cmd/#" -v

Migrations-Checkliste

Mit dieser Checkliste wechseln Sie von 3.1.1 auf 5.0, ohne alles auf einen Schlag umzustellen.

1. Broker-Unterstützung bestätigen. Ihr Broker muss beide Versionen gleichzeitig akzeptieren. ConnectMQ tut das, sodass alte und neue Clients sich während der Umstellung Topics teilen können.
2. Clients nach Bibliothek inventarisieren. Listen Sie jeden Gerätetyp, jedes Gateway und jeden Service mit MQTT-Bibliothek und Version auf. Markieren Sie, welche schon heute auf MQTT 5 wechseln können.
3. Zuerst die Backend-Services aktualisieren. Sie profitieren am meisten (Reason Codes, Shared Subscriptions, Flusskontrolle) und lassen sich am einfachsten neu ausrollen.
4. Clean-Session-Logik ersetzen. Bilden Sie clean_session=True auf Clean Start mit Session Expiry 0 ab und clean_session=False auf Clean Start false mit einem expliziten Expiry statt „für immer“.
5. Reason Codes behandeln. Protokollieren Sie Reason Codes und Reason Strings bei CONNACK, SUBACK, PUBACK und DISCONNECT und beenden Sie Wiederholungsversuche bei nicht wiederholbaren Codes wie „Not authorized“.
6. Kritische Daten noch nicht von Properties abhängig machen. Solange 3.1.1-Subscriber existieren, muss alles, was sie brauchen, im Payload oder im Topic bleiben.
7. Expiry gezielt einführen. Versehen Sie zuerst Befehle und zeitkritische Alarme mit Message Expiry, wo verspätete Zustellung schadet.
8. Shared Subscriptions einführen für horizontal skalierte Consumer und selbstgebaute Deduplizierung zwischen Instanzen entfernen.
9. Gateways und Geräte zuletzt aktualisieren, gruppenweise, und nach jeder Welle Verbindungsstatus und Fehlerraten beobachten.
10. Die Grundlagen erneut testen. Reconnect, Last Will, gespeicherter Zustand und persistente Sessions sollten sich wie zuvor verhalten; die MQTT-Test-Checkliste deckt jeden Punkt ab.

Sollten Sie upgraden?

Beginnen Sie neue Projekte mit MQTT 5, wo immer Ihre Bibliotheken es unterstützen. Bei bestehenden Flotten aktualisieren Sie Services und Gateways jetzt und Geräte bei passender Gelegenheit, etwa beim nächsten Firmware-Zyklus. Es gibt wenig Grund, ressourcenbeschränkte Geräte mit reiner 3.1.1-Bibliothek zu überstürzen, denn ein Broker, der beide Versionen spricht, nimmt den Druck heraus. Das gilt besonders in der Fertigung: Maschinen, Edge-Gateways und SPS-Anbindungen laufen dort oft zehn Jahre und länger, sodass eine gemischte Flotte im Werk eher die Regel als die Ausnahme ist. Das MQTT-Tutorial behandelt die gemeinsamen Grundlagen, falls Sie neue Teammitglieder einarbeiten.

Ein verwalteter MQTT-Broker, der beide Versionen unterstützt, macht die Umstellung unspektakulär. ConnectMQ akzeptiert MQTT-3.1.1- und 5.0-Clients auf demselben Broker und unterstützt MQTT-5-Funktionen wie Session Expiry, Message Expiry, Topic Alias, Response Topic, Retained Messages und Reason Codes, dazu Shared Subscriptions im kostenpflichtigen Serverless-Plan.

Upgraden Sie auf ConnectMQ in Ihrem eigenen Tempo

Erstellen Sie unter app.connectmq.com einen kostenlosen Serverless-Broker, ganz ohne Kreditkarte, verbinden Sie ein 3.1.1-Gerät und einen MQTT-5-Service und bestätigen Sie, dass beide zusammenarbeiten, bevor Sie den Rest der Migration planen.

Häufig gestellte Fragen

Sind MQTT 3.1.1 und MQTT 5.0 kompatibel?

Auf demselben Broker ja. Clients wählen ihre Version beim Verbinden, und Nachrichten fließen zwischen den Versionen. Ein 3.1.1-Subscriber erhält lediglich keine MQTT-5-Properties.

Was ist der größte Vorteil von MQTT 5?

Für die meisten Teams sind es die Reason Codes, weil Fehler nicht länger stille Verbindungsabbrüche sind. Session- und Message-Expiry sowie Shared Subscriptions folgen dicht dahinter.

Warum heißt MQTT 3.1.1 Protokollversion 4?

Das CONNECT-Paket enthält ein Protocol-Level-Byte, das bei MQTT 3.1.1 den Wert 4 und bei MQTT 5.0 den Wert 5 hat. Bibliotheken wie MQTT.js verwenden diese Zahl in ihren Optionen.

Muss ich meine ESP32-Geräte auf MQTT 5 umstellen?

Nicht unbedingt. Wenn Sie eine 3.1.1-Bibliothek wie PubSubClient verwenden, können die Geräte weiter mit einem Broker arbeiten, der beide Versionen unterstützt, während Ihr Backend auf MQTT 5 umsteigt.