Daten in niotix empfangen

Daten können in niotix aus unterschiedlichsten Quellen, Übertragungstechnologien und Protokollen empfangen werden (technologieagnostisch). Für die Entgegennahme von Daten werden Konnektoren verwendet, die die spezifischen Aufgaben der jeweiligen Übertragungstechnologie übernehmen. Zudem können Daten, die nicht dem erwarteten Datenformat entsprechen, in einem Konnektor transformiert werden. Alle verfügbaren Konnektoren können hier eingesehen werden: Übersicht der Konnektoren.

Daten an Virtuelle Geräte oder Digiale Zwillinge speichern

Um Daten mit Kontext zu versehen, können sie entweder an ein Virtuelles Gerät (digitales Abbild eines physischen Sensors oder Systems) oder einen Digitalen Zwilling (digitales Abbild eines physischen Objekts) geschrieben werden. Die Messwerte werden in sogenannten Datenpunkten gespeichert, die einen historischen Verlauf der einzelnen Messwerte ermöglichen. Es gibt Unterschiede zwischen Virtuellen Geräten und Digitalen Zwillingen, da Daten von Sensoren häufig mehrere Messwerte in einem Datenpaket enthalten, die zudem komprimiert sind und über einen sensorspezifischen “Parser” entschlüsselt werden müssen. Dieser “Parser” ist Teil der Gerätetreiber in niotix. (Doku Gerätetreiber).

Standard Eingangsdatenformat für das Update von Datenpunkten

Datenpunkte können in niotix direkt über einen identifier oder indirekt über routing adressiert werden. Im Folgenden wird das Standardformat für niotix beschrieben. Falls die Daten nicht im Standardformat ankommen, müssen sie über das Template im Konnektor transformiert werden.

Adressieren von Datenpunktupdates mit Identifier

Bei der direkten Adressierung eines Datenpunktes wird die Kombination aus identifier, variable und data verwendet:

{
      "identifier": 42,
      "variable": "consumption",
      "data": {
          "value": 100,
          "time": "2025-03-21T09:26:04Z"
      }
}

• Mit identifier muss passend zu dem im Datenpunkt hinterlegten Datenpunkt sein. Da die Bennung von Variablen häufig mehrfach in einem Account vorkommt, dient dies dazu das korrekte Ziel zu identifizieren. Siehe [1]
• Die variable muss passend zu der Variable im Datenpunkt sein. Siehe [2]
• data enthält die Informationen valueund time
  • value enthält den Messwert der an den Datenpunkt geschrieben werden soll
  • time enthält den Zeitstempel der an den Messwert geschrieben werden soll. Ist dieser Parameter nicht gesetzt, so wird die aktuelle Systemzeit verwendet.

Das passende Beispiel für eine Konfiguration eines Datenpunktes:

Adressieren von Datenpunktupdates über Datenrouting

Da eine direkte Verknüpfung eines Datenpunktes zu einem Konnektor und Idenitifier für einige Prozesse, wie zum Beispiel die Wechsel auf einen anderen Konnektor oder das schreiben der Daten Datenpunkte eines anderen Objektes viel Aufwand bedeutet gibt es zusätzlich die Möglichkeit Datenpunkte von Digitalen Zwillingen über routing zu adressieren:

{
    "routing": {
        "refKey": "42"
    },
    "variable": "volume",
    "data": {
        "value": 900,
        "time": "2025-03-21T10:45:04Z"
    }
}

• Mit routing können ein oder mehrere Digitale Zwillinge über die Kombination aus Referenz-Id-Schlüssel & Referenz-Id-Wert adressiert werden. Siehe [1]
• Die variable in diesem Fall passend zum Schlüssel des Datenpunktes sein. Siehe [2]
• data enthält die Informationen valueund time
  • value enthält den Messwert der an den Datenpunkt geschrieben werden soll
  • time enthält den Zeitstempel der an den Messwert geschrieben werden soll. Ist dieser Parameter nicht gesetzt, so wird die aktuelle Systemzeit verwendet.

Referenz-Id-Schlüssel & Referenz-Id-Wert werden im Digitalen Zwilling in den Meta-Informationen hinterlegt:

Im Datenpunkt wird im Feld “Schlüssel” die Variable hinterlegt:

Adressieren von Daten für Virtuelle Geräte

Da Datenpakete für Virtuelle Geräte häufig mehrere und komprimierte Messwerte enthalten, besteht hier die Möglichkeit diese über einen Gerätetreiber zu parsen. In diesem Fall wird das Datenpaket an das Virtuelle Gerät mit der Externen Id gesendet, welches zu dem im Konnektor definierten identifier passt. Der am Virtuellen gerät hinterlegte Gerätetreiber definiert dann wie die Daten entschlüsselt und in Zielvariablen aufgeteilt werden soll. Dadurch wird in diesem Fall keine variable benötigt, da diese intern vom Gerätetreiber erzeugt wird. Die erzeugten Zielvariablen werden automatisiert im Virtuellen Gerät als Datenpunkt angelegt und beim erhalt eines neuen Datenpaketes nach dem Durchlaufen des Gerätetreibers aktualisiert.

Datenstruktur für komprimierte Daten (HEX)

{
"identifier":"vd-pass-through",
"data":{
  "value":{
      "payload": "002B406EA710",
      "port": 42
  },
  "time": "2025-03-21T10:30:46.157Z"
  }
}

• Mit identifier wird das gewünschte Virtuelle Gerät adressiert. Die Externe Id des Virtuellen Gerätes muss entsprechend übereinstimmen.
• data enthält die Informationen value und time
  • value enthält die Informationen payload und port:
    • payload enthält den HEX dekodierten Payload der die Messwerte enthält
    • port kann optional übertragen werden, wenn Payload z.B. abhängig von dem Port unterschiedlich dekodiert werden soll.
  • time enthält den Zeitstempel der an den Messwert geschrieben werden soll. Ist dieser Parameter nicht gesetzt, so wird die aktuelle Systemzeit verwendet.

Datenstruktur für Klardaten (JSON)

{
"identifier":"vd-pass-through-json",
"data":{
    "value":{
        "payload": {
          "key1": 23,
          "key2": "value2"
        },
        "port": 42
    },
    "time": "2025-03-21T13:12:01.157Z"
    }
}

• Mit identifier wird das gewünschte Virtuelle Gerät adressiert. Die Externe Id des Virtuellen Gerätes muss entsprechend übereinstimmen.
• data enthält die Informationen value und time
  • value enthält die Informationen payload und port:
    • payload enthält die Schlüssel-Wert-Paare.
    • port kann optional übertragen werden, wenn Payload z.B. abhängig von dem Port unterschiedlich dekodiert werden soll.
  • time enthält den Zeitstempel der an den Messwert geschrieben werden soll. Ist dieser Parameter nicht gesetzt, so wird die aktuelle Systemzeit verwendet.

Mehrere Datenpakete mit einem Request übertragen

Sollen mehrere Datenpakete mit einem Request übertragen werden, so sind diese als Array zu übertragen, z.B.:

[
{
    "routing": {
        "refKey": "42"
    },
    "variable": "volume",
    "data": {
        "value": 900,
        "time": "2025-03-21T10:45:04Z"
    }
},
  {
    "routing": {
        "refKey": "42"
    },
    "variable": "energy",
    "data": {
        "value": 100,
        "time": "2025-03-21T10:45:04Z"
    }
}
]