Gerätetreiber sind die zentrale Schnittstelle zwischen den Rohdaten der Konnektoren und den Virtuellen Geräten in niotix. Das Feature richtet sich an IoT-Administratoren, die neue Gerätetypen und Anwendungsfälle in niotix aufsetzen. Sie erfüllen drei wesentliche Aufgaben:

1. Transformation der Nutzdaten (Parser)
Gerätespezifische Nachrichten – ob JSON, Hex-, Base64- oder andere Formate – werden in ein einheitliches internes Datenformat mit definierten Variablen überführt. So können z. B. eine JSON-Objektstruktur umgebaut, ein Hex-String dekodiert oder Zeitstempel angepasst werden. Diese Variablen bilden die Grundlage für die Datenpunkte der Virtuellen Geräte, in die die Messwerte geschrieben werden.

2. Bewertung des Gerätezustands (Gerätestatuskonfig)
Über die Gerätestatuskonfig werden gerätespezifische Fehler- und Warnmeldungen (z. B. Batterie, Konnektivität, Sensormeldungen) auf ein einheitliches internes Modell abgebildet. So entsteht ein konsistenter Gesundheitszustand („Health“) pro Virtuelles Gerät, der in der Oberfläche, in Alarmen und in Auswertungen genutzt werden kann – unabhängig vom jeweiligen Herstellerformat.

3. Standard-Downlinks (optional)
Für unterstützte Konnektoren können im Gerätetreiber vordefinierte Downlink-Nachrichten hinterlegt werden (z. B. Reset, An/Aus), die an den Virtuellen Geräten zur Auswahl stehen.

Ein Gerätetreiber fasst damit Parser, Gerätestatuskonfig und ggf. Downlinks für einen Gerätetyp zusammen und wird von allen Virtuellen Geräten dieses Typs gemeinsam genutzt – oder, bei Einsatz von Gerätetemplates, zentral im Template vorgegeben.

Einen vorhanden Gerätetreiber suchen

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

Einen neuen 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 Typ 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:

• Einzel Parser: 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

Auf der Seite zur Einstellung kann ein Einzel Parser, Multi Parser oder Funktions Parser ausgewählt werden. Wenn noch kein Parser gesetzt ist, wählst du zuerst die Parser-Form und öffnest danach die Konfiguration.

Gemeinsame Parser-Felder und Test

Die folgenden Felder und Schritte gelten für alle Parser-Typen:

1. Berechnungsvariablen: Definiere Transformationsformeln oder Berechnungen für Zielvariablen. Weitere Einträge fügst du über das “Plus”-Icon hinzu, Einträge entfernst du über das “Papierkorb”-Icon.
2. Typ-Definition: Lege den Datentyp der Zielvariablen fest (z. B. für InfluxDB/Grafana). Die Liste wird automatisch mit den Zielvariablen befüllt. Wähle den passenden Typ, andernfalls Number.
3. Parser Test: Teste mit einer Beispiel-Payload und prüfe das Ergebnis über den Button “Parsen”. Bei Funktions Parser (JavaScript) kann console.log im Code verwendet werden – die Ausgabe wird im Parser Tester angezeigt und unterstützt beim Debuggen.
4. Parser wechseln: Beim Wechsel der Parser-Form werden bestehende Eingaben gelöscht.

Einzel Parser

Wähle diesen Parser für einfache 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. Nutze optional einen vordefinierten Einzel Parser als Startpunkt.
3. Lege im Feld “Parser” die Bits und Typen (Integer, Boolean, String, Float) für die Zielvariablen fest (z. B. Temperatur).
4. Nutze danach die gemeinsamen Schritte aus Gemeinsame Parser-Felder und Test.

Multi Parser

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. Konfiguriere je Ziel-Parser im Feld “Parser” die Bits und Typen für die Zielvariablen.
3. Definiere je Ziel-Parser im Feld “Ziel Parser Berechnung” die Transformationsformeln.
4. Klicke auf “Standardparser editieren”, um den Fallback-Parser zu konfigurieren. Dieser greift, wenn keine Switch-Regel passt.
5. Konfiguriere den Standardparser wie einen Einzel Parser.
6. Nutze für alle Parser (Switch-Ziele und Standardparser) die gemeinsamen Schritte aus Gemeinsame Parser-Felder und Test.

Funktions Parser

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 nutzen.

Häufig stellen Hardwareanbieter JavaScript-Parser für den LoRaWAN-Netzwerkserver “Things Stack” bereit. Eine Beschreibung zur Einbindung dieser Parser findest du im Abschnitt Best Practices.

1. Nutze die Kurz-Anleitung im Dialog als Einstieg und Beispielvorlage.
2. Trage den Parser-Code im Feld “Parser” ein. Über die Auswahl oberhalb des Feldes wechselst du zwischen Elixir, JavaScript und URL Payload Parser.
3. Nutze anschließend die gemeinsamen Schritte aus Gemeinsame Parser-Felder und Test.

Anforderungen an JavaScript Packet Decoder (niotix)

Wenn du einen JavaScript-Decoder in niotix einsetzt (z. B. aus einer Herstelleranleitung), sollte dein Decoder folgende Voraussetzungen erfüllen.

Ziel und Schnittstelle

Ein Decoder wandelt eingehende Payloads in strukturierte Messwerte um, die in niotix als States gespeichert werden.

• Eingang: payload, meta
• Ausgang: Objekt, null oder Liste von Objekten (Extended Return Structure)
• Skriptsprache: JavaScript
• Export-Pflicht: module.exports = ...

Laufzeitumgebung

• Node.js Runtime (backend/unify-service): v22.16.0 (Stand: 18.02.2026)
• Ausführung: in einer gesicherten VM (Sandbox)

Erlaubte globale Hilfsmittel im Decoder

Im Decoder sind folgende Bibliotheken/Objekte direkt verfügbar:

• _ (Lodash, mit Security-Blacklist einzelner Funktionen)
• Buffer (gesicherte Implementierung)
• mathjs
• cbor2
• console.log/info/warn/error/debug (wird intern gesammelt)

Nicht verfügbar / gesperrt

Aus Sicherheitsgründen sind unter anderem nicht erlaubt:

• require(...), dynamische Modulnachladung
• process, global, globalThis
• eval, Function(...), Constructor-Chain-Building
• Netzwerkaufrufe wie fetch(...), XMLHttpRequest
• Unsichere Buffer-Methoden wie Buffer.allocUnsafe

Funktionssignatur

Der Decoder muss als CommonJS-Funktion exportiert werden:

module.exports = function (payload, meta) {
  // ...
  return {};
};

Eingabeparameter

1. payload
   • Hex-String, z. B. "002B406EA710"
   • oder JSON-Objekt/Array (je nach Inbound-Quelle)
2. meta (Objekt), typische Felder:
   • meta.lora.fport (LoRaWAN Frame Port zur Unterscheidung von Nachrichtentypen)
   • meta.source_time (Quellzeitpunkt der Nachricht, falls vom Inbound mitgeliefert)
   • meta.device_id (eindeutige ID des sendenden Geräts in niotix)
   • meta.device_driver_id (ID des zugeordneten Gerätetreibers)

Rückgabeformat

Standard (ein Datensatz):

{
  battery: 43,
  temperature: 3.72,
  port: 1,
  raw: "002B406EA710"
}

Extended Return Structure (mehrere Datensätze pro Paket):

[
  {
    temperature: 20.1,
    pressure: 777,
    meta: { time: "2026-01-01T12:34:56Z" }
  },
  {
    temperature: 20.3,
    pressure: 778,
    meta: { time: "2026-01-01T12:39:56Z" }
  }
]

Semantik und Feldregeln

• meta.time (ISO-8601-String) überschreibt den Paket-Timestamp.
• Interne niotix-Keys sollten nicht als Messwert-Keys genutzt werden: _raw, _health, _parsed.
• Bei Extended Return Structure ist meta für Zeit-/Routing-Metadaten reserviert.
• Rückgabe null ist erlaubt (kein Datensatz).

Zeit- und Größenlimits (Standardwerte)

• Skript-Timeout: 1000 ms
• Parameter-Tiefenlimit: 120
• Parameter-Größenlimit: 1,000,000 Zeichen
• Buffer-Limits:
  • max. Allokation pro Buffer: 1 MB
  • max. Gesamtallokation pro Ausführung: 10 MB
  • max. Anzahl Buffer: 100

Hinweis: Diese Limits können instanzspezifisch konfiguriert werden.

Empfehlungen für robuste Decoder in niotix

• Decoder deterministisch und ohne Seiteneffekte schreiben.
• Nur benötigte Felder zurückgeben (flaches, stabiles Output-Schema).
• Datentypen konsistent halten (z. B. Temperatur immer Number).
• Bei Sammeltelegrammen die Extended Return Structure verwenden.
• Bei Fehlern defensiv programmieren (ungültige Payloads abfangen).

Mindest-Testfälle vor produktivem Einsatz

1. Gültiger Beispiel-Payload -> erwartetes Objekt
2. Ungültiger/zu kurzer Payload -> robuster Fehlerpfad
3. Optional: Extended Return Structure mit 2+ Zeitpunkten
4. Grenzwerte (Min/Max, Vorzeichen, Endianness)
5. Regressionstest mit realem Hersteller-Telegramm

Was du vom Hersteller anfordern solltest

• Decoder-Code (module.exports = function(payload, meta) { ... })
• Kurzbeschreibung der dekodierten Felder inkl. Einheit
• Beispiel-Eingänge (Hex/JSON) und erwartete Ausgabe
• Hinweise zu Sonderfällen (Fehlercodes, Firmware-Versionen, optionalen Bytes)

Extended Return Structure

Mit der Extended Return Structure kann ein Funktions Parser statt eines einzelnen Ergebnisobjekts eine Liste von Ergebnisobjekten zurückgeben. So kannst du mehrere Messwerte aus einem Paket mit unterschiedlichen Zeitpunkten in States schreiben, z. B. bei Sammeltelegrammen.

Die formalen Anforderungen, Feldregeln und ein vollständiges Rückgabebeispiel findest du im Abschnitt Anforderungen an JavaScript Packet Decoder (niotix).

Das funktioniert auch bei MQTT- und WebHook-Inbound für Virtuelle Geräte, wenn bereits geparste Payloads als Liste von Objekten übergeben werden.

URL Payload Parser

Diese Art Parser kommt zum Einsatz, wenn ein über HTTP erreichbarer externer Dienst die Payload-Umwandlung übernehmen soll. niotix sendet bei jedem eingehenden Paket einen HTTP POST an die im Gerätetreiber hinterlegte URL und erwartet eine JSON-Antwort mit den dekodierten Werten.

Ablauf:

1. Bei eingehender Gerätenachricht wird der Request an die konfigurierte URL gesendet.
2. Request: HTTP POST, Body als JSON (Content-Type: application/json). Enthalten sind die Rohdaten sowie Metadaten (z. B. Gerät, Port, Zeitstempel).
3. Antwort: Der Dienst muss innerhalb des Timeouts mit einem JSON-Body antworten (siehe unten). Die zurückgelieferten Werte werden – wie beim JavaScript-Parser – optional über die Berechnungsvariablen des Gerätetreibers nachbearbeitet und den Datenpunkten zugeordnet.

Request-Body (Beispiel):

Das an die URL gesendete JSON-Objekt hat folgende Struktur:

{
  "payload": "002B406EA710",
  "meta": {
    "device_id": 12345,
    "device_driver_id": 67,
    "source_time": "2026-02-19T10:00:00.000Z",
    "lora": { "fport": 1 }
  }
}

• payload: Die Roh-Payload (z. B. Hex-String oder bereits als Objekt/Array, je nach Konnektor).
• meta: Metadaten zur Nachricht (Virtuelles Gerät, Gerätetreiber, Quellzeit, bei LoRaWAN der FPort).

Erwartete Antwort:

• Erfolg: JSON-Objekt mit Feld result, das die dekodierten Variablen enthält (z. B. { "result": { "temperature": 20.1, "battery": 88 } }).
• Fehler: Optional kann der Dienst error setzen; niotix wertet das als Parserfehler und bricht die Verarbeitung entsprechend ab.

Voraussetzungen:

• URL: Es muss eine gültige URL konfiguriert werden (z. B. https://parser.example.com/decode). Die URL wird beim Speichern des Gerätetreibers validiert.
• Erreichbarkeit: Der Parser-Dienst muss vom niotix-Backend (unify-service) aus per HTTP/HTTPS erreichbar sein. Lokale Adressen (z. B. localhost) sind nur nutzbar, wenn der Dienst im gleichen Netz wie niotix läuft.
• Timeout: Die Antwort muss innerhalb von 5 Sekunden erfolgen. Andernfalls bricht niotix die Anfrage ab und die Verarbeitung schlägt fehl.
• Berechnungsvariablen: Wie beim Funktions Parser (JavaScript) können im Gerätetreiber Berechnungsvariablen definiert werden; sie werden auf das vom externen Dienst zurückgelieferte result angewendet.

Ein Beispiel-JSON für Request und Antwort findest du in der Parser-Kurzanleitung im System.

Gerätestatuskonfig

Diese Funktionalität erlaubt es, den Gesundheitszustand eines Virtuellen Geräts anhand der verfügbaren Variablen zu ermitteln.

Herkunft der Konfiguration:

• Wenn ein Gerätetemplate verwendet wird: Die Gerätestatuskonfig wird aus dem Gerätetemplate übernommen. Die Konfiguration kann im Gerätetemplate gepflegt und auf die verknüpften Virtuellen Geräte synchronisiert werden. Details dazu finden sich in der Dokumentation Gerätetemplates.
• Wenn kein Gerätetemplate verwendet wird: Die Gerätestatuskonfig wird aus dem Gerätetreiber übernommen. Beim Anlegen eines Virtuellen Geräts wird diese Konfiguration in den “Health”-Datenpunkt kopiert und kann dort gerätespezifisch angepasst werden. Die Konfiguration im Gerätetreiber entspricht einer allgemeinen Blaupause für alle Anwendungsfälle ohne Template.

Erweiterter/Experten Modus: Hier kann der erweiterte Modus aktiviert werden, in dem die Konfiguration als JavaScript hinterlegt werden kann, um beispielsweise verschachtelte Bedingungen abzubilden.

Auf Virtuelle Geräte anwenden: Über diese Funktion lässt sich die Konfiguration auf alle verknüpften Virtuellen Geräte ausrollen. Diese Option ist nur relevant, wenn kein Gerätetemplate verwendet wird.

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 Alarmberichte 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: Bezieht sich auf Batteriefehler eines Geräts.
• Konnektivität: Bezieht sich auf das erwartete Sendeverhalten eines Geräts (z. B. mindestens ein Paket pro 24 Stunden).
• Gerät: Bezieht sich auf gerätespezifische Fehler, die ein Sensor anbietet, wie beispielsweise “Systemfehler” oder “Manipulationsalarm”.

Meldungstext: Möglichst kurzer, für Nutzer verständlicher Text, worum es bei diesem Eintrag geht. Dieser Text wird in der Benutzeroberfläche an den Virtuellen Geräten oder im Alarmprotokoll angezeigt.

Datenpunkt: Variable (bzw. im Virtuellen Gerät der daraus resultierende Datenpunkt) angeben, anhand derer die Bedingung ausgewertet 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ätetreiber 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ätetreiber 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.
• Encoding: Wähle zwischen den Codierungen base16, base64 oder utf8.
• Gateway IDs: Gib die ID des Gateways 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.

Einen vorhandenen Gerätetreiber löschen

Auf der Übersichtsseite befinden sich hinter jedem Gerätetreiber zwei Icons zum Bearbeiten und zum Löschen. Über das “Papierkorb”-Icon kann der Gerätetreiber gelöscht werden. Bei erfolgreicher Löschung erscheint eine Bestätigungsmeldung.

Was beim Löschen passiert:

• Der Gerätetreiber wird dauerhaft entfernt. Parser-Konfiguration, Gerätestatuskonfig und Standard-Downlinks dieses Typs sind danach nicht mehr verfügbar.
• Virtuelle Geräte, die diesen Gerätetreiber genutzt haben, können keine neuen Daten mehr über die bisherige Parser-Logik verarbeiten. Vor dem Löschen sollten betroffene Virtuelle Geräte entweder einem anderen Gerätetreiber zugeordnet oder die Zuordnung geklärt werden.

Verwandte Seiten

• Virtuelle Geräte – Anlegen und Konfiguration von Virtuellen Geräten inkl. “Health”-Datenpunkt
• Gerätetemplates – zentrale Konfiguration inkl. Gerätestatuskonfig für viele Virtuelle Geräte