Device management

Virtual Devices

The function of virtual devices is to integrate different data sources of the Internet of Things into our software. This includes all kinds of LPWAN technologies, but furthermore also communication protocols that are common or established on the market, such as MQTT.

A virtual device represents an endpoint that delivers data. Each virtual device has a type of virtual device associated with it, which is called a “connector” in our software. So for virtual devices, there can be a variety of connectors in the system, these are captured to the account. After linking to the account, a virtual device of the corresponding type can be created in the application.

In this overview, it is also possible to create new virtual devices, show the favorites view or display the virtual devices on a map.

In addition, the virtual devices can be edited from this overview by pressing the corresponding pencil button on the right of the table. If necessary, virtual devices can also be deleted.

In the top menu bar there is a button to activate the statistics. In the modal that appears, the volume increase for the selected period is displayed broken down by “connector” and by “account”.

In this view, the same filters can be applied to limit the selection and adapt it to needs.

Meaning of special table columns:

“Last seen”: This value indicates how much time has passed since the arrival of the last data packet.
“External ID”: virtual devices can have different data sources. They represent objects from the connected data sources. This value specifies the ID of the object in the connected data source.
“Health”: this value expresses whether everything is OK with the virtual device. If a warning or an alarm is displayed, the value can be clicked to ignore the alarm or the warning. Furthermore, several warnings and alarms can exist for each object, these are displayed after clicking. Ignored warnings or alarms can be set to active again when editing the object.

Create virtual devices

To easily and quickly create a new application, click on the “Create” button. A new window opens where the user first selects an account to which the virtual device should be created. After selecting the account, the second field to the right of it shows the connectors available for the account.

Once a connector has been selected, both fields are locked for editing and can be subsequently adjusted again using the change button. In the next step, a new virtual device can be created for this connector or an existing virtual device can be imported. If the user decides to import an existing virtual device, he enters the external identifier of the device in the corresponding input field and presses the “Import” button. After that, the virtual device is searched in the system connected by the connector. If the search is successful, all possible input fields are pre-filled. If it is determined during the import that the device is already recorded in the system, a corresponding message is displayed to the user and then the user can decide whether he wants to continue using the already created device or still import the device a second time.

By clicking the “Create” button, the user can create a new virtual device. The input fields to be filled in in order to create a new device will appear:

Title:* Give the device a meaningful title for easy identification.
Parent object:* In this input field, you can select the digital twin to whose authorization environment the virtual device should be created.
Description: Enter a short description of the device that will appear on the detail page. (Supports Markdown formatting)
Tags: Use a dropdown to select tags that already exist in the system or to enter new tags.
Operational status: You can choose between “Not set”, “On the way”, “Operational”, “In operation”, “Temporarily inactive” or “Shut down”. To check the status for the report display on the details page, the most recent operating status of the device is combined with the threshold value.
Device Type: If the virtual device belongs to a specific device type, you can select this type from the list and assign the devices directly to interpret the payload of data packets during installation and after commissioning.
Groups: Virtual devices can be assigned to an infinite number of device groups. In the dropdown “Groups” you can choose between the different groups already existing in the system. You can also select multiple groups. If the corresponding device group does not exist in the system, a new device group can be entered in the “New device group” input field and added to the existing groups by clicking the button with the plus symbol.

CSV-Export for virtual devices

You can export incoming data from virtual devices as CSV-file. To do this easily, select a device, then click on data states. By clicking the CSV-icon you can configure the export [1].

When you click on the CSV icon, a new window will open where you can select the time period as well as select the required data points. You can also specify a name and an email address to which a download link will be sent after the download is finished. As soon as you select a data point, you can generate the CSV-file by clicking on the “export” button.

You can find the CSV-file by clicking on the “CSV” button in the top right corner of the menu bar. Then the page “CSV-Export” opens, where you can download the file. Here you can either click directly on the icon located on the right side of the line [2], or you can select the file and click on the download icon.

Connector-specific data

Each virtual device has special data that is essential for the operation of the device. This data varies depending on the connector type.

TTI Connector

In this connector, a terminal device ID must first be recorded. This ID may only consist of lower case letters and numbers are not allowed. Next to the and device ID, the activation method must be selected. Depending on the activation method, further special input fields build-up, which have to be filled in according to the technology and the supplied details of the device manufacturer.

Firefly

The connector specific data can be used to remotely control the common LoRaWAN settings of the sensor in the Firefly LNS. The setting “Deduplicate packets” sets the option “Ignore consecutive packets with equal frame counter” in the Firefly, which ensures that a data packet with a frame counter that already exists is discarded. “Skip frame counter increment check” controls the option of the same name in Firefly, which ensures that packets are only accepted if they have a higher frame counter than previously received packets.

Edit virtual devices

Virtual devices already registered in the system can be viewed and edited by the user. Edit a single device by clicking on a device in the overview list or on the “Edit” icon on the right. This will take you to the device information.

Here you can change various properties like title, EUI, description, and other fields. In this tab, the type of the device is displayed in the upper left corner, which is used to interpret the payload, among other things. This device type is clickable and leads the user after clicking directly to the overview of the corresponding device type. To the right of the device type, the user is shown when the device was created and how much time has passed since the last incoming data packet. To the right of this information is a dropdown for selecting a relative or absolute time period. This time period specifies for which time period all the information listed below will be prepared.

In the next line, the user will find the packet history as well as the live view. Here, all packets are listed that were received by the system in the selected time period. If the selected period ends in the current time, packets received in real-time are displayed live in the packet history. To the right of the packet history is the packet visualization. In the packet visualization, on the one hand, the raw received data of the data packet is displayed in JSON format, moreover, the payload interpreted by the previously assigned device type is displayed as JSON.

In the next section, the user is shown a bar chart visualizing the packet volumes received by the system in the selected time period. Here, the colored bars show the currently selected time period, and the gray bars show the previous time period. This gives the possibility to easily see if the device is sending data reliably compared to the previous period.

Below this, there is now the general device information such as external, e.g. identification number, the operating status, the device type, and the device group(s) as well as the possibility to add a new device group. All data can be changed and saved here.

Below this, the user will find the section of downlinks. Here you can enter a payload, select encoding, and a corresponding port over which the payload is to be sent. In addition, it is possible to select whether the downlink should be confirmed by the system or not. By clicking on the “Send” button, the corresponding downlink is sent to the virtual device in the real world.

Change Device Type

The last section of this overview contains the connector-specific data. This data cannot be changed and is read at runtime from the system that is connected by the connector and displayed. If there is a wish to change this data, the user must log in to the connected system and perform the data change there.

There is both the option to resynchronise a device type to apply changes of a device type to the virtual device, and the option to change the entire device type.

Both functionalities should be used with caution, as that change to the Virtual Devices will also affect data states in Digital Twins and these may need to be re-created to receive data again. The data in the Virtual Device itself will be deleted with both functionalities.

To resynchronise the device type of a virtual device and apply the changes of the device type to the virtual device, click on the button next to the device type and then save the virtual device.

To assign a new device type to the virtual device, the list of available device types must first be unlocked. To do this, click on the button with the lock. The desired device type can then be searched for and selected. Once the correct device type has been selected, save the virtual device.

Please note that the changes to the virtual device are only applied when the device is saved.

Important Data States

Each of these objects has two non-erasable data states which are generated automatically. The “_raw” data state is the unmodified data that is sent to the object. The “Health” data state stores the information for determining the “Health”.

“Health” Data State

The data state is particularly important because the calculation for the system status of the object takes place in it. In edit mode, you can select from all data states created by the device type that are relevant for determining the “Health”. After that, when a specific detection logic is defined for each selected item. Program examples are given for this determination logic.

For example, a device can receive a warning when the battery level is below 40% and an alarm when the battery level is below 20%. At the same time, another alarm can be triggered if the device reports an error. The “Health” can therefore assume and display several faulty states at the same time.

To avoid having to configure every device, the configuration can be prepared once in the device type. This can be done under “Device Health Config” and applies to all devices created afterwards that are assigned this device type.

Overview of different health states and evaluation logic

The health state will be evaluated with every new packet that is processed for the device and additionally in a time interval defined by the health check - rule which is created automatically with the health state. By default this rule is executed once a day, so that even if not data is arriving to the sensor an alarm will be created for this devices if for example the health state is configured to set an alarm if no data was received for example for 24 hours.

Different health states:

Unknown: before a device receives the first data packet the health state status will always be unknown, even though there might be configuration to check for packets every 24 hours. This is to more easy distinguish devices which have real errors from those which are not activated yet but were already imported to the system.
Ok: If devices received at least on data packet in the past and have no warnings or errors.
Warning: If according to the configuration of the health state an error is detected.
Alarm: If according to the configuration of the health state an alarms is detected.
Invalid: If there is no health state for this device (could be devices which were created before the health state was available) or the value can not be interpreted by the system (which might occur if the health state has a custom javascript transformer).

Authorisations

All virtual devices, unless otherwise set, are created to the root twin of the corresponding account when the device is created or when the device is changed. This means that only users who have permission to view and/or change the root twin can see the devices. If a device is to be given a different permission setting, for example to belong to the permission group of a child twin, this can be set by changing the parent object (under Meta information).

For a user to have viewing as well as writing permissions of the virtual devices, the following roles are required on the respective account: DigitalTwin.list and VirtualDevice.manage.

For a user with only reading rights to the virtual devices, the VirtualDevice.read role is required.

Devicetypes

Under the menu item “Devicetypes” you will see a list of the device types to which you have access with your account. Here you create templates for using and grouping devices with the same functions and data structures with the appropriate user rights. You can use standards for converting packet data via a packet parser. Devicetypes can be used for IoT-Data-Hub Devices and Virtual Devices. See full documentation can be found here in the IoT-Data-Hub section.