Mapping industrial data streams to asset properties - Amazon IoT SiteWise
Setting a property alias (console)Setting a property alias (CLI)
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).

Mapping industrial data streams to asset properties

You can define a property alias on any type of asset property so that you can easily identify an asset property when you ingest or retrieve asset data. If your asset has measurement properties, you can define the property aliases to map your data streams to those measurement properties.

This process requires that you know your property alias.

  • If you ingest data from OPC-UA servers using an OPC-UA data source in a gateway, your property alias is the path to a variable under the Objects node, starting with /. For example, if the path to your variable is company/windfarm/3/turbine/7/temperature, then your property alias is /company/windfarm/3/turbine/7/temperature. For more information about OPC-UA information architecture, see Information Model and Address Spacing mapping in the OPC UA Online Reference.

    Notes

    • If you configure a data stream prefix for your OPC-UA source, you must include that prefix in the property alias for all data streams from that source. For example, if you use /RentonWA as a prefix, then the previous alias is /RentonWA/company/windfarm/3/turbine/7/temperature.

    • Property aliases can contain up to 1,000 bytes. OPC-UA variables paths can contain up to 4,096 bytes. Currently, Amazon IoT SiteWise doesn't support ingesting data from OPC-UA variables with long paths.

  • If you ingest data from Modbus servers using a Modbus TCP data source in a gateway, your property alias is Modbus register set tag name. You can use this value to send data from this register set to an asset property.

  • If you ingest data from other sources, such as using Amazon IoT rules or the API, you define your property aliases. You can define a property alias naming system that is applicable to your device configuration. For example, if you ingest data from Amazon IoT things, you can include the thing name in property aliases to uniquely identify data streams. For more information about this example, see the Ingesting data from Amazon IoT things tutorial.

Property aliases must be unique within a Region and Amazon account. Amazon IoT SiteWise returns an error if you set a property alias to one that already exists on another asset property.

If you have multiple OPC-UA sources with identical data stream paths, you can add a prefix to each source's paths to form unique aliases. For more information, see Configuring data sources.

Setting a property alias (console)

You can use the Amazon IoT SiteWise console to set an alias for an asset property.

To set a property alias (console)

  1. Navigate to the Amazon IoT SiteWise console.

  2. In the navigation pane, choose Assets.

  3. Choose the asset for which you want to set a property alias.

    Tip

    You can choose the arrow icon to expand an asset hierarchy to find your asset.

    Amazon IoT SiteWise "Assets" page screenshot with an asset hierarchy highlighted.

  4. Choose Edit.

  5. Find the property for which you want to set an alias, and then enter the property alias.

    Amazon IoT SiteWise "Edit asset" page screenshot with a property alias highlighted.

  6. Choose Save.

Setting a property alias (CLI)

You can use the Amazon Command Line Interface (Amazon CLI) to set an alias for an asset property.

You must know your asset's assetId and property's propertyId to complete this procedure. If you created an asset but don't know its assetId, use the ListAssets operation to view all of your assets for a specific model. Then, use the DescribeAsset operation to view your asset's properties including property IDs.

To map a data stream to your asset's property, use the UpdateAssetProperty operation. Specify the following parameters:

  • assetId – The asset's ID.

  • propertyId – The asset property's ID.

  • propertyAlias – The data stream's path to alias to the property.

  • propertyNotificationState – The property value notification state: ENABLED or DISABLED. Specify the property's existing notification state when you update the property alias. You can retrieve the existing notification state with the DescribeAssetProperty operation.

    If you omit this parameter, the new notification state is DISABLED. For more information about property notifications, see Interacting with other Amazon services.

To set a property alias (CLI)

  1. Run the following command to retrieve the property's current notification state. Replace asset-id and property-id with the asset property's IDs.

    aws iotsitewise describe-asset-property \
  --asset-id asset-id \
  --property-id property-id

    The operation returns a response that contains the asset property's details in the following format. The property notification state is in assetProperty.notification.state in the JSON object.

    {
  "assetId": "a1b2c3d4-5678-90ab-cdef-22222EXAMPLE",
  "assetName": "Wind Turbine 7",
  "assetModelId": "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE",
  "assetProperty": {
    "id": "a1b2c3d4-5678-90ab-cdef-33333EXAMPLE",
    "name": "Wind Speed",
    "notification": {
      "topic": "$aws/sitewise/asset-models/a1b2c3d4-5678-90ab-cdef-11111EXAMPLE/assets/a1b2c3d4-5678-90ab-cdef-22222EXAMPLE/properties/a1b2c3d4-5678-90ab-cdef-33333EXAMPLE",
      "state": "DISABLED | ENABLED"
    },
    "dataType": "DOUBLE",
    "unit": "m/s",
    "type": {
      "measurement": {}
    }
  }
}

  2. Run the following command to set the asset property's alias. Replace property-alias with the property alias and notification-state with the notification state, or omit --property-notification-state to disable notifications. You can optionally update the asset's unit with a new unit and --property-unit.

    aws iotsitewise update-asset-property \
  --asset-id asset-id \
  --property-id property-id \
  --property-alias property-alias \
  --property-notification-state notification-state \
  --property-unit unit