Understand the interface-asset model relationship - Amazon IoT SiteWise
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Understand the interface-asset model relationship

Interfaces and asset models work together in a complementary relationship:

Interfaces vs. Asset Models
Aspect Interfaces Asset Models
Purpose Define standards and applies consistency Represent physical or logical assets
Asset Creation Cannot create assets directly Used to create assets
Properties Define standard properties that must be implemented in models Can have interface-applied and unique properties
Metrics Define standard calculations Implement interface metrics and can have additional metrics
Hierarchies Define data computation hierarchical relationships for rollup metrics Define physical hierarchical relationships for asset associations

When you apply an interface to an asset model:

  • The asset model must map all properties defined in the interface.

  • Property mappings define how interface properties correspond to asset model properties.

  • Mapped asset model properties must remain synchronized with their corresponding interface properties and cannot be modified in a way that would cause inconsistency between the two.

  • Unmapped interface properties are automatically created in the asset model.

  • The asset model can have additional properties beyond those defined in the interface.

  • The asset model implements interface metrics. Changes to interface metrics propagate to all asset models using the interface.

  • Interface hierarchies are used for computing rollup metrics. Asset model hierarchies can be defined independently, and the service will automatically map them when computing rollup metrics.

This relationship ensures standardization while allowing for the flexibility needed to represent diverse equipment types.

Standardize existing asset models

While interfaces are valuable when designing new asset models from scratch, they're equally powerful for standardizing existing asset models that may have evolved independently over time.

When working with existing asset models, you can apply interfaces to standardize metrics and properties:

  1. Identify common metrics and properties across your existing asset models

  2. Create an interface that defines these standard properties and metrics

  3. Apply the interface to your existing asset models using property mapping

  4. Use rollup metrics to aggregate data across your asset hierarchy

For example, if you have existing CNC machine asset models with different property names but similar data, like temp_celsius, temperature_c, machine_temp), you can:

  1. Create a CNC-INTERFACE with a standardized Temperature-in-C property

  2. Apply this interface to each CNC asset model, mapping the existing temperature properties to the interface's Temperature-in-C property

  3. Define rollup metrics in the interface that calculate statistics across all machines (e.g., average temperature)

This approach allows you to maintain your existing asset models while gaining the benefits of standardization and simplified metrics calculation.

Hierarchy relationships

Interface hierarchy

Defines relationships for calculating and aggregating data across different interfaces. For example, in a factory setting, an interface hierarchy could connect temperature-monitoring interfaces at different levels to calculate average temperatures. For example: machine, production line, and facility. When you define a rollup metric like AverageTemperature, the interface hierarchy determines how that metric aggregates data from lower levels to higher levels.

Asset model hierarchy

Represents the actual physical or logical structure of your assets. For instance, a CNC machine asset model might be part of a production line asset model, which in turn belongs to a factory asset model. This hierarchy reflects real-world relationships and helps organize assets in a way that matches their physical arrangement or business structure. When combined with interface hierarchies, asset model hierarchies help the system understand which assets should be included in rollup calculations.

These two hierarchy types work together: interface hierarchies define how to compute aggregated metrics, while asset model hierarchies define which specific assets should be included in those calculations.

Interface metrics and rollup calculations

Interfaces excel at defining standardized metrics that can be applied across different asset models. This is particularly valuable for rollup metrics that aggregate data from multiple assets.

When you define metrics in an interface, they're automatically applied to all asset models that implement the interface. The metrics can reference properties defined in the interface, use aggregation functions to calculate statistics across assets, and ensure consistent calculations across all implementing asset models For example, you can define an availability metric in an interface that calculates the ratio of running time to total time:

{ "name": "Availability", "dataType": "DOUBLE", "type": { "metric": { "expression": "Running-time / (Running-time + Down-time) * 100", "variables": [ { "name": "Running-time", "value": { "propertyId": "${Running-time}" } }, { "name": "Down-time", "value": { "propertyId": "${Down-time}" } } ], "window": { "tumbling": { "interval": "1h" } } } }, "unit": "Percent" }

When this interface is applied to multiple asset models, the availability metric is calculated consistently for all of them, even if the underlying property names differ (thanks to property mapping).

For more information about defining metrics and using aggregation functions, see Aggregate data from properties and other assets (metrics).

Rollup metrics with interfaces

Interfaces can also define rollup metrics that aggregate data across assets in a hierarchy. When you define a hierarchy in an interface and apply it to an asset model, you can create metrics that aggregate data from child assets.

For example, you can define a metric that calculates the average temperature across all CNC machines in a factory:

{ "name": "AverageTemperature", "dataType": "DOUBLE", "type": { "metric": { "expression": "avg(Temperature-in-C)", "variables": [ { "name": "Temperature-in-C", "value": { "propertyId": "${Temperature-in-C}", "hierarchyId": "${CNC-machines}" } } ], "window": { "tumbling": { "interval": "1h" } } } }, "unit": "Celsius" }

This metric uses the avg() aggregation function to calculate the average temperature across all CNC machines in the hierarchy. The hierarchyId parameter specifies which hierarchy to use for the aggregation.

When this interface is applied to an asset model, the rollup metric automatically aggregates data from all child assets that match the hierarchy mapping.