Node Red

Einführung

Node-RED ist ein flussbasiertes, low-code Werkzeug zum Verbinden von Hardware, APIs und Onlinediensten. Mit der IoT-Plattform erfüllt es mehrere Zwecke:

• Als Software Development Kit zum Erstellen und Validieren von Übersetzern und Flow-Komponenten der IoT-Plattform.
• Als Simulationswerkzeug, das den Datenaustausch mit der IoT-Plattform erleichtert, um verschiedene Szenarien zu untersuchen.
• Als Verifikationswerkzeug zur Simulation verschiedener Integrationsmethoden und Protokolle, was die Abnahmetests für neue Softwareversionen der IoT-Plattform vereinfacht.
• Als Integrationswerkzeug, das Verbindungen zu verschiedenen Drittanbieterdiensten und -systemen ermöglicht.

Node-RED hat jedoch auch seine Grenzen. Es erfordert Kenntnisse in der JavaScript-Programmierung und arbeitet als Single-Tenant-System, wodurch es an Skalierbarkeit mangelt. Zudem bietet es nur einen grundlegenden Schutz vor unbefugtem Zugriff durch einen einfachen Anmeldebildschirm, weshalb ein strikter Firewall-Schutz erforderlich ist.

Was Sie tun können (und wo Sie anfangen)

Ihr Ziel	Beginnen Sie mit
Geräte simulieren / Testdaten in die IoT-Plattform einspeisen	Erste Schritte - der MQTT-Beispiel-Flow
Die Daten der IoT-Plattform über die REST-API lesen	Erste Schritte - der REST-Teil des Beispiel-Flows
Übersetzer erstellen, testen und hochladen	Übersetzer der IoT-Plattform mit Node-RED erstellen
Geräteübergreifende Datenflüsse erstellen (additionalDeviceUpdates)	Datenflüsse

Voraussetzungen

• Node-RED installiert auf einem Computer oder Server (nodered.org).
• Ein Konto auf der IoT-Plattform mit Zugriff auf die Swagger-UI Ihres Servers (https://staging.yggio.net/swagger) - wird verwendet, um ein API-Token zu erhalten und um MQTT-Topics zu reservieren / Zugangsdaten zu erstellen.
• Netzwerkzugriff von Node-RED zum MQTT-Broker und zur REST-API der IoT-Plattform. Betreiben Sie Node-RED hinter einer Firewall (es hat nur ein einfaches Login).
• Grundlegende JavaScript-Kenntnisse für die REST-API- und Übersetzerarbeit.

Erste Schritte

Installieren Sie Node-RED auf einem Computer oder Server gemäß den Node-RED-Anweisungen. Der einfachste Weg, Daten mit der IoT-Plattform auszutauschen, sind die Standard-Nodes MQTT in / MQTT out, die auf den MQTT-Broker der IoT-Plattform zeigen - von dort aus können Sie Flows und Dashboards erstellen und Datensätze simulieren. Die REST-API der IoT-Plattform stattdessen zu verwenden ist leistungsfähiger, erfordert aber mehr JavaScript.

Schnellster erster Erfolg. Der Beispiel-Flow unten ist vollständig (6 simulierte Geräte, bidirektionales MQTT, plus REST) - großartig zum Lernen, aber viel auf einmal. Wenn Sie zunächst nur einen einzelnen Datenpunkt in der IoT-Plattform ankommen sehen wollen: Reservieren Sie ein MQTT-Topic (die IoT-Plattform, Schritt 5 unten), fügen Sie einen einzelnen MQTT out-Node hinzu, der darauf zeigt, und veröffentlichen Sie eine kleine JSON-Nachricht wie {"temperature": 21}. Innerhalb einer Minute erscheint ein Gerät in der IoT-Plattform. Importieren Sie dann den vollständigen Flow für das Gesamtbild.

Für einen schnellen Einstieg importieren Sie den folgenden Beispiel-Node-RED-Flow in Ihre Node-RED-Installation:

Node-RED-Beispiel-Flow-JSON

Der Beispiel-Flow zeigt, wie man MQTT verwendet, um simulierte Daten zu veröffentlichen und sie vom MQTT-Broker der IoT-Plattform zu abonnieren. Zusätzlich enthält er ein Beispiel für die Anmeldung mit der REST-API der IoT-Plattform, das Speichern eines Tokens und die Durchführung einer GET-Anfrage an /iotnodes sowie einer Zeitreihe.

Führen Sie die folgenden Konfigurationen in der IoT-Plattform durch:

1. Gehen Sie zum Swagger der IoT-Plattform.
2. Rufen Sie ein gültiges Token von der IoT-Plattform ab, indem Sie zum Endpunkt /auth/local navigieren. Klicken Sie auf „Try it out“, geben Sie Ihren Benutzernamen und Ihr Passwort für die IoT-Plattform ein, klicken Sie auf „Execute“, und kopieren Sie das Antworttoken in die Zwischenablage.
3. Klicken Sie oben rechts auf die grüne Schaltfläche „Authorize“, fügen Sie das Token in das Textfeld ein und klicken Sie auf „Authorize“. Sie sind nun in der API der IoT-Plattform in Swagger angemeldet und können alle APIs ausprobieren.
4. Gehen Sie zum Endpunkt /basicCredentialSet und erstellen Sie ein Basic Credential Set mit einem geeigneten, starken Benutzernamen und Passwort.
5. Gehen Sie zum Endpunkt /reservedMqttTopic, verwenden Sie das basicCredentialSet und reservieren Sie 6 verschiedene Topics für 6 IoT-Nodes in der IoT-Plattform. Das Topic muss der Struktur yggio/generic/v2/[youruniquedeviceid] folgen

Führen Sie die Konfigurationen in Node-RED durch:

1. Importieren Sie den Beispiel-Flow.
2. Aktualisieren Sie im oberen linken „Start“-Node den Benutzernamen und das Passwort, damit sie mit Ihren Zugangsdaten auf der IoT-Plattform übereinstimmen, um die Nutzung der REST-API zu ermöglichen.
3. Fügen Sie in einem der MQTT-Out-Nodes, die Geräte auf der IoT-Plattform repräsentieren, einen neuen MQTT-Server mit derselben URL wie die URL der IoT-Plattform hinzu und geben Sie im Abschnitt „Security“ Ihren Benutzernamen und Ihr Passwort ein.
4. Fügen Sie das Topic für Gerät 1 hinzu, das in Schritt 5 oben erstellt wurde.
5. Wiederholen Sie die obigen Schritte für die restlichen 5 MQTT-Out-Nodes, wobei Sie den zuvor erstellten MQTT-Server verwenden.

Sie können den Flow nun deployen und die REST-API-Integration GET /iotnodes testen, indem Sie oben links auf die Start-Schaltfläche klicken. Sie erhalten eine Fehlermeldung von den Zeitreihendaten, ignorieren Sie diese vorerst. Wenn Sie zu Ihrem Konto auf der IoT-Plattform zurückkehren, sollte nun ein MQTT-Node vorhanden sein, der in regelmäßigen Abständen simulierte Daten empfängt.

Führen Sie die abschließende Konfiguration durch, um bidirektionale Kommunikation zu erhalten:

1. Gehen Sie zu Ihrem Konto auf der IoT-Plattform und klicken Sie auf den neuen MQTT-Node.
2. Gehen Sie zum Tab „Channels“ und erstellen Sie einen neuen MQTT-Kanal. Wählen Sie den Kanaltyp basicCredentialSet und beziehen Sie sich auf die zuvor erstellte basicCredentialSetId.
3. Kopieren Sie das vollständige Topic aus dem MQTT-Kanal in die Zwischenablage.
4. Kehren Sie zu Node-RED zurück, suchen Sie den Node namens Device1-FromYggio und klicken Sie darauf. Dies ist ein MQTT-In-Node.
5. Wählen Sie Ihren bestehenden MQTT-Server aus und fügen Sie das aus der IoT-Plattform kopierte Topic in das Topic-Feld ein.
6. Um den Zeitreihen-API-Aufruf zum Laufen zu bringen, aktualisieren Sie die IoT-Node-ID im unteren der beiden „Prepare API call“ auf die _id im Tab „General“ in der Geräteliste Ihres neuen MQTT-Nodes.
7. Die Konfiguration ist nun abgeschlossen, und Sie können sie deployen. Innerhalb von 1 Minute werden weitere 5 MQTT-IoT-Nodes in der IoT-Plattform erstellt. Sie können beobachten, wie die Daten in Node-RED generiert, an die IoT-Plattform gesendet werden, indem sie auf dem MQTT-Broker der IoT-Plattform veröffentlicht werden, vom MQTT-Broker der IoT-Plattform abonniert, verzögert und dann erneut auf dem MQTT-Broker der IoT-Plattform veröffentlicht werden. Sie werden auch sehen, dass die Zeitreihen-API nun zu funktionieren beginnt.

Um die Simulation in Aktion zu sehen, gehen Sie zur Geräteliste in der IoT-Plattform. Verwenden Sie „Select many“, um die neuen MQTT-Nodes auszuwählen, gehen Sie zu Charts und untersuchen Sie die verschiedenen Felder der Simulation. Mit Node-RED und einigen technischen JavaScript-Programmierkenntnissen können Sie die IoT-Plattform schnell mit verschiedenen Systemen integrieren, Übersetzer der IoT-Plattform erstellen und verifizieren und Flow-Komponenten der IoT-Plattform entwickeln. Sie können auch diese nette Geräteliste-Ansicht importieren, um sie in Echtzeit in Aktion zu sehen: Node-RED-Geräteansicht.txt

Übersetzer der IoT-Plattform mit Node-RED erstellen

Die Grundlagen

Node-RED ist eine hervorragende Wahl als SDK zum Erstellen und Testen von Übersetzern der IoT-Plattform. Beide laufen auf Node.js - derselben JavaScript-Engine - sodass ein Übersetzer, der in einer Node-RED-Simulation funktioniert (und strikt gültiges JavaScript verwendet), sich nach dem Hochladen zur IoT-Plattform über die Übersetzer-API in Swagger gleich verhält.

Zwei Besonderheiten beim Übertragen von Code von Node-RED zur IoT-Plattform.

1. Sandbox-Umfang. Ein Node-RED-Function-Node hat vollen Zugriff auf Node.js; die Übersetzer-Sandbox der IoT-Plattform ist enger gefasst - sie stellt Standard-JavaScript (Date, Math, JSON), lodash (_), Buffer und console.log bereit, aber kein require, keine Timer, kein Netzwerk und kein Dateisystem. Beschränken Sie Ihre translate-Funktion darauf.
2. Konsistenz des Datenmodells. Die Ausgabe eines Übersetzers muss die kanonischen Feldnamen, Einheiten und Größen der IoT-Plattform verwenden - das ist es, was Dashboards, Alarme und nachgeschaltete Übersetzer über jedes Gerät hinweg funktionieren lässt. Lesen Sie vor dem Schreiben von Ausgabefeldern Übersetzer entwickeln und die Feldtabelle in der Referenz Translator API.

Mit der Entwicklung beginnen

Node-RED „mein erster Übersetzer“ JSON

Importieren Sie den obigen Flow in Node-RED. Er besteht aus:

1. Einem Inject-Node.
2. Einem Function-Node, der simulierte Daten generiert.
3. Einem Function-Node, der einen Übersetzer implementiert und das Ergebnis zurückgibt.
4. Einem Debug-Node, um die Daten sichtbar zu machen.
5. Einem Flow, um den Übersetzer und die Spezifikation zu stringifizieren, was im Node-RED-Konsolenlog ausgegeben wird.
6. Einer Spezifikation, die den Übersetzer und seine Ausgabe beschreibt. Die Feldnamen und Datentypen der Spezifikation müssen exakt mit der Ausgabe des Übersetzers übereinstimmen, sonst schlägt die Validierung fehl und es wird kein Ergebnis gespeichert.

Dies ist ein funktionierender Übersetzer, den Sie über die API hochladen und mit jedem Gerät verbinden können, das rssi und snr liefert. Er berechnet einen Signalstärkewert: rssi + snr, wenn snr negativ ist, andernfalls nur rssi. Die spec ist eine Vereinbarung mit dem Endnutzer und muss exakt mit der Ausgabe des Übersetzers übereinstimmen - jede Abweichung führt dazu, dass die Validierung fehlschlägt und das Ergebnis verworfen wird. Für dynamische oder variable Ergebnisse geben Sie diese innerhalb eines JSON-object-Feldes zurück.

Vollständige, kopierbare Vorlagen (Hardware, calculate, set-alarm, Analytics) und einen lokalen Test-Harness finden Sie unter Übersetzer entwickeln. Diese Seite konzentriert sich auf den Node-RED-spezifischen Workflow zum Erstellen und Simulieren.

Hardware-Decoder

Wenn der Hersteller einen Referenz-JavaScript-Decoder bereitstellt, sind Erstellung und Verifikation des Übersetzers meist schnell erledigt. Verwenden Sie denselben Übersetzer-Flow: Fügen Sie den Decoder des Herstellers in den Flow ein und rufen Sie ihn aus translate heraus auf, wobei Sie ihm die Hex-Payload übergeben.

Behalten Sie den Decoder des Herstellers unverändert bei und harmonisieren Sie als letzten Schritt: Bilden Sie seine Rohausgabe auf die kanonischen Feldnamen der IoT-Plattform ab und skalieren Sie die Einheiten korrekt. Geben Sie nicht die Rohausgabe des Decoders direkt zurück - rohe Herstellernamen wie TempC_SHT oder BatV sind keine kanonischen Felder. Im folgenden Beispiel ist rawTranslate der Decoder des Herstellers:

function translate ({encodedData}) {
  const {hexEncoded, port} = encodedData;

  if (!hexEncoded || !port) {
    throw new Error('Expected fields hexEncoded and/or port are missing');
  }

  const decoded = rawTranslate({hexEncoded, port}); // Decoder des Herstellers, unverändert

  // Harmonisieren: Rohe Herstellerfelder in kanonische Yggio-Felder umbenennen und
  // Einheiten auf die kanonische Einheit skalieren (z. B. mV -> V, hPa -> Pa).
  return {
    result: {
      temperature: decoded.TempC_SHT,        // Herstellername -> kanonisches Feld
      relativeHumidity: decoded.Hum_SHT,
      batteryVoltage: decoded.BatV / 1000,   // mV -> V
    },
  };
}

Um den Übersetzer zu verifizieren, benötigen Sie reale Payloads und die erwarteten Ergebnisse für jede Payload. Hersteller stellen üblicherweise Beispiele bereit, die zur Erstellung simulierter Daten für den Übersetzer verwendet werden können. Alternativ können Sie ein reales Gerät in der IoT-Plattform bereitstellen und die von der IoT-Plattform empfangenen Payloads als simulierte Daten für den Übersetzer verwenden.

Wenn kein Referenzdecoder vom Hersteller verfügbar ist, wird das Schreiben eines Decoders zu einer wesentlich größeren Aufgabe, die potenziell von einigen Stunden bis zu Wochen an Entwicklungsarbeit in Anspruch nehmen kann. Dieser Prozess umfasst oft komplexe Bit- und Byte-Verarbeitung, und es werden verschiedene Payloads benötigt, um ein zufriedenstellendes Verifikationsniveau zu erreichen.

Datenflüsse

Das Übersetzermodell der IoT-Plattform ermöglicht es einem Übersetzer, Übersetzungsergebnisse über 'additionalDeviceUpdates' an andere IoT-Nodes zu senden, vorausgesetzt, alle Administratoren eines Geräts haben Schreibzugriff auf die Ziele. Diese Funktion ermöglicht die Verwaltung sehr komplexer Anwendungsfälle und die Echtzeitvisualisierung angereicherter Daten, da Zielnodes je nach Übersetzung dynamisch bestimmt werden können. Die IoT-Plattform unterstützt außerdem atomare Updates von Aggregationsnodes, wodurch sichergestellt wird, dass das Ergebnis unabhängig von der Reihenfolge, in der Daten eintreffen, immer korrekt ist. Da Node-RED die Erstellung von Flows unterstützt, jedoch nicht dynamisch wie die IoT-Plattform, ist es ein hervorragendes Werkzeug zur Entwicklung und Verifikation von Übersetzern, die komplexe und dynamische Datenflüsse implementieren.

Prinzip zur Einrichtung von Datenfluss-Simulationen

1. Entwickeln Sie die Übersetzer mit 'additionalDeviceUpdates' nach der oben beschriebenen Standardmethode, indem Sie erwartete Eingabedaten simulieren und an die Übersetzer weiterleiten.
2. Sobald der Übersetzer fertig ist, laden Sie ihn über die Übersetzer-API zur IoT-Plattform hoch.
3. Kopieren Sie das ursprüngliche, oben auf dieser Seite beschriebene Flow-Beispiel und fügen Sie den neu entwickelten Übersetzer zu den MQTT-Nodes hinzu.
4. Erstellen Sie alle notwendigen 'Generic Nodes', an die Daten weitergegeben werden können.
5. Injizieren Sie Daten mit Node-RED in die Simulation über den MQTT-Broker der IoT-Plattform. Erstellen Sie bei Bedarf mehrere Nodes mit dem Übersetzer und verifizieren Sie alle erwarteten Verhaltensweisen.
6. Abonnieren Sie Daten von MQTT-Nodes und verwenden Sie sie, um alle weiteren erforderlichen Übersetzer zur Verwaltung des vollständigen Datenflusses zu entwickeln.
7. Ein wichtiger Punkt: „additionalDeviceUpdates“ benötigt den Identifikator des Ziel-Nodes; eine einfache Möglichkeit, den Identifikator konfigurierbar zu machen, ist die Verwendung der contextMap.

Beispiel für additionalDeviceUpdates:

function translate(iotnode) {
  const log = _.get(iotnode, 'log');
  const measurementFields = _.get(iotnode, 'contextMap.measurementFields','').split(',');
  const additionalDevice = _.get(iotnode,'contextMap.targetNodeSecret');
  const sourceDevice = _.get(iotnode,'name','unknown').replace(/\W/g, '-');
  let measurements = {};
  let result = {};

    // Transfer selected measurement fields to target node
  if (additionalDevice != undefined && measurementFields != undefined) {
    for (let i = 0; i < measurementFields.length; i++) {
      measurements[measurementFields[i]] = { [sourceDevice]: _.get(iotnode, measurementFields[i]) };
    }
    if (log != undefined && log.message != '')
      result = {
        ...result,
        'log': {
          'message': '',
          'type': '',
          'priority': '',
          'category': ''
        }
      };
  }
  else if (log == undefined || log.message == '')
    result = {
      'log': {
        'message': 'At least one of the 2 fields targetNodeSecret or measurementFields are missing in the contextMap.',
        'type': 'Error',
        'priority': 'Low',
        'category': 'Status'
      }
    }
    return {
      result,
      additionalDeviceUpdates:
        [{
          identifier: {
            secret: additionalDevice
          },
          result: { measurements }
        }],
    };
  }

Fehlersuche

Ihr Übersetzer funktioniert also einwandfrei in der Node-RED-Simulation, aber sobald er zur IoT-Plattform hochgeladen wurde, scheint nichts zu passieren, wenn sich der Node, dem er hinzugefügt wurde, aktualisiert. Ohne klare umsetzbare Informationen fragen Sie sich vielleicht, was als Nächstes zu tun ist. Es gibt drei mögliche Arten von Problemen, die dies verursachen könnten:

Prüfen Sie zuerst die Logs des Geräts. Wenn ein Übersetzer abstürzt, zeichnet die IoT-Plattform den Fehler in den Logs des Geräts auf und bewahrt ihn 6 Stunden lang auf. Öffnen Sie die Logs und filtern Sie nach Type = Debug und Category = System, um ihn zu sehen, und kopieren Sie dann die fehlerhafte Eingabe in Ihre Node-RED-Simulation, um sie zu reproduzieren. Eine erfolgreiche Übersetzung schreibt kein Log, sodass ein leeres Log bedeutet, dass sie entweder einwandfrei lief oder nie ausgelöst wurde - prüfen Sie die Spalte „Last reported“ des Geräts in der Geräteliste, um festzustellen, welches der Fälle zutrifft (wenn es aktualisiert wurde, lief der Übersetzer).

1. Die Validierung der Übersetzerausgabe gegen die Spezifikation schlägt fehl – dies ist der häufigste Grund und wird leicht übersehen. Stellen Sie sicher, dass Sie:

• Alle möglichen Ausgabefelder und ihre Datentypen überprüfen und sicherstellen, dass sie zu 100 % mit der Spezifikation übereinstimmen, einschließlich der Groß-/Kleinschreibung jedes einzelnen Zeichens.
• Datentypen mit Funktionen wie Number(), String() und Array.isArray(myArray) erzwingen, um Abweichungen bei den Datentypen zu vermeiden.
• Bestätigen, dass jedes Ausgabefeld ein kanonischer Feldname der IoT-Plattform ist (oder ein korrekt spezifizierter geräteseitiger) - ein falsch geschriebener oder nicht-kanonischer Name ist eine stille, nachgeschaltete Abweichung.

2. Der Übersetzer stürzt während der Ausführung ab: Wenn der Übersetzer abstürzt, liegt es wahrscheinlich an einer ungenauen Handhabung von Eingabedatenkombinationen. Der häufigste Grund ist der Versuch, einer undefinierten Variable einen Wert zuzuweisen oder sie zu referenzieren.

• Kopieren Sie die an den Übersetzer gesendeten Eingabedaten von der IoT-Plattform und fügen Sie sie zu Ihrer Node-RED-Simulation hinzu. Dies zeigt, ob der Übersetzer abstürzt oder nicht.
• Prüfen Sie, dass Sie nichts außerhalb der Sandbox der IoT-Plattform verwenden (require, Timer, Node-APIs), das in Node-RED zufällig funktioniert, aber nicht in der IoT-Plattform.

3. Der Übersetzer lässt sich in der IoT-Plattform nicht kompilieren: Wenn sich der Übersetzer in der IoT-Plattform nicht kompilieren lässt, könnte das Problem mit fehlenden Semikolons oder anderen Codeproblemen nach der Stringifizierung zusammenhängen.

• Um dies zu beheben, lassen Sie den Code durch Linter laufen, um zu prüfen, ob es sich um gültiges JavaScript und JSON handelt. Es gibt zahlreiche Online-JavaScript-Validatoren, die Sie durch Suche nach „Javascript online linter validation“ finden können.
• Wenn Ihre translate-Funktion Hilfsfunktionen aufruft, stellen Sie sicher, dass diese im hochgeladenen Code enthalten sind - der gesamte Code-String läuft in der Sandbox, sodass eine zurückgelassene Hilfsfunktion „X is not defined“ auslöst.

Siehe auch

• Übersetzer entwickeln - Regeln des Datenmodells, vollständige Übersetzer-Vorlagen, lokaler Test-Harness und Paketierung für den Upload.
• Translator API - das Übersetzer-Objektschema, die translate-Vereinbarung, Verkettung und die kanonische Feldtabelle.