Custom composite models (components) - AWS IoT SiteWise

Custom composite models (components)

When you're modeling an especially complex industrial asset, such as a complicated piece of machinery that has many parts, it can become a challenge to keep your asset models organized and maintainable.

In such cases, you can add custom composite models, or components if you're using the console, to your existing asset models and component models. These help you stay organized by grouping related properties and re-using subcomponent definitions.

There are two types of custom composite models:

  • Inline custom composite models define a set of grouped properties that apply to the asset model or component model to which the custom composite model belongs. You use them to group related properties. They consists of a name, a description, and a set of asset model properties. They are not reusable.

  • Component-model-based custom composite models reference a component model that you want to include in your asset model or component model. You use them to include standard subassemblies in your model. They consist of a name, a description, and the ID of the component model it references. They have no properties of their own; the referenced component model provides its associated properties to any created assets.

The following sections illustrate how to use custom composite models in your designs.

Inline custom composite models

Inline custom composite models provide a way to organize your asset model by grouping related properties.

For example, suppose you want to model a robot asset. The robot includes a servomotor, a power supply, and a battery. Each of those constituent parts has its own properties that you want to include in the model. You might define an asset model called robot_model that has properties such as the following.

  • robot_model

    • servo_status (integer)

    • servo_position (double)

    • powersupply_status (integer)

    • powersupply_temperature (double)

    • battery_status (integer)

    • battery_charge (double)

However, in some cases, there might be many subassemblies, or the subassemblies themselves might have many properties. In these cases, there might be so many properties that they become cumbersome to reference and maintain in a single flat list at the model root, like in the preceding example.

To deal with such situations, you can use an inline custom composite model to group properties. An inline custom composite model is a custom composite model that defines its own properties. For example, you could model your robot like the following.

  • robot_model

    • servo

      • status (integer)

      • position (double)

    • powersupply

      • status (integer)

      • temperature (double)

    • battery

      • status (integer)

      • charge (double)

In the preceding example, servo, powersupply, and battery are the names of inline custom composite models defined within the robot_model asset model. Each of these composite models then defines properties of its own.

Note

In this case, each custom composite model defines its own properties, so that all the properties are part of the asset model itself (robot_model in this case). These properties aren't shared with any other asset models or component models. For example, if you created some other asset model that also had an inline custom composite model called servo, then making a change to the servo within robot_model wouldn't affect the other asset model's servo definition.

If you want to implement such sharing (for example, to have only one definition for a servo, which all your asset models can share), you would create a component model for it instead, and then create component-model-based composite models that reference it. See the following section for details.

For information about how to create inline custom composite models, see Create custom composite models (components).

Component-model-based custom composite models

You can create a component model in AWS IoT SiteWise to define a standard, reusable sub-assembly. Once you have created a component model, you can add references to it in your other asset models and component models. You do this by adding a component-model-based custom composite model to any model where you want to reference the component. You can add references to your component from many models, or multiple times within the same model.

In this way, you can avoid duplicating the same definitions across models. It also simplifies maintaining your models, because any changes you make to a component model will be reflected across all asset models that use it.

For example, suppose that your industrial installation has many types of equipment that all use the same kind of servo motor. Some of them have many servo motors in a single piece of equipment. You create an asset model for each equipment type, but you don't want to duplicate the definition of servo every time. You want to model it just once and use it in your various asset models. If you later make a change to the definition of servo, it will be updated across all your models and assets.

To model the robot from the previous example in this way, you could define servo motors, power supplies, and batteries as component models, like this.

  • servo_component_model

    • status (integer)

    • position (double)

  • powersupply_component_model

    • status (integer)

    • temperature (double)

  • battery__component_model

    • status (integer)

    • charge (double)

You could then define asset models, such as robot_model, that reference these components. Multiple asset models can reference the same component model. You can also reference the same component model multiple times in one asset model, such as if your robot has multiple servomotors in it.

  • robot_model

    • servo1 (reference: servo_component_model)

    • servo2 (reference: servo_component_model)

    • servo3 (reference: servo_component_model)

    • powersupply (reference: powersupply_component_model)

    • battery (reference: battery_component_model)

For information about how to create component models, see Create component models.

For information about how to reference your component models in other models, see Create custom composite models (components).

Use paths to reference custom composite model properties

When you create a property on an asset model, component model, or custom composite model, you can reference it from other properties that use its value, such as transforms and metrics.

AWS IoT SiteWise provides different ways for you to reference your property. The simplest way is often to use its property ID. However, if the property you want to reference is on a custom composite model, you may find it more useful to reference it by path instead.

A path is an ordered sequence of path segments that specifies a property in terms of its position among the nested composite models within an asset model and composite model.

Obtain property paths

You can get a property's path from the path field of its AssetModelProperty.

For example, suppose you have an asset model robot_model that contains a custom composite model servo, which has a property position. If you call DescribeAssetModelCompositeModel on servo, then the position property would list a path field that looks like this:

"path": [ { "id": "asset model ID", "name": "robot_model" }, { "id": "composite model ID", "name": "servo" }, { "id": "property ID", "name": "position" } ]

Using property paths

You can use a property path when you define a property that references other properties, such as a transform or metric.

A property uses a variable to reference another property. For more information about working with variables, see Use variables in formula expressions.

When you define a variable to reference a property, you can use either the property's ID or its path.

To define a variable that uses the path of the referenced property, specify the propertyPath field of its value.

For example, to define an asset model that has a metric that references a property by using a path, you could pass a payload like this to CreateAssetModel:

{ ... "assetModelProperties": [ { ... "type": { "metric": { ... "variables": [ { "name": "variable name", "value": { "propertyPath": [ path segments ] } } ], ... } }, ... }, ... ], ... }