Gerätetreiber dienen der Transformation der gerätespezifischen Nachrichtenformate in ein standardisiertes internes Datenformat mit definierten Variablen. So kann beispielsweise die Objektstruktur einer JSON-Nachricht transformiert oder ein Hex- oder Base64-String dekodiert und die Zeitstempel einer Nachricht angepasst werden. Diese Variablen dienen später beim Anlegen der Virtuellen Geräte als Grundlage für die Verknüpfung von Datenpunkten in welche die Messwerte gespeichert werden.

Nach Gerätetreibern suchen

Auf der Übersichtsseite ist über der Liste mit Gerätetreibern eine Suchleiste, in der du nach einem Typ über den Titel oder der Id suchen kannst. Sobald du einen Buchstaben eingegeben hast, werden dir automatisch die Suchergebnisse angezeigt.

Gerätetreiber anlegen

Um einen neuen Gerätetreiber anzulegen, klickst du auf den Button “Anlegen” oben rechts. Dann öffnet sich ein neues Fenster, in dem du die Angaben zum Typen eingibst

Paket Parser für Gerätetreiber auswählen

Unter dem Reiter “Paket Parser” auf der Detailseite kannst du den Parser für diesen Gerätetreiber konfigurieren. Mit Parsern wird die übertragene Payload des Sensors interpretiert und entschlüsselt. Je nach Payload-Typ können unterschiedliche Parser verwendet werden:

• Einzelparser: Hex-Payload mit einheitlicher Nachrichtenstruktur, z.B. LoRaWAN
• Multi-Parser: Hex-Payload mit unterschiedlichen Nachrichtentypen mit fester Struktur, z.B. LoRaWAN
• Funktions-Parser: Hex-Payload oder JSON-Payload mit beliebigen Nachrichtenstrukturen, z.B. LoRaWAN, NB-IoT, LTE

Du findest auf der Seite zur Einstellung eines Parsers eine Kurzanleitung, um die Konfigurationsdetails besser nachzuvollziehen. Du kannst einen Einzel-Parser, Multi-Parser oder einen Funktions-Parser auswählen. Wenn kein Parser ausgewählt wurde, kannst du die Parser-Form auf der Seite auswählen. Dann öffnet sich ein Fenster, in dem du den Parser konfigurieren kannst.

Einzel-Parser einsetzen

Wähle diesen Parser für Simple-Payloads aus, für die keine komplexen Transformationen erforderlich sind.

1. Klicke auf der Übersichtsseite auf “Einzel-Parser”. So gelangst du auf die Seite mit den Konfigurationsdetails.
2. Oben findest du eine Kurz-Anleitung sowie die Möglichkeit, einen vordefinierten Einzel-Parser einzusetzen.
3. Lege im Feld “Parser” die Bits und Typen (Integer, Boolean, String, Float) für die Zielvariablen fest (z. B. Temperatur). Weitere Zielvariablen fügst du mit einem Klick auf das “Plus”-Icon hinzu. Mit dem “Papierkorb”-Icon entfernst du Variablen.
4. Definiere im Feld “Berechnungsvariablen” Transformationsformeln oder eine Berechnung für die Zielvariablen. Weitere Berechnungen für Zielvariablen fügst du mit einem Klick auf das “Plus”-Icon hinzu. Mit dem “Papierkorb”-Icon entfernst du diese.
5. Lege im Feld “Typ-Definition” den Typ der Zielvariablen im Parser fest. Wenn Messwerte in der InfluxDB indiziert und mit Grafana visualisiert werden sollen, ist es notwendig, den Variablen Typen zuzuordnen. Die Liste ist automatisch mit den Zielvariablen aus den vorherigen Abschnitten befüllt. Wähle einen Typ aus der Liste aus, die sich im Feld “Typ” öffnet, der zur Variable passt. Sollte kein Typ passen, wähle “Number” aus.
6. Teste im Feld “Parser Test”, ob die Definitionen funktionieren, indem du eine Beispiel-Payload verwendest (als Hexadezimalcode codiert). Gebe diese Payload in das angegebene Textfeld ein. Klicke auf den Button “Parsen” und prüfe das Ergebnis.
7. Wenn du die Parser-Form wechseln willst, klicke auf den roten Button “Parser wechseln”. Du wirst auf die Übersichtsseite der Parser-Typen weitergeleitet. Alle zuvor eingegebenen Daten werden gelöscht.

Multi-Parser einsetzen

Wähle diesen Parser für die Interpretation komplexerer Payloads mithilfe eines Switch-Parsers aus. Hier werden verschiedene Einzel-Parser miteinander kombiniert.

1. Klicke auf “Switchparser editieren”, um den Switchparser zu konfigurieren. Es öffnet sich ein Fenster.
2. Oben findest du eine Kurz-Anleitung sowie die Möglichkeit, einen vordefinierten Einzel-Parser einzusetzen.
3. Lege im Feld “Parser” die Bits und Typen (Integer, Boolean, String, Float) für die Zielvariablen fest (z. B. Temperatur). Weitere Zielvariablen fügst du mit einem Klick auf das “Plus”-Icon hinzu. Mit dem “Papierkorb”-Icon entfernst du Variablen.
4. Definiere im Feld “Ziel Parser Berechnung” Transformationsformel oder eine Berechnung für die Zielvariablen. Weitere Berechnungen für Zielvariablen fügst du mit einem Klick auf das “Plus”-Icon hinzu. Mit dem “Papierkorb”-Icon entfernst du diese.
5. Teste im Feld “Parser Test”, ob die Definitionen funktionieren, indem du eine Beispiel-Payload verwendest (als Hexadezimalcode codiert). Gebe diese Payload in das angegebene Textfeld ein. Klicke auf den Button “Parsen” und prüfe das Ergebnis.
6. Klicke auf “Standardparser editieren”, um den Standardparser zu konfigurieren. Es öffnet sich ein Fenster. Wenn die Payload keinem der Einzel-Parser im Switchparser entspricht, wird auf den Standardparser zugewiesen.
7. Erstelle den Standardparser wie oben in der Anleitung für den Einzel-Parser beschrieben.
8. Wenn du die Parser-Form wechseln willst, klicke auf den roten Button “Parser wechseln”. Du wirst auf die Übersichtsseite der Parser-Typen geleitet. Alle zuvor eingegebenen Daten werden gelöscht.

Funktions-Parser einsetzen

Wähle diesen Parser aus, um einen benutzerdefinierten Parser in Javascript oder Elixir zu definieren oder zur Umwandlung der Payload einen externen Parser (URL Payload Parser) zu benutzen.

Häufig stellen Hardwareanbieter Javascript Parser für den LoRaWAN Netzwerkserver “Things Stack” bereit. Eine Beschreibung zur Einbindung dieser Parser befindet sich im Abschnitt Best Practices.

1. Oben findest du eine Kurz-Anleitung mit Beispielen, wie der Parser in Javascript oder Elixir geschrieben wird.
2. In das Befehlsfeld unter “Parser” trägst du den Parser-Code ein. Über das Fenster über dem Feld kannst du zwischen Elixir und Javascript oder dem URL Payload Parser wechseln. Die Funktion des URL Payload Parsers ist im nächsten Kapitel beschrieben.
3. Definiere im Feld “Berechnungsvariablen” Transformationsformeln oder eine Berechnung für die Zielvariablen. Weitere Berechnungen für Zielvariablen fügst du mit einem Klick auf das “Plus”-Icon hinzu. Mit dem “Papierkorb”-Icon entfernst du diese.
4. Lege im Feld “Typ-Definition” den Typ und das Layout der Zielvariablen im Parser fest. Wenn Messwerte in InfluxDB indiziert- und mit Grafana visualisiert werden sollen, ist es notwendig, den Variablen Typen zuzuordnen. Die Liste wird automatisch mit den Zielvariablen aus den vorherigen Abschnitten befüllt. Wähle einen Typ aus der Liste aus, die sich im Feld “Typ” öffnet, der zur Variable passt. Sollte kein Typ passen, wähle “Number” aus.
5. Teste im Feld “Parser Test”, ob die Definitionen funktionieren, indem du eine Beispiel-Payload verwendest (als Hexadezimalcode codiert). Gebe diese Payload in das angegebene Textfeld ein. Klicke auf den Button “Parsen” und prüfe das Ergebnis.

Extended Return Structure

Virtuelle Geräte haben besondere neue Funktionen im Zusammenspiel mit Javascript und Elixir Function Parsern. Es kann vom Parser ein Ergebnisobjekt oder eine Liste von Ergebnisobjekten (Array) zurückgegeben werden. Die Struktur dieser Objektliste wird unten beispielhaft erklärt. Mit dieser Objektliste ist es möglich, mehrere Werte pro Paket zu unterschiedlichen Zeitpunkten zurückzugeben. Dies ist interessant, wenn es sich z.B. um einen Wasserzähler handelt, der täglich 24 Messungen durchführt und die Messungen dann mit den entsprechenden Ablesezeitstempeln einmal am Tag überträgt. Diese 24 Werte können nun am Datenpunkt des Virtuellen Geräts mit dem entsprechenden Zeitstempel hinterlegt werden.

Das funktioniert auch bei MQTT und WebHook Inbound Virtuellen Geräten, hier kann bei z.B. bereits geparster Payload eine Liste von geparsten Payload Objekten übergeben werden.
Das meta Object der erweiterten Rückgabestruktur kann in den Objekten angegeben werden und sorgt dann dafür, dass die Werte mit einem beliebigen Zeitpunkt an den State geschrieben werden können.

module.exports = function (payload, meta) {
  const port = meta.lora.fport;
    
  const buf = Buffer.from(payload, 'hex');
  const battery = buf.readUInt16BE(0);  // parse 2 bytes with offset 0
  const temperature = buf.readFloatBE(2); // parse 4 bytes with offset 2
    
  return [
    {
      battery: battery,
      temperature: temperature,
      meta: {                           // meta tag is optional
        time: "2020-01-01T12:34:56Z"
      },
    },
    {
      battery: battery,
      temperature: temperature,
      meta: {                           // meta tag is optional
        time: "2020-01-01T12:34:56Z"
      },
      }
  ]
}

Wichtig: bei der Extended Return Structure kann es aufgrund der schnellen Verarbeitung der Werte aus dem Array bei hoher Systemauslastung zu Inkonsistenzen bei der Ausführung von Regeln kommen (Regelauswertung mit falschem Wert). Dies ist äußerst selten. Dennoch wird davon abgeraten Sensoren die mehrere Messwerte in einen Paket schicken zu nutzen, wenn der Use Case kritisch ist und Regeln basierend auf den gelieferten Daten ausgeführt werden sollen.

URL Payload Parser

Diese Art Parser kommt zum Einsatz, wenn du einen über HTTP erreichbaren externen Parser einsetzen möchtest. In diesem Fall wird die Payload zum umwandeln an die spezifizierte URI als HTTP POST im “Body” als JSON Objekt gesendet, die Antwort enthält dann die umgewandelte Payload. Ein Beispiel JSON findest du in der Parser Kurzanleitung im System.

Gerätestatuskonfig

Diese funktionalität erlaubt es den Gesundheitszustand eines Virtuellen Gerätes anhand der verfügbaren Variablen zu ermitteln. Bei Anlegen eines Virtuellen Gerätes wird diese Konfiguration in den “Health”-Datenpunkt kopiert und kann dort gerätespezifisch angepasst werden. Die Konfiguration im Gerätetreiber entspricht also einer “allgemeinen Blaupause” die für alle Anwendungsfälle anwendbar sein sollte. Anwendungsfallspezfische Konfigurationen sollten im Virtuellen Gerät selbst oder über ein Gerätetemplate (coming soon) definiert werden.

Erweiterter/Experten Modus: Hier kann der erweitere Modus aktiviert werden in dem die Konfiguration als JavaScript hinterleght werden kann, um beispielsweise verschachtelte Bedingungen abzubilden.
Auf Virtuelle Geräte Anwenden: Über diese Funktion lässt die Konfiguration auf alle verknüpften Virtuellen Geräte ausrollen. Vorsicht! Anpassungen die in einzelnen Geräten gemacht wurden werden dabei überschrieben.
Art: Hier kann definiert werden ob es sich um einen Fehler oder eine Warnung handelt. Diese Unterscheidung kann später in der Auswertung genutzt werden, um beispielsweise nur Alarm-Reports (coming soon) für Geräte zu versenden die einen Fehler, nicht aber eine Warnung haben)
Kategorie: Hier kann für eine Differenzierung in der Auswertung aus folgenden Kategorien gewählt werden:

• Batterie: Diese Kategorie bezieht sich auf Batteriefehler eines Gerätes.
• Konnektivität: Diese Kategorie bezieht sich auf das erwartete Sendeverhalten eines Gerätes (z.B. mindestens ein Paket pro 24 Stunden)
• Gerät: Diese Kategorie bezieht sich auf gerätespezifische Fehler die ein Sensor anbietet, wie besipielsweise “Systemfehler” oder “Manipulationsalarm”

Meldungstext: Möglichst kurzer, für einen Benutzer verständlicher Text worum es bei diesem Fehler geht. Dieser Text wird in der Benutzeroberfläche an den Virtuellen Geräten oder im Alarmprotokoll angezeigt.
Datenpunkt: Hier die Variable (bzw. im Virtuellen Gerät den daraus resultierenden Datenpunkt angeben) anhand dessen die Bedingung ausgewertert werden soll.
Operator: Operator für die Bedingung.
Wert: Vergleichswert für die Bedingung.

Standard-Downlinks konfigurieren

Im Reiter “Downlinks” kannst du Standard-Downlinks für Gerätetreibern konfigurieren. Hiermit lassen sich aus den Geräten in niotix heraus einfache Downlink-Nachrichten an Geräte verschicken, z.B. für den Reset oder das An- oder Ausschalten. Momentan werden nur firefly-Geräte unterstützt. Die Downlinks kannst du nur für Gerätetreibern einsetzen, die nicht digimondo-zertifiziert sind. Kontaktiere deinen DIGIMONDO-Ansprechpartner, wenn du einen Downlink für einen zertifizierten Gerätetreiber erstellen möchtest.

Konfiguriere im Feld “Konfiguration” einen Downlink, in dem du auf den Plus-Button klickst und folgende Angaben einträgst:
Name: Gib den Namen des Downlinks an.
Port: Gib hier den Port ein.
Payload: Gib die Payload an, die versendet werden soll.
Enconding: Wähle zwischen den Codierungen base16, base64 oder utf8.
Gateways IDs: Gib die ID des Gateway an.

Bei Feldern mit Sternchen handelt es sich um Pflichtfelder.

Die definierten Downlinks können an jedem Virtuellen Gerät welches diesen Gerätetreiber verwendet im Tab “Geräte Informationen” –> “Downlink” ausgewählt werden.

Gerätetreiber löschen

Auf der Übersichtsseite findest du hinter jedem Gerätetreiber zwei Icons zum Bearbeiten und zum Löschen. Klicke auf das “Papierkorb”-Icon, um einen Typ zu löschen. Bei erfolgreicher Löschung erscheint eine grün gefärbte Bestätigungsmeldung “Gerätetreiber gelöscht”.