IoT SiteWise connector - Amazon IoT Greengrass
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.

Amazon IoT Greengrass Version 1 no longer receives feature updates, and will receive only security patches and bug fixes until June 30, 2023. For more information, see the Amazon IoT Greengrass V1 maintenance policy. We strongly recommend that you migrate to Amazon 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 Amazon 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 Amazon Web Services 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 Amazon IoT SiteWise? in the Amazon 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 Amazon IoT Greengrass core loses connection to the internet, the connector caches data until it can successfully connect to the Amazon Web Services 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 Amazon 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 Amazon 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 Amazon 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: Amazon IoT Greengrass Core software v1.10.2 and stream manager.

  • Amazon 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 Amazon IoT Greengrass and IoT SiteWise are supported.

  • An IAM policy added to the Greengrass group role. This role allows the Amazon 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: Amazon IoT Greengrass Core software v1.10.0 and stream manager.

  • Amazon 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 Amazon IoT Greengrass and IoT SiteWise are supported.

  • An IAM policy added to the Greengrass group role. This role allows the Amazon 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.

Version 5
  • Amazon 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 Amazon IoT Greengrass and IoT SiteWise are supported.

  • An IAM policy added to the Greengrass group role. This role allows the Amazon 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.

Version 4
  • Amazon 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 Amazon IoT Greengrass and IoT SiteWise are supported.

  • An IAM policy added to the Greengrass group role. This role allows the Amazon 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.

Version 3
  • Amazon 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 Amazon IoT Greengrass and IoT SiteWise are supported.

  • An IAM policy added to the Greengrass group role. This role allows the Amazon 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 1 and 2
  • Amazon 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 Amazon IoT Greengrass and IoT SiteWise are supported.

  • An IAM policy added to the Greengrass group role that allows access to Amazon 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 Amazon IoT Greengrass host that the IoT SiteWise connector can write persistent data to. Defaults to /var/sitewise.

Display name in the Amazon IoT console: Local storage path

Required: false

Type: string

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

AWSSecretsArnList

A list of secrets in Amazon 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 Amazon 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 Amazon IoT console: Maximum disk buffer size

Required: false

Type: string

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

Version 1
SiteWiseLocalStoragePath

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

Display name in the Amazon IoT console: Local storage path

Required: false

Type: string

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

SiteWiseOpcuaUserIdentityTokenSecretArn

The secret in Amazon 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 Amazon 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 Amazon IoT Greengrass group that references an OPC-UA user name and password secret.

Display name in the Amazon 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 Amazon IoT console: Maximum disk buffer size

Required: false

Type: string

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

Create Connector Example (Amazon CLI)

The following Amazon 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 Amazon 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 Amazon IoT SiteWise endpoints and quotas in the Amazon General Reference.

  • Maximum number of gateways per Amazon Web Services account.

  • Maximum number of OPC-UA sources per gateway.

  • Maximum rate of timestamp-quality-value (TQV) data points stored per Amazon Web Services account.

  • Maximum rate of TQV data points stored per asset property.

Licenses

Version 9, 10, 11, and 12

The IoT SiteWise connector includes the following third-party software/licensing:

This connector is released under the Greengrass Core Software License Agreement.

Versions 6, 7, and 8

The IoT SiteWise connector includes the following third-party software/licensing:

This connector is released under the Greengrass Core Software License Agreement.

Versions 1, 2, 3, 4, and 5

The IoT SiteWise connector includes the following third-party software/licensing:

This connector is released under the Greengrass Core Software License Agreement.

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 Amazon Web Services 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 Amazon IoT Greengrass Core software v1.10.0 or higher.

April 29, 2020

5

Fixed a compatibility issue with Amazon 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.

See also