Zum Hauptinhalt springen

Lektion 3.7 Übersetzerentwicklung

Ein Übersetzer decodiert die Rohdaten-Payload eines Geräts in das flache, kanonische Datenmodell der IoT-Plattform – er verwandelt TempC_SHT oder einen Hex-Blob in temperature, °C. In den vorherigen Lektionen haben Sie Übersetzer verwendet; in dieser bauen, testen und laden Sie Ihren eigenen hoch.

Die vollständige Referenz (Regeln des Datenmodells, vollständige Vorlagen, Tooling) ist das Entwicklerhandbuch Übersetzer entwickeln und die Translator-API. Diese Lektion führt Sie praktisch dort hindurch.

Bevor Sie beginnen​

  • Zugriff auf die Swagger-UI Ihres Servers (https://staging.yggio.net/swagger), um den Übersetzer hochzuladen und an ein Gerät anzuhängen.
  • Node.js installiert, wenn Sie den lokalen Test-Harness ausführen möchten.
  • Grundkenntnisse in JavaScript.

Übung 1 – Warum das Datenmodell wichtig ist​

Öffnen Sie die Datenmodell-Feldtabelle und beachten Sie, dass dieselbe Messgröße immer denselben Feldnamen, dieselbe Einheit und Größe hat – temperature (°C), relativeHumidity (%), batteryVoltage (V). Das ist es, was einen Alarm, ein Dashboard oder ein Grafana-Panel über jedes Gerät hinweg funktionieren lässt. Die goldene Regel: Bilden Sie die Rohnamen eines Geräts auf diese kanonischen Namen ab – erfinden Sie niemals eine neue Schreibweise.

Übung 2 – Einen Übersetzer bauen und testen​

  1. Kopieren Sie eine Vorlage aus Übersetzer entwickeln – beginnen Sie mit Vorlage 1 (einen Referenz-Decoder eines Herstellers einbinden) oder Vorlage 2 (eine Byte-Spezifikation selbst decodieren). Viele Decoder von Herstellern lesen die Payload als Node-Buffer (buf.readInt16BE(...)) – die Anleitung enthält für diesen häufigen Fall eine Buffer-Variante.
  2. Bilden Sie in der Funktion translate die Rohausgabe des Decoders als letzten Schritt auf kanonische Felder ab und rechnen Sie dabei Einheiten um (z. B. mV → V, hPa → Pa).
  3. Testen Sie ihn lokal mit dem Harness (translator-harness.js): Legen Sie Ihre Funktion in translate.js ab, fügen Sie eine echte Payload und die erwartete Ausgabe zum CASES-Array hinzu und führen Sie dann npm install lodash && node translator-harness.js aus. Grün bedeutet: die Sandbox wird identische Logik ausführen.

Übung 3 – Eine klare Beschreibung schreiben​

Die description ist das, was ein Benutzer in der IoT-Plattform liest, um zu entscheiden, ob Ihr Übersetzer passt – schreiben Sie sie gut:

  1. Beginnen Sie mit einem einfachen Satz in normaler Sprache: was das Gerät ist (Hardware) oder was es berechnet (verkettet / Analytics).
  2. Fügen Sie eine Liste ### Decoded output hinzu – `Feldname` (Einheit) - Bedeutung für jedes ausgegebene Feld.
  3. Erklären Sie bei Analytics-/verketteten Übersetzern zusätzlich die Logik, die Eingaben, die sie liest, und den Anwendungsfall. Ihr Nutzen ist aus einer Feldliste allein nicht offensichtlich, sodass eine vage Beschreibung zu einer falschen Anwendung des Übersetzers führt. Beispiel: „Wandelt einen kumulativen Energiezähler in Verbrauch pro Tag/Woche/Monat um, der um Mitternacht Ortszeit zurückgesetzt wird; kombinieren Sie ihn mit set-alarm-energy-consumption, um übermäßigen Verbrauch zu erkennen."

So werden Beschreibung, Datenmodell und Parameter eines Übersetzers dargestellt, sobald er einem Gerät hinzugefügt wurde:

Beispiel einer Übersetzerbeschreibung

Übung 4 – Verpacken und hochladen​

  1. Füllen Sie manifest.json aus (Name, Version, apiVersion, Beschreibung, match, spec, optional parameters) – deklarieren Sie jedes Ausgabefeld in spec mit seinem {type, unit, quantity}.

  2. Führen Sie node translator-build.js aus, um translator.json zu erzeugen.

  3. Senden Sie es per POST an den Translators-Endpunkt in Swagger und hängen Sie es dann über die translatorPreferences des Geräts an ein Gerät an. Alternativ können Sie es direkt im Bereich Translators des Geräts anhängen: Klicken Sie auf + Add translator, filtern Sie nach Namen und klicken Sie auf die (i)-Schaltfläche neben einem Ergebnis, um dessen Beschreibung vor dem Hinzufügen anzuzeigen.

    Add-translator-Auswahl mit Filter und Info-Schaltfläche

  4. Senden Sie (oder simulieren Sie) eine Payload und bestätigen Sie, dass die decodierten, kanonischen Felder am Gerät erscheinen.

Übung 5 – Fehlerbehebung​

Wenn nach einem Update nichts erscheint:

  • Öffnen Sie die Logs des Geräts, filtern Sie nach Type = Debug, Category = System – ein abstürzender Übersetzer protokolliert dort seinen Fehler (6 Stunden aufbewahrt). Kopieren Sie die fehlerhafte Eingabe zurück in den Harness, um das Problem zu reproduzieren.
  • Kein Log vorhanden? Der Übersetzer lief entweder fehlerfrei oder wurde nie ausgelöst – prüfen Sie die Spalte Last reported des Geräts; wenn sie sich aktualisiert hat, lief der Übersetzer.
  • Häufigste Ursache: ein Ausgabefeld, das nicht in spec steht, oder ein nicht-kanonischer Name.

Was Sie gelernt haben​

  • Warum Übersetzer kanonische Feldnamen, Einheiten und Größen ausgeben müssen.
  • Wie man lokal ohne jegliche Infrastruktur der IoT-Plattform testet, einen Übersetzer verpackt und hochlädt.
  • Wie man einen fehlschlagenden Übersetzer über die Geräte-Logs findet und behebt.

Wie geht es weiter​

  • Übersetzer entwickeln – Vorlagen für calculate-, set-alarm- und Analytics-Übersetzer sowie die vollständige Checkliste.
  • Verwandt: Node-RED – ein hervorragendes SDK zum Bauen und Simulieren von Übersetzern. Dies ist die letzte Lektion dieses Moduls.