How-To Configure the AWS IoT SiteWise Connection
What Does This Article Cover?
Intelligence Hub includes a configurable Connection that allows Intelligence Hub solutions to write data to AWS IoT SiteWise. The AWS IoT SiteWise Connection supports writing Intelligence Hub Models and Instances to AWS IoT SiteWise creating and updating AWS IoT SiteWise models and assets. The process to perform these actions are provided below. These process descriptions assume intermediate level knowledge of building Intelligence Hub component objects include Models, Instance, Flows and Connectors.
- What is AWS IoT SiteWise
- Configuring AWS IoT SiteWise Token Authentication
- Creating AWS SiteWise Assets and Models
- Writing Data to AWS SiteWise Assets and Models
- Design considerations
- Other related material
What is AWS IoT SiteWise?
AWS IoT SiteWise is an Amazon Web Services managed service that enables manufacturers to collect, model, analyze, and visualize data from industrial equipment at scale. AWS IoT SiteWise provides an asset modeling framework that may be used to build representations of industrial devices, processes, and facilities.
Configuring AWS IoT SiteWise Token Authentication:
An AWS Identity and Access Management (IAM) Access and Secret Key may be used to authenticate an Intelligence Hub AWS IoT SiteWise Connection to AWS IoT SiteWise. The following describes the configuration process.
- Use AWS Identity and Access Management to create a new policy with access to AWS IoT SiteWise. The minimum permissions for the policy include the following.
iotsitewise:CreateAsset
iotsitewise:CreateAssetModel
iotsitewise:ListAssets
iotsitewise:ListAssetModels
iotsitewise:ListAssociatedAssets
iotsitewise:ListAssetRelationships
iotsitewise:DescribeAsset
iotsitewise:DescribeAssetModel
iotsitewise:AssociateAssets
iotsitewise:UpdateAssetModel
iotsitewise:BatchPutAssetPropertyValue
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": [
"iotsitewise:CreateAsset",
"iotsitewise:CreateAssetModel",
"iotsitewise:ListAssets",
"iotsitewise:ListAssetModels",
"iotsitewise:ListAssociatedAssets",
"iotsitewise:ListAssetRelationships",
"iotsitewise:DescribeAsset",
"iotsitewise:DescribeAssetModel",
"iotsitewise:AssociateAssets",
"iotsitewise:UpdateAssetModel",
"iotsitewise:BatchPutAssetPropertyValue"
],
"Resource": "*"
}
]- Create a new user with AWS Identity and Access Management and assign the policy to the user.
- Generate the Access and Secret Keys
Creating AWS SiteWise Assets and Models:
Intelligence Hub Models and Instances are used to create AWS IoT SiteWise assets and models. AWS IoT SiteWise assets can be create one-by-one or multiple assets can be created simultaneously.
To create a new asset hierarchy starting at the root of the AWS IoT SiteWise hierarchy create Models and Instances in Intelligence Hub and then output them with the Create button enabled on the Connection Output and with all other Output settings left blank. The Models and Instances, including hierarchy, are built out in SiteWise. The Intelligence Hub Model name becomes the AWS IoT SiteWise model name and the Intelligence Hub Instance name becomes the AWS IoT SiteWise asset name.
The process consists of the following steps.
- Create an Intelligence Hub Model for the lower level of the asset hierarchy including Attributes for the values that will ultimately be sent to SiteWise. The name of this Model will become the name of the AWS IoT SiteWise model.
- Create an Intelligence Hub Instance from this Model. It might be necessary to create a templated Instance if there are multiple assets to be created at this level. The name of each Instance will become the name of the AWS IoT SiteWise asset.
- Create an Intelligence Hub Model for the root level asset and link the Model of the lower level of the hierarchy. The name of this Model will become the name of the AWS IoT SiteWise root asset’s model.
- Create an Intelligence Hub Instance for the root level asset. The name of this Instance will become the name of the AWS IoT SiteWise root asset.
- Create a new Output for the AWS IoT SiteWise Connection. All values for all fields should be empty and the Create radio button should be set to On. Save the Connection Output.
- Press the Save button on the Connection Overview tab to refresh the AWS IoT SiteWise cache in Intelligence Hub.
- Create an Intelligence Hub Flow mapping the Instance for the root asset to the Connection Output.
- Enable the Flow and press the Save button.
- An informational message may be displayed indicating that the models are being built. This message may also be viewed in the Intelligence Hub Log.
- Verify that the models and assets have been created in AWS IoT SiteWise. There may be some latency as the models and assets are being created.
Additional assets may be added to an existing AWS IoT SiteWise asset hierarchy. The process consists of the following steps.
- Find the Intelligence Hub Model for assets on the same level of the hierarchy as the asset to be created. The name of this Model will become the name of the asset’s AWS IoT SiteWise model. Create an Intelligence Hub Instance from this Model. It might be necessary to create a templated Instance if there are multiple new assets to be created at this level. The name of the Instance(s) will become the name(s) of the AWS IoT SiteWise asset(s).
- Create a new Output or edit an existing Output for the AWS IoT SiteWise Connection. The values for Parent Asset and Hierarchy Name must be populated. These values should match the information for the target parent asset in AWS IoT SiteWise. Save the Connection Output.
- Create an Intelligence Hub Flow mapping the Instance for the new asset to the Connection Output.
- Enable the Flow and press the Save button.
- An informational message may be displayed indicating that the model is being built. This message may also be viewed in the Intelligence Hub Log.
- Verify that the models and assets have been created in AWS IoT SiteWise. There may be some latency as the models and assets are being created.
The Intelligence Hub Model name and Instance name are used to name the AWS IoT SiteWise model and asset by default. However, they may be explicitly named. In addition, dynamic references may be used so that they may be named from the payload.
The AWS IoT SiteWise model and asset information is generated from an Intelligence Hub payload. This payload could come from Intelligence Hub Connections Input, for example a MQTT message, or be generated manually. The following is an example.
When the Intelligence Hub AWS IoT SiteWise Connection Output’s Create button is enabled, all changes to SiteWise Models and Assets are additive. The Intelligence Hub AWS SiteWise Connection does not delete, move or rename existing AWS IoT SiteWise measurements, models, assets or hierarchy.
Writing Data to AWS SiteWise Assets and Models:
When an Intelligence Hub AWS IoT SiteWise Connection Output’s Create button is disabled the Connection may be used to write data to an AWS IoT SiteWise Connection measurement. The Parent Name and Hierarchy Name should be left blank when writing to the root asset otherwise the the fields should be populated with the target asset’s parent asset and hierarchy information found in AWS IoT SiteWise.
Design Considerations:
Each time the Save button is pressed on the Intelligence Hub AWS IoT SiteWise Connection Overview tab the Connection caches all Models and Assets in AWS IoT SiteWise. Each time AWS IoT SiteWise Assets or Models are updated a user must press the Save button to cache the state again. Intelligence Hub does not synchronize changes made by multiple Hubs and changes made by any Hub require the cache to be refreshed by all Hubs.
The Intelligence Hub AWS IoT SiteWise Connection uses an Intelligence Hub Instance’s Attributes to create measurements in AWS IoT SiteWise. It does not create AWS IoT SiteWise attributes.