DTDL erklärt: Die Digital Twin Definition Language und ihre Abbildung auf MQTT

DTDL, die Digital Twin Definition Language, ist eine JSON-basierte Methode, um zu beschreiben, woraus ein digitaler Zwilling besteht: welche Telemetrie er aussendet, welche Eigenschaften er hält, welche Befehle er annimmt und wie er mit anderen Zwillingen zusammenhängt. In diesem Artikel erfahren Sie, wie DTDL-Modelle aufgebaut sind, lesen ein vollständiges Beispiel und sehen, wie Sie dieses Modell auf MQTT-Topics abbilden, damit Geräte und Zwillingsanwendungen einen klaren gemeinsamen Vertrag haben.

Wo Modelle im Gesamtbild einzuordnen sind, zeigt unser Leitfaden zur Digital-Twin-Technologie.

Was DTDL ist und warum es das gibt

Wenn zehn Teams unabhängig voneinander Zwillinge bauen, erfindet jedes seine eigene Art zu sagen: „Diese Pumpe hat einen Durchfluss in Litern pro Minute und einen Startbefehl." DTDL standardisiert diese Beschreibung. Es ist eine offene, von Microsoft veröffentlichte Sprache auf Basis von JSON-LD, die von Azure Digital Twins und IoT Plug and Play verwendet wird, doch nichts in der Sprache selbst bindet Sie an eine bestimmte Cloud. Eine DTDL-Datei ist einfach ein Dokument, das einen Asset-Typ beschreibt; Sie können damit Code generieren, Payloads validieren, Oberflächen bauen oder Topic-Verträge dokumentieren.

Die Sprache hat mehrere Versionen durchlaufen; DTDL v3 ist die aktuelle, v2 ist in bestehenden Projekten aber noch weit verbreitet. Die offizielle Spezifikation liegt im DTDL-GitHub-Repository.

Die Bausteine eines DTDL-Modells

In DTDL wird alles innerhalb eines Interface definiert. Ein Interface hat eine Kennung und eine Liste von Inhalten, die jeweils einem dieser Elementtypen entsprechen:

Jedes Modell und jedes Element hat einen DTMI (Digital Twin Model Identifier), etwa dtmi:com:example:Pump;1. Die Zahl am Ende ist die Version. Wenn Sie ein Modell inkompatibel ändern, erhöhen Sie die Version, statt das Modell an Ort und Stelle zu bearbeiten.

Telemetry vs. Property

Bei dieser Unterscheidung liegen Teams am häufigsten daneben. Telemetry ist ein Ereignisstrom: Jeder einzelne Messwert zählt, und die Zwillingsplattform speichert keinen „aktuellen Wert". Properties sind Zustand: Der Zwilling hat immer einen aktuellen Wert, und eine schreibbare Property kann von der Cloud-Seite gesetzt werden (ein Sollwert), während das Gerät seinen tatsächlichen Wert zurückmeldet.

Faustregel: Wenn ein neuer Viewer etwas sofort beim Laden sehen muss, ist es eine Property; wenn es nur als Zeitreihe zählt, ist es Telemetry.

Ein vollständiges DTDL-Beispiel

Hier ein DTDL-v3-Interface für eine Kreiselpumpe:

{
  "@context": "dtmi:dtdl:context;3",
  "@id": "dtmi:com:example:Pump;1",
  "@type": "Interface",
  "displayName": "Centrifugal Pump",
  "contents": [
    {
      "@type": ["Telemetry", "VolumeFlowRate"],
      "name": "flow",
      "schema": "double",
      "unit": "litrePerSecond"
    },
    {
      "@type": ["Telemetry", "Pressure"],
      "name": "dischargePressure",
      "schema": "double",
      "unit": "bar"
    },
    {
      "@type": "Property",
      "name": "running",
      "schema": "boolean"
    },
    {
      "@type": "Property",
      "name": "speedSetpoint",
      "schema": "double",
      "writable": true
    },
    {
      "@type": "Property",
      "name": "firmwareVersion",
      "schema": "string"
    },
    {
      "@type": "Command",
      "name": "resetRunHours"
    },
    {
      "@type": "Relationship",
      "name": "isPartOf",
      "target": "dtmi:com:example:PumpingStation;1"
    }
  ]
}

Semantische Typen wie VolumeFlowRate und Einheiten wie litrePerSecond stammen aus der DTDL-Erweiterung für quantitative Typen. Sie ermöglichen es Tools, Einheiten korrekt darzustellen, ohne zu raten. Die genaue Liste der in Ihrer Zielversion gültigen semantischen Typen und Einheiten finden Sie in der Spezifikation.

DTDL auf MQTT-Topics abbilden

DTDL beschreibt, was ein Zwilling enthält, aber nicht, wie die Daten transportiert werden. MQTT ist ein naheliegender Transport, und ein sauberes Mapping macht aus Ihrem DTDL-Modell einen Topic-Vertrag. Eine praxistaugliche Konvention:

Wenn <asset> ein ISA-95-Pfad wie acme/site1/water/station3/pump2 ist, kann ein Viewer acme/site1/water/# abonnieren und weiß anhand des Modells, wie jede Nachricht zu interpretieren ist. Genau so entsteht ein Unified Namespace (UNS): Die ISA-95-Hierarchie (Enterprise → Site → Area → Line → Cell) gibt die Topic-Struktur auf dem MQTT-Broker vor, etwa acme/werk-stuttgart/montage/linie-1/zelle-3/temperatur, und DTDL beschreibt, was unter jedem Knoten liegt. Struktur und Semantik ergänzen sich also; Hintergründe zum UNS liefert Sparkplug B und Unified Namespace.

Warum die Telemetrie in einer Nachricht pro Asset bündeln? Ein eigenes Topic pro Telemetriefeld vervielfacht die Nachrichtenanzahl, ohne Information hinzuzufügen, und die meisten Konsumenten wollen alle Felder mit demselben Zeitstempel. Properties profitieren von Retained Messages, damit Zwillings-Viewer sofort den aktuellen Zustand erhalten; das Tutorial Digitaler Zwilling mit Retained MQTT zeigt das in der Praxis.

Payloads gegen ein DTDL-Modell validieren

Wenn Sie ein Modell haben, nutzen Sie es auch. Eine kleine Python-Prüfung kann Telemetrie, die nicht zum Interface passt, zurückweisen, bevor sie Ihre Historie verunreinigt:

import json
import paho.mqtt.client as mqtt

with open("pump.json", encoding="utf-8") as f:
    model = json.load(f)

TYPE_MAP = {"double": (int, float), "boolean": bool, "string": str, "integer": int}
telemetry = {
    c["name"]: c["schema"]
    for c in model["contents"]
    if "Telemetry" in (c["@type"] if isinstance(c["@type"], list) else [c["@type"]])
}

def on_connect(client, userdata, flags, reason_code, properties):
    client.subscribe("connectmq/demo/d41f/+/+/+/+/telemetry")

def on_message(client, userdata, msg):
    data = json.loads(msg.payload)
    for name, schema in telemetry.items():
        if name not in data:
            print(f"{msg.topic}: missing {name}")
        elif not isinstance(data[name], TYPE_MAP[schema]):
            print(f"{msg.topic}: {name} should be {schema}")

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id="dtdl-validator-d41f")
client.on_connect = on_connect
client.on_message = on_message
client.connect("broker.connectmq.com", 1883)
client.loop_forever()

Testen Sie es, indem Sie eine Beispielnachricht an den öffentlichen MQTT-Broker publizieren, der für Tests gedacht ist, nicht für Produktionsdaten:

mosquitto_pub -h broker.connectmq.com -p 1883 -i dtdl-pub-d41f \
  -t "connectmq/demo/d41f/acme/site1/station3/pump2/telemetry" \
  -m '{"flow": 12.4, "dischargePressure": "4.1"}'

Der Validator meldet dischargePressure als String statt als Double, genau die Art von Fehler, die sonst Wochen später als kaputtes Diagramm auftaucht.

Checkliste für die DTDL-Modellierung

1. Ein Interface pro Asset-Typ, nicht pro Asset-Instanz.
2. Telemetry für Datenströme, Properties für Zustand, Commands für Aktionen.
3. Components für wiederverwendbare Teile wie Motoren oder Sensoren verwenden.
4. Einheiten nach Möglichkeit über semantische Typen angeben.
5. DTMIs versionieren und eine veröffentlichte Version niemals brechen.
6. Das MQTT-Mapping direkt neben dem Modell im selben Repository dokumentieren.
7. Payloads bei der Aufnahme validieren, nicht nur in der Oberfläche.

DTDL im Vergleich mit anderen Zwillingsmodellen

DTDL ist nicht die einzige Option. Die Verwaltungsschale (Asset Administration Shell) aus dem Umfeld der Plattform Industrie 4.0 setzt auf standardisierte Teilmodelle für Industrie-Assets und ist gerade im deutschsprachigen Maschinenbau verbreitet; siehe Verwaltungsschale erklärt. Eclipse Ditto verwendet eigene JSON-„Things" mit Attributen und Features. Viele Teams nutzen auch einfach ein JSON-Schema pro Asset-Typ. Entscheidend ist ein explizites Modell mit einem dokumentierten Mapping auf den Transport, und genau diese Rolle erfüllt DTDL gut. Wie die Modellschicht neben Messaging, Zustand und Visualisierung steht, beschreibt Architektur digitaler Zwillinge.

Ihren DTDL-basierten Zwilling auf ConnectMQ betreiben

DTDL definiert den Vertrag; einen zuverlässigen Transport brauchen Sie trotzdem. ConnectMQ ist ein verwalteter MQTT-Broker mit Unterstützung für MQTT 3.1.1 und 5.0, Retained Messages für Properties, TLS auf Port 8883 für Geräte und WSS auf Port 8084 für Browser-Zwillinge. Modellvalidierung, Codegenerierung und Zwillingsgraphen laufen in Ihren eigenen Tools, die sich als reguläre MQTT-Clients mit ConnectMQ verbinden. Erstellen Sie unter app.connectmq.com einen Broker im kostenlosen Serverless-Plan, ohne Kreditkarte, und publizieren Sie in wenigen Minuten Ihre erste DTDL-konforme Telemetrie.

Häufig gestellte Fragen

Ist DTDL nur für Azure gedacht?

Nein. DTDL ist eine offene, auf JSON-LD basierende Sprache. Azure Digital Twins nutzt sie nativ, doch Sie können DTDL-Modelle mit jedem Transport verwenden, auch mit MQTT auf einem beliebigen Broker.

Was ist der Unterschied zwischen einer DTDL-Property und Telemetry?

Eine Property ist Zustand mit einem aktuellen Wert, optional schreibbar; Telemetry ist ein Strom von Messwerten, bei dem jeder einzelne Wert zählt, aber kein aktueller Wert gespeichert wird.

Wie bilde ich DTDL-Commands über MQTT ab?

Publizieren Sie den Befehl mit QoS 1 und einer Correlation ID auf ein nicht retained Befehls-Topic und lassen Sie das Gerät das Ergebnis auf ein Antwort-Topic publizieren. Die MQTT-5-Eigenschaften Response Topic und Correlation Data unterstützen das direkt.

Welche DTDL-Version sollte ich verwenden?

Verwenden Sie für neue Projekte DTDL v3, es sei denn, ein Tool, auf das Sie angewiesen sind, unterstützt nur v2.