learn/mqtt

MQTT Topics und Wildcards: + und # mit Beispielen erklärt

Kurze Antwort

Ein MQTT Topic ist eine UTF-8-Zeichenkette aus Ebenen, die durch Schrägstriche getrennt sind, etwa plant/line-3/temp. Der Broker leitet Nachrichten anhand des Topics weiter. Subscriber können in Topic-Filtern zwei Wildcards nutzen: + steht für genau eine Ebene, # für beliebig viele Ebenen und muss am Ende stehen. Publisher veröffentlichen immer auf einem vollständigen Topic ohne Wildcards.

Aktualisiert:

Was ein MQTT Topic ist

Ein MQTT Topic ist die Adresse, an die eine Nachricht veröffentlicht wird. Es ist eine UTF-8-Zeichenkette, die der Broker mit den Abonnements vergleicht, um die Empfänger einer Nachricht zu bestimmen. Topics müssen nicht vorab angelegt werden. Ein Topic existiert, sobald ein Client darauf veröffentlicht oder es abonniert.

Der Schrägstrich / teilt ein Topic in Ebenen (Topic Levels):

plant/line-3/temp
fleet/ev-0042/soc
robot/arm-7/joint-3
enterprise/site-frankfurt/line-3/press-07/temp

Der Standard unterscheidet zwei Begriffe. Der Topic-Name ist das vollständige Topic in einem PUBLISH. Der Topic-Filter steht in einem SUBSCRIBE und darf Wildcards enthalten.

Regeln für Topic-Namen

MQTT 3.1.1 und 5.0 legen folgende Regeln fest:

Regel Beispiel
Groß- und Kleinschreibung zählt plant/Line-3 und plant/line-3 sind verschiedene Topics
Ein Topic hat mindestens ein Zeichen Eine leere Zeichenkette ist kein gültiges Topic
Leerzeichen sind erlaubt, aber unpraktisch plant/line 3 ist gültig
Leere Ebenen sind erlaubt plant//temp hat eine leere zweite Ebene
Ein führender Schrägstrich erzeugt eine leere erste Ebene /plant/line-3 ist nicht dasselbe wie plant/line-3
Das Nullzeichen (U+0000) ist nicht erlaubt
Maximale Länge 65.535 Bytes In der Praxis setzt meist der Broker engere Grenzen
Die Wildcards + und # sind in Topic-Namen verboten Sie sind nur in Topic-Filtern zulässig

Der Broker interpretiert die Bedeutung der Ebenen nicht. plant/line-3/temp ist kein Verzeichnispfad. Die Struktur spielt nur für Wildcards und die Zugriffskontrolle eine Rolle.

Die Single-Level-Wildcard +

Das Pluszeichen + steht für genau eine Topic-Ebene. Es muss eine Ebene vollständig allein belegen.

mosquitto_sub -h broker.example.com -t 'plant/+/temp' -v
Filter plant/+/temp Passt?
plant/line-3/temp Ja
plant/line-4/temp Ja
plant/line-3/press-07/temp Nein, zwischen plant und temp liegen zwei Ebenen
plant/temp Nein, die Ebene für + fehlt
plant//temp Ja, + passt auch auf eine leere Ebene

Ein Filter darf mehrere + enthalten, zum Beispiel fleet/+/+, um für jedes Fahrzeug alle Werte der zweiten Ebene zu erhalten. Ein Filter wie plant/line+/temp ist ungültig, weil sich + die Ebene mit anderen Zeichen teilt.

Die Multi-Level-Wildcard

Das Rautezeichen # steht für beliebig viele Ebenen, auch für null Ebenen. Es muss das letzte Zeichen des Filters sein und eine eigene Ebene belegen.

mosquitto_sub -h broker.example.com -t 'robot/arm-7/#' -v
Filter robot/arm-7/# Passt?
robot/arm-7/joint-3 Ja
robot/arm-7/joint-3/torque Ja
robot/arm-7 Ja, # erfasst auch die übergeordnete Ebene
robot/arm-8/joint-3 Nein

Ungültig sind etwa robot/#/torque (nicht am Ende) und robot/arm-7# (keine eigene Ebene).

Ein Abonnement auf # allein empfängt jede Nachricht auf dem Broker, mit Ausnahme der $-Topics. Zur Fehlersuche auf einem Testsystem ist das hilfreich. Auf einem Produktivsystem kann es eine sehr hohe Nachrichtenrate bedeuten und sollte in der Regel per Zugriffskontrolle gesperrt sein.

$SYS und andere Topics mit $

Topics, die mit $ beginnen, sind für den Broker reserviert. Ein Filter, der mit einer Wildcard beginnt, erfasst sie nicht. Weder # noch +/broker/uptime passen auf $SYS/broker/uptime. Um sie zu empfangen, müssen Sie die erste Ebene ausdrücklich angeben:

mosquitto_sub -h broker.example.com -t '$SYS/#' -v

$SYS/ ist eine verbreitete Konvention für Broker-Statistiken, der Inhalt ist aber nicht standardisiert. Jeder Broker veröffentlicht dort andere Topics. Anwendungen sollten nicht auf Topics veröffentlichen, die mit $ beginnen.

MQTT 5.0 definiert ein weiteres $-Präfix: Shared Subscriptions. Ein Filter wie $share/historians/plant/# verteilt passende Nachrichten auf alle Clients der Gruppe historians, statt jedem eine Kopie zu senden. So teilen sich mehrere Instanzen eines Abnehmers die Last.

So bauen Sie eine MQTT-Topic-Struktur auf

Eine gute Topic-Struktur geht vom Allgemeinen zum Speziellen, damit Wildcards sinnvolle Gruppen auswählen. In der Industrie folgt sie häufig dem Aufbau der Anlage:

enterprise/site/area/line/cell/measurement
enterprise/site-frankfurt/line-3/press-07/temp

Mit dieser Struktur liefert enterprise/site-frankfurt/# alle Daten eines Standorts, und enterprise/+/+/+/temp liefert die Temperatur jeder Maschine über alle Standorte hinweg. Eine solche Struktur ist die Grundlage eines Unified Namespace.

Praxisregeln, die später Ärger ersparen:

  • Nur Kleinbuchstaben verwenden und ein einheitliches Trennzeichen für Wörter, etwa -.
  • Topics nicht mit / beginnen. Das erzeugt eine leere Ebene ohne Nutzen.
  • Leerzeichen und Sonderzeichen vermeiden. Sie sind gültig, erschweren aber Skripte und ACLs.
  • Die Gerätekennung vor den Messwert setzen, etwa fleet/ev-0042/soc, damit fleet/ev-0042/# alles zu einem Fahrzeug liefert.
  • Nutzdaten gehören in die Payload, nicht ins Topic. Keine Messwerte oder Zeitstempel in Topic-Ebenen schreiben. Jedes eindeutige Topic belegt Speicher auf dem Broker und erschwert Abonnements.
  • Zugriffskontrolle mit der Struktur planen. ACLs werden meist als Topic-Filter formuliert. Eine klare Struktur ergibt klare Berechtigungen.
  • Das Schema dokumentieren und prüfen, bevor neue Geräte in Betrieb gehen.

Topics und Retained Messages

Wildcard-Abonnements erfassen auch Retained Messages. Ein Client, der plant/# abonniert, erhält sofort die gespeicherte Retained Message jedes passenden Topics und danach die Live-Daten. Bei einer großen Topic-Struktur können das viele Nachrichten in kurzer Zeit sein. Abnehmer sollten darauf vorbereitet sein.

01ultramq/learn/faq

Häufige Fragen

Was ist der Unterschied zwischen + und # bei MQTT?

Die Wildcard + steht für genau eine Topic-Ebene, # für beliebig viele Ebenen einschließlich null und muss das letzte Zeichen im Filter sein. So passt plant/+/temp auf plant/line-3/temp, und plant/# erfasst alle Topics unterhalb von plant.

Kann ich auf ein MQTT Topic mit Wildcard veröffentlichen?

Nein. Wildcards sind nur in Abonnements erlaubt. Ein PUBLISH braucht einen vollständigen Topic-Namen; enthält er + oder #, wertet der Broker das als Protokollfehler und trennt die Verbindung.

Unterscheiden MQTT Topics zwischen Groß- und Kleinschreibung?

Ja. Plant/Line-3 und plant/line-3 sind zwei verschiedene Topics. Die meisten Teams verwenden deshalb ausschließlich Kleinbuchstaben.

Sollte ein MQTT Topic mit einem Schrägstrich beginnen?

Besser nicht. Ein führender Schrägstrich erzeugt eine leere erste Ebene, sodass /plant/line-3 und plant/line-3 verschiedene Topics sind. Das führt leicht zu Abonnements, die nichts empfangen.

03ultramq/start

Sprechen Sie mit einem Engineer über Ihr Projekt.

Sagen Sie uns, was Sie verbinden möchten, wo es laufen muss und wohin die Daten fließen sollen. Wir antworten per E-Mail.

SUBultramq/#