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

This article describes how to connect your data into TwinMaker model. The data including static data or time series data or video data. TwinMaker has the capability to connect the data inside of AWS and the data inside of your own systems.

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.

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 intends to integrate our machine's sensor data into TwinMaker models. The sensor data is currently stored in our own system. Additionally, we would like to connect the time series data from our other equipment, which is stored in Amazon, to the relevant TwinMaker models."

Let's assume that you have already created the Equipment entity named "Equipment1" and its child machine element entity named "Element1." If you haven't created these entities yet, please refer to the guide How to create my factory and equipment in TwinMaker? for instructions on creating them.

To visualize your data in the 3D scene or in your dashboard, you will need to create Components under your entity. Components provide context and data for entities within a scene. They can include static data, such as a list of documents or the coordinates of a geographic location. Additionally, they can incorporate functions that connect to other systems, including systems that contain time series data like AWS IoT SiteWise and other time-series cloud historians.

Howto_Component_General

Here we will use an easy example of TwinMaker provided Component to show you the Component management process. Other components will be introduced in the following sessions.

AWS Console

In this section, we will create an Entity Component to store static data using the AWS Console.

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, we will use the "Equipment1" 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_Step1

Step 3: On the "Component information" page, enter "Equipment_Information" in the name field. From the "Type" drop-down list, select "com.amazon.iottwinmaker.parameters." This is one of the first-party component types provided by TwinMaker.

Create_Components_Step2

Step 4: Within this component, we will create two properties. Click on the "Add" button and then the "Add another Property" button to add two properties inside the component:

  • Property 1: Select the "String" type and label it as "Brand."
  • Property 2: Select the "Integer" type and label it as "Production Date." By adding these properties, you can capture and store relevant information about the equipment's brand and production date within the component.

Create_Components_Step3

Step 5. Click "Add component" button to save the component. The component will be save to the entity.

Create_Components_Result1

The Json content for the component will also shows on the page like:

{
   "Brand": {
      "definition": {
         "dataType": {
            "type": "STRING"
         },
         "isTimeSeries": false,
         "isRequiredInEntity": false,
         "isExternalId": false,
         "isStoredExternally": false,
         "isImported": false,
         "isFinal": false,
         "isInherited": false,
         "displayName": "Brand"
      },
      "value": {
         "stringValue": "MockBrand"
      }
   },
   "ProductionDate": {
      "definition": {
         "dataType": {
            "type": "INTEGER"
         },
         "isTimeSeries": false,
         "isRequiredInEntity": false,
         "isExternalId": false,
         "isStoredExternally": false,
         "isImported": false,
         "isFinal": false,
         "isInherited": false,
         "displayName": "ProductionDate"
      },
      "value": {
         "integerValue": 2023
      }
   }
}

The "com.amazon.iottwinmaker.parameters" also support listed values:

  • Double
  • Long
  • Boolean
  • List
  • Map
  • Relationship

Relationship type allow you to store the relationship with another Entity/Component for query purpose.

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 '{
   "ParameterTest": {
      "updateType": "CREATE",
      "description": "",
      "componentTypeId": "com.amazon.iottwinmaker.parameters",
      "propertyUpdates": {
         "Brand": {
            "definition": {
               "dataType": {
                  "type": "STRING"
               }
            },
            "value": {
               "stringValue": "MockBrand"
            }
         },
         "ProductionDate": {
            "definition": {
               "dataType": {
                  "type": "INTEGER"
               }
            },
            "value": {
               "integerValue": 2023
            }
         }
      }
   }
}'

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 '{
   "ParameterTest": {
      "updateType": "DELETE"
   }
}'