Adding a prediction definition (console)Training a prediction (console)Starting or stopping inference on a prediction (console)Adding a prediction definition (CLI)Training a prediction and starting inference (CLI)Training a prediction (CLI)Starting or stopping inference on a prediction (CLI)

Detecting equipment anomalies with Amazon Lookout for Equipment

Note

Anomaly detection is only available in the Regions where Amazon Lookout for Equipment is available.

You can integrate Amazon IoT SiteWise with Amazon Lookout for Equipment to gain insights about your industrial equipment through anomaly detection and predictive maintenance of industrial equipment. Lookout for Equipment is a machine learning (ML) service for monitoring industrial equipment that detects abnormal equipment behavior and identifies potential failures. With Lookout for Equipment, you can implement predictive maintenance programs and identify suboptimal equipment processes. For more information about Lookout for Equipment, see What is Amazon Lookout for Equipment? in the Amazon Lookout for Equipment User Guide.

When you create a prediction to train an ML model to detect anomalous equipment behavior, Amazon IoT SiteWise sends asset property values to Lookout for Equipment to train an ML model to detect anomalous equipment behavior. To define a prediction definition on an asset model, you specify the IAM roles needed for Lookout for Equipment to access your data and the properties to send to Lookout for Equipment and send processed data to Amazon S3. For more information, see Creating asset models.

To integrate Amazon IoT SiteWise and Lookout for Equipment, you'll perform the following high-level steps:

Add a prediction definition on an asset model that outlines what properties you want to track. The prediction definition is a reusable collection of measurements, transforms, and metrics that is used to create predictions on the assets that are based on that asset model.
Train the prediction based on historical data that you provide.
Schedule inference, which tells Amazon IoT SiteWise how often to run a specific prediction.

Once inference is scheduled, the Lookout for Equipment model monitors the data it receives from your equipment and looks for anomalies in equipment behavior. You can view and analyze the results in SiteWise Monitor, using the Amazon IoT SiteWise GET API operations, or the Lookout for Equipment console. You can also create alarms using alarm detectors from the asset model to alert you about abnormal equipment behavior.

Topics

Adding a prediction definition (console)
Training a prediction (console)
Starting or stopping inference on a prediction (console)
Adding a prediction definition (CLI)
Training a prediction and starting inference (CLI)
Training a prediction (CLI)
Starting or stopping inference on a prediction (CLI)

Adding a prediction definition (console)

To begin sending data collected by Amazon IoT SiteWise to Lookout for Equipment, you must add an Amazon IoT SiteWise prediction definition to an asset model.

To add a prediction definition to an Amazon IoT SiteWise asset model

Navigate to the Amazon IoT SiteWise console.
In the navigation pane, choose Models and select the asset model to which you want to add the prediction definition.
Choose Predictions.
Choose Add prediction definition.

Define details about the prediction definition.

Enter a unique Name and a Description for your prediction definition. Choose the name thoughtfully because after you create the prediction definition, you can't change its name.

Create or select an IAM permissions role that allows Amazon IoT SiteWise to share your asset data with Amazon Lookout for Equipment. The role should have the following IAM and trust policies. For help creating the role, see Creating a role using custom trust policies (console).

IAM policy


{
    "Version": "2012-10-17",
    "Statement": [{
            "Sid": "L4EPermissions",
            "Effect": "Allow",
            "Action": [
                "lookoutequipment:CreateDataset",
                "lookoutequipment:CreateModel",
                "lookoutequipment:CreateInferenceScheduler",
                "lookoutequipment:DescribeDataset",
                "lookoutequipment:DescribeModel",
                "lookoutequipment:DescribeInferenceScheduler",
                "lookoutequipment:ListInferenceExecutions",
                "lookoutequipment:StartDataIngestionJob",
                "lookoutequipment:StartInferenceScheduler",
                "lookoutequipment:UpdateInferenceScheduler",
                "lookoutequipment:StopInferenceScheduler"
            ],
            "Resource": [
                "arn:aws:lookoutequipment:Region:Account_ID:inference-scheduler/IoTSiteWise_*",
                "arn:aws:lookoutequipment:Region:Account_ID:model/IoTSiteWise_*",
                "arn:aws:lookoutequipment:Region:Account_ID:dataset/IoTSiteWise_*"
            ]
        },
        {
            "Sid": "L4EPermissions2",
            "Effect": "Allow",
            "Action": [
                "lookoutequipment:DescribeDataIngestionJob"
            ],
            "Resource": "*"
        },
        {
            "Sid": "S3Permissions",
            "Effect": "Allow",
            "Action": [
                "s3:CreateBucket",
                "s3:ListBucket",
                "s3:PutObject",
                "s3:GetObject"
            ],
            "Resource": ["arn:aws:s3:::iotsitewise-*"]
        },
        {
            "Sid": "IAMPermissions",
            "Effect": "Allow",
            "Action": [
                "iam:GetRole",
                "iam:PassRole"
            ],
            "Resource": "arn:aws:iam::Account_ID:role/Role_name"
        }
    ]
}

Trust policy


{
    "Version": "2012-10-17",
    "Statement": [{
            "Effect": "Allow",
            "Principal": {
                "Service": "iotsitewise.amazonaws.com"
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    "aws:SourceAccount": "Account_ID"
                },
                "ArnEquals": {
                    "aws:SourceArn": "arn:aws:iotsitewise:Region:Account_ID:asset/*"
                }
            }
        },
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "lookoutequipment.amazonaws.com"
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    "aws:SourceAccount": "Account_ID"
                },
                "ArnEquals": {
                    "aws:SourceArn": "arn:aws:lookoutequipment:Region:Account_ID:*"
                }
            }
        }
    ]
}

Choose Next.

Select data attributes (measurements, transforms, and metrics) that you want to send to Lookout for Equipment.
1. (Optional) Select measurements.
2. (Optional) Select transforms.
3. (Optional) Select metrics.
4. Choose Next.
Review your selections. To add the prediction definition to the asset model, on the summary page, choose Add prediction definition.

You can also Edit or Delete an existing prediction definition that has active predictions attached.

Training a prediction (console)

After you've added a prediction definition to an asset model, you can train the predictions that are on your assets.

To train a prediction in Amazon IoT SiteWise

Navigate to the Amazon IoT SiteWise console.
In the navigation pane, choose Assets, and select the asset you want to monitor.
Choose Predictions.
Select the predictions that you want to train.
Under Actions, choose Start training, and do the following:
1. Under Prediction details, select an IAM permissions role that allows Amazon IoT SiteWise to share your asset data with Lookout for Equipment. If you need to create a new role, choose Create a new role.
2. For Training data settings, enter a Training data time range to select which data to use to train the prediction.
3. (Optional) Select sampling rate of the data after post processing.
4. (Optional) For Data labels, provide an Amazon S3 bucket and prefix that holds your labeling data. For more information about labeling data, see Labeling your data in the Amazon Lookout for Equipment User Guide.
5. Choose Next.
(Optional) If you want the prediction to be active as soon as it has completed training, under Advanced settings, select Automatically activate the prediction after training, and then do the following:
1. Under Input data, for Data upload frequency, define how often data is uploaded, and for Offset delay time, define how much of a buffer to use.
2. Choose Next.
Review the details of the prediction and choose Save and start.

Starting or stopping inference on a prediction (console)

Note

Lookout for Equipment charges apply to scheduled inferences with the data transferred between Amazon IoT SiteWise and Lookout for Equipment. For more information, see Amazon Lookout for Equipment pricing.

If you added a prediction b"lookoutequipment:CreateDataset",ut did not choose to activate it after training, you must activate it for it to start monitoring your assets.

To start inference for a prediction

Navigate to the Amazon IoT SiteWise console.
In the navigation pane, choose Assets, and select the asset the prediction is added to.
Choose Predictions.
Select the predictions that you want to activate.
Under Actions, choose Start inference, and do the following:
1. Under Input data, for Data upload frequency, define how often data is uploaded, and for Offset delay time, define how much of a buffer to use.
2. Choose Save and start.

To stop inference for a prediction

Navigate to the Amazon IoT SiteWise console.
In the navigation pane, choose Assets, and select the asset the prediction is added to.
Choose Predictions.
Select the predictions that you want to stop.
Under Actions, choose Stop inference.

Adding a prediction definition (CLI)

To define a prediction definition on a new or existing asset model, you can use the Amazon Command Line Interface (Amazon CLI). After you define the prediction definition on the asset model, you train, and schedule inference for, a prediction on an asset in Amazon IoT SiteWise to do anomaly detection with Lookout for Equipment.

Prerequisites

To complete these steps, you must have an asset model and at least one asset created. For more information, see Creating an asset model (Amazon CLI) and Creating an asset (Amazon CLI).

If you are new to Amazon IoT SiteWise, you must call the CreateBulkImportJob API operation to import asset property values into Amazon IoT SiteWise, which will be used to train the model. For more information, see Create a bulk import job (Amazon CLI).

To add a prediction definition

Create a file called asset-model-payload.json. Follow the steps in these other sections to add your asset model's details to the file, but don't submit the request to create or update the asset model.
- For more information about how to create an asset model, see Creating an asset model (Amazon CLI)
- For more information about how to update an existing asset model, see Updating an asset or component model (Amazon CLI)

Add a Lookout for Equipment composite model (assetModelCompositeModels) to the asset model by adding the following code.

Replace Property with the ID of the properties that you want to include. To get those IDs, call DescribeAssetModel.
Replace RoleARN with the ARN of an IAM role that allows Lookout for Equipment to access your Amazon IoT SiteWise data.


{ 
  ...
  "assetModelCompositeModels": [
    {
      "name": "L4Epredictiondefinition",
      "type": "AWS/L4E_ANOMALY",
      "properties": [
          {
            "name": "AWS/L4E_ANOMALY_RESULT",
            "dataType": "STRUCT",
            "dataTypeSpec": "AWS/L4E_ANOMALY_RESULT",
            "unit": "none",
            "type": {
              "measurement": {}
            }
          },
          {
            "name": "AWS/L4E_ANOMALY_INPUT",
            "dataType": "STRUCT",
            "dataTypeSpec": "AWS/L4E_ANOMALY_INPUT",
            "type": {
               "attribute": {
                 "defaultValue": "{\"properties\": [\"Property1\", \"Property2\"]}"
               }
            }
          },
          {
            "name": "AWS/L4E_ANOMALY_PERMISSIONS",
            "dataType": "STRUCT",
            "dataTypeSpec": "AWS/L4E_ANOMALY_PERMISSIONS",
            "type": {
              "attribute": {
                "defaultValue": "{\"roleArn\": \"RoleARN\"}"
              }
            }
          },
          {
            "name": "AWS/L4E_ANOMALY_DATASET",
            "dataType": "STRUCT",
            "dataTypeSpec": "AWS/L4E_ANOMALY_DATASET",
            "type": {
                "attribute": {}
            }
          },
          {
            "name": "AWS/L4E_ANOMALY_MODEL",
            "dataType": "STRUCT",
            "dataTypeSpec": "AWS/L4E_ANOMALY_MODEL",
            "type": {
              "attribute": {}
            }
          },
          {
            "name": "AWS/L4E_ANOMALY_INFERENCE",
            "dataType": "STRUCT",
            "dataTypeSpec": "AWS/L4E_ANOMALY_INFERENCE",
            "type": {
              "attribute": {}
            }
          },
          {
            "name": "AWS/L4E_ANOMALY_TRAINING_STATUS",
            "dataType": "STRUCT",
            "dataTypeSpec": "AWS/L4E_ANOMALY_TRAINING_STATUS",
            "type": {
              "attribute": {
                "defaultValue": "{}"
              }
            }
          },
          {
            "name": "AWS/L4E_ANOMALY_INFERENCE_STATUS",
            "dataType": "STRUCT",
            "dataTypeSpec": "AWS/L4E_ANOMALY_INFERENCE_STATUS",
            "type": {
              "attribute": {
                "defaultValue": "{}"
              }
            }
          }
   ]
}

Create the asset model or update the existing asset model. Do one of the following:
- To create the asset model, run the following command:
```
aws iotsitewise create-asset-model --cli-input-json file://asset-model-payload.json
```
- To update the existing asset model, run the following command. Replace asset-model-id with the ID of the asset model that you want to update.
```
aws iotsitewise update-asset-model \
  --asset-model-id asset-model-id \
  --cli-input-json file://asset-model-payload.json
```

After you run the command, note the assetModelId in the response.

Training a prediction and starting inference (CLI)

Now that the prediction definition is defined, you can train assets based on it and start inference. If you want to train your prediction but not start inference, skip to Training a prediction (CLI). To train the prediction and start inference on the asset, you’ll need the assetId of the target resource.

To train and start inference of the prediction

Run the following command to find the assetModelCompositeModelId under assetModelCompositeModelSummaries. Replace asset-model-id with the ID of the asset model that you created in Updating an asset or component model (Amazon CLI).
```
aws iotsitewise describe-asset-model \
  --asset-model-id asset-model-id \
```
Run the following command to find the actionDefinitionId of the TrainingWithInference action. Replace asset-model-id with the ID used in previous step and replace asset-model-composite-model-id with the ID returned in the previous step.
```
aws iotsitewise describe-asset-model-composite-model \
  --asset-model-id asset-model-id \
  --asset-model-composite-model-id asset-model-composite-model-id \
```
Create a file called train-start-inference-prediction.json and add the following code, replacing the following:
- asset-id with the ID of the target asset
- action-definition-id with the ID of the TrainingWithInference action
- StartTime with the start of the training data, provided in epoch seconds
- EndTime with the end of the training data, provided in epoch seconds
- TargetSamplingRate with the sampling rate of the data after post processing by Lookout for Equipment. Allowed values are: PT1S | PT5S | PT10S | PT15S | PT30S | PT1M | PT5M | PT10M | PT15M | PT30M | PT1H.
```
{
  "targetResource": {
    "assetId": "asset-id"
  },
  "actionDefinitionId": "action-definition-Id",
  "actionPayload":{
    "stringValue": "{\"l4ETrainingWithInference\":{\"trainingWithInferenceMode\":\"START\",\"trainingPayload\":{\"exportDataStartTime\":StartTime,\"exportDataEndTime\":EndTime},\"targetSamplingRate\":\"TargetSamplingRate\"},\"inferencePayload\":{\"dataDelayOffsetInMinutes\":0,\"dataUploadFrequency\":\"PT5M\"}}}"
  }
}
```

Run the following command to start training and inference:


aws iotsitewise execute-action --cli-input-json file://train-start-inference-prediction.json

Training a prediction (CLI)

Now that the prediction definition is defined, you can train assets based on it. To train the prediction on the asset, you’ll need the assetId of the target resource.

To train the prediction

Run the following command to find the assetModelCompositeModelId under assetModelCompositeModelSummaries. Replace asset-model-id with the ID of the asset model that you created in Updating an asset or component model (Amazon CLI).
```
aws iotsitewise describe-asset-model \
  --asset-model-id asset-model-id \
```
Run the following command to find the actionDefinitionId of the Training action. Replace asset-model-id with the ID used in previous step and replace asset-model-composite-model-id with the ID returned in the previous step.
```
aws iotsitewise describe-asset-model-composite-model \
  --asset-model-id asset-model-id \
  --asset-model-composite-model-id asset-model-composite-model-id \
```
Create a file called train-prediction.json and add the following code, replacing the following:
- asset-id with the ID of the target asset
- action-definition-id with the ID of the training action
- StartTime with the start of the training data, provided in epoch seconds
- EndTime with the end of the training data, provided in epoch seconds
- (Optional) BucketName with the name of the Amazon S3 bucket that holds your label data
- (Optional) Prefix with the prefix associated with the Amazon S3 bucket.
- TargetSamplingRate with the sampling rate of the data after post processing by Lookout for Equipment. Allowed values are: PT1S | PT5S | PT10S | PT15S | PT30S | PT1M | PT5M | PT10M | PT15M | PT30M | PT1H.
  
  Note
  Include both the bucket name and prefix or neither.
```
{
  "targetResource": {
    "assetId": "asset-id"
  },
  "actionDefinitionId": "action-definition-Id",
  "actionPayload":{ "stringValue": "{\"l4ETraining\": {\"trainingMode\":\"START\",\"exportDataStartTime\": StartTime, \"exportDataEndTime\": EndTime, \"targetSamplingRate\":\"TargetSamplingRate\"}, \"labelInputConfiguration\": {\"bucketName\": \"BucketName\", \"prefix\": \"Prefix\"}}}"
}
}
```

Run the following command to start training:


aws iotsitewise execute-action --cli-input-json file://train-prediction.json

Before you can start inference, training must be completed. To check the status of the training, do one of the following:

From the console, navigate to the asset the prediction is on.
From the Amazon CLI, call BatchGetAssetPropertyValue using the propertyId of the trainingStatus property.

Starting or stopping inference on a prediction (CLI)

Once the prediction is trained, you can start inference to tell Lookout for Equipment to start monitoring your assets. To start or stop inference, you’ll need the assetId of the target resource.

To start inference

Run the following command to find the assetModelCompositeModelId under assetModelCompositeModelSummaries. Replace asset-model-id with the ID of the asset model that you created in Updating an asset or component model (Amazon CLI).
```
aws iotsitewise describe-asset-model \
  --asset-model-id asset-model-id \
```
Run the following command to find the actionDefinitionId of the Inference action. Replace asset-model-id with the ID used in previous step and replace asset-model-composite-model-id with the ID returned in the previous step.
```
aws iotsitewise describe-asset-model-composite-model \
  --asset-model-id asset-model-id \
  --asset-model-composite-model-id asset-model-composite-model-id \
```

Create a file called start-inference.json and add the following code, replacing the following:

asset-id with the ID of the target asset
action-definition-id with the ID of the start inference action
Offset with the amount of buffer to use
Frequency with how often data is uploaded


{
  "targetResource": {
    "assetId": "asset-id"
  },
  "actionDefinitionId": "action-definition-Id",
  "actionPayload":{ "stringValue": "{\"l4EInference\": {\"inferenceMode\":\"START\",\"dataDelayOffsetInMinutes\": Offset, \"dataUploadFrequency\": \"Frequency\"}}"
}}

Run the following command to start inference:


aws iotsitewise execute-action --cli-input-json file://start-inference.json

To stop inference

Run the following command to find the assetModelCompositeModelId under assetModelCompositeModelSummaries. Replace asset-model-id with the ID of the asset model that you created in Updating an asset or component model (Amazon CLI).
```
aws iotsitewise describe-asset-model \
  --asset-model-id asset-model-id \
```
Run the following command to find the actionDefinitionId of the Inference action. Replace asset-model-id with the ID used in previous step and replace asset-model-composite-model-id with the ID returned in the previous step.
```
aws iotsitewise describe-asset-model-composite-model \
  --asset-model-id asset-model-id \
  --asset-model-composite-model-id asset-model-composite-model-id \
```

Create a file called stop-inference.json and add the following code, replacing the following:

asset-id with the ID of the target asset
action-definition-id with the ID of the start inference action


{
  "targetResource": {
    "assetId": "asset-id"
  },
  "actionDefinitionId": "action-definition-Id",
  "actionPayload":{ "stringValue": "{\"l4EInference\":{\"inferenceMode\":\"STOP\"}}"
}}

Run the following command to stop inference:


aws iotsitewise execute-action --cli-input-json file://stop-inference.json

Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Integrating with Amazon IoT TwinMaker

Managing data storage