CSV-Import

Inhalt

CSV-Import für virtuelle Geräte

Bis zu 500 Virtuelle Geräte lassen sich per CSV Datei importieren. Klicke dafür auf den Massenimport-Button (). Wähle dann das Ziel-Konto sowie einen Konnektor aus. Du kannst zusätzlich festlegen, ob die importierten Geräte einem Geräte-Template zugeordnet oder als einzelne Geräte angelegt werden sollen (mit Auswahl des Konnektor-Typs).

Hier zu sind folgende Schritte durchzuführen:

  • Import Variablen definieren: Eine Übersicht der verfügbaren Variablen und deren Bedeutung findest du in der folgenden Tabelle Import Variablen. Außerdem ist es möglich, ein Template für die Import-Datei zu erstellen und herunterzuladen. 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.

  • Upload der CSV-Datei: 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.

  • Überprüfen und Bestätigen: 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. Nachdem der Import abgeschlossen ist, kann die Seite verlassen werden.

CSV-Format Hinweise:

  • Trennzeichen: In der CSV-Datei ist es sowohl möglich Kommas als Trennzeichen zu verwenden, als auch Semikolons.
  • UTF-8 Encoding: Die CSV-Datei sollte im UTF-8 Encoding gespeichert werden.

Import Variablen

Die verfügbaren Variablen hängen vom ausgewählten Konnektor-Typ/Gerätetemplate ab. Eine vollständige Übersicht der verfügbaren Variablen wird dir direkt in der Import-Maske angezeigt (Reiter “Anleitung zum Import” ausklappen).

Allgemeine Variablen

Variable Beschreibung
coordinates Standortkoordinaten im Format latitude,longitude.
custom_KEYNAME Benutzerdefinierte Eigenschaften. Im Titel wird der Key mit Präfix custom_ benötigt; als Zeilenwert wird der zugehörige Value eingetragen.
description Beschreibungstext des virtuellen Geräts in niotix.
device_id ID des zu importierenden Geräts. Bei Firefly-Geräten entspricht dies der Device EUI.
deviceType ID des niotix Gerätetyps, um die Payload zu parsen.
deviceDriver ID des Gerätetreibers. Dieses Feld kann nur verwendet werden, wenn kein Geräte-Template genutzt wird.
groups Gerätegruppen in niotix.
faIcon Icon für die Anzeige in der UI. Siehe Font Awesome V5 Icon Übersicht.
isDeviceImport Ist dieser Parameter nicht gesetzt, versucht niotix das Gerät im externen System, z. B. Firefly, anzulegen. Sind die Geräte im externen System bereits vorhanden, müssen sie nur importiert werden. Setze den Parameter dafür auf true.
location Postanschrift, an der sich das Gerät befindet. Bitte verwende das Format Adresse, Ort, Land oder mindestens Ort, Land, damit der Coordinate Lookup funktioniert. Beispiel: Bei den Mühren 70, 20457 Hamburg, Deutschland.
operationalStatus Betriebsstatus des virtuellen Geräts in niotix.
performAddressLookup Schlägt beim Import von Koordinaten automatisch die Adresse nach. Nutze dies zusammen mit coordinates.
performCoordinateLookup Schlägt beim Import einer Postanschrift automatisch die Koordinaten nach. Nutze dies zusammen mit location.
tags Tags des virtuellen Geräts in niotix.
targetReferenceId_KEYNAME Referenz-ID für das Dynamische Datenrouting. Ersetze KEYNAME durch den Referenzschlüssel des Ziel-Digitalen-Zwillings, z. B. targetReferenceId_Melo. In der CSV-Zeile steht dann der zugehörige Referenzwert, z. B. MesslokationsnummerWert.
title Anzeigename des virtuellen Geräts in niotix.

Firefly-spezifische Variablen

Variable Beschreibung
activation LoRaWAN Join-Verfahren des Geräts. Wähle OTAA für Join per Application Key oder ABP für manuell gesetzte Session Keys und Device Address. Importiere Geräte mit unterschiedlichen Join-Verfahren in getrennten Imports.
adr_limit LoRaWAN Adaptive Datenrate.
application_key LoRaWAN Application Key. Nur für OTAA relevant.
application_session_key LoRaWAN Application Session Key. Nur für ABP relevant.
class_c Legt fest, ob es sich um ein Class-C-Gerät handelt.
deduplicate Legt fest, wie doppelte Nachrichten behandelt werden.
dev_status_req Legt fest, ob ein LoRaWAN Device-Status-Request an das Gerät gesendet wird.
address LoRaWAN Device Address. Nur für ABP relevant.
network_session_key LoRaWAN Network Session Key. Nur für ABP relevant.
region LoRaWAN-Regionalparameter. Standardwert: EU868.
rx2_data_rate Datenrate mit Spreizfaktor und Bandbreite.
skip_fcnt_check Legt fest, ob der LoRaWAN-Frame-Counter ignoriert werden soll.

LwM2M-spezifische Variablen

Variable Beschreibung
device_id LwM2M-Endpoint-Name des Geräts. Die Bezeichnung ist herstellerspezifisch – manche Hersteller verwenden die IMEI, Elvaco z. B. die serialNumber. (Pflichtfeld; in der Allgemeinen Tabelle gelistet, hier mit LwM2M-Bedeutung.)
security_mode Sicherheitsmodus der LwM2M-Verbindung. Aktuell sind nur nosec (unverschlüsselt, Security Mode deaktiviert) oder psk möglich. Muss in der Regel im Geräte-Template gesetzt sein (siehe Pflichtfelder).
connection_server_type Typ des LwM2M-Servers: bootstrap oder management. In der Regel wird bootstrap verwendet. Muss in der Regel im Geräte-Template gesetzt sein.
key LwM2M Pre-Shared Key (PSK) als Hexstring (64 Zeichen). Bei Elvaco auch als bootstrapTransportKey bezeichnet.

wM-Bus-spezifische Variablen

Variable Beschreibung
Manufacturer Herstellercode, bestehend aus drei Großbuchstaben, zur Identifizierung des Herstellers.
IdentificationNumber Geräteseriennummer des Herstellers (HEX, 8-stellig).
key AES-Gerätekey (HEX, 32-stellig). Nicht erforderlich bei unverschlüsselten Nachrichten.

Hinweis zum wM-Bus-Konnektor: Die Externe ID wird – anders als bei anderen Konnektoren – nicht angegeben, sondern vom System automatisch nach dem Schema Herstellercode_Seriennummer generiert. Die Option isDeviceImport ist hier daher nicht verfügbar bzw. nicht notwendig. Beim Erreichen des Gerätelimits für den Wireless M-Bus Decoder im Konto können keine weiteren Geräte angelegt werden.


MQTT- und Webhook-spezifische Variablen

Die Konnektoren MQTT und Webhook haben keine spezifischen Variablen. Es werden lediglich title und device_id als Pflichtfelder sowie die Allgemeinen Variablen verwendet.


Minimale Pflichtfelder pro Konnektor

Welche Felder verpflichtend sind, hängt davon ab, ob der Import mit oder ohne Geräte-Template erfolgt:

Konnektor Pflichtfelder ohne Template Pflichtfelder mit Template
firefly title, region, device_id, activation title, device_id
lwm2m title, device_id, security_mode, connection_server_type title, device_id
mqtt title, device_id title, device_id
webhook title, device_id title, device_id
wmbus title, Manufacturer, IdentificationNumber title, Manufacturer, IdentificationNumber
  • Beim Massenimport mit Geräte-Template werden konnektor- und treiberbezogene Felder aus dem Template übernommen; entsprechende Spalten in der CSV-Datei werden ignoriert. Bei firefly stammen so z. B. region und activation aus dem Template.
  • Einige konnektor-spezifische Pflichtfelder können und müssen ausschließlich im Template gesetzt werden (bei LwM2M security_mode und connection_server_type). Sind sie im Template nicht gesetzt, schlägt der Import fehl – die Werte aus der CSV-Datei werden in diesem Fall nicht berücksichtigt.
  • Die Option isDeviceImport ist nur bei den Konnektoren firefly und lwm2m relevant.

Häufige Fehlerquellen

  • UTF-8 und Excel: Wird eine CSV-Datei per Doppelklick in Excel geöffnet, wird sie in der Regel nicht als UTF-8 interpretiert – Umlaute und Sonderzeichen werden dann falsch dargestellt. Importiere die Datei stattdessen über Datei → Importieren → CSV-Datei und wähle dabei explizit das UTF-8-Encoding.
  • location und performCoordinateLookup: Damit der Coordinate-Lookup funktioniert, muss die Anschrift das Land enthalten (z. B. …, Deutschland). Beispiel: Bei den Mühren 70, 20457 Hamburg, Deutschland.
  • Pflichtfelder, die das Template setzt: Achte auf den Unterschied zwischen Import mit und ohne Geräte-Template. Felder wie security_mode und connection_server_type (LwM2M) können nur über das Template gesetzt werden; fehlen sie dort, schlägt der Import fehl. Es wird empfohlen, ein neu erstelltes Template (z. B. für firefly) vor dem ersten Import noch einmal zu öffnen bzw. zu bearbeiten, die mit einem Stern markierten Pflichtfelder (z. B. activation) dort explizit zu setzen und das Template anschließend zu speichern, bevor der erste Import mit diesem Template durchgeführt wird.

Best Practices & nützliche Felder

  • tags: Hilfreich, um Geräte später über Smart Groups zu gruppieren. Verwende dafür kurze Tags wie z. B. altona. Beispiel: Alle Zähler eines Stadtteils bzw. Bezirks lassen sich so für ein übersichtlicheres Monitoring in einer Smart Group zusammenfassen.
  • custom_<KEYNAME>: Eignet sich für Metadaten und Stammdaten, z. B. custom_InterneZählernummer.
  • targetReferenceId_<KEYNAME>: Steuert das Dynamische Datenrouting auf digitale Zwillinge, z. B. targetReferenceId_Melo. Verwende als Wert eine stabile ID, die sich in der Regel nicht ändert (z. B. Messlokations- oder GIS-ID). So bleiben bei einem Gerätetausch oder Turnuswechsel die Daten demselben digitalen Zwilling zugeordnet (nahtloser Zählertausch).
  • isDeviceImport: Nur für die Konnektoren firefly und lwm2m relevant. Gibt an, ob das Gerät im externen System (z. B. firefly oder LwM2M-Server) bereits existiert und nur importiert werden soll (true) oder ob niotix es dort neu anlegt.