# Asset model interfaces AWS IoT SiteWise interfaces set standards across different asset models. They define a common structure that ensures consistency while allowing for variations in implementation. Interfaces share the same structure as asset models (properties, composite models, and hierarchies) but you cannot create assets directly from them. Instead, interfaces are applied to existing asset models to ensure standardization. Component models are not supported for interfaces. Using interfaces provides several benefits: + Standardized properties and metrics across different asset model variations + Simplified metric definitions at the interface level + More efficient management of complex asset hierarchies + Independent property lifecycle management for each asset model variation + Enhanced cross-team collaboration where operations teams focus on physical asset representation while data teams establish standards across equipment We recommend creating your asset models first to model your real-world industrial equipment. Every equipment type, with their own set of properties, can be represented by their own asset models. ## Asset model standardization use case Interfaces help standardize properties across different asset models while preserving their unique characteristics. For example, there are four stations in a powertrain shop: engine, transmission, differential, and assembly. Each station contains various equipment types. For example, the engine station includes CNC machines, but they differ in specifications: some are 3-axis, while others are 5-axis. ![\[Diagram showing the hierarchy of the powertrain shop's equipment using only asset models and assets. The powertrain shop is at the top, then each of the asset models for the engine, transmission, differential and assemble stations on the second level down. On the third level down, there's the individual CNC machines broken down by axis stemming from the engine station asset model. Conversely, there's asset models stemming from the assemble station model as well. On the fourth level, are each of the assets representing the individual CNC machines or robotic arms by name.\]](http://docs.aws.amazon.com/iot-sitewise/latest/userguide/images/models-interface-hierarchy.png) However, interfaces let you create standards for commonalities seen in the CNC machines. You can use the repeatable properties in an interface rather than create asset models for each property. For example, you can: 1. Create separate asset models for each category of machine types. In this example, that's the "CNC 3 Axis machines" and the "CNC 5 Axis machines." 1. Define a standard interface with common properties and metrics. In this example, `Temperature-in-C`, `Down-time`, and `Running-time` are all common properties that apply to both CNC machines. 1. Apply this interface to all CNC machine asset models, still allowing for device-specific properties on the individual asset models. ![\[Diagram showing how interfaces simplify the organization of asset models from previous diagram. It shows several repeatable parameters for the engine station CNC machines now governed by the interfaces carrying over to various properties to the 3-axis and 5-axis CNC machine asset models, while also allowing for device-specific properties on each.\]](http://docs.aws.amazon.com/iot-sitewise/latest/userguide/images/models-interface-to-asset-models.png) You can also define availability metrics at the interface level. For example, `Avail = avg(Down-time, Running-time)` calculates the availability based on the down time and running time values. Using interfaces simplifies your asset model management by ensuring consistent property definitions and metrics across applicable equipment while maintaining the unique characteristics of each machine type. ## Structure and components Interfaces include the same property types as asset models: attributes, measurements, transforms, and metrics. When overlayed on an asset model, you map existing properties to their interface counterparts. Unmapped interface properties are automatically created in the asset model. Interface hierarchies define rollup metrics, while asset model hierarchies enable asset associations. When you use an interface, the service will automatically map asset model hierarchies to interface hierarchies when computing rollup metrics. After applying an interface, rollup metrics are defined through the interface hierarchy rather than the asset model's own hierarchy. ## Considerations When working with interfaces, keep these considerations in mind: + Asset model and interface properties can be automatically mapped by name or manually mapped. Hierarchies are automatically mapped by the service when computing rollup metrics. + You cannot define additional metrics in the linked asset model that use interface metrics as inputs. + An asset model can only be linked to one interface. However, you can have multiple asset models applied to the same interface. + Alarms are not supported in interfaces. + Component models are not supported for interfaces. **Topics** + [Asset model standardization use case](#interface-powertrain-shop-example) + [Structure and components](#interface-structure) + [Considerations](#interface-considerations) + [Understand the interface-asset model relationship](interface-asset-model-relationship.md) + [Create an interface](interface-create.md) + [Apply an interface to an asset model](interfaces-link-asset-model.md) + [Manage interfaces, linked asset models, and properties](interfaces-manage.md) + [Additional interface examples](interface-additional-examples.md) # 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 1. Create an interface that defines these standard properties and metrics 1. Apply the interface to your existing asset models using property mapping 1. 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 1. Apply this interface to each CNC asset model, mapping the existing temperature properties to the interface's `Temperature-in-C` property 1. 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)](metrics.md). ### 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. # Create an interface You can create interfaces using either the AWS IoT SiteWise console or the AWS CLI. ------ #### [ Console ] 1. Navigate to the [AWS IoT SiteWise console](https://console.aws.amazon.com/iotsitewise/) and choose **Models** from the navigation pane. 1. Choose **Create interface**. 1. Enter a unique **Name** and optional **Description** for your interface. You can also optionally add an **External ID** of you choosing. 1. Add properties to your interface. You can add attributes, measurements, transforms, and metrics just like with asset models. For more information, see [Create an asset model (console)](create-asset-models.md#create-asset-model-console). 1. Choose **Create interface** to create the interface. 1. If you have hierarchies to define parent-child relationships between interfaces, choose **Add hierarchy** and enter relevant details. ------ #### [ AWS CLI ] To create an interface, use the `CreateAssetModel` operation with the `assetModelType` parameter set to `INTERFACE`: ``` aws iotsitewise create-asset-model \ --asset-model-name "CNC-INTERFACE" \ --asset-model-description "Standard interface for CNC machines" \ --asset-model-type "INTERFACE" \ --asset-model-properties '[ { "name": "Temperature-in-C", "dataType": "DOUBLE", "type": { "measurement": {} }, "unit": "Celsius" }, { "name": "Down-time", "dataType": "DOUBLE", "type": { "measurement": {} }, "unit": "Minutes" }, { "name": "Running-time", "dataType": "DOUBLE", "type": { "measurement": {} }, "unit": "Minutes" }, { "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" } ]' ``` ------ # Apply an interface to an asset model When applying an interface to an asset model, you map asset model properties and hierarchies to their interface counterparts. For unmapped interface properties, corresponding properties are automatically created in the asset model. After linking, the service prevents changes to the asset model that would violate interface standards. You can add one asset model to an interface at a time. However, multiple asset models can be linked to a single interface. ------ #### [ Console ] 1. Navigate to the [AWS IoT SiteWise console](https://console.aws.amazon.com/iotsitewise/) and choose **Models** from the navigation pane. 1. Select the asset model to which you want to apply an interface. 1. Choose **Link asset model** in the **Link asset models** section. This brings up the **Link interface** page. 1. In the **Asset models and interfaces** section, select an asset model from the **Select a model to link** dropdown menu. 1. In the **Property mappings** section, map each interface property to an existing asset model property or create a new property. AWS IoT SiteWise automatically links properties with matching names in the asset model and interface. 1. Review the property mappings and choose **Link interface**. ------ #### [ AWS CLI ] To apply an interface to an asset model, use the `PutAssetModelInterfaceRelationship` operation: ``` aws iotsitewise put-asset-model-interface-relationship \ --asset-model-id "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE" \ --interface-asset-model-id "a1b2c3d4-5678-90ab-cdef-22222EXAMPLE" \ --property-mapping-configuration '{ "createMissingProperty": true, "matchByPropertyName": true, "overrides": [ { "assetModelPropertyId": "a1b2c3d4-5678-90ab-cdef-44444EXAMPLE", "interfaceAssetModelPropertyId": "a1b2c3d4-5678-90ab-cdef-33333EXAMPLE" } ] }' ``` To retrieve information about an interface relationship, use the `DescribeAssetModelInterfaceRelationship` operation: ``` aws iotsitewise describe-asset-model-interface-relationship \ --asset-model-id "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE" \ --interface-asset-model-id "a1b2c3d4-5678-90ab-cdef-22222EXAMPLE" ``` To list all asset models that have a specific interface applied to them, use the `ListInterfaceRelationships` operation: ``` aws iotsitewise list-interface-relationships \ --interface-asset-model-id "a1b2c3d4-5678-90ab-cdef-22222EXAMPLE" \ --max-results 10 ``` To delete an interface relationship, use the `DeleteAssetModelInterfaceRelationship` operation: ``` aws iotsitewise delete-asset-model-interface-relationship \ --asset-model-id "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE" \ --interface-asset-model-id "a1b2c3d4-5678-90ab-cdef-22222EXAMPLE" ``` ------ # Manage interfaces, linked asset models, and properties After creating interfaces and linking them to asset models, you can manage relationships, edit, and delete interfaces through the console or AWS CLI. ## Modify an interface and asset model relationship To change an interface's relationship to an asset model, do the following in either the AWS IoT SiteWise console or through AWS CLI: ------ #### [ Console ] 1. Navigate to the [AWS IoT SiteWise console](https://console.aws.amazon.com/iotsitewise/) and choose **Models** from the navigation pane. 1. Select the interface you want modify. 1. Choose the asset model to modify and edit it. You can follow the [Apply an interface to an asset model](interfaces-link-asset-model.md) instructions to link a different asset model. 1. Choose **Apply interface** to save your changes. ------ #### [ AWS CLI ] To edit an interface and asset model relationship, use the `PutAssetModelInterfaceRelationship` action. Replace *your-asset-model-id* and *your-interface-asset-model-id* with your own values. For more information, see [PutAssetModelInterfaceRelationship](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_PutAssetModelInterfaceRelationship.html) in the *AWS IoT SiteWise API Reference*. ``` aws iotsitewise put-asset-model-interface-relationship \ --asset-model-id your-asset-model-id \ --interface-asset-model-id your-interface-asset-model-id ``` ------ ## Modify an interface property mapping To change an interface's property, do the following in either the AWS IoT SiteWise console or through AWS CLI: ------ #### [ Console ] 1. Navigate to the [AWS IoT SiteWise console](https://console.aws.amazon.com/iotsitewise/) and choose **Models** from the navigation pane. 1. Select the interface for which you want modify property mappings. The **Edit property mappings** page appears. 1. In the **Property mappings** section, filter the list to find the appropriate property mappings. 1. Change the properties using the **Model property** column. ------ #### [ AWS CLI ] To edit an interface and asset model relationship, use the `PutAssetModelInterfaceRelationship` action. Replace *your-asset-model-id* and *your-interface-asset-model-id* with your own values. For more information, see [PutAssetModelInterfaceRelationship](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_PutAssetModelInterfaceRelationship.html) in the *AWS IoT SiteWise API Reference*. ``` aws iotsitewise put-asset-model-interface-relationship \ --asset-model-id your-asset-model-id \ --interface-asset-model-id your-interface-asset-model-id \ ``` ------ ## List interfaces linked to an asset model To get a list of interfaces applied to an asset model, do the following in either the AWS IoT SiteWise console or through AWS CLI: ------ #### [ Console ] 1. Navigate to the [AWS IoT SiteWise console](https://console.aws.amazon.com/iotsitewise/) and choose **Models** from the navigation pane. 1. In the **Models** section, choose the appropriate asset model or interface. You can view a list of either applied interfaces or linked asset models on the model's corresponding details page. + When viewing a particular interface, see the **Linked asset models** section. + When viewing a particular asset model, see the **Applied interfaces** section. ------ #### [ AWS CLI ] To list interfaces, you can use the `ListInterfaceRelationships` operation. Replace *your-interface-asset-model-id* with your own value. For more information, see [ListInterfaceRelationships](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_ListInterfaceRelationships.html) in the *AWS IoT SiteWise API Reference*. ``` aws iotsitewise list-interface-relationships \ --interface-asset-model-id your-interface-asset-model-id \ [--next-token your-next-token] \ [--max-results 20] ``` ------ ## View the details of an interface and asset model relationship To see the details of an interface applied to an asset model, do the following in either the AWS IoT SiteWise console or through AWS CLI: ------ #### [ Console ] View the details of applied interfaces and linked asset models. 1. Navigate to the [AWS IoT SiteWise console](https://console.aws.amazon.com/iotsitewise/) and choose **Models** from the navigation pane. 1. In the **Models** section, search for the appropriate asset model or interface. Select the model or interface's **Name** to open up a page containing more details. ------ #### [ AWS CLI ] To view interface details for an interface and asset model relationship, use the `DescribeAssetModelInterfaceRelationship` action. Replace *your-asset-model-id* and *your-interface-asset-model-id* with your own values. For more information, see [DescribeAssetModelInterfaceRelationship](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeAssetModelInterfaceRelationship.html) in the *AWS IoT SiteWise API Reference*. ``` aws iotsitewise describe-asset-model-interface-relationship \ --asset-model-id your-asset-model-id \ --interface-asset-model-id your-interface-asset-model-id ``` ------ ## Remove an interface applied to an asset model To remove an interface applied to an asset model, do the following in either the AWS IoT SiteWise console or through AWS CLI: ------ #### [ Console ] We recommend removing an interface through the asset model. You can also delete an interface or unlink an interface through a particular interface's page. 1. Navigate to the [AWS IoT SiteWise console](https://console.aws.amazon.com/iotsitewise/) and choose **Models** from the navigation pane. 1. Select the appropriate asset model from which to remove the interface relationship. 1. Choose **Unlink asset model**. ------ #### [ AWS CLI ] To remove an interface relationship from an asset model, you can use the `DeleteAssetModelInterfaceRelationship` action. Replace *your-interface-asset-model-id* with your own value. For more information, see [DeleteAssetModelInterfaceRelationship](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DeleteAssetModelInterfaceRelationship.html) in the *AWS IoT SiteWise API Reference*. ``` aws iotsitewise delete-asset-model-interface-relationship \ --asset-model-id your-asset-model-id \ --interface-asset-model-id your-interface-asset-model-id ``` ------ # Additional interface examples Here are additional examples of how interfaces can be used in different industrial scenarios: ## Energy generation equipment A power generation company can use interfaces to standardize metrics across different types of generation equipment: ``` { "assetModelName": "GENERATOR-INTERFACE", "assetModelDescription": "Standard interface for power generators", "assetModelType": "INTERFACE", "assetModelProperties": [ { "name": "ActivePower", "dataType": "DOUBLE", "type": { "measurement": {} }, "unit": "MW" }, { "name": "ReactivePower", "dataType": "DOUBLE", "type": { "measurement": {} }, "unit": "MVAR" }, { "name": "Frequency", "dataType": "DOUBLE", "type": { "measurement": {} }, "unit": "Hz" }, { "name": "PowerFactor", "dataType": "DOUBLE", "type": { "metric": { "expression": "cos(atan(ReactivePower / ActivePower))", "variables": [ { "name": "ActivePower", "value": { "propertyId": "${ActivePower}" } }, { "name": "ReactivePower", "value": { "propertyId": "${ReactivePower}" } } ], "window": { "tumbling": { "interval": "5m" } } } }, "unit": "None" } ] } ``` This interface can be applied to various generator asset models (gas turbines, steam turbines, wind turbines) to ensure consistent power metrics across the fleet. ## Water treatment facilities A water utility can use interfaces to standardize monitoring across treatment plants: ``` { "assetModelName": "WATER-QUALITY-INTERFACE", "assetModelDescription": "Standard interface for water quality monitoring", "assetModelType": "INTERFACE", "assetModelProperties": [ { "name": "pH", "dataType": "DOUBLE", "type": { "measurement": {} }, "unit": "pH" }, { "name": "Turbidity", "dataType": "DOUBLE", "type": { "measurement": {} }, "unit": "NTU" }, { "name": "DissolvedOxygen", "dataType": "DOUBLE", "type": { "measurement": {} }, "unit": "mg/L" }, { "name": "QualityIndex", "dataType": "DOUBLE", "type": { "metric": { "expression": "(pH >= 6.5 && pH <= 8.5 ? 100 : 50) * (Turbidity < 1 ? 1 : 0.8) * (DissolvedOxygen > 5 ? 1 : 0.7)", "variables": [ { "name": "pH", "value": { "propertyId": "${pH}" } }, { "name": "Turbidity", "value": { "propertyId": "${Turbidity}" } }, { "name": "DissolvedOxygen", "value": { "propertyId": "${DissolvedOxygen}" } } ], "window": { "tumbling": { "interval": "1h" } } } }, "unit": "Score" } ] } ``` This interface ensures that water quality is measured consistently across all treatment facilities, regardless of their specific equipment configurations. ## Hierarchical interfaces Interfaces can be organized hierarchically to support aggregate metrics at different levels of your operation: 1. **Equipment-level interface** (for example, `PUMP-INTERFACE`) + Properties: Flow rate, pressure, power consumption, vibration + Metrics: Efficiency, health score 1. **Process-level interface** (for example, `PUMPING-STATION-INTERFACE`) + Properties: Total flow, average pressure, total power + Metrics: Station efficiency, operational cost per volume + Hierarchy: Contains `PUMP-INTERFACE` equipment 1. **Facility-level interface** (for example, `WATER-FACILITY-INTERFACE`) + Properties: Facility throughput, energy usage, chemical usage + Metrics: Facility efficiency, cost per unit volume, carbon footprint + Hierarchy: Contains `PUMPING-STATION-INTERFACE` processes This hierarchical approach allows metrics to be calculated at each level while maintaining consistency across your entire operation.