Virtuelle Geräte



Die Funktion der virtuellen Geräte ist sinngemäß, unterschiedliche Datenquellen des Internets der Dinge in unsere Software zu integrieren. Dazu gehören alle Arten von LPWAN-Technologien, aber darüber hinaus auch am Markt gängige, etablierte Kommunikationsprotokolle wie z.B. MQTT.

Ein virtuelles Gerät repräsentiert einen Endpunkt, der Daten liefert. Zu jedem virtuellen Gerät gehört ein Typ des virtuellen Geräts, der in unserer Software als “Konnektor” bezeichnet wird. Für virtuelle Geräte können also eine Vielzahl von Konnektoren im System existieren, diese werden zum Konto erfasst. Nach der Verknüpfung mit dem Konto kann ein virtuelles Gerät vom entsprechenden Typ in der Anwendung angelegt werden.

Über das Menü “Virtuelle Geräte” werden alle verfügbaren Geräte angezeigt, auf die der Nutzer Zugriff hat.

In dieser Übersicht können außerdem neue virtuelle Geräte angelegt, die Favoritenansicht eingeblendet oder die virtuellen Geräte auf einer Karte angezeigt werden.

Zudem können die virtuellen Geräte aus dieser Übersicht heraus bearbeitet werden, indem der Nutzer auf den entsprechenden Stift-Button rechts in der Tabelle drückt. Bei Bedarf können virtuelle Geräte auch gelöscht werden.

In der oberen Menüleiste befindet sich eine Schaltfläche zum aktivieren der Statistiken. In dem erscheinenden Modal wird der Mengenaufwuchs für den ausgewählten Zeitraum nach “Konnektor” und nach “Konto” aufgelöst angezeigt.

Die Anwendung bietet eine Filterfunktion, über die der Nutzer die Möglichkeit hat, die angezeigte Gesamtliste auf seine Bedürfnisse zu filtern.

Bedeutung besonderer Tabellenspalten:

  1. “Zuletzt gesehen”: Dieser Wert gibt an wie viel Zeit nach dem Eintreffen des letzten Datenpakets vergangen ist.
  2. “Externe ID”: virtuelle Geräte können unterschiedliche Datenquellen besitzen. Sie repräsentieren Objekte aus den verbundenen Datenquellen. Dieser Wert gibt die ID des Objektes in der verbundenen Datenquelle an.
  3. “Systemstatus”: dieser Wert drückt aus, ob mit dem virtuellen Gerät alles in Ordnung ist. Sollte eine Warnung oder ein Alarm angezeigt werden, so kann der Wert angeklickt werden um den Alarm beziehungsweise die Warnung anzuzeigen oder zu ignorieren. Für jedes Objekt können mehrere Warnungen und Alarme existieren. Ignorierte Warnungen oder Alarme können in der Bearbeitung des Objektes wieder auf aktiv gesetzt werden.

Virtuelle Geräte anlegen

Um einfach und schnell ein virtuelles Gerät zu erstellen, klickst du auf den Button “Anlegen”. Es öffnet sich ein neues Fenster, in dem der Nutzer zunächst ein Konto auswählt, zu dem das virtuelle Gerät angelegt werden soll. Nach der Auswahl des Kontos zeigt das zweite Feld rechts daneben die für das Konto verfügbaren Konnektoren an.

Nach der Auswahl eines Konnektors werden die beiden Felder zur Bearbeitung gesperrt und können über den Änderungsbutton nachträglich wieder angepasst werden. Im weiteren Schritt kann nun ein neues virtuelles Gerät zu diesem Konnektor angelegt oder ein bereits bestehendes virtuelles Gerät importiert werden.

Entscheidet sich der Benutzer dazu ein bestehendes virtuelles Gerät zu importieren, so trägt er den externen Identifikator des Geräts in dem entsprechenden Eingabefeld ein und betätigt den Button “Importieren”. Danach wird das virtuelle Gerät in dem durch den Konnektor verbundenen System gesucht. Bei einer erfolgreichen Suche werden alle möglichen Eingabefelder bereits vorausgefüllt. Sollte beim Import festgestellt werden, dass das Gerät bereits im System erfasst ist, wird dem Nutzer eine entsprechende Meldung angezeigt und danach kann sich der Nutzer entscheiden, ob er das bereits angelegte Gerät weiter verwenden möchte oder dennoch das Gerät ein weiteres Mal importieren möchte.

Über den Button “Anlegen” kann man als Nutzer ein neues virtuelles Gerät erstellen. Es erscheinen die Eingabefelder, die auszufüllen sind, um ein neues Gerät anzulegen:

  • Titel:* Gib dem Gerät einen aussagekräftigen Titel für die einfache Identifizierung.
  • Übergeordnetes Objekt:* In diesem Eingabefeld kannst du den digitalen Zwilling auswählen, zu dessen Berechtigungsumfeld das virtuelle Gerät angelegt werden soll.
  • Beschreibung: Gebe eine kurze Beschreibung des Geräts ein, die auf der Detailseite erscheint. (Unterstützt Markdown-Formatierung)
  • Tags: Über ein Dropdown können bereits im System existierende Tags ausgesucht oder neue Tags erfasst werden.
  • Betriebsstatus: Du kannst zwischen “Nicht gesetzt”, “Unterwegs”, “Betriebsbereit”, “In Betrieb”, “Vorübergehend inaktiv” oder “Stillgelegt” wählen. Um den Status für die Berichtsanzeige auf der Detailseite zu überprüfen, wird der jüngste Betriebsstatus des Geräts mit dem Schwellenwert kombiniert.
  • Geräte-Typ: Wenn das virtuelle Gerät zu einem bestimmten Gerätetyp gehört, kannst du diesen Typen aus der Liste auswählen und die Geräte direkt zuordnen, damit bei der Anlage und nach der Inbetriebnahme die Nutzlast der Datenpakete interpretiert werden kann.
  • Gruppen: Virtuelle Geräte können bis unendlich viele Gerätegruppen zugewiesen werden. In dem Dropdown “Gruppen” kannst du zwischen den verschiedenen im System bereits existierenden Gruppen wählen. Es können auch mehrere Gruppen ausgewählt werden. Existiert die entsprechende Gerätegruppe nicht im System, kann im Eingabefeld “Neue Geräte Gruppe” eine neue Gerätegruppe über die Eingabe erfasst werden und über das Betätigen des Buttons mit dem Plus-Symbol zu den existierenden Gruppen hinzugefügt werden.

CSV-Import für virtuelle Geräte

Bis zu 500 Virtuelle Geräte lassen sich per CSV Datei importieren. Klicke hierfür auf den Massenimport-Button () und wähle das Konto aus, in den die Geräte importiert werden sollen, sowie der Konnektor, über den die anzulegenden Geräte Daten empfangen sollen.
Der Import erfolgt nun in drei Schritten:

  1. Definieren In diesem Schritt ist es möglich, ein Template für die Import-Datei zu erstellen. Wähle über das Dropdown die optionalen Spalten aus, die in der Datei vorhanden sein sollen. Die für den ausgewählten Konnektor definieren Pflichtfelder sind bereits vorausgewählt.

    Trennzeichen:
    In der CSV-Datei ist es sowohl möglich Kommas als Trennzeichen zu verwenden, als auch Semikolons.

Variablen

Anzeigename Variable Bezieht sich auf Variable Konnektor Beschreibung
Activation activation Firefly LoRaWAN Join-Verfahren (ABP/OTAA). Import von Geräten mit unterschiedlichen Join-Verfahren bitte in getrennten Imports durchführen.
ADR Limit adr_limit Firefly LoRaWAN Adaptive Datenrate
Application Key application_key activation Firefly LoRaWAN Application Key
Application Session Key application_session_key activation Firefly LoRaWAN Application Session Key
Class C class_c Firefly Handelt es sich um ein Class C Gerät?
Coordinates coordinates Alle Konnektoren Dieses Feld benötigt die Standortkoordinaten im Format “latitude,longitude”
Custom properties custom_KEYNAME Alle Konnektoren Benutzerdefinierte Eigenschaften. Im Titel wird der Key mit Präfix “custom_” benötigt. Als Zeilen-Wert dann der Value.
Deduplicate packets deduplicate Firefly Wie sollen doppelte Nachrichten behandelt werden?
Description description Alle Konnektoren niotix Beschreibungstext des Virtuellen Geräts
Device Address address activation Firefly Relevant für Aktivierung von ABP Geräte. Nicht Relevant, wenn Aktivierung OTAA. Die LoRaWAN Geräteadresse (Hexadezimal-Kodiert)
Device EUI device_id Firefly ID des zu importierenden Geräts
Device ID device_id Alle Konnektoren außer Firefly ID des zu importierenden Geräts
Device Type deviceType Alle Konnektoren ID des niotix Gerätetyps um die Payload zu parsen
Groups groups Alle Konnektoren niotix Gerätegruppen
Icon faIcon Alle Konnektoren Das Icon für die Anzeige in der UI Font Awesome V5 Icon Übersicht
Location location Alle Konnektoren Die Adresse (Postanschrift) an der sich das Gerät befindet
Network Session Key network_session_key activation Firefly LoRaWAN Network Session Key
Operational Status operationalStatus Alle Konnektoren niotix Betriebsstatus
Perform Address Lookup performAddressLookup coordinates Alle Konnektoren Soll beim Import von Koordinaten automatisch die Adresse nachgeschlagen werden?
Perform Coordinate Lookup performCoordinateLookup location Alle Konnektoren Sollen beim Import einer Postanschrift automatisch die Koordinaten nachgeschlagen werden?
Region region Firefly LoRaWAN Regionalparameter; Default: EU868
RX2 Data Rate rx2_data_rate Firefly Datenrate (Streufaktor und Bandbreite)
Skip frame counter increment check skip_fcnt_check Firefly Soll der LoRaWAN Frame Counter ignoriert werden?
Tags tags Alle Konnektoren niotix Tags
Title title Alle Konnektoren niotix Anzeigename
  1. Upload Lade nun die fertig vorbereitete Datei hoch. Sollte die CSV Datei Fehlerhaft sein, werden hier die Fehlermeldungen inklusive der zugehörigen Zeile in der Datei angezeigt. Somit kann der Fehler schnell identifiziert werden.

  2. Bestätigen Im dritten Schritt werden die Geräte noch einmal aufgelistet. Hier ist es möglich, die zu importierenden Geräte noch einmal anzusehen. Nachdem ein Titel eingegeben wurde, kann mit Klick auf den “Erstellen”-Button ein Hintergrundjob angelegt werden. Im Anschluss wird automatisch ein Gerät pro Sekunde angelegt. Dabei werden die einzelnen Jobs systemweit nacheinander ausgeführt. Der Job startet, sobald die vorherigen Jobs abgeschlossen sind. Der Status des Imports kann in den Hintergrundjobs eingesehen werden. Hier werden auch Fehler aufgelistet, sollten Geräten nicht importiert werden können.

Konnektor-spezifische Daten

Jedes virtuelle Gerät hat spezielle Daten, die für den Betrieb des Gerätes unerlässlich sind. Diese Daten variieren je nach Konnektor-Typ.

TTI-Konnektor

In diesem Konnektor muss zunächst eine Endgerät-ID erfasst werden. Diese ID darf nur aus kleinen Buchstaben bestehen und Zahlen sind nicht erlaubt. Neben der and Geräte-ID muss die Aktivierungsmethode ausgewählt werden. In Abhängigkeit von der Aktivierungsmethode bauen sich weitere spezielle Eingabefelder auf, die entsprechend der Technologie und der gelieferten Details des Geräteherstellers ausgefüllt werden müssen.

Firefly

Über die konnektorspezifischen Daten lassen sich die gängigen LoRaWAN Einstellungen des Sensors im Firefly LNS fernsteuern. Die Einstellung “Deduplicate packets” setzt im Firefly, die Option “Ignore consecutive packets with equal frame counter”, welche dafür sorgt, dass ein Datenpaket mit einem Framecounter der bereits existiert verworfen wird. “Skip frame counter increment check” steuert die gleichnamige Option im Firefly welche dafür sorgt, dass Pakete nur akzeptiert werden, wenn sie einen höheren Framecounter haben als bereits zuvor empfangene Pakete.

Virtuelle Geräte bearbeiten

Bereits erfasste virtuelle Geräte im System können vom Nutzer angezeigt und bearbeitet werden.

Einzelne Geräte bearbeiten

Bearbeite und editiere ein einzelnes Gerät, indem du auf ein Gerät in der Übersichtsliste bzw. auf den “Bearbeiten”-Icon rechts klickst. So gelangst du zu den Geräteinformationen.

Hier kannst du verschiedene Eigenschaften wie Titel, EUI, Beschreibung und weitere Felder verändern. In diesem Reiter wird oben links der Typ des Geräts angezeigt, mit dem unter anderem auch die Nutzlast interpretiert wird. Dieser Gerätetyp ist anklickbar und führt den Benutzer nach Anklicken direkt auf die Übersicht des entsprechenden Gerätetyps. Rechts neben dem Gerätetyp wird dem Nutzer angezeigt, seit wann das Gerät angelegt wurde und wie viel Zeit vergangen ist seit dem letzten eingehenden Datenpaket. Rechts neben diesen Informationen befindet sich ein Dropdown zur Auswahl eines relativen oder absoluten Zeitraumes. Dieser Zeitraum gibt an, für welche Zeitspanne alle im folgenden aufgeführten Informationen aufbereitet werden.

In der nächsten Zeile findet der Nutzer die Pakethistorie sowie die Liveansicht. Hier werden alle Pakete aufgelistet, die im ausgewählten Zeitraum vom System empfangen wurden. Endet der ausgewählte Zeitraum in der aktuellen Zeit, so werden in Echtzeit empfangene Pakete live in der Pakethistorie angezeigt. Rechts neben der Pakethistorie befindet sich die Paketvisualisierung. In der Paketvisualisierung werden einerseits die rohen empfangenen Daten des Datenpakets im JSON-Format angezeigt, darüber hinaus wird die durch den zuvor zugewiesenen Gerätetyp interpretierte Nutzlast als JSON angezeigt.

Im nächsten Abschnitt wird dem Nutzer ein Balken-Diagramm angezeigt, welches die vom System empfangenen Paketmengen in dem ausgewählten Zeitraum visualisiert. Dabei zeigen die farbigen Balken den aktuell ausgewählten Zeitraum an, die grauen Balken zeigen den vorherigen Zeitraum an. So besteht die Möglichkeit einfach zu sehen, ob das Gerät zuverlässig Daten sendet im Vergleich zum vergangenen Zeitraum.

Darunter befinden sich nun die allgemeinen Geräteinformationen wie die externe Identifikationsnummer, der Betriebsstatus, der Gerätetyp und die Gerätegruppen sowie die Möglichkeit eine neue Gerätegruppe hinzuzufügen. Alle Daten können hier verändert und gespeichert werden.

Des Weiteren findet man als Nutzer die Sektion der Downlinks. Hier kann man eine Nutzlast eintragen, eine Kodierung auswählen und einen entsprechenden Port, worüber die Nutzlast versendet werden soll. Zusätzlich ist es möglich auszuwählen, ob der Downlink vom System bestätigt werden soll oder nicht. Durch einen Klick auf den “Senden”-Button wird der entsprechende Downlink an das virtuelle Gerät in der realen Welt versendet.

Im letzten Abschnitt dieser Übersicht befinden sich die Konnektor spezifischen Daten. Diese Daten sind nicht änderbar und werden zur Laufzeit aus dem System, welches durch den Konnektor angebunden ist, ausgelesen und zur Anzeige gebracht. Besteht der Wunsch diese Daten zu ändern, muss sich der Nutzer in dem verbundenen System anmelden und die Datenänderung dort durchführen.

Mehrere Geräte bearbeiten

Bearbeite und editiere bis zu 50 Geräte, indem du in der Übersichtsliste die zu bearbeitenden Geräte über die Checkbox selektierst und anschließend auf den Button “Auswahl bearbeiten” klickst. Die Bearbeitung erfolgt in drei Schritten.


1. Modus
Wähle im Dropdown den Modus aus. Aktuell ist nur der Modus “Meta-Informationen anpassen” verfügbar.


2. Änderungen konfigurieren
Die verfügbaren Änderungen basieren auf dem ausgewählten Modus.

Verfügbare Änderungen im Modus “Meta-Informationen anpassen”:

  • Betriebsstatus
  • Zugriffsbereich
  • Gruppen: Dem Gerät eine oder mehere Gruppen zufügen. Die Gruppe muss bereits angelegt sein.
  • Tags: Dem Gerät einen oder mehere Tags zufügen. Der Tag muss bereits angelegt sein.


3. Änderungen anwenden
Im dritten Schritt kann den Änderungen ein Titel zugefügt werden, um Änderungen später nachvollziehen zu können. Nach einem Klick auf “Änderungen anwenden” wird ein Hintergrundjob erstellt, sodass niotix weiter genutzt werden kann, während die Verarbeitung läuft.

Der Fortschritt dieser Hintergrundjobs lässt sich unter “Hintergrundjobs” einsehen. Dieser Bereich ist unter dem Toolbar-Icons oben rechts erreichbar.

Den Gerätetyp ändern

Es gibt sowohl die Möglichkeit, einen Gerätetyp neu zu synchronisieren um Änderungen an einem Gerätetyp auf das Virtuelle Gerät anzuwenden, als auch den ganzen Gerätetypen zu ändern.

Beide Funktionalitäten sollten mit Bedacht verwendet werden, da die Änderung an den Virtuellen Geräten auch Auswirkungen auf Datenpunkte in Digitalen Zwillingen haben und diese möglicherweise neu erstellt werden müssen, um wieder Daten zu empfangen. Die Daten im Virtuellen Gerät selbst werden bei beiden Funktionalitäten gelöscht.

Um den Gerätetyp eines Virtuelle Geräts neu zu synchronisieren und die Änderungen am Gerätetyp auch auf das Virtuelle Gerät anzuwenden, auf den Button neben dem Gerätetyp klicken und das Virtuelle Gerät im Anschluss speichern.

Um dem Virtuellen Gerät einen neuen Gerätetyp zuzuordnen muss die Liste der verfügbaren Gerätetypen zunächst entsperrt werden. Hierzu auf den Button mit dem Schloss klicken. Im Anschluss kann der gewünschte Gerätetyp gesucht und ausgewählt werden. Wurde der richtige Gerätetyp ausgewählt, das Virtuelle Gerät speichern.

Zu Beachten ist hierbei, dass die Änderungen am Virtuellen Gerät erst mit Speichern ebendieses übernommen werden.

Wichtige Datenpunkte

Jedes dieser Objekte besitzt drei Datenpunkte, welche automatisch erzeugt werden und nicht löschbar sind. Der “_raw” Datenpunkt zeigt die unveränderten Daten an, welche an das Objekt gesendet werden. Der “_parsed” Datenpunkt enthält das JSON, welches nach dem Durchlaufen des Parsers im Gerätetyp aus dem rohen Payload des Sensors generiert wurde. Der “Health” Datenpunkt speichert Informationen zur Ermittlung des “Systemstatus”.

Der “_raw” Datenpunkt

Dieser Datenpunkt enhält die unveränderten Daten die am Konnektor für dieses Gerät eingegangen sind. Da für die weitere Verarbeitung nur das Payload für die Berechnung der einzelnen Messwert-Datenpunkte verwendet wird, dient dieser Datenpunkt dazu spezifische Datenpunkte für zum Beispiel RSSI/SNR/SF im LoRaWAN Fällen abzuleiten. Zudem ermöglich der State einen zuverlässige Revision der Daten.

Der “_parsed” Datenpunkt

Dieser Datenpunkt enthält das JSON welches durch das Parsen des rohen Payloads erzeugt wird. Er kann verwendet werden, um beispielsweise aggegierte Datenpunkte, welche Berechnungen aus verschiedenen Messwerten enhalten soll zu erstellen. Zusätzlich eignet er sich für das Weiterleiten von Daten an Drittsysteme, wenn mehr als ein Messpunkt weiterverarbeitet werden soll.

Der “Health” Datenpunkt

Dieser Datenpunkt ist besonders wichtig, da in ihm die Berechnung für den Systemstatus des Objektes erfolgt. Im Bearbeitungsmodus kann aus allen durch den Gerätetyp entstandenen Datenpunkten ausgewählt werden, welche für die Ermittlung des Systemstatus relevant sind. Danach wird für jedes ausgewählte Element eine spezielle Ermittlungslogik festgelegt. Für diese Ermittlungslogik sind Programm-Beispiele angeführt.

Zum Beispiel kann ein Gerät bei einem Batteriestand unter 40 % eine Warnung erhalten und bei einem Batteriestand unter 20 % einen Alarm. Gleichzeitig kann ein weiterer Alarm ausgelöst werden, sollte das Gerät einen Fehler melden. Der Systemstatus kann also mehrere fehlerhafte Zustände parallel annehmen und darstellen.

Um die Konfiguration nicht bei jedem Gerät jeweils vornehmen zu müssen, kann die Konfiguration gesammelt im Gerätetyp vorbereitet werden. Dies geschieht unter “Gerätestatuskonfig” und gilt für alle danach angelegten Geräte, die diesen Gerätetyp zugewiesen bekommen.

Zustände des Health Datenpunktes und Auswertungslogik

Der Health Datenpunkt wird bei jedem neuen Paket, das für das Virtuelle Gerät verarbeitet wird ausgewertet. Zusätzlich gibt es eine zeitbasierte Auswertung, welche durch die Health Check - Regel definiert wird. Diese wird automatisch mit dem Health Datenpunkt erstellt. Standardmäßig wird diese Regel einmal am Tag ausgeführt, so dass auch dann, wenn keine Daten am Sensor ankommen, ein Alarm für dieses Gerät erzeugt wird. Wenn z.B. der Health Datenpunkt so konfiguriert ist, dass ein Alarm gesetzt wird, wenn z.B. 24 Stunden lang keine Daten empfangen wurden.

Zustände des Health Datenpunktes:
  • Unbekannt: Bevor ein Gerät das erste Datenpaket empfängt, ist der Gesundheitszustand immer unbekannt, auch wenn es so konfiguriert ist, dass alle 24 Stunden nach Paketen gesucht wird. Dies dient dazu, Geräte mit echten Fehlern leichter von solchen zu unterscheiden, die noch nicht aktiviert sind, aber bereits in das System importiert wurden.
  • Ok: Wenn das Virtuelle Gerät in der Vergangenheit mindestens ein Datenpaket empfangen hat und keine Warnungen oder Fehler vorhanden sind.
  • Warnung: Wenn gemäß der Konfiguration des Gesundheitszustands ein Fehler erkannt wird.
  • Alarm: Wenn gemäß der Konfiguration des Gesundheitszustands ein Alarm erkannt wurde.
  • Ungültig: Wenn es für dieses Gerät keinen Health Datenpunkt gibt (z. B. Geräte, die erstellt wurden, bevor der Gesundheitszustand verfügbar war) oder wenn der Wert vom System nicht interpretiert werden kann (was der Fall sein kann, wenn der Gesundheitszustand einen benutzerdefinierten Javascript-Transformator enthält). Nach diesem Status kann aus technischen Gründen nicht gefiltert werden.

Berechtigungen

Alle virtuellen Geräte werden, insofern nicht anders eingestellt, bei Geräteanlage oder bei Geräteänderung zu dem Root-Zwilling des entsprechenden Kontos angelegt. Das bedeutet, dass nur Nutzer die Geräte sehen können, die eine Berechtigung zur Anzeige und/ oder Änderung des Root-Zwillings besitzen. Soll ein Gerät eine andere Berechtigungseinstellung erhalten, zum Beispiel zur Berechtigungsgruppe eines untergeordneten Zwillings gehören, kann dies durch die Änderung des übergeordneten Objektes (unter Meta-Informationen) eingestellt werden.

Für einen Nutzer mit Einsicht sowie Schreibrechten der virtuellen Geräte werden folgende Rollen auf dem jeweiligen Konto benötigt: DigitalTwin.list und VirtualDevice.manage.

Für einen Nutzer mit nur Leserecht auf die virtuellen Geräte ist die Rolle VirtualDevice.read notwendig.

Gerätetypen

Unter dem Menüpunkt “Gerätetypen” siehst du eine Liste der Gerätetypen, auf die du mit deinem Konto Zugriff hast. Hier erstellst du mit den entsprechenden Benutzerrechten Vorlagen zur Verwendung und Gruppierung von Geräten mit den selben Funktionen und Datenstrukturen. Du kannst Standards für die Umwandlung von Paketdaten über einen Paket-Parser einsetzen. Gerätetypen können gleichermaßen im IoT-Data-Hub, als auch für Virtuelle Geräte verwendet werden. Die detaillierte Dokumentation findest du hier im Bereich IoT-Data-Hub.