How to connect my data in SiteWise? - johnnyw-aws/aws-iot-twinmaker-samples GitHub Wiki

This article describes how to connect your data into TwinMaker model. In this article we focus on the how to connect the time series data you stored in SiteWise in to Twinmaker.

Prerequisites

To work with AWS IoT TwinMaker in this tutorial, you will need:

  1. An AWS Account and the necessary permissions to use IoT TwinMaker. If you already have an AWS IoT TwinMaker set up, you can proceed to the next section. Otherwise, follow the instructions to set up an account and configure authentication. The instructions will guide you through the necessary steps to ensure successful completion.
  2. A TwinMaker workspace. If you already have an AWS IoT TwinMaker workspace set up, you can proceed to the next section. Otherwise, follow the instructions to create one.
  3. A TwinMaker Entity. If you already have an AWS IoT TwinMaker Entity set up, you can proceed to the next section. Otherwise, follow the instructions to create one.
  4. An AWS SiteWise Asset. If you already have an AWS IoT TwinMaker Entity created, you can proceed to the next section. Otherwise, you can go to your SiteWise console home page, and click the "Create demo" button on the page. It will generate demo SiteWise asset model and asset for you.

Developer tools

This article highlights how to complete different management operations using the AWS IoT TwinMaker Console. You can also craft these same management calls using the other tools like AWS CLI

  • AWS IoT TwinMaker Console: A web-based interface that offers a visual representation of your IoT TwinMaker data, enabling you to manage models and build workflows.
  • AWS Command Line Interface (CLI): Provides a command-line interface to interact with and manage your IoT TwinMaker data using CLI commands.

By leveraging these developer tools and interfaces, you can effectively manage models within your AWS IoT TwinMaker, enabling seamless integration and orchestration of your IoT devices and services.

Goals

"My company utilizes AWS SiteWise to store our time series data, and we aim to integrate this data with TwinMaker for convenient visualization within our 3D scene."

Assuming you have already created the Equipment entity named "Equipment1" and its child machine element entity named "Element1," please refer to the guide How to create my factory and equipment in TwinMaker? if you haven't created them yet.

TwinMaker offers a first-party component designed to seamlessly combine your SiteWise data with TwinMaker, simplifying the integration process.

AWS Console

In this section, we will create an Entity Component in the AWS Console to store time series data.

Step 1: Log into your AWS account Console and select the workspace that you own.

Step 2: Choose one of your Entities. For this example, let's use the "Element1" Entity that we created in the guide How to create my factory and equipment in TwinMaker?. Once you have selected the entity, click on the "Add component" button. Create_Components_SiteWise1

Step 3: On the "Component information" page, enter the following details:

  • Name: "Element_Sensor_Data"
  • Type: Select "com.amazon.iotsitewise.connector" from the drop-down list.

By specifying these values, we are creating a component named "Element_Sensor_Data" with the type "com.amazon.iotsitewise.connector". Create_Components_SiteWise_Create

Once we picked the component type, the page will refresh and shows out the SiteWise component related fields.

  • Asset Model: From the "Asset Model" drop-down list, select "Demo Turbine Asset Model" (generated in the "Prerequisites" Step 4). If you have your own SiteWise asset model, choose the model you want to use. After selecting the asset model, TwinMaker will automatically filter out all assets generated from that model.

  • Asset: In the "Asset" drop-down list, choose the desired asset you want to combine with your TwinMaker entity. In this case, we will select "Demo Turbine Asset 1" (generated in the "Prerequisites" Step 4). If you have your own SiteWise asset, select the asset you want to use.

Create_Components_SiteWise2

Step 4. After the asset been selected, this component will query SiteWise service automatically and pull all the asset's properties. You could review the properties on the page to check whether it is your target asset. Create_Components_SiteWise3

Step 5. Click "Add component" button to save the component. The component will be save to the entity. The component json will look like:

{
  "sitewiseAssetId": {
    "definition": {
      "dataType": {
        "type": "STRING"
      },
      "isTimeSeries": false,
      "isRequiredInEntity": true,
      "isExternalId": true,
      "isStoredExternally": false,
      "isImported": false,
      "isFinal": false,
      "isInherited": false
    },
    "value": {
      "stringValue": "<sitewiseAssetId>"
    }
  },
  "sitewiseAssetModelId": {
    "definition": {
      "dataType": {
        "type": "STRING"
      },
      "isTimeSeries": false,
      "isRequiredInEntity": false,
      "isExternalId": false,
      "isStoredExternally": false,
      "isImported": false,
      "isFinal": true,
      "isInherited": false
    },
    "value": {
      "stringValue": "<sitewiseAssetModelId>"
    }
  }
}

AWS CLI

The lifecycle of a component is tied to the TwinMaker entity it belongs to. Therefore, you can utilize entity-related CLI commands to manage your components. To add a component to an existing entity, you can use the AWS TwinMaker update-entity command.

In the example provided, we are using the CookieFactoryV2 workspace as a reference TwinMaker workspace. If you are using your own workspace please replace it with the ID of your own workspace. Similarly, ensure to replace the entity ID in the command with the ID of the specific entity you want to attach the component to.

aws iottwinmaker update-entity --workspace-id CookieFactoryV2 --entity-id <YourTargetEntityID> --component-updates '{
   "Element_Sensor_Data": {
      "updateType": "CREATE",
      "componentTypeId": "com.amazon.iotsitewise.connector",
      "propertyUpdates": {
         "sitewiseAssetId": {
            "definition": {
               "dataType": {
                  "type": "STRING"
               }
            },
            "value": {
               "stringValue": "<YourSitewiseAssetId>"
            }
         },
         "sitewiseAssetModelId": {
            "definition": {
               "dataType": {
                  "type": "STRING"
               }
            },
            "value": {
               "stringValue": "<YourSitewiseAssetModelId>"
            }
         }
      }
   }
}'

Clean up

If you would like to delete the component from your entity, please follow the steps below:

AWS Console

Step 1: Log into your AWS account Console and select the workspace that you own.

Step 2: In the left navigation tree, locate and select the entity your component belongs to. Then select the target component on the right page.

Step 3: Click "Actions" dropdown list on the top right, select "View component details" button.

Step 4: On the component detail page, click on the "Delete" button located at the top right corner to remove the component from Entity.

AWS CLI

You can use AWS TwinMaker update-entity to delete the component from Entity.  Here we are using CookieFactoryV2 workspace as the example TwinMaker workspace, you could replace it into your own workspace Id.

aws iottwinmaker update-entity --workspace-id CookieFactoryV2 --entity-id <YourTargetEntityID> --component-updates '{
   "Element_Sensor_Data": {
      "updateType": "DELETE"
   }
}'