MQTT

Hermetry spricht MQTT 3.1.1. Diese Seite ist die Verbindungsreferenz für Geräteentwickler: wie man den Broker erreicht, wie man sich anmeldet, wie sich Sitzungen verhalten, was wann bestätigt wird und was zu tun ist, wenn eine Verbindung abgelehnt wird. Die Topics und Payloads stehen in der Referenz zu MQTT-Topics und Payloads.

Verbindung

Element	Wert
Protokoll	MQTT 3.1.1 (Protokollstufe 4). Ein CONNECT für MQTT 5 wird mit CONNACK 1 abgelehnt.
Port, TLS	8883
Port, unverschlüsselt	1883, nur für Geräte eines Profils, das unverschlüsseltes MQTT erlaubt
Host	Der Broker-Host auf der Karte Verbindungsdetails des Geräts. Verwenden Sie den Host der Region Ihrer Organisation.
Clean Session	Senden Sie true. Ein CONNECT mit false wird als Clean Session behandelt.
Keepalive	Verwenden Sie das MQTT-Keepalive. Ein Keepalive von 0 oder ein Wert oberhalb des Maximums des Brokers (300 Sekunden bei einer Standardinstallation) wird auf das Maximum gesetzt.
Will-Nachricht	Erlaubt, wird ignoriert. Hermetry bestimmt den Verbindungsstatus selbst.
Retain-Flag	Wird ignoriert. Die Nachricht wird verarbeitet, nicht gespeichert.
Verbindungszeit	Vom TCP-Verbindungsaufbau bis zu einem akzeptierten CONNECT (einschließlich TLS-Handshake und Anmeldung) hat das Gerät einige Sekunden Zeit (standardmäßig 5).

Während ein Gerät offline ist, wird nichts für es zwischengespeichert, außer Befehlen mit Kennzeichnung „persistent“. Nach jeder Verbindung abonniert das Gerät erneut und fragt seine gemeinsamen Attribute ab, sodass es die aktuellen Werte erhält.

TLS

• Mindestens TLS 1.2, TLS 1.3 wird bevorzugt.
• TLS-1.2-Suites: ECDHE-ECDSA-AES128-GCM-SHA256, ECDHE-RSA-AES128-GCM-SHA256, ECDHE-ECDSA-CHACHA20-POLY1305. Kein RSA-Schlüsselaustausch, kein CBC.
• SNI ist erforderlich. Verbinden Sie sich über den Host-Namen, nicht über eine IP-Adresse.
• Bei Geräten von Drittanbietern ist das Serverzertifikat ein öffentliches. Prüfen Sie es gegen Ihren üblichen CA-Bundle und den Host-Namen.
• Der Server fordert ein Client-Zertifikat an, verlangt es aber nicht, sodass ein Port alle Anmeldetypen bedient.
• Kleine Geräte können 4-KB-TLS-Records anfordern (max_fragment_length).

Ein Profil legt fest, ob seine Geräte den unverschlüsselten Port überhaupt nutzen dürfen (Plain MQTT auf dem Reiter Transport & Authentifizierung des Profils). Nur TLS ist der Standard. Siehe Transportsicherheit für Geräte.

Anmeldung

Anmeldedaten	Client-ID	Benutzername	Passwort
Access Token	beliebige gültige ID	das Access Token	leer
MQTT-Basis	beliebig oder die fixierte Client-ID	der Benutzername	das Passwort
X.509-Zertifikat	die Gerätenummer (muss dem CN des Zertifikats entsprechen)	die Seriennummer (wird ignoriert)	leer

• Eine Client-ID hat 1 bis 64 Zeichen aus A–Z a–z 0–9 . _ : -. Alles andere wird mit CONNACK 2 abgelehnt.
• Ein CONNECT mit Benutzername, aber ohne Passwort, wird als Access Token gelesen. Ein CONNECT ohne Benutzername wird abgelehnt.
• Wenn ein Client-Zertifikat vorgelegt wird, entscheidet es. Es gibt keinen Rückfall auf ein Passwort. Ein nicht vertrauenswürdiges Zertifikat beendet den TLS-Handshake.
• Der Benutzername provision öffnet eine Provisionierungssitzung (siehe Geräte hinzufügen und beanspruchen).
• Das Profil muss den Anmeldetyp, das Netzwerk des Geräts und den Port (TLS oder unverschlüsselt) erlauben; andernfalls wird die Anmeldung mit CONNACK 5 abgelehnt.

Sitzungen

• Eine Sitzung pro Gerät. Eine zweite Verbindung desselben Geräts übernimmt die Sitzung und schließt die erste. Ein Gerät, dessen Sitzung immer wieder aus zwei Netzwerken übernommen wird, wird für eine Weile zurückgehalten, und Ihre Administratoren erhalten eine Meldung („Takeover-Konflikt“). Prüfen Sie, ob zwei Geräte dieselben Anmeldedaten teilen.
• Prüfungen. Jede aktive Sitzung wird etwa alle 60 Sekunden erneut geprüft. Ein rotierter oder widerrufener Anmeldedatensatz, ein deaktiviertes oder gelöschtes Gerät, eine gesperrte Organisation oder eine Profiländerung, die die Sitzung nicht mehr erfüllt, beendet sie sofort.
• Quarantänegeräte können sich verbinden, aber ihre Telemetrie und Attribute werden bestätigt und verworfen, bis ein Administrator sie aktiviert.
• Hinweis auf neues Netzwerk. Meldet sich ein Gerät aus einem anderen Netzwerk als beim letzten Mal an, erhalten Ihre Administratoren gegebenenfalls eine Meldung (höchstens einmal pro Stunde und Gerät), damit ein gestohlener Anmeldedatensatz nicht unbemerkt bleibt.
• Limit verbundener Geräte. Begrenzt Ihr Tarif, wie viele Geräte gleichzeitig verbunden sein dürfen, wird ein CONNECT oberhalb dieses Limits mit CONNACK 5 abgelehnt.

Bestätigungen und QoS

• Veröffentlichen Sie mit QoS 1. QoS 0 wird akzeptiert; QoS 2 wird wie QoS 1 behandelt.
• Hermetry sendet das PUBACK erst, wenn die Nachricht sicher eingereiht ist. PUBACKs werden in der Reihenfolge gesendet, in der das Gerät veröffentlicht hat.
• Kann eine Nachricht nicht eingereiht werden, erhält sie kein PUBACK (ebenso wenig alles danach auf dieser Sitzung), und die Sitzung wird nach wenigen Sekunden geschlossen. Das Gerät sendet die unbestätigten Nachrichten nach einer Wiederverbindung erneut.
• Ein Gerät darf standardmäßig höchstens 20 unbestätigte QoS-1-Nachrichten gleichzeitig unterwegs haben (das Profil-Feld Max. unbestätigte Nachrichten (MQTT), 1 bis 1.000).
• Duplikate mit demselben Gerät, Schlüssel und Zeitstempel werden nur einmal gespeichert, daher ist erneutes Senden unbedenklich.

Limits

Limit	Standard	Wo es festgelegt wird
Telemetrienachrichten	10:1,300:60 (10 pro Sekunde und 300 pro Minute)	Profil Limits
Telemetrie-Datenpunkte	200:1,6000:60	Profil Limits
Attributnachrichten	5:1,60:60	Profil Limits
Nachrichtengröße	64 KiB, bis zu 1.000 Schlüssel-Wert-Datenpunkte	Profil Max. Nutzlast pro Nachricht (Bytes)
Nachrichten an das Gerät	64 KiB (4 KiB für lizenzierte Geräte)	Profil Max. Downlink-Nutzlast (Bytes)

• Bei Überschreitung eines Limits wird die Nachricht bestätigt und verworfen. Ein Gerät, das sein Limit immer wieder überschreitet (mehr als das Dreifache seines Minutenkontingents innerhalb einer Minute verworfen), wird in seiner Sitzung geschlossen. Eigentümer und Administratoren erhalten pro Gerät und Stunde eine Meldung.
• Eine zu große Nachricht wird vollständig verworfen; die Verbindung bleibt bestehen.
• Ihre Organisation insgesamt hat außerdem Ratenlimits aus ihrem Tarif.
• Gepufferte Messwerte, die ein Gerät nach einem Ausfall sendet (jeder Datensatz trägt einen älteren ts), müssen ebenfalls in das Profil-Feld Wiedergabe-Nachrichten pro Sekunde passen.
• Telemetrie- und Attributnachrichten zählen auf Ihr monatliches Nachrichtenkontingent; Verbindungsereignisse, Befehle und Alarme nicht. Siehe Nachrichtenkontingent und Nutzung.

CONNACK-Codes

Code	Bedeutung	Was das Gerät tun sollte
0	Akzeptiert	Fortfahren.
1	Protokollversion nicht unterstützt	Keine Wiederholungen; Client korrigieren.
2	Client-ID abgelehnt	Anhalten, bis sich die Konfiguration ändert.
3	Server nicht verfügbar: Der Dienst ist ausgelastet, startet oder stoppt, oder die Adresse ist kurzzeitig gesperrt	Zurückweichen und mit Jitter erneut versuchen.
4	Falscher Benutzername oder falsches Passwort	Mindestens 5 Minuten warten (bis zu 1 Stunde).
5	Nicht autorisiert: Gerät deaktiviert, Zertifikat widerrufen oder abgelaufen, Organisation gesperrt oder über ihrem Geräte- oder Verbindungslimit, Anmeldetyp, Netzwerk oder Port vom Profil nicht erlaubt	Mit dem langen Zeitplan zurückweichen.

Der Grund für Code 5 wird nie an das Gerät gesendet. Er wird im Reiter Log des Geräts festgehalten.

Trennungsgründe

Der Reiter Log des Geräts zeigt, warum eine Sitzung beendet wurde:

Grund	Bedeutung
client_disconnect	Das Gerät hat die Verbindung geschlossen.
keepalive_timeout	Innerhalb der Keepalive-Zeit kam nichts an.
takeover	Eine andere Verbindung desselben Geräts hat die Sitzung übernommen.
auth_revoked	Anmeldedaten, Gerät oder Organisation sind nicht mehr zugelassen.
rate_limit	Das Gerät hat sein Ratenlimit wiederholt überschritten.
server_shutdown	Der Broker-Knoten wurde neu gestartet; neu verbinden.
protocol_error, inflight_exceeded, socket_error	Der Client hat das Protokoll verletzt, zu viele unbestätigte Nachrichten gesendet, oder das Netzwerk ist ausgefallen.

Empfohlenes Geräteverhalten

1. Über TLS mit Host-Namen verbinden, Keepalive zwischen 30 und 300 Sekunden.
2. Nach CONNACK 0 die Downlink-Topics abonnieren, gemeinsame Attribute abfragen, Client-Attribute melden und dann gepufferte Telemetrie vor Live-Daten senden.
3. Verwenden Sie QoS 1 und warten Sie auf PUBACK, bevor Sie einen zwischengespeicherten Messwert löschen.
4. Bündeln Sie Messwerte, wenn Sie mehr als eine Probe pro Sekunde senden.
5. Bei einer abgelehnten Verbindung folgen Sie dem Backoff der CONNACK-Tabelle; fügen Sie zufälligen Jitter hinzu, damit sich eine Geräteflotte nicht gleichzeitig neu verbindet.

Verwandte Themen

• MQTT-Themen und Nutzlast-Referenz
• Gerätezugangsdaten
• Geräteprofile
• Ein Gerät verbindet sich nicht