Associate 3D objects with source devices

Create digital twin experiences through the integration of live systems data and real-time 3D data. When working with a small number of devices, you can sometimes map source devices to their 3D representations in Unity. However, it's impractical to manually map source devices when dealing with a large number of devices and complex Unity applications. In this case, leverage the data association to programmatically and automatically map IoT devices to their 3D representations in Unity. With data association, you can define rules that tell the system how to map your source devices to their 3D representations in your application. Direct Mapping and Regular Expression are the supported rules.

Data associations create relationships between source devices reporting on telemetry and 3D objects within your application. You can interact with the data association service through the Live Systems Data API or the Digital Twins Live SDK.

For more information on data association terms, refer to the glossary.

Prerequisites

Before you use data associations, you must:

Configure a device connector to import your source devices into the system. Once configured, you can retrieve devices with the GET Devices endpoint.
Import the 3D object information from the model and/or scene used by your application. Once configured, you can retrieve 3D object information with the 3D Object Information GET endpoint.

Import 3D object information from your scene or model

Within the CAD software used to create your model and/or scene are BIM objects. These objects contain user-defined properties for the models in a scene that you can export and use in the Live Systems Data SDK. After you import these properties in the Live Systems Data SDK, you can associate the source devices obtained from the device connector with specific 3D objects in your scene.

To import 3D object information, follow these steps:

Use the 3D Object Information POST endpoint in the API or the Create3DObjectInfoAsync operation in the SDK.
Supply a JSON payload containing an array of objects, where each object in the array represents a 3D object in the scene to which you would like to associate a source device. The JSON for each object should contain the following:
- A key that facilitates mapping the 3D object to a source device.
- A key you can use to create an association with a source device, referred to as a CustomPropertiesMappingKey in a rule.
- A key with a value that uniquely identifies the 3D object in the scene, referred to as a CustomPropertiesGeometryKey in a rule.

The following JSON is indicative of 3D object information for wind turbines. In this example, you can use the DeviceId or SerialNumber key as the CustomPropertiesMappingKey in the rule, depending on if you want a Direct Mapping or Regular Expression rule. Also in this example, the GeometryValue key is used as the CustomPropertiesGeometryKey in the rule.

[
   {
      "DeviceId": "123",
      "Category": "Site",
      "Model": "T1000",
      "SerialNumber": "Turbine_SG400_T123_V1",
      "GeometryValue": "12345"
   },
   {
      "DeviceId": "456",
      "Category": "Site",
      "Model": "T1000",
      "SerialNumber": "Turbine_SG400_T456_V1",
      "GeometryValue": "6789"
   }
]

Data association rules

You can define rules to use with your facility to establish one-to-one relationships between source devices and 3D objects.

Supported rule types

Rule interpreters within the system run the rules. To view the supported rule interpreters, use the GET Rule Interpreters endpoint or use the GetRuleInterpretersAsync operation in the SDK.

The following rule interpreters are supported:

Direct Mapping
Regular Expression

Direct mapping rules

Direct mapping rules match a source device to a corresponding 3D object when the two share a key with a common value. For example, you can write a rule to associate the id of the source device to the deviceId of the 3D object.

Direct mapping rules are expressed as JSON and have the following properties:

SourceDeviceKey: the name of the key in the source device JSON, whose value is used to establish a relationship with a 3D object.
CustomPropertiesMappingKey: the name of the key in the 3D object's custom properties JSON, whose value is used to establish a relationship with a source device.
CustomPropertiesGeometryKey: the name of the key in the 3D object's custom properties JSON, whose value represents the ID of the game object that receives the source device telemetry.

The following example illustrates a direct mapping rule that associates a wind turbine (source device) that has an id of 123 with a game (3D) object in the application that has a DeviceId of 123. This allows the correct 3D object in the application to display telemetry for the correct source device.

Example of a direct mapping rule associating a wind turbine with a GameObject in the application

Direct mapping rule JSON operating against top-level keys:

{
    'SourceDeviceKey': 'id',
    'CustomPropertiesMappingKey': 'DeviceId',
    'CustomPropertiesGeometryKey': 'GeometryValue'
}

The following is a complete example of a direct mapping rule operating against top-level keys:

  {
    "name": "Wind Turbine Direct Mapping Rule",
    "expression": "{'SourceDeviceKey':'id','CustomPropertiesMappingKey':'DeviceId','CustomPropertiesGeometryKey':'GeometryValue'}",
    "ruleInterpreterName": "DirectMapping",
    "isAutomated": true,
    "isDisabled": false
  }

You can also write direct mapping rules that operate against nested keys.

Example of direct mapping rules operating against nested keys

Direct mapping rule JSON operating against nested keys and values:

{
    'SourceDeviceKey': 'Properties.SourceId',
    'CustomPropertiesMappingKey': 'Properties.SourceId',
    'CustomPropertiesGeometryKey': 'Properties.Code'
}

The following is a complete example of a direct mapping rule operating against nested keys:

  {
    "name": "Wind Turbine Direct Mapping Rule (Nested Keys)",
    "expression": "{'SourceDeviceKey':'Properties.SourceId','CustomPropertiesMappingKey':'Properties.SourceId','CustomPropertiesGeometryKey':'Properties.Code'}",
    "ruleInterpreterName": "DirectMapping",
    "isAutomated": true,
    "isDisabled": false
  }

Regular expression rules

Regular expression rules match a source device to a corresponding 3D object through use of .Net regular expressions.

Use regular expression rules instead of direct mapping rules when the source device and 3D object have a common value that must be extracted before a comparison is possible. For example, you can write a rule to associate the id of the source device via the Turbine_([0-9]+) expression and the deviceId of the 3D object via the Turbine_SG400_T([0-9]+)_V1 expression.

Note: When a regular expression matches multiple groups, the last one will be used during data association.

Regular expression rules are expressed as JSON and have the following properties:

SourceDeviceKey: the name of the key in the source device JSON, whose value is used to establish a relationship with a 3D object.
SourceDeviceKeyExpression: the .Net regular expression used to extract the value from the key specified in SourceDeviceKey.
CustomPropertiesMappingKey: the name of the key in the 3D object's custom properties JSON, whose value is used to establish a relationship with a source device.
CustomPropertiesMappingKeyExpression: the .Net regular expression used to extract the value from the key specified in CustomPropertiesMappingKey.
CustomPropertiesGeometryKey: the name of the key in the 3D object's custom properties JSON, whose value represents the ID of the game object that receives the source device telemetry.

The following sample data has a regular expression rule (Turbine_([0-9]+)) that associates a wind turbine (source device) that has an id of Turbine_123 with a game (3D) object in the application that has a SerialNumber of Turbine_SG400T123_V1 based on the common text 123. When you run the regular expression, it returns two groups (Turbine_123 and 123) and the last group (123) is used. This allows the correct 3D object in the application to display telemetry for the correct source device.

Example of a regular expression rule associating a wind turbine with a GameObject in the application

Regular expression rule JSON operating against top-level keys:

{
   "SourceDeviceKey": "id",
   "SourceDeviceKeyExpression": "Turbine_([0-9]+)",
   "CustomPropertiesMappingKey": "SerialNumber",
   "CustomPropertiesMappingKeyExpression": "Turbine_SG400_T([0-9]+)_V1",
   "CustomPropertiesGeometryKey": "GeometryValue"
}

The following is a complete example of a regular expression rule operating against top-level keys:

{
  "name": "Wind Turbine Regular Expression Rule",
  "expression": "{'SourceDeviceKey':'id','SourceDeviceKeyExpression':'Turbine_([0-9]+)','CustomPropertiesMappingKey':'SerialNumber','CustomPropertiesMappingKeyExpression':'Turbine_SG400_([0-9]+)_V1','CustomPropertiesGeometryKey':'GeometryValue'}",
  "ruleInterpreterName": "RegularExpression",
  "isAutomated": true,
  "isDisabled": false
}

You can also write regular expression rules that operate against nested keys.

Example of regular expression rules operating against nested keys

Regular expression rule JSON operating against nested keys:

{
   "SourceDeviceKey": "Properties.DeviceId",
   "SourceDeviceKeyExpression": "Turbine_([0-9]+)",
   "CustomPropertiesMappingKey": "Properties.SerialNumber",
   "CustomPropertiesMappingKeyExpression": "Turbine_SG400_T([0-9]+)_V1",
   "CustomPropertiesGeometryKey": "Properties.Code"
}

The following is a complete example of a regular expression rule operating against nested keys:

{
  "name": "Wind Turbine Regular Expression Rule (Nested Keys)",
  "expression": "{'SourceDeviceKey':'Properties.DeviceId','SourceDeviceKeyExpression':'Turbine_([0-9]+)','CustomPropertiesMappingKey':'Properties.SerialNumber','CustomPropertiesMappingKeyExpression':'Turbine_SG400_([0-9]+)_V1','CustomPropertiesGeometryKey':'Properties.Code'}",
  "ruleInterpreterName": "RegularExpression",
  "isAutomated": true,
  "isDisabled": false
}

Rule Creation

When you create rules, you must provide the following properties:

name: a user-defined name for the rule.
expression: the JSON that contains the rule.

Note: Keys and values within the rule JSON must be enclosed with single quotes, not double quotes.
ruleInterpreterName: the name of the rule interpreter to execute this rule.
isAutomated: indicates whether or not the rule runs automatically.
isDisabled: indicates whether or not the rule is disabled. Disabled rules can't be executed.

{
   "name": "string",
   "expression": "string",
   "ruleInterpreterName": "string",
   "isAutomated": true,
   "isDisabled": false
}

You can use disassociate operations to remove the relationship between a source device and a 3D object. You can remove all associations for a workspace and facility or only for devices that match a specific rule.

Endpoints

Refer to the Live Systems Data REST API documentation for information about the REST API endpoints available for data association.