CSV-Import

Content

CSV-Import for virtual devices

Up to 500 virtual devices can be imported via CSV file. To do this, click on the bulk import button () and select the account into which the devices are to be imported, whether a device template should be applied, and the connector through which the devices to be created are to receive data.

The following steps are required:

  • Define import variables: An overview of the available variables and their meaning can be found in the following table: Import variables. It is also possible to create and download a template for the import file. Use the dropdown to select the optional columns that should be present in the file. The mandatory fields defined for the selected connector are already preselected.

  • Upload the CSV file: Upload the prepared CSV file. If the CSV file contains errors, the error messages including the corresponding line in the file are displayed here. This makes it easy to identify the issue.

  • Review and confirm: After a title has been entered, a background job can be created by clicking the “Create” button. After that, one device is created automatically per second. The individual jobs are executed system-wide one after another. The job starts as soon as the previous jobs have been completed. The status of the import can be viewed in the background jobs. Errors are also listed there if devices cannot be imported. Once the import has finished, you can leave the page.

CSV format notes:

  • Separator:
    In the CSV file it is possible to use commas as separators as well as semicolons.
  • UTF-8 encoding: The CSV file should be saved using UTF-8 encoding.

Import variables

The following variables are available for CSV import.

General variables

Variable Description
coordinates Location coordinates in the format latitude,longitude.
custom_KEYNAME Custom properties. Use the key with the custom_ prefix in the header and provide the matching value in the row.
description Description text of the virtual device in niotix.
device_id ID of the device to be imported. For Firefly devices, this corresponds to the Device EUI.
deviceType ID of the niotix device type used to parse the payload.
deviceDriver ID of the device driver. This field can only be used when no device template is applied.
groups Device groups in niotix.
faIcon Icon shown in the UI. See Font Awesome V5 Icon Overview.
isDeviceImport If this parameter is not set, niotix will try to create the device in the external system, e.g. Firefly. If the devices already exist in the external system, they only need to be imported. In that case, set this parameter to true.
location Postal address where the device is located. Please use the format Street, City, Country or at least City, Country so that the coordinate lookup works correctly. Example: Bei den Mühren 70, 20457 Hamburg, Deutschland.
operationalStatus Operational status of the virtual device in niotix.
performAddressLookup Automatically looks up the address when coordinates are imported. Use it together with coordinates.
performCoordinateLookup Automatically looks up coordinates when a postal address is imported. Use it together with location.
tags Tags of the virtual device in niotix.
targetReferenceId_KEYNAME Reference ID for Dynamical Data Routing. Replace KEYNAME with the reference key of the target digital twin, e.g. targetReferenceId_Melo. The CSV row then contains the corresponding reference value, e.g. MesslokationsnummerWert.
title Display name of the virtual device in niotix.

Firefly-specific variables

Variable Description
activation LoRaWAN join procedure of the device. Choose OTAA for joining via application key or ABP for manually assigned session keys and device address. Import devices with different join procedures in separate imports.
adr_limit LoRaWAN adaptive data rate.
application_key LoRaWAN application key. Only relevant for OTAA.
application_session_key LoRaWAN application session key. Only relevant for ABP.
class_c Defines whether the device is a Class C device.
deduplicate Defines how duplicate messages should be handled.
dev_status_req Defines whether a LoRaWAN device status request is sent to the device.
address LoRaWAN device address for ABP devices. Not relevant for OTAA.
network_session_key LoRaWAN network session key. Only relevant for ABP.
region LoRaWAN regional parameter. Default: EU868.
rx2_data_rate Data rate including spreading factor and bandwidth.
skip_fcnt_check Defines whether the LoRaWAN frame counter should be ignored.

LwM2M-specific variables

Variable Description
device_id LwM2M endpoint name of the device. The exact term is vendor-specific – some vendors use the IMEI, Elvaco for example uses the serialNumber. (Mandatory field; listed in the General variables table, here with its LwM2M meaning.)
security_mode Security mode of the LwM2M connection. Currently only nosec (unencrypted, security mode disabled) or psk are possible. Usually has to be set in the device template (see Minimum required fields).
connection_server_type Type of the LwM2M server: bootstrap or management. bootstrap is used in most cases. Usually has to be set in the device template.
key LwM2M Pre-Shared Key (PSK) as a hex string (64 characters). With Elvaco also referred to as bootstrapTransportKey.

wM-Bus-specific variables

Variable Description
Manufacturer Manufacturer code, consisting of three uppercase letters, used to identify the manufacturer.
IdentificationNumber Device serial number assigned by the manufacturer (HEX, 8 digits).
key AES device key (HEX, 32 digits). Not required for unencrypted messages.

Note on the wM-Bus connector: Unlike other connectors, the external ID is not provided but generated automatically by the system using the scheme ManufacturerCode_SerialNumber. The isDeviceImport option is therefore not available or necessary here. Once the device limit for the Wireless M-Bus Decoder in the account is reached, no further devices can be created.


MQTT- and Webhook-specific variables

The MQTT and Webhook connectors do not have any specific variables. They only use title and device_id as mandatory fields together with the General variables.


Minimum required fields per connector

Which fields are mandatory depends on whether the import is performed with or without a device template:

Connector Mandatory fields without template Mandatory fields with 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
  • During a bulk import with a device template, connector- and driver-related fields are taken from the template; the corresponding columns in the CSV file are ignored. For firefly, region and activation for example come from the template.
  • Some connector-specific mandatory fields can and must be set in the template only (for LwM2M security_mode and connection_server_type). If they are not set in the template, the import fails – the values from the CSV file are not taken into account in that case.
  • The isDeviceImport option is only relevant for the firefly and lwm2m connectors.

Common pitfalls

  • UTF-8 and Excel: When a CSV file is opened by double-clicking it in Excel, it is usually not interpreted as UTF-8 – umlauts and special characters are then displayed incorrectly. Instead, import the file via File → Import → CSV file and explicitly choose the UTF-8 encoding.
  • location and performCoordinateLookup: For the coordinate lookup to work, the address must include the country (e.g. …, Deutschland). Example: Bei den Mühren 70, 20457 Hamburg, Deutschland.
  • Mandatory fields set by the template: Mind the difference between importing with and without a device template. Fields such as security_mode and connection_server_type (LwM2M) can only be set via the template; if they are missing there, the import fails. It is recommended to open or edit a newly created template (e.g. for firefly) once before the first import, set the mandatory fields marked with an asterisk (e.g. activation) explicitly, and save the template before running the first import with it.

Best practices & useful fields

  • tags: Helpful for grouping devices later via Smart Groups. Use short tags such as altona. Example: all meters of a district can thus be combined into a single Smart Group for clearer monitoring.
  • custom_<KEYNAME>: Suitable for metadata and master data, e.g. custom_InternalMeterNumber.
  • targetReferenceId_<KEYNAME>: Controls Dynamical Data Routing to digital twins, e.g. targetReferenceId_Melo. Use a stable ID as the value that does not normally change (e.g. a metering point or GIS ID). This keeps the data assigned to the same digital twin when a device is swapped or replaced on a maintenance cycle (seamless meter exchange).
  • isDeviceImport: Only relevant for the firefly and lwm2m connectors. Indicates whether the device already exists in the external system (e.g. Firefly or LwM2M server) and only needs to be imported (true), or whether niotix creates it there.