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 eingehende Konnektoren verwendet, die die spezifischen Aufgaben der jeweiligen Übertragungstechnologie übernehmen. Jeder eingehende Konnektor bietet die Möglichkeit, über ein konfigurierbares Template eingehende Daten in das auf dieser Seite beschriebene Standardformat zu transformieren – dies ist erforderlich, wenn das Quelldatenformat vom Standardformat abweicht. Die verfügbaren eingehenden Konnektoren sowie die Template-Konfiguration sind hier beschrieben: Eingehende Konnektoren.

Daten an Virtuelle Geräte oder Digitale Zwillinge senden

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. Geräteabhängige Transformationen – z.B. das Parsen von HEX-Payloads oder die Zuordnung von Rohwerten zu Zielvariablen – werden im Gerätetreiber definiert.

Je nach Zielobjekt unterscheiden sich das Eingangsdatenformat und die Art der Adressierung:

Daten an ein Virtuelles Gerät senden

Datenpakete für Virtuelle Geräte werden über den identifier adressiert, der mit der Externen Id des Virtuellen Geräts übereinstimmen muss. Da Datenpakete häufig mehrere und komprimierte Messwerte enthalten, kann der am Virtuellen Gerät hinterlegte Gerätetreiber die Daten entschlüsseln und auf Zielvariablen aufteilen. (Doku Gerätetreiber)

Klardaten (JSON-Payload)

Bei Klardaten werden die Messwerte als JSON-Objekt unter data.value.payload übergeben:

{
  "identifier": "device-42",
  "data": {
    "value": {
      "payload": {
        "temperature": 23.5,
        "humidity": 60
      }
    },
    "time": "2025-03-21T13:12:01.157Z"
  }
}

• identifier: Externe Id des Virtuellen Geräts.
• data.value.payload: JSON-Objekt mit den Schlüssel-Wert-Paaren der Messwerte. Die Schlüssel entsprechen den Zielvariablen, die im Gerätetreiber definiert sind.
• data.time: Zeitstempel des Paketeingangs. Ohne diesen Wert wird die aktuelle Systemzeit verwendet.

Komprimierte Daten (HEX-Payload)

Bei HEX-Payloads wird der kodierte Payload als String übergeben. Der am Virtuellen Gerät hinterlegte Gerätetreiber übernimmt die Dekodierung:

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

• identifier: Externe Id des Virtuellen Geräts.
• data.value.payload: HEX-kodierter Payload mit den Messwerten.
• data.value.port (optional): Port-Nummer, wenn der Payload abhängig vom Port unterschiedlich dekodiert werden soll.
• data.time: Zeitstempel des Paketeingangs. Ohne diesen Wert wird die aktuelle Systemzeit verwendet.

Mehrere Pakete als Array

Sollen mehrere Datenpakete in einem einzigen Request übertragen werden, werden die Objekte als JSON-Array übergeben:

[
  {
    "identifier": "device-42",
    "data": {
      "value": {
        "payload": {
          "temperature": 23.5,
          "humidity": 60
        }
      },
      "time": "2025-03-21T13:12:01.157Z"
    }
  },
  {
    "identifier": "device-43",
    "data": {
      "value": {
        "payload": {
          "temperature": 21.0,
          "humidity": 55
        }
      },
      "time": "2025-03-21T13:12:05.157Z"
    }
  }
]

Daten an einen Digitalen Zwilling senden

Datenpunkte in Digitalen Zwillingen können über zwei Verfahren adressiert werden: über das Dynamische Datenrouting (Standard) oder über eine Direktadressierung per Identifier (wenn als Datenquelle „Konnektor" konfiguriert ist).

Dynamisches Datenrouting (Standard)

Das Standard-Verfahren für Digitale Zwillinge ist das Dynamische Datenrouting. Über routing können ein oder mehrere Digitale Zwillinge über die Kombination aus Referenz-Id-Schlüssel und Referenz-Id-Wert adressiert werden. Dieses Verfahren ist besonders dann vorteilhaft, wenn Datenpunkte verschiedener Digitaler Zwillinge über denselben Konnektor befüllt werden oder ein Konnektor-Wechsel ohne Neukonfiguration der Datenpunkte möglich sein soll:

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

• routing: Objekt mit genau einem Schlüssel-Wert-Paar. Der Schlüssel (stationsId im Beispiel) entspricht dem im Digitalen Zwilling konfigurierten Referenz-Id-Schlüssel; der Wert ("42") dem zugehörigen Referenz-Id-Wert. Alle Digitalen Zwillinge mit übereinstimmendem Schlüssel und Wert werden adressiert. Siehe [1]
• variable: Schlüssel des Datenpunktes im Digitalen Zwilling. Siehe [2]
• data.value: Messwert, der an den Datenpunkt geschrieben wird.
• data.time: Messzeitpunkt. Ohne diesen Wert wird die aktuelle Systemzeit verwendet.

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

Im Datenpunkt wird im Feld „Schlüssel" die Variable hinterlegt:

Direktadressierung über Identifier (Datenquelle: Konnektor)

Als Alternative zum Dynamischen Datenrouting kann ein Datenpunkt direkt adressiert werden, wenn als Datenquelle „Konnektor" konfiguriert ist. Die Adressierung erfolgt über die Kombination aus identifier und variable:

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

• identifier: Muss mit dem im Datenpunkt hinterlegten Identifier übereinstimmen. Der Identifier identifiziert ein bestimmtes Gerät im Quellsystem und stellt so sicher, dass bei gleichnamigen Variablen der korrekte Datenpunkt adressiert wird. Siehe [1]
• variable: Muss mit dem Variablennamen des Datenpunktes übereinstimmen. Der Wert stammt aus dem Konnektor – bei Verwendung des Pass-through-Templates in der Regel der Variablenname aus dem Quellsystem. Siehe [2]
• data.value: Messwert, der an den Datenpunkt geschrieben wird.
• data.time: Messzeitpunkt. Ohne diesen Wert wird die aktuelle Systemzeit verwendet.

Das passende Beispiel für eine Konfiguration eines Datenpunktes:

Mehrere Pakete als Array

Sollen mehrere Datenpakete in einem einzigen Request übertragen werden, werden die Objekte als JSON-Array übergeben. Dies gilt für beide Adressierungsverfahren:

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

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