Requirements Parameters Input data Output data Limits Licenses Changelog See also

AWS IoT Greengrass Version 1 entered the extended life phase on June 30, 2023. For more information, see the AWS IoT Greengrass V1 maintenance policy. After this date, AWS IoT Greengrass V1 won't release updates that provide features, enhancements, bug fixes, or security patches. Devices that run on AWS IoT Greengrass V1 won't be disrupted and will continue to operate and to connect to the cloud. We strongly recommend that you migrate to AWS IoT Greengrass Version 2, which adds significant new features and support for additional platforms.

IoT SiteWise connector

The IoT SiteWise connector sends local device and equipment data to asset properties in AWS IoT SiteWise. You can use this connector to collect data from multiple OPC-UA servers and publish it to IoT SiteWise. The connector sends the data to asset properties in the current AWS account and Region.

Note

IoT SiteWise is a fully managed service that collects, processes, and visualizes data from industrial devices and equipment. You can configure asset properties that process raw data sent from this connector to your assets' measurement properties. For example, you can define a transform property that converts a device's Celsius temperature data points to Fahrenheit, or you can define a metric property that calculates the average hourly temperature. For more information, see What is AWS IoT SiteWise? in the AWS IoT SiteWise User Guide.

The connector sends data to IoT SiteWise with the OPC-UA data stream paths sent from the OPC-UA servers. For example, the data stream path /company/windfarm/3/turbine/7/temperature might represent the temperature sensor of turbine #7 at wind farm #3. If the AWS IoT Greengrass core loses connection to the internet, the connector caches data until it can successfully connect to the AWS Cloud. You can configure the maximum disk buffer size used for caching data. If the cache size exceeds the maximum disk buffer size, the connector discards the oldest data from the queue.

After you configure and deploy the IoT SiteWise connector, you can add a gateway and OPC-UA sources in the IoT SiteWise console. When you configure a source in the console, you can filter or prefix the OPC-UA data stream paths sent by the IoT SiteWise connector. For instructions to finish setting up your gateway and sources, see Adding the gateway in the AWS IoT SiteWise User Guide.

IoT SiteWise receives data only from data streams that you have mapped to the measurement properties of IoT SiteWise assets. To map data streams to asset properties, you can set a property's alias to be equivalent to an OPC-UA data stream path. To learn about defining asset models and creating assets, see Modeling industrial assets in the AWS IoT SiteWise User Guide.

Notes

You can use stream manager to upload data to IoT SiteWise from sources other than OPC-UA servers. Stream manager also provides customizable support for persistence and bandwidth management. For more information, see Manage data streams on the AWS IoT Greengrass core.

This connector runs in No container isolation mode, so you can deploy it to a Greengrass group running in a Docker container.

This connector has the following versions.

Version	ARN
12 (recommended)	`arn:aws:greengrass:region::/connectors/IoTSiteWise/versions/12`
11	`arn:aws:greengrass:region::/connectors/IoTSiteWise/versions/11`
10	`arn:aws:greengrass:region::/connectors/IoTSiteWise/versions/10`
9	`arn:aws:greengrass:region::/connectors/IoTSiteWise/versions/9`
8	`arn:aws:greengrass:region::/connectors/IoTSiteWise/versions/8`
7	`arn:aws:greengrass:region::/connectors/IoTSiteWise/versions/7`
6	`arn:aws:greengrass:region::/connectors/IoTSiteWise/versions/6`
5	`arn:aws:greengrass:region::/connectors/IoTSiteWise/versions/5`
4	`arn:aws:greengrass:region::/connectors/IoTSiteWise/versions/4`
3	`arn:aws:greengrass:region::/connectors/IoTSiteWise/versions/3`
2	`arn:aws:greengrass:region::/connectors/IoTSiteWise/versions/2`
1	`arn:aws:greengrass:region::/connectors/IoTSiteWise/versions/1`

For information about version changes, see the Changelog.

Requirements

This connector has the following requirements:

Version 9, 10, 11, and 12

Important

This version introduces new requirements: AWS IoT Greengrass Core software v1.10.2 and stream manager.

AWS IoT Greengrass Core software v1.10.2.
Stream manager enabled on the Greengrass group.
Java 8 installed on the core device and added to the PATH environment variable.
This connector can be used only in Amazon Web Services Regions where both AWS IoT Greengrass and IoT SiteWise are supported.

An IAM policy added to the Greengrass group role. This role allows the AWS IoT Greengrass group access to the iotsitewise:BatchPutAssetPropertyValue action on the target root asset and its children, as shown in the following example. You can remove the Condition from the policy to allow the connector to access all of your IoT SiteWise assets.


{
    "Version": "2012-10-17",
    "Statement": [
        {
             "Effect": "Allow",
             "Action": "iotsitewise:BatchPutAssetPropertyValue",
             "Resource": "*",
             "Condition": {
                 "StringLike": {
                     "iotsitewise:assetHierarchyPath": [
                         "/root node asset ID",
                         "/root node asset ID/*"
                     ]
                 }
             }
        }
    ]
}

For more information, see Adding and removing IAM policies in the IAM User Guide.

Versions 6, 7, and 8

Important

This version introduces new requirements: AWS IoT Greengrass Core software v1.10.0 and stream manager.

AWS IoT Greengrass Core software v1.10.0.
Stream manager enabled on the Greengrass group.
Java 8 installed on the core device and added to the PATH environment variable.
This connector can be used only in Amazon Web Services Regions where both AWS IoT Greengrass and IoT SiteWise are supported.


{
    "Version": "2012-10-17",
    "Statement": [
        {
             "Effect": "Allow",
             "Action": "iotsitewise:BatchPutAssetPropertyValue",
             "Resource": "*",
             "Condition": {
                 "StringLike": {
                     "iotsitewise:assetHierarchyPath": [
                         "/root node asset ID",
                         "/root node asset ID/*"
                     ]
                 }
             }
        }
    ]
}

For more information, see Adding and removing IAM policies in the IAM User Guide.

Version 5

AWS IoT Greengrass Core software v1.9.4.
Java 8 installed on the core device and added to the PATH environment variable.
This connector can be used only in Amazon Web Services Regions where both AWS IoT Greengrass and IoT SiteWise are supported.


{
    "Version": "2012-10-17",
    "Statement": [
        {
             "Effect": "Allow",
             "Action": "iotsitewise:BatchPutAssetPropertyValue",
             "Resource": "*",
             "Condition": {
                 "StringLike": {
                     "iotsitewise:assetHierarchyPath": [
                         "/root node asset ID",
                         "/root node asset ID/*"
                     ]
                 }
             }
        }
    ]
}

For more information, see Adding and removing IAM policies in the IAM User Guide.

Version 4

AWS IoT Greengrass Core software v1.10.0.
Java 8 installed on the core device and added to the PATH environment variable.
This connector can be used only in Amazon Web Services Regions where both AWS IoT Greengrass and IoT SiteWise are supported.


{
    "Version": "2012-10-17",
    "Statement": [
        {
             "Effect": "Allow",
             "Action": "iotsitewise:BatchPutAssetPropertyValue",
             "Resource": "*",
             "Condition": {
                 "StringLike": {
                     "iotsitewise:assetHierarchyPath": [
                         "/root node asset ID",
                         "/root node asset ID/*"
                     ]
                 }
             }
        }
    ]
}

For more information, see Adding and removing IAM policies in the IAM User Guide.

Version 3

AWS IoT Greengrass Core software v1.9.4.
Java 8 installed on the core device and added to the PATH environment variable.
This connector can be used only in Amazon Web Services Regions where both AWS IoT Greengrass and IoT SiteWise are supported.


{
    "Version": "2012-10-17",
    "Statement": [
        {
             "Effect": "Allow",
             "Action": "iotsitewise:BatchPutAssetPropertyValue",
             "Resource": "*",
             "Condition": {
                 "StringLike": {
                     "iotsitewise:assetHierarchyPath": [
                         "/root node asset ID",
                         "/root node asset ID/*"
                     ]
                 }
             }
        }
    ]
}

For more information, see Adding and removing IAM policies in the IAM User Guide.

Versions 1 and 2

AWS IoT Greengrass Core software v1.9.4.
Java 8 installed on the core device and added to the PATH environment variable.
This connector can be used only in Amazon Web Services Regions where both AWS IoT Greengrass and IoT SiteWise are supported.

An IAM policy added to the Greengrass group role that allows access to AWS IoT Core and the iotsitewise:BatchPutAssetPropertyValue action on the target root asset and its children, as shown in the following example. You can remove the Condition from the policy to allow the connector to access all of your IoT SiteWise assets.


{
    "Version": "2012-10-17",
    "Statement": [
        {
             "Effect": "Allow",
             "Action": "iotsitewise:BatchPutAssetPropertyValue",
             "Resource": "*",
             "Condition": {
                 "StringLike": {
                     "iotsitewise:assetHierarchyPath": [
                         "/root node asset ID",
                         "/root node asset ID/*"
                     ]
                 }
             }
        },
        {
            "Effect": "Allow",
            "Action": [
                 "iot:Connect",
                 "iot:DescribeEndpoint",
                 "iot:Publish",
                 "iot:Receive",
                 "iot:Subscribe"
            ],
            "Resource": "*"
        }
    ]
}

For more information, see Adding and removing IAM identity permissions in the IAM User Guide.

Parameters

Versions 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, and 12

SiteWiseLocalStoragePath

The directory on the AWS IoT Greengrass host that the IoT SiteWise connector can write persistent data to. Defaults to /var/sitewise.

Display name in the AWS IoT console: Local storage path

Required: false

Type: string

Valid pattern: ^\s*$|\/.

AWSSecretsArnList

A list of secrets in AWS Secrets Manager that each contain a OPC-UA user name and password key-value pair. Each secret must be a key-value pair type secret.

Display name in the AWS IoT console: List of ARNs for OPC-UA username/password secrets

Required: false

Type: JsonArrayOfStrings

Valid pattern: \[( ?,? ?\"(arn:(aws(-[a-z]+)*):secretsmanager:[a-z0-9\\-]+:[0-9]{12}:secret:([a-zA-Z0-9\\\\]+\/)*[a-zA-Z0-9\/_+=,.@\\-]+-[a-zA-Z0-9]+)*\")*\]

MaximumBufferSize

The maximum size in GB for IoT SiteWise disk usage. Defaults to 10GB.

Display name in the AWS IoT console: Maximum disk buffer size

Required: false

Type: string

Valid pattern: ^\s*$|[0-9]+

Version 1

SiteWiseLocalStoragePath

The directory on the AWS IoT Greengrass host that the IoT SiteWise connector can write persistent data to. Defaults to /var/sitewise.

Display name in the AWS IoT console: Local storage path

Required: false

Type: string

Valid pattern: ^\s*$|\/.

SiteWiseOpcuaUserIdentityTokenSecretArn

The secret in AWS Secrets Manager that contains the OPC-UA user name and password key-value pair. This secret must be a key-value pair type secret.

Display name in the AWS IoT console: ARN of OPC-UA username/password secret

Required: false

Type: string

Valid pattern: ^$|arn:(aws(-[a-z]+)*):secretsmanager:[a-z0-9\\-]+:[0-9]{12}:secret:([a-zA-Z0-9\\\\]+/)*[a-zA-Z0-9/_+=,.@\\-]+-[a-zA-Z0-9]+

SiteWiseOpcuaUserIdentityTokenSecretArn-ResourceId

The secret resource in the AWS IoT Greengrass group that references an OPC-UA user name and password secret.

Display name in the AWS IoT console: OPC-UA username/password secret resource

Required: false

Type: string

Valid pattern: ^$|.+

MaximumBufferSize

The maximum size in GB for IoT SiteWise disk usage. Defaults to 10GB.

Display name in the AWS IoT console: Maximum disk buffer size

Required: false

Type: string

Valid pattern: ^\s*$|[0-9]+

Create Connector Example (AWS CLI)

The following AWS CLI command creates a ConnectorDefinition with an initial version that contains the IoT SiteWise connector.


aws greengrass create-connector-definition --name MyGreengrassConnectors --initial-version '{
    "Connectors": [
        {
            "Id": "MyIoTSiteWiseConnector",
            "ConnectorArn": "arn:aws:greengrass:region::/connectors/IoTSiteWise/versions/11"
        }
    ]
}'

Note

The Lambda functions in this connector have a long-lived lifecycle.

In the AWS IoT Greengrass console, you can add a connector from the group's Connectors page. For more information, see Getting started with Greengrass connectors (console).

Input data

This connector doesn't accept MQTT messages as input data.

Output data

This connector doesn't publish MQTT messages as output data.

Limits

This connector is subject to the following all limits imposed by IoT SiteWise, including the following. For more informatison, see AWS IoT SiteWise endpoints and quotas in the AWS General Reference.

Maximum number of gateways per AWS account.
Maximum number of OPC-UA sources per gateway.
Maximum rate of timestamp-quality-value (TQV) data points stored per AWS account.
Maximum rate of TQV data points stored per asset property.

Licenses

Changelog

The following table describes the changes in each version of the connector.

Version	Changes	Date
12	This version contains bug fixes.	December 22, 2021
11	Support for strings that contain hidden or unprintable characters. Hidden and unprintable characters are automatically removed before the strings are sent to the AWS Cloud. Fixed an issue that caused the IoT SiteWise gateway to infinitely retry invalid requests. Fixed an issue that caused a corrupted checkpoint when the IoT SiteWise gateway was connected to a high-frequency data source. Improved error messages to help troubleshoot the gateway configuration.	March 24, 2021
10	Configured `StreamManager` to improve handling when the source connection is lost and re-established. This version also accepts OPC-UA values with a `ServerTimestamp` when no `SourceTimestamp` is available.	January 22, 2021
9	Support launched for custom Greengrass `StreamManager` stream destinations, OPC-UA deadbanding, custom scan mode and custom scan rate. Also includes improved performance during configuration updates made from the IoT SiteWise gateway.	December 15, 2020
8	Improved stability when the connector experiences intermittent network connectivity.	November 19, 2020
7	Fixed an issue with gateway metrics.	August 14, 2020
6	Added support for CloudWatch metrics and automatic discovery of new OPC-UA tags. This version requires stream manager and AWS IoT Greengrass Core software v1.10.0 or higher.	April 29, 2020
5	Fixed a compatibility issue with AWS IoT Greengrass Core software v1.9.4.	February 12, 2020
4	Fixed an issue with OPC-UA server reconnection.	February 7, 2020
3	Removed `iot:*` permissions requirement.	December 17, 2019
2	Added support for multiple OPC-UA secret resources.	December 10, 2019
1	Initial release.	December 2, 2019

A Greengrass group can contain only one version of the connector at a time. For information about upgrading a connector version, see Upgrading connector versions.