Digital Twin

This section describes the features of the digital twin, which can be accessed through the corresponding menu in the main menu. The functions are displayed to you according to your assigned role. Depending on your role, you are allowed to view, edit or create a digital twin.

Digital twin hierarchy

The first page of the menu, “digital twin” gives you an overview of all available digital twins. You can navigate through the tree hierarchy and fold or unfold digital twins (1). You can also switch from the tree hierarchy to a simple list view by clicking the button in the upper right corner. In this view, you can filter the twins by accounts with the button on the top.

With the search field, you can search by the name of a digital twin (2). The hierarchy is automatically filtered.

To see more details of a digital twin, you click on its name. Open the map view with the location of the digital twin via the button “Load map” on the top right (3). In the tree hierarchy of Digital Twins, the ID is displayed next to the title.

By clicking on the “star” icon, you can filter for the twins you marked as favorites.

Map view

If you select a digital twin and click on the “Load map” button, you can see the twin and its sub-twin on a map. Like in other applications like Google maps, you can move the visible section of the map by clicking and dragging.

If you click on a digital twin, the dashboard with the states of the twin opens up. You can edit states directly here.

With a click on the gear icon in the lower-left corner, you can open the map settings. Here you can change the view of the map. You can filter by tags associated with the states so that only the corresponding states appear. In addition, you can select states so that certain state values are displayed directly in the map with the coloring corresponding to the value. You define the color in each state itself, e.g., in the visualization of a data point value as a dial gauge.

Click on the gear wheel icon on the top right to switch between different appearances of the map view in the settings of your browser.

With one click on the button of the map, you can return to the digital twin detail page.

Create and edit a new digital twin

To create a new digital twin, select the parent digital twin in the hierarchy and click on the “+” icon [1]. A new digital twin will be created as a child of the selected digital twin.

To edit a digital twin, select the digital twin in the hierarchy and click on the pencil icon [2].

To duplicate the selected digital twin, click on the “papers” icon [3]. The digital twin will be duplicated and saved on the same hierarchy level.

If you have admin rights, you can delete a digital twin with a click on the trash bin icon [4].

Duplicate digital twins and add multiple via CSV upload (bulk upload)

The copy function allows you to duplicate a digital twin and create a large number of twins (up to 50 copies) simultaneously. You can use the CSV upload here to perform a mass import quickly and easily.

Note: You cannot copy a root twin, so the duplicate button is not displayed here. Duplicating is only possible with “sub” twins. Only the selected twin is copied at a time. If you copy a twin under which other sub-twins are arranged, only this one twin is duplicated.

Duplicate data states based on virtual devices:

With these steps you duplicate a twin with data points based on virtual devices:

  1. With these steps you duplicate a twin with data points based on virtual devices:

  2. A pop-up appears in which the duplicates can be configured. Select “Virtual devices” in the data state selection mode.

Now there is the possibility to create the duplicates via CSV import, or via the interface.

Creating duplicates of data states based on virtual devices via CSV import

To create the duplicates via CSV import, first download the sample CSV file as a template. After filling in the CSV file, it can be uploaded again and the duplication triggered.

ℹ️ Note the information given in the user interface for the structure of the file.

Create duplicates of data states based on virtual devices via user interface

  • Number of copies: Specify how many copies of the twin are to be created. According to the selection, one column appears per desired duplicate.

  • Parental Object: If the toggle button “Use the same parent twin for all” is activated, the input field is activated and a uniform twin can be selected under which all duplicates are hung. The fields for the parent objects of the individual duplicates are deactivated by this.

    In the following line, the meta data to be configured can be selected, which are to be changed during copying. Input fields are added to the respective twins.

    If these fields are not activated, the respective data of the twin to be copied are taken over.

  • Tags: Assign tags to the copies of the twin.

  • Address: Assign an address to the copies of the twin.

  • Geo-coordinates Config: If this field is activated, geo-coordinates (latitude & longitude) can be defined for each copy.

  • Custom Properties: If this field is activated, any number of user-defined properties can be added to each copy in the format “Key: Value”.

Meta Data
  • Title: Specify the title of the copy of the twin.
  • Parental Objekt: Select which twin is to be the parent object if the copied twin is to be subordinate to another sub-twin, for example.
Data States

  • The following section displays the title data points based on Virtual Devices (or on IoT Datahub devices). To create duplicates, the External ID of the device to which the data points of the new copy are to be linked must be entered here.

  • Data State Options: There are three dots behind each input field for the External ID. By clicking on them, it can be defined for each data point that this data point should not be created in a duplicate. In addition, it is possible to define that this data point should be created, but not connected to a virtual device (“Source Type: None”).

    ℹ️ This function is only possible for data points based on Virtual Devices.

  • Three copies are always displayed per page. To add or edit further copies, you can switch between the individual pages of 3 copies at the bottom.

When all mandatory fields are filled in, the button “Duplicate” is activated. With one click you can create the copies. If the addition is successful, a confirmation appears. The new twins will immediately appear in the list.

Duplicate data points based on IoT Data Hub devices:

Use these steps to duplicate a twin:

  1. To duplicate the selected digital twin, click on the “Copy” icon, the second button from the left at the top.

  2. A pop-up window will appear, in which you will enter the following information.

    • Number of copies: Specify how many copies of the twin should be created. Then, at the bottom of the field, according to the number, more gray boxes will appear, where you can enter the information.
    • Datapoint selection mode: Here you can choose between “Complete” and “Only EUIs for IoT Hub data points.” To map the states, you can either use the complete UI with search and variable-picker or have a reduced UI with just a field for EUIs for each IoT Hub state. In the latter case, it is expected that the variable-name of the linked IotHub device is the same - and only IotHub states can be mapped, all connectors will be copied untouched. If you want to use the CSV upload, this only works under “Only EUIs for IoT Hub data points.”
    • Parental object: If you click the adjacent button “Use the same parent twin for all,” the field will be activated, and you can select one twin as parent object for all copied twins.
    • Title of digital twin: Enter the title of the copy of the twin.
    • Parental Object: Select which of the twins should be considered as the parent object if the copied twin should be subordinated to another sub-twin, for example.
    • Tags: Immediately assign tags to the copies of the twin.

  3. If you choose the CSV upload option, you can upload a CSV file with the information for the duplicates under the “Upload CSV” button. You can download a sample file from the link below the “Number of copies” input window. If you include the latitude and longitude information in your CSV file, a polygon will automatically be created in the map around the position of the copied twin.

  4. When all mandatory fields are filled in, the button “Duplicate” will be activated. With one click, you can create the copies. If the addition was successful, a confirmation will appear. The new twins will appear on the list immediately.

Mass Synchronization of Digital Twins

You can synchronize a Digital Twin with one or more twins in a few steps. Information such as the title, twin type, icon of the twin, or visualizations of its states is thus simply overwritten to other twins and all synchronized uniformly. This is especially useful when updating javascript transformers, for example.

  1. Click on the button on the far right of the top bar. Then a window opens, in which all twins available for you are shown in a list. Synchronization is also possible across accounts, so if you have access to multiple accounts, you can see all the twins available to you. Select the twins you want to synchronize with the opened twin.

  2. Below the list of twins is the “Information” field where you select which information or data points that are part of the selected twin should be synchronized with the other twins. This information will be overwritten in the other twins if there is an identical data point key in them. The synchronization can be done for the basic values such as title, unit, icon, visualization, and javascript transformer.

  3. When all mandatory fields are filled in, the “Synchronize” button is activated. With one click you can perform the synchronization.

Digital twin page

The digital twin page is split into five tabs to group different functionalities:

  1. Dashboard: Visualize a digital twins’ states.

  2. Information: Edit basic information (master data) like title or type.

  3. Details: Configure digital-twin-type related information like geolocation.

  4. Data states: configure IoT-related information (process data) and connect digital twins to physical IoT devices.

  5. Rule editor: Define rules to trigger actions.

    In the detailed view of a Digital Twin, you can easily switch to other twins in the tree hierarchy, where the current twin is located, by clicking one button.

Dashboard

The dashboard visualizes the states. When adding a state, a corresponding element is automatically added to the dashboard.

Beside the value itself, each tile shows the name ([1]), the measurement unit ([2]) and the timestamp of the last update ([3]) as well. With the calendar icon ([4]), you can display past values (for numeric data states).

View data states’ history

With the calendar icon on each tile you can (for numeric data states) see the historical values. The data can be displayed as diagram as well as in a table.

In the diagram, the shown data points are an aggregation of the corresponding raw data for the interval. Due to technical constraints, this aggregation is necessary, especially for longer timespans.

With the date picker on the top right ([1]), you can select the timespan (x-axis). With the dropdown list on the bottom left ([2]), you can choose how long a data point’s interval should be. Beside, you can activate/ deactivate different graphs to display the minimum, maximum and average for the interval ([3]). With the checkbox “smoothen lines” you can smoothen the graph. The checkbox “hide empty values” lets you remove timespans with no data ([4]).

In the second tab, you can find a table with the raw data for the selected timespan. Due to technical constraints, this list is limited to 1000 values.

Meta information (master data)

  • Digital twin title: displayed name of the digital twin
  • Icon: the displayed icon for the digital twin
  • Description: providing details about this digital twin
  • Twin type: Select the corresponding type of digital twin (e.g. “building”, “zone”) to activate type-specific functionalities and text fields; e.g. the access management for “building” twins (requires additional modules).
    • Default (default): Can be used for structuring your Digital Twins
    • Building (building): Can be used for structuring your Digital Twins
    • Sensor (sensor): Can be used for structuring your Digital Twins
    • Room (room): Can be used for structuring your Digital Twins
    • Door (door): Can be used for structuring your Digital Twins
    • Zone (zone): For Asset Management
    • Floor/Level (floor): With this Twin type, you are able to add a Floor Plan to your map.
    • Trackable (trackable): For Asset Management
  • Parent object: Define to which parent the digital twin belongs; e.g. to move a digital twin between different organizations.
  • Tags: Apply tags for your individual needs, e.g. to organize the status during configuration (“ready”, “work in progress”) or to group digital twins by different criteria. Tags are displayed under the description.
  • Users and responsibilities: You can assign users from your account as responsible employees and technicians for a digital twin. Assigning users does not have any effect on the twin. It is solely information for you and your account’s users.
  • Attachments: Upload files (e.g. PDFs, images, technical documents, etc.) with up to 10 MB as attachments for each twin to keep all relevant information in one place.
  • Custom properties: You can add your own attributes (e.g. “serial number” or “address” etc.) and their value to enrich the digital twin’s information with individual properties. Click on the “+”-button to add as many fields as needed.

To save changes in this section, click on the “Save”-button in the upper right corner. To cancel these changes, use the “Cancel”-button.

With the “disable”-button on the top, you can switch off a digital twin. By this, the digital twin will be invisible to all other users except for administrating users with the rule “all.manage”. Besides, the states will store the last received value and will not update anymore. Rules in the rule editor will not be re-evaluated or trigger actions anymore. Disabling a digital twin is the way to make it disappear in niotix. Because a digital twin has a lot of dependencies with other twins, devices, and accounts, it is not possible to directly delete a digital twin. By this, it is ensured for all users that no inconsistencies might appear.

Details

Depending on the type of digital twin, you can configure different properties in the first tab.

For all digital twins you can set up the geo-location, which can be a single position and additionally a geographical area (see below for description) or visualize the different locations and the movement of a digital twin in a certain period and area.

Define single point location

To set up the location of a digital twin, fill out the following fields:

  • Address: Type in the address where the digital twin should be displayed on the map. If the address is found in our database, the latitude and longitude will automatically be added.
  • Latitude, Longitude: As an alternative, you can also fill in these fields manually.

Automatically defined polygon

As soon as you enter an address, a static polygon is automatically created around each map icon of a digital twin, the radius you can freely set using the button below the map. This allows you to visualize the status of moving digital twins in the map. If you move only the map icon in the map, the polygon will move accordingly. If you click on the polygon, you can move it individually or delete it by clicking on the trash can icon in the map for the current view. You cannot save this view, it will automatically create a new polygon when you open the twin again. Below the map you will find the field “Geo Polygon”, where the latitude and longitude are automatically listed.

If you click on the rectangular icon in the upper right corner of the map, you can create the area around the map icon in the shape you want.

This is useful when visualizing multiple twins located at the same address.

Customize icon in map view

In addition, you can customize what icon is used for the map view. By default, the icon defined in the field “icon” will be used.

  • Map icon: Add a URL to an image (e.g. company logo or picture of the physical object).

NOTE: This only affects the map view, which can be reached when you select a digital twin in the hierarchy and click on the button “load map” (see section “Map view” above). The background banner of a digital twin and the preview in the “Digital Twin Details” will not display the custom icon.

Map Mode: Standard and Coordinate History

Under the “Details” tab, you can select two map modes: “Standard” and “Coordinate History”. Under Standard, the simple one-point location is displayed on the map. If you select Coordinate History, the different locations and the movement of a Digital Twin in a certain time period and a certain area will be visualized. You can use the arrows in the map to click the map icon to the different positions of the geo-history. You can zoom the map in the standard format with one click and zoom in on this form with the scroll wheel.

Map setting floor/floor with overlay wizard to include floor plans in map view

If you select “Floor” as twin type in the “Information” tab, the field “Floor settings (indoor)” appears under the “Details” tab. You can select this type if the twin is an indoor area, such as a floor of a building. If this selection is not made, the twin will automatically be interpreted as an out-of-building location.

You can enter a floor number or a floor name in the field. The floor number is additional information to the twin’s title. It is used for external identification and to display a floor switcher on the map.

You can easily embed the floor plans and plans of a building into the map view of a digital twin with the help of an assistance program. This way, you can also visualize relevant buildings from the inside, e.g., see the sensor’s exact position more easily.

  1. Click on the green button “Overlay Assistant”, then a new window opens with the wizard for embedding images in the map of the twin.
  2. Upload the image to be included. It will appear in the left part of the window.
  3. In the right field enter the address or coordinates of the area over which you want to place the image.
  4. Click on two places in the image left pane to create anchor points. These can be moved afterward.
  5. Then select their world coordinates in the map on the right. Note that the red and blue markers in both maps correspond to the same coordinates! Tip It is best to use prominent features like building corners, chimneys, etc. that are easy to assign.
  6. Click on the button “Calculate Overlay Bounds”. The image will now be transferred to the map view and rotated accordingly based on the position of the anchor points. The rotated image appears below the longitude and latitude data.
  7. Click on the button “Transfer data to twin”. The image now appears in the map view.

Data states

In the fourth tab, you find Data states (or short “states”) which are the connection for incoming data of a digital twin. Each digital twin can have many states to group data from different sources. Sources can be e.g. data from sensors, aggregated data from other digital twins, or randomly generated data for testing.

Data states are a powerful feature in niotix: With states, you can use digital twins to group different data from the IoT world (e.g. different sensors with different protocols) in a logical container representing a physical object. For e.g. an office can be represented by a digital twin, grouping all the different sensors in each room for humidity and temperature in one place.

In this tab, you can add a single state [1] or view details of all existing states [2]. You can export the CSV file of the received data of the devices [3].

Furthermore, you can edit [4] and delete [5] each state. By clicking on the “clock”-button, you can see the history of state updates (changed/reported values) [6].

Add single state

If you click on the “+”-button, you can add a single state. Basic settings of a state are:

  • Title: title for this state
  • Identifier: A key without special characters for identifying this state in the system (must be unique per digital twin). You can use a state to dynamically update the geo-location of a digital twin. By this, a digital twin can represent a mobile asset, and the reported position of a GPS device can update the digital twin. As soon as an identifier starts with “lon” or “lat”, the state will automatically be linked to the longitude- and latitude fields.
  • Unit: The unit which is displayed together with the value delivered from this state.
  • Icon: An icon for the state. To search for other icons, simply type in a keyword and the system will propose suitable icons.
  • Source: Select the bridge defined in your account for incoming data: “Aggregated” to use data from other digital twins or “Random” to generate random data or the bridge configured in your account (e.g. niotix; further description of each source see below).
    • For Connector-Type “MQTT”: With the text fields (Device)Identifier” and “parsed packet variable,” you can define the topic a state should subscribe to on the MQTT broker. The “Device)Identifier” is required, the other value is optional. Both fields are concatenated and must follow the pattern defined in the MQTT-connect in the field “path”.
  • Value type: Define the type of the value; e.g. if it is a number, a boolean (true/false) or a string
  • Value: Define a default value - which might be overwritten by the incoming data from a selected data source.
  • Is null: Mark this checkbox if the value should be empty - not the value “0”!
  • Skip transformer: Mark this checkbox if niotix should not run the javascript transformer when you save the state for the first time. Deactivate this switch if you manually set an initial value for a sensor, and you do not want to overwrite it directly with the latest devices’ value (e.g. if the device is not yet installed but activated and thus not measuring the right values)
  • Lower bound: The lower bound is used for the visualization on the dashboard to define the limits of e.g. a gauge.
  • Upper bound: The upper bound is used for the visualization on the dashboard to define the limits of e.g. a gauge.
  • Javascript transformer: Define a transformation function for transforming input data to the desired state value. The transformation will be executed each time the state is updated. See the description below for details.
Source “Random”

Use the source “random” to generate random values of a state. You can define the lower and upper bound of a value in the text fields.

E.g. if you set lower bound to 1 and upper bound to 5, niotix will create random values in the range of 1 and 5 (e.g. 4.3345345) every time you open (re-load) this page.

Source “Aggregate”

With aggregate states, you can select existing states from other states and combine them. By this, you can e.g. calculate the average temperature in a building based on its sub-twins, which represent a room in the building equipped with temperature sensor. Every time a selected state from another digital twin is updated, the aggregated state will update as well.

To define an aggregate state, select “Aggregate” as a source. Navigate through the displayed hierarchy of twins and select the required states [1]. niotix will list the selected states under the hierarchy [2] to keep the overview and quickly remove states not needed in the aggregation. Below, in the section Aggregate value you can also review how the incoming data of the aggregated state looks like.

Source “Aggregated timeseries”

Using the source “Aggregated timeseries” you can calculate a new data state based on the historical data of an existing data state.

This is useful, for example, if you want to calculate the maximum value of the last hour or the consumption of yesterday.

The following options are generally available for configuration:

  • Time aggregated data state [1] : select here the data state to be used for the calculation
  • Operation [2]: select what to do with the historical data of the data states:
    • AVG: Calculate the average
    • MIN: Determine the minimum
    • MAX: Determine the maximum
    • SUM: Calculate the sum
    • MEDIAN: Determine the median
    • COUNT: Count the number of data states
    • Difference to last period: Determine the difference of the maximum values from the selected and previous period
    • Difference to last value: Determine the difference between the last two values received. This function is helpful, for example, to calculate load profiles.

For simple use cases, the following setting can be done in the first gray box ("Predefined periods"):

  • Aggregation Duration [3]: select the period for the historical data of the selected data states. This is calculated starting from the current time. I.e. if it is 13:00 and an aggregation duration of 1 hour is selected, all data states up to 12:00 are used for the calculation.

Alternatively, the “Expert mode” is also available in the second gray box below, that allows you to configure detailed settings. In contrast to the “Aggregation duration” before, here you can set up calculations based on full calendar days, months, etc. (instead of calculations based on the current time).

  • Offset: Specifies how many units (e.g. days, months) should be calculated back. A value of 0 corresponds to the current unit (e.g. current day, current month). Negative values are not allowed.
  • Offset Unit: Specifies the unit for the offset.
  • Period length: Specifies the time period from which - starting from the offset - the data is to be aggregated forward.
  • Period unit: Specifies the unit for the time duration.

Note 1: Aggregation will only work correctly if all values are numeric, i.e. no non-numeric-strings, Boolean values or JSON values are present in the history.

Note 2: Regardless of the selected time period, at most the latest 5000 values will be aggregated.

Note 3: The time aggregated data states store their own value in the database and are recalculated whenever the connected data point updates. I.e. if the configuration of the time aggregated data states is changed afterwards, the already calculated values will not be recalculated.

Note 4: If an aggregation duration is selected for the time aggregated data state that is lower than the transmission interval of the sensor, it can happen that no packet was received in a certain aggregation interval. If there is no packet within a aggregation interval, niotix uses 0 for the calculation.

Note 5: As soon as the “Aggregation Duration” is selected, the fields in the “Expert Mode” area fill automatically. Conversely, the “Aggregation Duration” will deactivate if the fields from the “Expert Mode” are filled manually.

Example 1 on the configuration options

To illustrate the various configuration possibilities, here is an example:

The initial situation is a data state with the received temperatures listed in the first two columns.

The goal is to find out the maximum temperature of the last 15 min. by means of a temporally aggregated data states.

To do this, use the “Time aggregated data state” area to select the corresponding data state (in this example, “Temperature”) from which an aggregation is to be created over a period of time. Select the maximum value (“MAX”) under “Operation”, then a period of 15 minutes under “Aggregation Duration” and the type “Number” for the visualization in the “Type” field. You can optionally set the first value in the “Value” field (the value will be overwritten by the data source at the first update). Click “Save”, then the time aggregated data state will appear in the dashboard and in the list of data states.

In our example from above, the value 22 °C is shown as the maximum temperature in the last 15 minutes (see column 3: the maximum is taken from the data from 10:00 to 09:45). You can do the same principle with other operations (e.g. “MIN”).

If, on the other hand, in the same example, you select the operation “Difference to last period” and a period of 15 minutes, then the difference of the maximum temperatures between the last two intervals will be shown here.

For our example this would be the difference from:

  • The 1st interval (from 9:45 to 10:00), where the maximum temperature is 22 °C.
  • The 2nd interval (from 9:30 to 9:45), where the maximum temperature is 35°C.

The difference between the two temperatures is displayed, i.e. 22°C-35°C = 13°C.

Example 2 about the configuration options

If, on the other hand, the goal is to find out the maximum temperature of 2 days ago from the whole (calendar) day for the temperature values given above, then you have to choose the expert mode.

With the “offset” of 2 and the offset unit “day” you select the day before yesterday (2 days ago). The following table gives an example of the offset function:

Select 1 as the time duration and “Day” as the time unit to include the entire calendar day as the time period for the evaluation.

Source “IoT Data Hub Aggregation”

The source “IoT Data Hub Aggregation” provides the possibility to process several variables of a device at the same time as one state. This function is particularly useful if, for example, you want to link the humidity and temperature values that originate from a device in a condition of a rule. Based on the condition, the rule can be triggered afterwards.

Furthermore, this functionality is used to link GPS coordinates (longitude and latitude) from a device directly and easily in one step with the geo-coordinate of the digital twin.

To display the history of GPS data in the detailed view of a twin on a map, you can create the aggregated state according to this instruction:

  1. Select the source “IoT Data Hub Aggregation” and a device from the IoT Data Hub to receive data from.

  2. Then select all the desired variables, whose values will be aggregated into a JSON object.

  3. The value type is a JSON.

  4. In the Javaskript transformer, define the two variables lat and lon, e.g.:

    module.exports = (data) => {
 return {lat: data.gpsLatitude, lon: data.gpsLongitude};
}

  5. Then link this state to the geo-coordinates of the twin.

  6. With the next incoming data packet the position of the twin will be updated directly.

Source Bridges

Depending on the bridges configured in your account, you can also select these bridges to connect your digital twin via states to other sources (e.g. niota 1.0).

The necessary text fields for configuring a state depend on the type of bridge you use. The following fields are an example for a niota 1.0 bridge:

  • niotix Data sources: Select the concrete bridge instance you would like to use. The names displayed here are based on the field “instance name” of each bridge in the account management.
  • niotix Device: Start typing in the device name from niota 1.0 you are looking for - niotix will automatically propose results.

After selecting the device, you choose the values you want to bind to this state by simply marking the checkbox on the left.

Visualization

For each data point, you can set different visualizations that will appear in the dashboard and map view. The following visualizations are available:

Standard: If you do not select any other visualization, the counter will appear automatically.
Gauge: Can be used for temperature or light intensity. With a dial gauge, critical limit values are displayed with value specifications and different colors. Define these values using the Minimum value and Maximum value fields as well as one or more comma-separated threshold values. These values are displayed in the dial gauge. You can also define in which colors the values should be displayed.
Donut: This visualization is suitable, among other things, for displaying individual percentage values, e.g. for people counting. In the donut, partial values of a whole are visualized as parts of a circle.
Counter: Can be used for metering. With the counter you can tailor the visualization to your needs: Determine the minimum character length and the decimal places.
Battery: Here the state of charge of e.g. a device is visualized by bars in a battery.
Line chart: The historical data of a data point is displayed in a graph. You can specify the lowest and highest value on the X-axis as well as the time period.

In order to be able to compare several line charts in a dashboard with each other, it can be useful to fix the values of the y-axis. For each chart it is now possible to set a minimum and a maximum value of the y-axis. The y-axis is then fixed in the dashboard. Values above the maximum or below the minimum are cut off in the visualisation. If no minimum or maximum value is defined, the axis remains variable at this section of the axis.

Since a longer period of time is often to be considered in a line chart, it is also helpful to give this visualisation a larger space in the dashboard.

Therefore, it is possible to define the space they take up in the dashboard, as well as the time span and interval to be displayed.


Boolean: With this visualization, it is possible to display truth values. For each state (True or False), a title, an icon, and the color of the icon needs to be selected.

Boolean Button

It is possible to create a button in the dashboard of a digital twin that can be used to generate the boolean values True and False to be used in rules and to send downlinks to devices.

This button is a data state with the visualisation for boolean values. Accordingly, it is created as follows: Since the button does not access any data source, the source “none” must be selected and the type “boolean”. It is then possible to select “button” as the visualisation. By saving, the boolean button is created as dashboard tile.

If the status of the boolean button is to be accessed in another data point, this is possible by creating an aggregated state and the following transformer, whereby “button_identifier” must be replaced by the respective key of the data state in which the boolean button was created:

module.exports = (data) => {
  return data.button_identifier.value;
}

Linking data points with geocoordinates of a twin

To display the history of recorded GPS data from other connectors (not IoT Data Hub) in the map view, you can create the data points according to these instructions:

  1. Create two separate data points/states for your Twin, namely Longitude and Latitude. Only one variable can be selected per state.

  2. For the dashboard visualization of the two states you can select “hidden”, as they do not necessarily have to be displayed.

  3. Create another state of the source “Aggregated” and select the two previously created states for aggregation.

  4. Set the state type as “json”.

  5. Add the following to the transformer:

     module.exports = (data) => {
 return {lat: data.gpsLatitude, lon: data.gpsLongitude};
}

  6. Activate the upper checkbox “Link to geo-coordinate”.

  7. Now your twin will be positioned in the map view based on the aggregated data point.

Javascript Transformer

You can define custom transformers to transform incoming data into the desired format and values. To use this powerful feature, basic knowledge of javascript is required.

  • Sample scripts: niotix provides some basic javascript as examples of how to work with the transformer. Select one of the examples from the dropdown list to see the javascript code.
  • Helper methods: Here you can see a list of often applied and supported javascript libraries that you can use to write transformers. Please have a look at the corresponding documentation of each library.
  • Sample value: To test your transformer, you can insert a value here. The button “preview” will use this value as incoming data for the transformer and display the result in the field “transformer result preview".

In general, the javascript transformer uses a similar annotation to NPM packages. A transformer is handled like a module and needs to explicitly define the exported result (module.exports). You can define the variable name of the incoming data by using the arrow function (...= (IncomingData) => { ... }). You have to return the result with return(TransformedResult)

module.exports = (IncomingDataFromSource) => {
     return (TransformedResult);
     }

Copying data states from digital twins

Under the digital twins there is also the possibility to copy already created data states and to use its attributes for the new creation of another data state from the same or another twin. This function thus makes it possible to create multiple data states with similar attributes from the same or different (device) sources more easily and quickly.

To copy a data state, first go to the “Edit” icon of the data point you want to copy. In the upper line of the edit view you will find the button “Copy configuration” [1], then click on it and close the window again.

To create a new data state in the same twin or in another twin, click on the plus symbol in the upper right corner [2].

Now click on the button “Apply Config” [3].

A new window will open where all attributes (title, key, unit, visualization, etc.) are already automatically selected for the next step of the transfer. However, you can change the selection of attributes according to your needs. After the selection you click on “Apply configuration”[4].

The fields or settings of the new datapoint will now be configured and filled in based on the previously selected information from the original datapoint. Please note that as the last step of the configuration you have to add the data source and possibly change the key (if the same title remains), as this may only occur once for each twin.

CSV-Export state history

You can export incoming data from digital twins as CSV-file. To do this easily, click on Data points. 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.

Rule editor

With the rule editor, you can bring your digital twin “intelligence”. Rules are used to evaluate incoming data from states and trigger actions, e.g. send emails or downlink packages to LoRaWAN-devices. By clicking on the “+”-button, the interface for adding new states opens.

Create event-based rule

To create a new rule, you have to go through at least 3 steps in the interface:

  1. Define the states to use (state metrics).
  2. Define the conditions to evaluate the state metrics (conditions)
  3. Define the action which is triggered when the conditions are met (commands).
  4. Optionally, you can test your rules (rule tester).

In the section State metrics, you can select the relevant states:

  • State: Select the state from the dropdown list.
  • Metric alias: Use this alias to define a custom name that can be used in the rule editor. By this, you can define self-explanatory alias instead of the state name. Or you can use the same state with different alias in your rule (e.g. to use the last value of a state as well as the average value to calculate if the current value is above the historical average)
  • Last X minutes: Define the time interval from which the reported values for the rule originate. Click the checkbox on the left to use or not use this setting.
  • Last X values: Define how many reported packets should be used. Again, click the checkbox to use or not use this setting. If both checkboxes are activated, all reported values matching one of the criteria are used (“OR”-condition)
  • Math. Operation: Select the operation which should be supplied to the selected values: E.g. SUM() to calculate the sum of the values or max() to only use the highest value.
  • Transformation: Optionally, you can transform the incoming values with javascript-based functions. To do so, add your code as a return value. This feature is useful if you have different sensors reporting different formatting for values and you want to unify them (e.g. temperature-sensor 1 sends values with 3 digits after the decimal point and temperature-sensor 2 sends values with only 1 digit after the decimal point).

You can add more states for your rule by clicking on the “+” -button and delete states with the “trash bin”-button. Note: When testing the rule using the button, the state-name variable is not replaced by the concrete value.

After setting up the states, you can define the conditions. This is done in 4 steps:

  1. Select the corresponding state metric defined previously.
  2. Select the evaluation type; e.g. "greater than >", "equal to ==" or "greater or equal to >=" from the dropdown list.
  3. Set the value to be evaluated against.

By clicking on the “+”-button, you can add further conditions on the same level. With the dropdown on the left, you can choose how to connect them (“AND” or “OR”).

By clicking on the “f(x)"-button, you can furthermore nest conditions (sub-conditions).

To remove conditions, simply click on the “trash bin”-icon.

The following pictures give you an example for a condition to evaluate 2 temperature sensors and trigger actions if both sensors are above or below a pre-defined corridor:

In the last step, you have to set up the action (command) that is triggered when the conditions are met:

  • “If condition…": Select the way of triggering: Choose changes if the action should only be triggered when the evaluation changes (e.g. from true to false). Choose evaluates if the rule was evaluated and met the criteria (e.g. it was set to true in the past, got re-evaluated and the result of the evaluation is again true)
  • "…to…": Define if an action should be triggered when the condition is true (all conditions are met) are false (conditions are not met).
  • "…execute…": Here, depending on the configured bridges in your account, you can select e.g. to trigger an email, MQTT-message and in addition send downlink packets to devices in firefly or actility. Depending on the selected command, further possibilities will appear such as the receiver, subject and text of an email message. Furthermore, in each text field - also depending on the selected connector - in addition to the title, the ID and the concrete value of the previously selected data state, one can now also use its hierarchy and the custom properties by means of the syntax/ placeholders in rules of a digital twin. For example, when a rule is triggered, additional information can be provided to the receiving third-party system so that it can process the data automatically.

Optionally, as the last step you can test your rule with the rule tester:

For each state metric, you can define a sample value in the text field. With the “Test metrics and conditions”-button, the rule will be evaluated.

Create a time-based rule

In addition to an event-based rule, you can set a time-based trigger. Here you can define times and rules at which the conditions defined above are additionally checked, even if no state value has changed or updated. The rule will continue to be executed outside the defined times when a state value is updated.

You can find this option when opening the window for creating a new rule under the fold-out box “Time-based triggers”. You can select whether the rule will be triggered in a repeating time interval, e.g. every 2nd hour at the 30th minute, on a certain day of the week or on a certain day of the month. At this set time, the specified condition is then automatically checked, and the command is executed only if the condition is met. Note: With the “Repeating” setting, the smallest possible interval is one hour. If a smaller interval is required, the rule must be created several times.

INFO: The interval for time-based trigger must be at least 1 hour. The user interface automatically corrects smaller intervals to avoid mistakes. If you need a smaller intervals (e.g. every 30 min.), you should create several rules with different starting times.

Under the field “Comparison metrics” you can now also use the mathematical operation “SINCE_LAST_UPDATE”, which in combination with the time triggers becomes a simple health check. The operation returns the number of seconds since the last update, regardless of what filters were selected above. However, this is not an active metric, it is recommended to work in combination with temporal triggers. It always needs a temporal trigger to be checked, as it does not return data point changes, but a period of time.

Create location-based rules

In addition to the existing event and time-based rules, you can use the locations of Digital Twins as additional triggers for a rule: For example, when a Digital Twin moves out of or into a defined area, an action is triggered. To use this rule, you set twins for the area as well as twins for the object.

To create a location-based rule, you need to go through the following steps in the user interface:

  1. Click the plus button in the upper right corner to create a new rule.

  2. In the window that opens, click the “Geofencing” box. This will cause a second “Geofencing” tab to appear under “Rule Input”.

  3. To create a location-based rule for the twin, you must have created a second twin of type “zone” before creating the rule, and you must have defined a polygon in its “Detail” tab. In the “Twin with geo zone” field you select this twin. Only twins of type “zone” will be displayed as clickable.

  4. After you have selected the zone for your object twin, you define the “trigger mode” in the drop-down field next to it. Here you can choose between “Zone Entry”, “Zone Exit”, “Zone Duration”, “Duration Out of Zone”, “Entry into Radius” or “Exit from Radius”.

Some modes require additional information: When you select them, a third field appears in which you can enter information such as duration or meters. For example, as soon as your object enters the defined zone, the rule is triggered and the action you define further down in the box as for the other rules is performed.

You can also uncheck the “Data Point Comparison Metrics” box in the Rules mode and create a rule that will be triggered only in case of a location change. In addition, you can combine location-based rules with event-based or time-based rules, as well as Javascript conditions.

Note: Location-based rules are not only a trigger but also a condition for triggering a rule. Even if you have defined a time-based trigger for geofencing, at least one geofence condition must be met at that time to trigger the rule.

Duplicate rules

You can copy rules from one digital twin to one or more other twins in the same account.

  1. In the overview in the “Rule Editor” tab, you will find the “Copy” button. When you click it, a new pop-up window will open with a list of the twins available to you. In this list, you can only select the twins that are in the same account of the original rule, as rules are account-dependent.

  2. Once you select a twin, another field will appear at the bottom where you select the data points to which the duplicated rule in the other twin should refer.

  3. The button “Create copies” will be activated and you can transfer the rules to other twins with one click.

Rule overview

In the last tab, you can see all the rules created for this twin and its child twins in a list. The rule includes title, assigned twin, last execution, last result, the commands for execution, and corresponding icons for rules based on time or geo-location.