Skip to content

Device Mapping

In order to correlate the device simulators and their measurements to MindSphere assets and their aspects you need to define a mapping. This can be done manually by "Asset Mapping" provided in the Device Management Application. Therefore, go to Device Management > Asset Mapping.

The main view is separated into two panels: Navigation (containing Devices and Assets) and Mappings area. On the navigation panel, the left side shows all available device groups and devices. The right-hand side shows all available assets of the related MindSphere tenant. A table below shows the current mappings.

On the top there are filters which can be applied to the device and asset view. Depending on the default view setting (Configuration), the devices are shown in a list or in a group view showing the devices within their groups. If the group view is enabled, the search applies to group names only. When devices should be searched by name, the "All devices" view can be used.

Device mapping

Differences among available kinds of mappings

Measurement mappings are the usually used mappings to map measurements/ data-points of a device to an (dynamic) aspect of an asset.

In case of non-number values event-data mappings can be used, if it is needed to map those non-number values like Strings to an (dynamic) aspect of an asset. In this case those values can be send by the device as an event. An event-data mapping can then be configured to take the content from the event-data mapping and transmit it to the mapped aspect.

For device information which should be transmitted to MindSphere metadata mappings can be used. Any arbitrary metadata provided in the device object can be mapped to a static aspect.

For device related events and alarms which should be transmitted to MindSphere, event mappings and alarm mappings can be used respectively. Both events and alarms can be mapped to MindSphere events.

Create a mapping

To create a mapping proceed as follows:

  1. Select a device on the left-hand side of Navigation Panel. (You can see available data-links in the dropdown menu in the Mappings-Area)
  2. Select an asset on the right-hand side of Navigation Panel.
  3. Click "+ Add Mapping". (You can only add a new mapping when you select a device and an asset)
  4. Specify mapping details in the dialog.

In case of many devices and assets, the search text fields for each section can help finding devices or assets on navigation panel.

  • The search auto applies once you hit the "Return" (Enter) key.
  • Also: if you delete the existing search string and click "Return", all devices and assets are shown again. (If the filter type is set to "SHOW ALL", this will show the "group view")
  • Enter at least 3 characters to activate the search immediately without hitting the "Return" key.
  • "Clear all" is implemented inside the search box which clears the entered text and shows the "Group view".

Click on "Clear selection" to clear the selection on the navigation panel.

Clear selection

After clicking "+ Add Mapping" a dialog appears to select the mapping information of the selected device and asset. The "+ Add Mapping" button is disabled in case the selected device and asset are mapped using a template.

There are several options to add a mapping:

  1. Choose from existing mapping template:
    • Select a template from the drop-down menu.
    • Click "+ Add" to apply this template to the selected device and asset. Add mapping
  2. Add measurement (data point) mapping:
    • Select the required "Source", "Target" and "Converter" information:
      1. "Measurement": Source measurement of IoT Extension
      2. "Series": Source series within selected measurement of IoT Extension
      3. "Aspect": Target aspect of MindSphere
      4. "Variable": Target variable within selected aspect of MindSphere
      5. "Converter": Possible conversion of units of measurement from Source to Target (e.g. Celsius to Fahrenheit)
  3. Add event-data mapping:
    • This process is very similar to measurement mapping.
      1. "Event Type": Select from all event types the device is sending
      2. "Event Property": (optional): Select specific property of the event
      3. "Aspect Name": Select aspect of chosen asset
      4. "Variable": Select variable of selected aspect
      5. "Converter": Possible conversion of units of measurement from Source to Target (e.g. Celsius to Fahrenheit) Event data
  4. Add metadata mapping:
    • This process is very similar to measurement mapping and event-data mapping.
      1. "Property Name": Select from all device properties
      2. "Aspect Name": Select aspect of chosen asset
      3. "Variable": Select variable of selected aspect
      4. "Converter": Possible conversion of units of measurement from Source to Target (e.g. Celsius to Fahrenheit) Metadat mapping
  5. Add event mapping:
    • Select the required "Source" and "Target" information:
      1. "Event Type": Select from all event types the device is sending.
      2. "Event Type": Type in the event type from MindSphere which should be used for event creation. After typing in first three letters, press enter. The dropdown displays the available event type starting with entered letters.
      3. “Severity”: Enter the severity of the event. By default, the severity is 40.
    • Add Custom Field Mapping (optional): Click on "Add custom field mapping" to map specific properties of the events between IoT Extension and MindSphere.
      1. “Source Property”: Select specific property of the event.
      2. “Target Property”: Select specific property of the MindSphere event to which source property should be mapped. Event mapping It is possible to add multiple custom mappings in an event mapping.
  6. Add alarm mapping: The creation of alarm mapping is similar to the creation of event mapping. However, in case of alarm mapping, an alarm type is mapped to an event type. Based on the created alarm mapping, a device alarm is mapped to a MindSphere event. A "1:1" mapping is maintained between an alarm in IoT Extension and an event in MindSphere based on their IDs. For a new instance of an alarm of the mapped alarm type raised in IoT Extension, a new event is created in MindSphere. Any further update to that alarm would trigger an update of the same event until the alarm is set to "CLEARED". Once an alarm is cleared, another device alarm of the same alarm type would be mapped to a new event in the MindSphere.

Note

The event would always hold the timestamp once it is first created as MindSphere event does not allow updating the timestamp.

  • Select the required "Source" and "Target" information:
    1. “Alarm type”: Select from all alarm types.
    2. "Event Type": Type in the event type from MindSphere which should be used for event creation. After typing in first three letters, press enter. The dropdown displays the available event type starting with entered letters.
    3. “Severity”: Enter the different severities of the alarm. Based on severity of the alarm selected in source, one of the four severity in target is used during event creation. By default, the severity is 20 for critical and major alarms and 30 for minor and warning alarms.

Note

In the source only the type of alarm is selected. However, the actual alarms in IoT Extension can be of different severity, even from the same type. For example, an alarm of type "myDeviceAlarm" can be raised with severity "Major" or "Warning". Depending on this source severity the related event in MindSphere is created with the specific target severity specified in the mapping.

  • Add Custom Field Mapping (optional): Click on "Add custom field mapping" to map specific properties of the events between IoT Extension and MindSphere.
    1. “Source Property”: Select specific property of the alarm.
    2. “Target Property”: Select specific property of the MindSphere event to which source property should be mapped.

Add Custom Field Mapping

It is possible to add multiple custom mappings in an alarm mapping.

Clicking on "+ Add" creates a mapping between source and target. You can add more mappings by repeating the above steps.

At this state the mapping is not committed yet. Mappings must be committed (published) by clicking on "Commit Changes" and applying those changes in the confirmation dialog box. This action activates all mappings immediately. As long as there are no mappings to commit, nothing will be shown in "Commit Changes" pop up.

Commit changes

Add

Mappings of any devices or assets are shown on demand. (No mappings will be shown unless any device / asset is selected)

  • Mappings can be sorted based on the Measurement, Series, Aspect Name, Variable and Status.
  • Mappings can be deleted by clicking on the "trash" icon.
  • If no mapping is found for the device or asset, the following notification appears:

Mapping

Existing mappings can be saved as template:

Map template

Delete a mapping

Deleting single mappings can be done as soon as a device or an asset and one of its datalinks is selected.

The datalink between a device and the onboarded asset can be deleted by selecting it and clicking on the trash-icon afterwards. We can choose whether the created MindSphere asset should be deleted or not. In any case the locked asset will be unlocked when deleting the datalink.

Any questions left?

Ask the community


Except where otherwise noted, content on this site is licensed under the MindSphere Development License Agreement.


Last update: May 9, 2022