How to customize connector for my equipment?

Prerequisites

before you can complete this tutorial make sure you have the following prerequisite:

1. You already have created component type that describes the properties for your equipment. We will use component "com.example.cookiefactory.watertank" as an example in Cookie Factory v2 project.

Data connector definition

In the component type definition, there is a section to define functions for data reader. You will define the Lambda function for your component as dataReader function. This will be the Lambda function getting executed when the user access properties defined in this component by using GetPropertyValue or GetPropertyValueHistory APIs.

"functions": {
    "dataReader": {
      "implementedBy": {
        "lambda": {
          "arn": "arn:aws:lambda:us-east-1:848667580024:function:iottwinmaker-tsUDQ-CookieFactoryDemo"
        },
        "isNative": false
      },
      "isInherited": false
    }
  }

Customize data connector Lambda function for your data source

For the WaterTank component, the data source is Amazon TimeStream. If you have TimeSeries data from Amazon TimeStream, you can reuse our example data connector Lambda function and customize to your TimeStream data.

1. In entity_query() function, you need to modify query_string so it gets the right data from your TimeStream data source.
2. In component_type_query(), you need to modify query_string so it handles component type query. For example, you can use component type query in Grafana dashboard so you don't have to configure query for each entity.

As show below, here is the JSON schema for the example WaterTank component:

{
  "componentTypeId": "com.example.cookiefactory.watertank",
  "propertyDefinitions": {
    "flowRate1": {
      "dataType": {
        "type": "DOUBLE"
      },
      "isTimeSeries": true,
      "isRequiredInEntity": false,
      "isExternalId": false,
      "isStoredExternally": true
    },
    "flowrate2": {
      "dataType": {
        "type": "DOUBLE"
      },
      "isTimeSeries": true,
      "isRequiredInEntity": false,
      "isExternalId": false,
      "isStoredExternally": true
    },
    "tankVolume1": {
      "dataType": {
        "type": "DOUBLE"
      },
      "isTimeSeries": true,
      "isRequiredInEntity": false,
      "isExternalId": false,
      "isStoredExternally": true
    },
    "tankVolume2": {
      "dataType": {
        "type": "DOUBLE"
      },
      "isTimeSeries": true,
      "isRequiredInEntity": false,
      "isExternalId": false,
      "isStoredExternally": true
    },
    "telemetryAssetId": {
      "dataType": {
        "type": "STRING"
      },
      "isTimeSeries": false,
      "isRequiredInEntity": true,
      "isExternalId": true,
      "isStoredExternally": false
    }
  }
}

For more examples, see AWS IoT TwinMakercookie factory example time-series connector.

Specific topic: How to change the demo to connect to my data? How to test my connection?

Building on what was covered in the Synthetic Data Lambda section:

To change the data returned by AWS IoT TwinMaker the areas we'll potentially change are:

1. the entity model to add new properties as needed (by adding a new component)
2. the component type definition to point to your Lambda implementation to retrieve data from your datastore (used by the component added to your entity)
3. the Lambda implementation

As a general starting point we'd suggest the following steps:

1. define a GetPropertyValueHistory API request to send via the CLI to be used to test your changes as you make them (see above for the example used or our documentation [1] for details)
2. copy the synthetic_replay_connector [1] Lambda implementation as a new Lambda function
3. copy the CookieLine component type and replace the dataReader [1] Lambda reference to the new Lambda function as well as add any additional properties you'd like to return - at this point, by invoking the GetPropertyValueHistory request through CLI the request may fail but you should be able to verify that the new Lambda function is being called
4. modify the Lambda function as needed to retrieve from your data source instead until the AWS CLI command can successfully return the data you are connecting to.

• Note: if you are also building a consumer application you may also consider simply adjusting the sample json dataset to return synthetic data relevant to your use-case to allow you to develop the consumer application without having to adjust data in your data source during development