> For the complete documentation index, see [llms.txt](https://docs.kiloiot.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kiloiot.io/kilo-docs-de/kilo-iot-server/connectors/mqtt-connector/topics-and-device-routing.md).
# Topics und Geräte-Routing
MQTT-Topic-Struktur und Geräte-ID-Routing in Kilo IoT — Platzhalter für Muster, Registerkarten „Mapping/Topic“, zweistufiges Speichern.
Diese Seite behandelt, wie der Kilo IoT Server eine eingehende MQTT-Nachricht einem bestimmten Digital Twin zuordnet: die Struktur eingehender Topics, die **Geräte-ID-Topic** Bedeutung des Feldmusters, die inneren Mapping-/Topic-Unterregisterkarten, den bytegenauen Abgleich zwischen der Device-ID-Eingabe und dem Topic-Segment auf Geräteebene sowie den zweiphasigen Speicherablauf, den die Mapping-Registerkarte erfordert. Lesen Sie dies, bevor Sie MQTT-Geräte in Produktivumgebungen registrieren — die meisten Support-Tickets „Gerät registriert, aber keine Telemetrie“ lassen sich auf eines der hier dokumentierten Muster zurückführen.
## Topic-Form nach der Verarbeitung auf Broker-Seite
Der Broker der Plattform stellt eingehende MQTT-Nachrichten mit einem connector-spezifischen Präfix bereit. Für Cloud MQTT ist das Präfix das Topic-Präfix des Connectors (`iot/{org}/{connection}`). Für External MQTT veröffentlicht die ausgehende Bridge der Plattform eingehende Nachrichten von Ihrem Broker in einen internen Namespace erneut; die Topic-Form auf Geräteebene bleibt erhalten.
Nach dem internen Entfernen des Präfixes lautet das Topic, das für das Routing des Geräts gesehen wird, das Segment auf Geräteebene:
```
Cloud MQTT: plant-3/line-a/EM-4492/data (nach Entfernen des Präfixes)
External MQTT: plant-3/line-a/EM-4492/data (nach Entfernen des Bridge-Namespace)
```
Das Feld Device ID Topic beschreibt nur diese Form auf Geräteebene. Die Connector-Präfix-Behandlung ist intern in der Plattform; der Betreiber konfiguriert sie nicht.
## Erstellen des Device ID Topic
**MQTT-Topic für die Geräte-ID** auf der Connection-Registerkarte des Geräts ist kein Freitextfeld — es ist ein Segment-Builder. Das Topic-Präfix des Connectors ist bereits vorhanden und gesperrt, und Sie fügen jeweils ein Segment mit der **+** Schaltfläche hinzu. Jedes Segment gehört zu einer von zwei Arten:
| Segment | Wofür es verwendet wird |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Textsegment** | Ein wörtlicher Teil des Topics, direkt eingegeben — `meters`, `line-a`, `SENSOR`. Wird exakt mit dem eingehenden Topic abgeglichen. |
| **Device ID** | Kennzeichnet das Segment, dessen Wert *ist* die Gerätekennung. Genau eines ist erforderlich, und der an dieser Position gefundene Wert wird mit dem **Device ID** Feld oben abgeglichen. |
A **Vorschau der Auflösung** unter dem Builder zeigt das vollständige Topic, das das Muster für dieses Gerät erzeugt, damit Sie es vor dem Speichern mit dem vergleichen können, was Ihr Publisher tatsächlich sendet. Ziehen Sie den Device-ID-Chip, um ihn an eine andere Position zu verschieben.
**Woher die Geräte-ID kommt** neben dem Builder legt fest, wo die Kennung gelesen wird — **Topic** (die von Ihnen markierte Position) ist die übliche Wahl.
Beispielhafte Topic-Formen und die nach dem Präfix hinzuzufügenden Segmente:
| Veröffentlichungstopic | Segmente |
| ------------------------------- | --------------------------------------------- |
| `plant-3/line-a/EM-4492/data` | `plant-3` · `line-a` · **Device ID** · `data` |
| `tasmota/PlugKitchen/SENSOR` | `tasmota` · **Device ID** · `SENSOR` |
| `zigbee2mqtt/LivingRoomSensor` | `zigbee2mqtt` · **Device ID** |
| `home/sensors/esp-kitchen/data` | `home` · `sensors` · **Device ID** · `data` |
Für verschachtelte industrielle Topic-Formen wie Sparkplug B (`spBv1.0/{group}/DDATA/{node}/{device}`), fügen Sie den hierarchischen Kontext als Textsegmente hinzu und setzen Sie die Device ID auf das Segment, das den registrierten Gerätedatensatz eindeutig identifiziert.
## Die Device-ID-Eingabe muss mit dem extrahierten Segment bytegenau übereinstimmen
Das Feld Device ID im Gerätedatensatz speichert die kanonische Kennung, nach der die Plattform am Device-ID-Segment sucht. Der Abgleich erfolgt bytegenau: groß-/kleinschreibungssensitiv, leerzeichensensitiv und unicode-sensitiv.
Ein Muster, das Integratoren häufig erwischt: **Die Device-ID-Eingabe entfernt beim Speichern Leerzeichen.** Ein Gerät, das auf `plant-3/line-a/EM 4492/data` (mit einem Leerzeichen in der Geräte-ID) sendet, stimmt nicht mit einer Device ID überein, die als `EM 4492` eingegeben wurde — die Eingabe wird normalisiert zu `EM4492` (oder teilweise gekürzt; das genaue Verhalten ist nicht garantiert). Die Abweichung erfolgt ohne Meldung — beim Speichern erscheint kein Fehler und beim Eintreffen der Telemetrie ebenfalls kein Fehler. Die Mapping-Registerkarte bleibt einfach leer.
Die Empfehlung für Produktivumgebungen: Vermeiden Sie Leerzeichen in Gerätekennungen vollständig. Verwenden Sie Bindestriche (`EM-4492`), Unterstriche (`EM_4492`) oder gar kein Trennzeichen (`EM4492`). Was auch immer Sie wählen: Die veröffentlichende Seite und das Feld Device ID müssen exakt denselben String erzeugen.
## Die Mapping-Registerkarte hat zwei Unterregisterkarten
Wenn Sie die Mapping-Registerkarte eines Geräts öffnen, zeigt die UI eine äußere Registerkarte mit der Bezeichnung **Zuordnung** mit zwei Unterregisterkarten: **Topic** und **Zuordnung**. Wenn Sie die äußere Registerkarte auswählen, landen Sie standardmäßig auf der **Topic** Unterregisterkarte.
* **Topic-Unterregisterkarte** — Device ID Topic, Woher die Geräte-ID kommt, Device ID Payload Path (wenn die Quelle Payload ist), Telemetry topics (metrische Definitionen pro Topic für Veröffentlichungsarten mit einer Metrik pro Topic).
* **Mapping-Unterregisterkarte** — Zeilen mit Connector-Schlüsseln, die Payload-Schlüssel mit normalisierten Metriken verknüpfen.
Ein Gerät, das registriert wurde, ohne die innere Mapping-Unterregisterkarte zu besuchen, hat eine Topic-Konfiguration, aber keine Metrikzuordnungen — selbst wenn der Topic-Abgleich erfolgreich ist und „Zuletzt empfangene Daten“ aktualisiert wird, enthält der Gerätedatensatz keine Telemetrie. Klicken Sie **Weiter** unten auf der Topic-Unterregisterkarte oder klicken Sie auf die innere **Zuordnung** Bezeichnung, um zu den zeilenweisen Schlüsseln zu gelangen.
## Telemetry topics: wann sie konfiguriert werden sollten
Die **Telemetry topics** Zeilen auf der Topic-Unterregisterkarte sind für Veröffentlichungsarten gedacht, bei denen jede Metrik ihr eigenes MQTT-Topic hat — z. B. eine PLC-Bridge, die Leistung an `meters/{deviceId}/power`, Spannung an `meters/{deviceId}/voltage`, Strom an `meters/{deviceId}/current`, jeweils mit einem einzelnen numerischen Wert als Payload.
Für moderne Flat-JSON-Veröffentlichungsschemata — Zigbee2MQTT, Tasmota mit einem SENSOR-Objekt, benutzerdefinierte Firmware, die ein JSON-Statusobjekt ausgibt — sind Telemetry-topics-Zeilen nicht erforderlich. Die Plattform analysiert automatisch jeden Schlüssel in der JSON-Payload und stellt sie als Connector-Key-Kandidaten bereit. Verschachtelte Objekte werden in Pfade in Punktnotation abgeflacht (`{"vibration": {"rms": 0.42}}` wird zu `vibration.rms`).
Konfigurieren Sie Telemetry-topic-Zeilen nur, wenn Sie tatsächlich eine Veröffentlichung mit einem Topic pro Metrik haben oder wenn Sie den automatischen Parser für eine bestimmte Topic-Form überschreiben möchten.
## Dropdown für Connector-Schlüssel: der zweiphasige Speicherablauf
Die **Connector-Schlüssel** Spalte der Mapping-Unterregisterkarte ist ein Dropdown. Die Optionen des Dropdowns stammen aus Payload-Schlüsseln, die tatsächlich vom Gerät empfangen wurden — nicht aus einer frei formulierbaren Texteingabe.
Bei einem brandneuen Gerät ohne historischen Datenverkehr ist das Dropdown leer. Die Plattform weiß noch nicht, was das Gerät sendet, und hat daher nichts, womit sie die Optionen füllen könnte. Das ist beabsichtigt, bedeutet aber, dass der Registrierungsablauf zweiphasig ist:
**Phase 1:**
1. Fügen Sie pro Metrik, die das Gerät erzeugt, eine Mapping-Zeile hinzu.
2. Wählen Sie den **Normalisierter Schlüssel** aus dem Vorlagen-Dropdown. Verwenden Sie **+ Neue Metrik hinzufügen** um bei Bedarf eine neue Sensorvorlage zu erstellen. (Das Modal erstellt sowohl den normalisierten Namen als auch die Sensorvorlage — das Vorab-Erstellen von Namen über die Metriken-Registerkarte ist optional.)
3. Setzen Sie **Datentyp** (Reported State, Telemetry oder Device Metadata — siehe unten).
4. Lassen Sie **Connector-Schlüssel** leer.
5. Speichern Sie den Gerätedatensatz.
**Phase 2:**
6. Stellen Sie sicher, dass das Gerät sendet — bei einem über Z2M gebridgten Gerät, dass die Bridge läuft und das Gerät mindestens einmal gemeldet hat. Bei einer PLC-Bridge, dass der Bridge-Prozess Daten sendet.
7. Öffnen Sie den Gerätedatensatz erneut. Das **Connector-Schlüssel** Dropdown listet jetzt die vom Gerät empfangenen Schlüssel auf.
8. Ordnen Sie jeder Mapping-Zeile einen Payload-Schlüssel zu.
9. Speichern Sie erneut.
Nachfolgende Veröffentlichungen für die zugeordneten Schlüssel werden an die Logs-Registerkarte weitergeleitet.
## Reported State vs Telemetry vs Device Metadata
Die **Datentyp** Dropdown klassifiziert jede Metrik:
* **Reported State** — steuerbare Geräteeigenschaften, deren aktuellen Wert das Gerät veröffentlicht. Der Sollwert eines HVAC-Controllers, der geöffnet/geschlossen-Status eines Ventils, der Ein/Aus-Status eines Aktors. Werte, die das Gerät auch per Befehl ändern kann.
* **Telemetry** — schreibgeschützte Messwerte. Prozessvariablen, Messwerte von Energiemessgeräten, RMS-Werte von Vibrationen, Verbindungsqualität, Umgebungsmessungen. Das Gerät beobachtet sie; es ändert sie nicht.
* **Device Metadata** — Werte, die das Gerät selbst und nicht seinen Betriebszustand beschreiben. Firmware-Version, Hardwaremodell, Seriennummer, Kalibrierungsdatum.
Wählen Sie den Typ, der der betrieblichen Bedeutung entspricht. Reported State eignet sich für Zustandsmaschinenfelder und konfigurierbare Sollwerte; Telemetry eignet sich für Sensorwerte und Diagnosen; Device Metadata eignet sich für statische Geräteidentitätsfelder.
## Zuordnung von Payload-Typ → Metriktyp
Der Typ der Metrikvorlage (Integer, Float, String, Boolean) wird durch die für den Normalisierten Schlüssel ausgewählte Vorlage festgelegt. Stimmen Sie den Vorlagen-Typ auf die Daten ab, die das Gerät tatsächlich sendet:
* **Als String kodierte Enumerationen und Binärzustände** — Werte wie `"OPEN"`/`"CLOSED"`, `"ON"`/`"OFF"`, `"running"`/`"stopped"` kommen als JSON-Strings an. Ordnen Sie sie einem **String** Typ zu. Wählen Sie nicht Boolean — das führt zu Nullwerten.
* **Numerische Skalare** — Integer oder Float, je nachdem, ob das Gerät Dezimalzahlen erzeugt.
* **Freiformtext** — String.
Bei über Zigbee2MQTT gebridgten Geräten listen die [zigbee2mqtt.io](https://www.zigbee2mqtt.io/supported-devices/) Geräteseiten jede Funktion mit einem Typ auf — übersetzen Sie wie folgt:
| Z2M-Feature-Typ | Metriktyp | Beispiel |
| --------------- | ---------- | --------------------------------- |
| `binary` | **String** | `state` (`"ON"`/`"OFF"`) |
| `numeric` | **Zahl** | `brightness`, `linkquality` |
| `enum` | **String** | `power_on_behavior`, `color_mode` |
| `text` | **String** | Freiform-Textfelder |
## Mapping-Registerkarte: Spalte „Wert“ vs. Verlauf auf der Logs-Registerkarte
Nach Phase 2 des Speicherablaufs:
* Die **Wert** Spalte auf der Mapping-Registerkarte wird anhand der neuesten Payload aktualisiert — ein Live-Snapshot. Werte erscheinen, sobald der Topic-Abgleich erfolgreich ist, noch bevor alle Connector-Schlüssel ausgefüllt sind.
* Die **Protokolle** Registerkarte ist der Verlauf pro Sensor. Sie wird nur durch Veröffentlichungen gefüllt, die ankommen *nach* Connector-Schlüssel gespeichert sind. Ältere Veröffentlichungen werden nicht nachträglich normalisiert.
Operativ: Erzeugen Sie nach Abschluss von Phase 2 eine neue Veröffentlichung (ein durch ein Ereignis aufgewecktes Gerät, ein geplannter Bericht, eine Abrufanfrage von der Bridge), um zu bestätigen, dass die Logs-Registerkarte Datensätze empfängt. Wenn das Gerät nur nach Zeitplan oder bei Statusänderung meldet, planen Sie die Validierung anhand dieses Takts.
### Iterative Verfeinerung der Zuordnung
Die anfängliche Zuordnung deckt selten jedes nützliche Feld ab, das ein Gerät bereitstellt. Betreiber stellen nach der Bereitstellung häufig fest, dass das Gerät zusätzliche Schlüssel veröffentlicht — herstellerspezifische Diagnosefelder, undokumentierte Statuswerte, verschachtelte Unterobjekte mit betrieblich relevanten Pfaden. Das empfohlene Muster besteht darin, die Mapping-Registerkarte erneut zu besuchen, nachdem über einen repräsentativen Zeitraum Daten eingegangen sind:
* Untersuchen Sie das **Connector-Schlüssel** Dropdown und die **Wert** Spalte, um genau zu sehen, was das Gerät in der Produktion veröffentlicht.
* Fügen Sie neue Mapping-Zeilen für Felder hinzu, die die Bereitstellung jetzt im Digital Twin haben möchte.
* Legen Sie pro Zeile den passenden Normalisierten Schlüssel und Datentyp fest.
* Speichern.
* Erzeugen Sie eine neue Veröffentlichung, damit die Logs-Registerkarte mit der Aufzeichnung des Verlaufs für die neu zugeordneten Felder beginnt.
Bei Flotten nominal identischer Geräte führen Sie diese Verfeinerung an einer repräsentativen Stichprobe durch, bevor Sie die Zuordnungsänderungen auf den Rest der Flotte ausrollen — Firmware-Versionen können subtile Schlüsselunterschiede einführen.
## Wie es weitergeht
* [Fehlerbehebung](/kilo-docs-de/kilo-iot-server/connectors/mqtt-connector/troubleshooting.md) — Diagnoseverfahren für Topic-Abgleichsfehler und das Muster einer leeren Logs-Registerkarte.
* [MQTT Edge Gateways](/kilo-docs-de/kilo-iot-server/gateways/mqtt-edge-gateways.md) — Muster für industrielle MQTT-erzeugende Bridges, die diese Routing-Pipeline speisen (unter Gateways).
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.kiloiot.io/kilo-docs-de/kilo-iot-server/connectors/mqtt-connector/topics-and-device-routing.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
