# Add data sources to your AWS IoT SiteWise Edge gateway After setting up an AWS IoT SiteWise Edge gateway, you can add and configure data sources to ingest data from local industrial equipment to AWS IoT SiteWise. SiteWise Edge supports various protocols, including OPC UA, and many other protocols available through partner data sources. These sources enable your gateway to connect with local servers and retrieve your industrial data. By configuring data sources, you can ingest data from a variety of data sources, and then associate the data streams with asset properties, enabling comprehensive industrial asset modeling and data mapping in AWS IoT SiteWise. **Topics** + [OPC UA data sources for AWS IoT SiteWise Edge gateways](configure-sources-opcua.md) + [Partner data sources on SiteWise Edge gateways](partner-data-sources.md) # OPC UA data sources for AWS IoT SiteWise Edge gateways After you set up an AWS IoT SiteWise Edge gateway, you can configure data sources so that your SiteWise Edge gateway can ingest data from local industrial equipment to AWS IoT SiteWise. Each source represents a local server, such as an OPC UA server, that your SiteWise Edge gateway connects and retrieves industrial data streams. For more information about setting up a SiteWise Edge gateway, see [Create a self-hosted SiteWise Edge gateway](create-gateway-ggv2.md). The gateway type, MQTT-enabled, V3 gateways versus Classic stream, V2 gateways, influences how OPC UA data is handled. In Classic stream, V2 gateways, OPC UA data sources are added directly to the gateway IoT SiteWise publisher configuration. Each data source is coupled with the gateway, and data routing is configured individually for each source. In contrast, using MQTT-enabled, V3 gateways, OPC UA data sources are converted to MQTT topics and are managed through centralized destinations. For more information on each type, see [MQTT-enabled, V3 gateways for AWS IoT SiteWise Edge](mqtt-enabled-v3-gateway.md) and [Classic streams, V2 gateways for AWS IoT SiteWise Edge](classic-streams-v2-gateway.md). **Note** AWS IoT SiteWise restarts your SiteWise Edge gateway each time you add or edit a source. Your SiteWise Edge gateway won't ingest data while it's updating source configuration. The time to restart your SiteWise Edge gateway depends on the number of tags on your SiteWise Edge gateway's sources. Restart time can range from a few seconds (for a SiteWise Edge gateway with few tags) to several minutes (for a SiteWise Edge gateway with many tags). After you create sources, you can associate your data streams with asset properties. For more information about how to create and use assets, see [Model industrial assets](industrial-asset-models.md). You can view CloudWatch metrics to verify that a data source is connected to AWS IoT SiteWise. For more information, see [AWS IoT Greengrass Version 2 gateway metrics](monitor-cloudwatch-metrics.md#gateway-metrics-ggv2). Currently, AWS IoT SiteWise supports the following data source protocols: + [OPC UA](https://en.wikipedia.org/wiki/OPC_Unified_Architecture) – A machine-to-machine (M2M) communication protocol for industrial automation. ## Support for additional industrial protocols SiteWise Edge supports a wide range of industrial protocols through integration with data source partners. These partnerships enable connectivity with over 200 different protocols, accommodating various industrial systems and devices. For a list of available data source partners, see [SiteWise Edge gateway partner data source options](connect-partner-data-source.md). # Set up an OPC UA source in SiteWise Edge You can use the AWS IoT SiteWise console or a SiteWise Edge gateway capability to define and add an OPC UA source to your SiteWise Edge gateway to represent a local OPC UA server. **Topics** + [Configure an OPC UA source (console)](#config-opcua-source-console) + [Configure an OPC UA source (AWS CLI)](#configure-opc-ua-source-cli) ## Configure an OPC UA source (console) You can use the console to configure the OPC UA source with the following procedure. **Note** Warning: Duplicate TQVs may result in double charging. **To configure an OPC UA source using the AWS IoT SiteWise console** 1. Navigate to the [AWS IoT SiteWise console](https://console.aws.amazon.com/iotsitewise/). 1. In the left navigation, choose **Edge gateways** in the **Edge** section. 1. Select the SiteWise Edge gateway to add an OPC UA source. 1. Choose **Add data source**. 1. Enter a name for the source. 1. Enter the **Local endpoint** of the data source server. The endpoint can be the IP address or hostname. You may also add a port number to the local endpoint. For example, your local endpoint might look like this: **opc.tcp://203.0.113.0:49320** 1. (Optional) For **Node ID for selection**, add node filters to limit which data streams are ingested to the AWS Cloud. By default, SiteWise Edge gateways use the root node of a server to ingest all data streams. You can use node filters to reduce your SiteWise Edge gateway's startup time and CPU usage by only including paths to data that you model in AWS IoT SiteWise. By default, SiteWise Edge gateways upload all OPC UA paths except those that start with `/Server/`. To define OPC UA node filters, you can use node paths and the `*` and `**` wildcard characters. For more information, see [Use OPC UA node filters in SiteWise Edge](opc-ua-node-filters.md). 1. **Destinations** vary between MQTT-enabled, V3 gateways and Classic streams, V2 gateways. + **Classic steams, V2 gateway destinations** have a 1:1 relationship with the source. Each source sends data to a particular destination. + **MQTT-enabled, V3 gateway destinations** are set up separately because the hub and spoke model lets you centralize configuration and management of multiple data sources across different gateways. To set up destinations in a V3 gateway, see [Understand AWS IoT SiteWise Edge destinations](gw-destinations.md#source-destination). ------ #### [ Classic steams, V2 gateway destinations ] + **AWS IoT SiteWise real-time** – Choose this to send data directly to AWS IoT SiteWise storage. Ingest and monitor data in real-time at the edge. + **AWS IoT SiteWise Buffered using Amazon S3** – Send data in Parquet format to Amazon S3 and then import into AWS IoT SiteWise storage. Choose this option to ingest data in batches, and store historical data in a cost-effective way. You can configure your preferred Amazon S3 bucket location, and the frequency at which you want data to be uploaded to Amazon S3. You can also choose what to do with the data after ingestion into AWS IoT SiteWise. You can choose to have the data available in both AWS IoT SiteWise and Amazon S3 or you can choose to delete it automatically from Amazon S3 after it has been imported into AWS IoT SiteWise. + The Amazon S3 bucket is a staging and buffering mechanism and supports files in the Parquet format. + If you select the check box **Import data into AWS IoT SiteWise storage**, data is uploaded into Amazon S3 first, and then into AWS IoT SiteWise storage. + If you select the check box **Delete data from Amazon S3**, data is deleted from Amazon S3, after it is imported into SiteWise storage. + If you clear the check box **Delete data from Amazon S3**, data is stored both in Amazon S3, and in SiteWise storage. + If you clear the check box **Import data into AWS IoT SiteWise storage**, data is stored only in Amazon S3. It is not imported into SiteWise storage. Visit [Manage data storage](manage-data-storage.md) for details on the various storage options AWS IoT SiteWise provides. To learn more about pricing options, see [AWS IoT SiteWise pricing](https://aws.amazon.com/iot-sitewise/pricing/). + **AWS IoT Greengrass stream manager** – Use AWS IoT Greengrass stream manager to send data to the following AWS Cloud destinations: channels in AWS IoT Analytics, streams in Amazon Kinesis Data Streams, asset properties in AWS IoT SiteWise, or objects in Amazon Simple Storage Service (Amazon S3). For more information, see [Manage data streams on the AWS IoT Greengrass Core](https://docs.aws.amazon.com/greengrass/v2/developerguide/manage-data-streams.html) in *AWS IoT Greengrass Version 2 Developer Guide*. Enter a name for the AWS IoT Greengrass stream. ------ #### [ MQTT-enabled, V3 gateway destinations ] 1. See [MQTT-enabled, V3 gateways for AWS IoT SiteWise Edge](mqtt-enabled-v3-gateway.md) for information on adding your relevant destinations. 1. Return to this procedure after adding your source destinations. ------ 1. In the **Advanced configuration** pane, you can do the following: 1. Choose a **Message security mode** for connections and data in transit between your source server and your SiteWise Edge gateway. This field is the combination of the OPC UA security policy and message security mode. Choose the same security policy and message security mode that you specified for your OPC UA server. 1. If your source requires authentication, choose an AWS Secrets Manager secret from the **Authentication configuration** list. The SiteWise Edge gateway uses the authentication credentials in this secret when it connects to this data source. You must attach secrets to your SiteWise Edge gateway's AWS IoT Greengrass component to use them for data source authentication. For more information, see [Configure data source authentication for SiteWise Edge](configure-source-authentication-ggv2.md). **Tip** Your data server might have an option named **Allow anonymous login**. If this option is **Yes**, then your source doesn't require authentication. 1. (Optional) You can activate a data stream prefix by selecting **Activate data stream prefix - *optional***. 1. Enter a **Data stream prefix**. The SiteWise Edge gateway adds this prefix to all data streams from this source. Use a data stream prefix to distinguish between data streams that have the same name from different sources. Each data stream should have a unique name within your account. 1. (Optional) Choose a **Data type conversion** option to convert unsupported OPC UA data types into strings before ingesting them into AWS IoT SiteWise. Convert array values with simple data types to JSON strings and DateTime data types to ISO 8601 strings. For more information, see [Converting unsupported data types](string-conversion.md). 1. Choose a **Default data change trigger** for nodes that are not contained in a user-defined property group. The default data change trigger determines when the OPC UA server sends updated values to the gateway. You can choose one of the following options: + **Status** – to receive data only when a status changes. + **StatusValue** – to receive data when a status or value changes. + **StatusValueTimestamp** – to receive data when a status, value, or timestamp changes. 1. (Optional) On an MQTT-enabled, V3 gateway, you can use **Discovery configuration** to configure the OPC UA node discovery process. Discovery configuration replaces the previous config override file system for these options with console-based settings that update dynamically without needing to restart the gateway. **Note** **Default data change trigger** requires version 3.1.0 or later of the IoT SiteWise OPC UA collector component. For more information, see [Update the version of an AWS IoT SiteWise component](manage-gateways-ggv2.md#update-component-version). 1. For **Maximum concurrent browse request count**, enter the maximum number of browse requests that your OPC UA server can handle simultaneously. You can configure up to 500 concurrent browse requests per data source. 1. For **Maximum node count per browse request**, enter the maximum number of nodes to send in each browse request to the OPC UA server. You can send up to 1,000 nodes per browse request. 1. Choose **Avoid node tree loops** to prevent the gateway from getting stuck in circular references when browsing the OPC UA server's structure. When selected, the gateway tracks visited locations to avoid infinite loops that can occur when server nodes reference each other in a circular pattern. 1. Choose **Enable node traversal** to allow the gateway to explore the complete structure of your OPC UA server to discover all available data points from your equipment and devices. When selected, the gateway navigates through your equipment's data organization beyond the root level to find all sensors, controls, and measurement points automatically. 1. Choose **Enable periodic discovery** to automatically run discovery operations at regular intervals to detect changes in the OPC UA server's structure. When selected, the gateway continuously monitors for newly added equipment or data points, ensuring they are automatically detected and made available for data collection. 1. For **Periodic discovery interval**, set the time interval between automatic discovery operations when periodic discovery is running. The minimum periodic discovery interval is 30 seconds and the maximum is 30 days. 1. For **Maximum nodes discovered per interval**, set the maximum number of nodes that should be discovered per discovery interval. This helps control the load on both the gateway and the OPC UA server during discovery operations. 1. (Optional) For **Property groups**, choose **Add new group**. 1. Enter a **Name** for the property group. 1. For **Properties**: 1. For **Node paths**, add OPC UA node filters to limit which OPC UA paths are uploaded to AWS IoT SiteWise. The format is similar to **Node ID for selection**. 1. For **Group settings**, do the following: 1. For **Data quality setting**, choose the type of data quality that you want AWS IoT SiteWise Collector to ingest. 1. For **Scan mode setting**, configure the standard subscription properties using **Scan mode**. You can select **Subscribe** or **Poll**. For more information about scan mode, see [Filter data ingestion ranges with OPC UA](opcua-data-acquisition.md). ------ #### [ Subscribe ] **To send every data point** 1. Choose **Subscribe** and set the following: 1. **[Data change trigger](https://reference.opcfoundation.org/v104/Core/docs/Part4/7.17.2/)** – The condition that initiates a data change alert. 1. **[Subscription queue size](https://reference.opcfoundation.org/v104/Core/docs/Part4/7.16/)** – The depth of the queue on an OPC UA server for a particular metric where notifications for monitored items are queued. 1. **[Subscription publishing interval](https://reference.opcfoundation.org/v104/Core/docs/Part4/5.13.2/)** – The interval (in milliseconds) of publishing cycle specified when subscription is created. 1. **Snapshot interval - *Optional*** – The snapshot frequency timeout setting to ensure that AWS IoT SiteWise Edge ingests a steady stream of data. 1. **Scan rate** – The rate that you want the SiteWise Edge gateway to read your registers. AWS IoT SiteWise automatically calculates the minimum allowable scan rate for your SiteWise Edge gateway. 1. **Timestamp** – The timestamp to include with your OPC UA data points. You can use the server timestamp or your device's timestamp. **Note** Use version 2.5.0 or later of the IoT SiteWise OPC UA collector component. If you use the timestamp feature with earlier versions, configuration updates fail. For more information, see [Update the version of an AWS IoT SiteWise component](manage-gateways-ggv2.md#update-component-version). 1. In **Deadband settings**, configure a **Deadband type**. The deadband type controls what data your source sends to your AWS IoT SiteWise, and what data it discards. For more information about the deadband setting, see [Filter data ingestion ranges with OPC UA](opcua-data-acquisition.md). + **None** – The associated server sends all data points for this property group. + **Percentage** – The associated server only sends data that falls outside a specified percentage of the data's range. This range is computed by the server based on the engineering unit minimum and maximum defined for each node. If the server does not support percentage deadbands or lacks defined engineering units, the gateway calculates the range using the minimum and maximum values provided below. + **Absolute** – The associated server only sends data that falls outside of a specific range. 1. Set the **Deadband value** as the percentage of the data range to deadband. 1. (Optional) Specify a minimum and maximum for the deadband range using **Minimum range - *optional*** and **Maximum range - *optional***. ------ #### [ Poll ] **To send data points at a specific interval** + Choose **Poll** and set the following: 1. **Scan rate** – The rate that you want the SiteWise Edge gateway to read your registers. AWS IoT SiteWise automatically calculates the minimum allowable scan rate for your SiteWise Edge gateway. 1. **Timestamp** – The timestamp to include with your OPC UA data points. You can use the server timestamp or your device's timestamp. **Note** Use version 3.1.0 or later of the IoT SiteWise OPC UA collector component. If you use the timestamp feature with earlier versions, configuration updates fail. For more information, see [Update the version of an AWS IoT SiteWise component](manage-gateways-ggv2.md#update-component-version). **Note** **Deadband settings** are applicable when you've selected **Subscribe** in the **Scan mode settings**. ------ 1. Choose **Save**. ## Configure an OPC UA source (AWS CLI) You can define OPC UA data sources for an SiteWise Edge gateway using the AWS CLI. To do this, create an OPC UA capability configuration JSON file and use the [ update-gateway-capability-configuration](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iotsitewise/update-gateway-capability-configuration.html#) command to update the SiteWise Edge gateway configuration. You must define all of your OPC UA sources in a single capability configuration. ------ #### [ MQTT-enabled, V3 gateway ] This capability has the following namespace. + `iotsitewise:opcuacollector:3` ``` { "sources": [ { "name": "string", "endpoint": { "certificateTrust": { "type": "TrustAny" | "X509", "certificateBody": "string", "certificateChain": "string", }, "endpointUri": "string", "securityPolicy": "NONE" | "BASIC128_RSA15" | "BASIC256" | "BASIC256_SHA256" | "AES128_SHA256_RSAOAEP" | "AES256_SHA256_RSAPSS", "messageSecurityMode": "NONE" | "SIGN" | "SIGN_AND_ENCRYPT", "identityProvider": { "type": "Anonymous" | "Username", "usernameSecretArn": "string" }, "nodeFilterRules": [ { "action": "INCLUDE", "definition": { "type": "OpcUaRootPath", "rootPath": "string" } } ] }, "measurementDataStreamPrefix": "string", "typeConversions": { "array": "JsonArray", "datetime": "ISO8601String" }, "destination": { { "type":"MQTT" } }, "defaultPropertyGroupConfig": { "dataChangeTrigger": "STATUS" | "STATUS_VALUE" | "STATUS_VALUE_TIMESTAMP" }, "discoveryConfig": { "enableNodeTraversal": true | false, "avoidNodeTreeLoops": true | false, "maxConcurrentBrowseRequests": integer, "maxNodesPerBrowseRequest": integer, "periodicDiscovery": { "interval": "string", "maxNodesDiscoveredPerInterval": integer } }, "propertyGroups": [ { "name": "string", "nodeFilterRuleDefinitions": [ { "type": "OpcUaRootPath", "rootPath": "string" } ], "deadband": { "type": "PERCENT" | "ABSOLUTE", "value": double, "eguMin": double, "eguMax": double, "timeoutMilliseconds": integer }, "scanMode": { "type": "EXCEPTION" | "POLL", "rate": integer, "timestampToReturn": "SOURCE_TIME" | "SERVER_TIME" }, "dataQuality": { "allowGoodQuality": true | false, "allowBadQuality": true | false, "allowUncertainQuality": true | false }, "subscription": { "dataChangeTrigger": "STATUS" | "STATUS_VALUE" | "STATUS_VALUE_TIMESTAMP", "queueSize": integer, "publishingIntervalMilliseconds": integer, "snapshotFrequencyMilliseconds": integer } } ] } ] } ``` ------ #### [ Classic streams, V2 gateway ] This capability has the following namespace. + `iotsitewise:opcuacollector:2` Request syntax ``` { "sources": [ { "name": "string", "endpoint": { "certificateTrust": { "type": "TrustAny" | "X509", "certificateBody": "string", "certificateChain": "string", }, "endpointUri": "string", "securityPolicy": "NONE" | "BASIC128_RSA15" | "BASIC256" | "BASIC256_SHA256" | "AES128_SHA256_RSAOAEP" | "AES256_SHA256_RSAPSS", "messageSecurityMode": "NONE" | "SIGN" | "SIGN_AND_ENCRYPT", "identityProvider": { "type": "Anonymous" | "Username", "usernameSecretArn": "string" }, "nodeFilterRules": [ { "action": "INCLUDE", "definition": { "type": "OpcUaRootPath", "rootPath": "string" } } ] }, "measurementDataStreamPrefix": "string", "typeConversions": { "array": "JsonArray", "datetime": "ISO8601String" }, "destination": { "type": "StreamManager", "streamName": "string", "streamBufferSize": integer, }, "propertyGroups": [ { "name": "string", "nodeFilterRuleDefinitions": [ { "type": "OpcUaRootPath", "rootPath": "string" } ], "deadband": { "type": "PERCENT" | "ABSOLUTE", "value": double, "eguMin": double, "eguMax": double, "timeoutMilliseconds": integer }, "scanMode": { "type": "EXCEPTION" | "POLL", "rate": integer, "timestampToReturn": "SOURCE_TIME" | "SERVER_TIME" }, "dataQuality": { "allowGoodQuality": true | false, "allowBadQuality": true | false, "allowUncertainQuality": true | false }, "subscription": { "dataChangeTrigger": "STATUS" | "STATUS_VALUE" | "STATUS_VALUE_TIMESTAMP", "queueSize": integer, "publishingIntervalMilliseconds": integer, "snapshotFrequencyMilliseconds": integer } } ] } ] } ``` ------ ### Request body `sources` A list of OPC UA source definition structures that each contain the following information: `name` A unique, friendly name for the source. `endpoint` An endpoint structure that contains the following information: `certificateTrust` A certificate trust policy structure that contains the following information: `type` The certificate trust mode for the source. Choose one of the following: + `TrustAny` – The SiteWise Edge gateway trusts any certificate when it connects to the OPC UA source. + `X509` – The SiteWise Edge gateway trusts an X.509 certificate when it connects to the OPC UA source. If you choose this option, you must define `certificateBody` in `certificateTrust`. You can also define `certificateChain` in `certificateTrust`. `certificateBody` (Optional) The body of an X.509 certificate. This field is required if you choose `X509` for `type` in `certificateTrust`. `certificateChain` (Optional) The chain of trust for an X.509 certificate. This field is used only if you choose `X509` for `type` in `certificateTrust`. `endpointUri` The local endpoint of the OPC UA source. For example, your local endpoint might look like `opc.tcp://203.0.113.0:49320`. `securityPolicy` The security policy to use so that you can secure messages that are read from the OPC UA source. Choose one of the following: + `NONE` – The SiteWise Edge gateway doesn't secure messages from the OPC UA source. We recommend that you choose a different security policy. If you choose this option, you must also choose `NONE` for `messageSecurityMode`. + `BASIC256_SHA256` – The `Basic256Sha256` security policy. + `AES128_SHA256_RSAOAEP` – The `Aes128_Sha256_RsaOaep` security policy. + `AES256_SHA256_RSAPSS` – The `Aes256_Sha256_RsaPss` security policy. + `BASIC128_RSA15` – (Deprecated) The `Basic128Rsa15` security policy is deprecated in the OPC UA specification because it's no longer considered secure. We recommend that you choose a different security policy. For more information, see [Profile SecurityPolicy – Basic128Rsa15](https://profiles.opcfoundation.org/profile/1532). + `BASIC256` – (Deprecated) The `Basic256` security policy is deprecated in the OPC UA specification because it's no longer considered secure. We recommend that you choose a different security policy. For more information, see [SecurityPolicy – Basic256](https://profiles.opcfoundation.org/profile/1536). If you choose a security policy other than `NONE`, you must choose `SIGN` or `SIGN_AND_ENCRYPT` for `messageSecurityMode`. You must also configure your source server to trust the SiteWise Edge gateway. For more information, see [Set up OPC UA servers to trust the AWS IoT SiteWise Edge gateway](enable-source-trust.md). `messageSecurityMode` The message security mode to use to secure connections to the OPC UA source. Choose one of the following: + `NONE` – The SiteWise Edge gateway doesn't secure connections to the OPC UA source. We recommend that you choose a different message security mode. If you choose this option, you must also choose `NONE` for `securityPolicy`. + `SIGN` – Data in transit between the SiteWise Edge gateway and the OPC UA source is signed but not encrypted. + `SIGN_AND_ENCRYPT` – Data in transit between the gateway and the OPC UA source is signed and encrypted. If you choose a message security mode other than `NONE`, you must choose a `securityPolicy` other than `NONE`. You must also configure your source server to trust the SiteWise Edge gateway. For more information, see [Set up OPC UA servers to trust the AWS IoT SiteWise Edge gateway](enable-source-trust.md). `identityProvider` An identity provider structure that contains the following information: `type` The type of authentication credentials required by the source. Choose one of the following: + `Anonymous` – The source doesn't require authentication to connect. + `Username` – The source requires a user name and password to connect. If you choose this option, you must define `usernameSecretArn` in `identityProvider`. `usernameSecretArn` (Optional) The ARN of an AWS Secrets Manager secret. The SiteWise Edge gateway uses the authentication credentials in this secret when it connects to this source. You must attach secrets to your SiteWise Edge gateway's IoT SiteWise connector to use them for source authentication. For more information, see [Configure data source authentication for SiteWise Edge](configure-source-authentication-ggv2.md). This field is required if you choose `Username` for `type` in `identityProvider`. `nodeFilterRules` A list of node filter rule structures that define the OPC UA data stream paths to send to the AWS Cloud. You can use node filters to reduce your SiteWise Edge gateway's startup time and CPU usage by only including paths to data that you model in AWS IoT SiteWise. By default, SiteWise Edge gateways upload all OPC UA paths except those that start with `/Server/`. To define OPC UA node filters, you can use node paths and the `*` and `**` wildcard characters. For more information, see [Use OPC UA node filters in SiteWise Edge](opc-ua-node-filters.md). Each structure in the list must contain the following information: `action` The action for this node filter rule. You can choose the following option: + `INCLUDE` – The SiteWise Edge gateway includes only data streams that match this rule. `definition` A node filter rule structure that contains the following information: `type` The type of node filter path for this rule. You can choose the following option: + `OpcUaRootPath` – The SiteWise Edge gateway evaluates this node filter path against the root of the OPC UA path hierarchy. `rootPath` The node filter path to evaluate against the root of the OPC UA path hierarchy. This path must start with `/`. `measurementDataStreamPrefix` A string to prepend to all data streams from the source. The SiteWise Edge gateway adds this prefix to all data streams from this source. Use a data stream prefix to distinguish between data streams that have the same name from different sources. Each data stream should have a unique name within your account. `typeConversions` The types of conversions available for unsupported OPC UA data types. Each data type is converted to strings. For more information, see [Converting unsupported data types](string-conversion.md). `array` The simple array data type that is converted to strings. You can choose the following option: + `JsonArray` – Indicates that you choose to convert your simple array data types to strings. `datetime` The DateTime data type that is converted to strings. You can choose the following option: + `ISO8601String` – Indicates that you choose to convert ISO 8601 data types to strings. `destination` Configuration for the destination of OPC UA tags. Classic stream, v2 and MQTT-enabled, V3 gateways have differing configurations for destinations. `type` The type of the destination. `streamName` – *only for Classic streams, V2 gateways* The name of the stream. The stream name should be unique. `streamBufferSize` – *only for Classic streams, V2 gateways* The buffer size of the stream. This is important for managing the flow of data from OPC UA sources. `defaultPropertyGroupConfig` – *MQTT-enabled, V3 gateways only* (Optional) Configuration for the default property group. The default property group contains all nodes not otherwise contained in a user-defined property group. `dataChangeTrigger` The default data change trigger to use in the default property group. Valid values are `STATUS_VALUE_TIMESTAMP`, `STATUS_VALUE`, or `STATUS`. `defaultPropertyGroupConfig` requires version 3.1.0 or later of the IoT SiteWise OPC UA collector component. For more information, see [Update the version of an AWS IoT SiteWise component](manage-gateways-ggv2.md#update-component-version). `discoveryConfig` – *MQTT-enabled, V3 gateways only* (Optional) Configuration for the OPC UA node discovery process. `enableNodeTraversal` Specifies whether to continue traversing child nodes of the root node defined by the data source's node filter. When set to `false`, discovery stops at the root node. `avoidNodeTreeLoops` Specifies whether to avoid infinite loops during the OPC UA node browsing process. When set to `true`, the gateway tracks visited nodes to prevent circular references. `maxConcurrentBrowseRequests` The maximum number of concurrent browse requests that your OPC UA server can handle simultaneously. Valid range is 1 to 500. `maxNodesPerBrowseRequest` The maximum number of nodes to send in each browse request to the OPC UA server. Valid range is 1 to 1,000. `periodicDiscovery` Configuration for running discovery periodically at fixed intervals. Periodic discovery is enabled when this configuration is provided. `interval` The amount of time between periodic discovery operations. You can use `m` for minutes, `h` for hours, and `d` for days. For example, `90m` or `1h`. The minimum interval is 30 seconds. `maxNodesDiscoveredPerInterval` The maximum number of nodes that should be discovered per discovery interval. This helps control the load on both the gateway and the OPC UA server. `periodicDiscovery` requires version 3.1.0 or later of the IoT SiteWise OPC UA collector component. For more information, see [Update the version of an AWS IoT SiteWise component](manage-gateways-ggv2.md#update-component-version). If discovery loops infinitely, enable `avoidNodeTreeLoops`. Monitor discovery progress in CloudWatch logs under the `aws.iot.SiteWiseOpcUaCollector` component. `propertyGroups` (Optional) The list of property groups that define the `deadband` and `scanMode` requested by the protocol. `name` The name of the property group. This should be a unique identifier. `deadband` The `deadband` value defines the minimum change in a data point's value that must occur before the data is sent to the cloud. It contains the following information: `type` The supported types of deadband. You can choose the following options: + `ABSOLUTE` – A fixed value that specifies the minimum absolute change required to consider a data point significant enough to be sent to the cloud. + `PERCENT` – A dynamic value that specifies the minimum change required as a percentage of the last sent data point's value. This type of deadband is useful when the data values vary significantly over time. `value` The value of the deadband. When `type` is `ABSOLUTE`, this value is a unitless double. When `type` is `PERCENT`, this value is a double between `1` and `100`. `eguMin` (Optional) The engineering unit minimum when using a `PERCENT` deadband. You set this if the OPC UA server doesn't have engineering units configured. `eguMax` (Optional) The engineering unit maximum when using a `PERCENT` deadband. You set this if the OPC UA server doesn't have engineering units configured. `timeoutMilliseconds` The duration in milliseconds before timeout. The minimum is `100`. `scanMode` The `scanMode` structure that contains the following information: `type` The supported types of `scanMode`. Accepted values are `POLL` and `EXCEPTION`. `rate` The sampling interval for the scan mode. `timestampToReturn` The source of the timestamp. You can choose the following options: + `SOURCE_TIME` – Uses the timestamp from your device. + `SERVER_TIME` – Uses the timestamp from your server. Use `TimestampToReturn` with version 2.5.0 or later of the IoT SiteWise OPC UA collector component. If you use this feature with earlier versions, configuration updates fail. For more information, see [Update the version of an AWS IoT SiteWise component](manage-gateways-ggv2.md#update-component-version). `nodeFilterRuleDefinitions` (Optional) A list of node paths to include in the property group. Property groups can't overlap. If you don't specify a value for this field, the group contains all paths under the root, and you can't create additional property groups. The `nodeFilterRuleDefinitions` structure contains the following information: `type` `OpcUaRootPath` is the only supported type. This specifies that the value of `rootPath` is a path relative to the root of the OPC UA browsing space. `rootPath` A comma-delimited list that specifies the paths (relative to the root) to include in the property group. ### Additional capability configuration examples for Classic streams, V2 gateways (AWS CLI) The following example defines an OPC UA SiteWise Edge gateway capability configuration from a payload stored in a JSON file. ``` aws iotsitewise update-gateway-capability-configuration \ --capability-namespace "iotsitewise:opcuacollector:2" \ --capability-configuration file://opc-ua-configuration.json ``` **Example : OPC UA source configuration** The following `opc-ua-configuration.json` file defines a basic, insecure OPC UA source configuration. ``` { "sources": [ { "name": "Wind Farm #1", "endpoint": { "certificateTrust": { "type": "TrustAny" }, "endpointUri": "opc.tcp://203.0.113.0:49320", "securityPolicy": "NONE", "messageSecurityMode": "NONE", "identityProvider": { "type": "Anonymous" }, "nodeFilterRules": [] }, "measurementDataStreamPrefix": "" } ] } ``` **Example : OPC UA source configuration with defined property groups** The following `opc-ua-configuration.json` file defines a basic, insecure OPC UA source configuration with defined property groups. ``` { "sources": [ { "name": "source1", "endpoint": { "certificateTrust": { "type": "TrustAny" }, "endpointUri": "opc.tcp://10.0.0.9:49320", "securityPolicy": "NONE", "messageSecurityMode": "NONE", "identityProvider": { "type": "Anonymous" }, "nodeFilterRules": [ { "action": "INCLUDE", "definition": { "type": "OpcUaRootPath", "rootPath": "/Utilities/Tank" } } ] }, "measurementDataStreamPrefix": "propertyGroups", "propertyGroups": [ { "name": "Deadband_Abs_5", "nodeFilterRuleDefinitions": [ { "type": "OpcUaRootPath", "rootPath": "/Utilities/Tank/Temperature/TT-001" }, { "type": "OpcUaRootPath", "rootPath": "/Utilities/Tank/Temperature/TT-002" } ], "deadband": { "type":"ABSOLUTE", "value": 5.0, "timeoutMilliseconds": 120000 } }, { "name": "Polling_10s", "nodeFilterRuleDefinitions": [ { "type": "OpcUaRootPath", "rootPath": "/Utilities/Tank/Pressure/PT-001" } ], "scanMode": { "type": "POLL", "rate": 10000 } }, { "name": "Percent_Deadband_Timeout_90s", "nodeFilterRuleDefinitions": [ { "type": "OpcUaRootPath", "rootPath": "/Utilities/Tank/Flow/FT-*" } ], "deadband": { "type":"PERCENT", "value": 5.0, "eguMin": -100, "eguMax": 100, "timeoutMilliseconds": 90000 } } ] } ] } ``` **Example : OPC UA source configuration with properties** The following JSON example for `opc-ua-configuration.json` defines an OPC UA source configuration with the following properties: + Trusts any certificate. + Uses the `BASIC256` security policy to secure messages. + Uses the `SIGN_AND_ENCRYPT` mode to secure connections. + Uses authentication credentials stored in a Secrets Manager secret. + Filters out data streams except those whose path starts with `/WindFarm/2/WindTurbine/`. + Adds `/Washington` to the start of every data stream path to distinguish between this "Wind Farm \$12" and a "Wind Farm \$12" in another area. ``` { "sources": [ { "name": "Wind Farm #2", "endpoint": { "certificateTrust": { "type": "TrustAny" }, "endpointUri": "opc.tcp://203.0.113.1:49320", "securityPolicy": "BASIC256", "messageSecurityMode": "SIGN_AND_ENCRYPT", "identityProvider": { "type": "Username", "usernameSecretArn": "arn:aws:secretsmanager:region:123456789012:secret:greengrass-windfarm2-auth-1ABCDE" }, "nodeFilterRules": [ { "action": "INCLUDE", "definition": { "type": "OpcUaRootPath", "rootPath": "/WindFarm/2/WindTurbine/" } } ] }, "measurementDataStreamPrefix": "/Washington" } ] } ``` **Example : OPC UA source configuration with certificate trust** The following JSON example for `opc-ua-configuration.json` defines an OPC UA source configuration with the following properties: + Trusts a given X.509 certificate. + Uses the `BASIC256` security policy to secure messages. + Uses the `SIGN_AND_ENCRYPT` mode to secure connections. ``` { "sources": [ { "name": "Wind Farm #3", "endpoint": { "certificateTrust": { "type": "X509", "certificateBody": "-----BEGIN CERTIFICATE----- MIICiTCCAfICCQD6m7oRw0uXOjANBgkqhkiG9w 0BAQUFADCBiDELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAldBMRAwDgYDVQQHEwdTZ WF0dGxlMQ8wDQYDVQQKEwZBbWF6b24xFDASBgNVBAsTC0lBTSBDb25zb2xlMRIw EAYDVQQDEwlUZXN0Q2lsYWMxHzAdBgkqhkiG9w0BCQEWEG5vb25lQGFtYXpvbi5 jb20wHhcNMTEwNDI1MjA0NTIxWhcNMTIwNDI0MjA0NTIxWjCBiDELMAkGA1UEBh MCVVMxCzAJBgNVBAgTAldBMRAwDgYDVQQHEwdTZWF0dGxlMQ8wDQYDVQQKEwZBb WF6b24xFDASBgNVBAsTC0lBTSBDb25zb2xlMRIwEAYDVQQDEwlUZXN0Q2lsYWMx HzAdBgkqhkiG9w0BCQEWEG5vb25lQGFtYXpvbi5jb20wgZ8wDQYJKoZIhvcNAQE BBQADgY0AMIGJAoGBAMaK0dn+a4GmWIWJ21uUSfwfEvySWtC2XADZ4nB+BLYgVI k60CpiwsZ3G93vUEIO3IyNoH/f0wYK8m9TrDHudUZg3qX4waLG5M43q7Wgc/MbQ ITxOUSQv7c7ugFFDzQGBzZswY6786m86gpEIbb3OhjZnzcvQAaRHhdlQWIMm2nr AgMBAAEwDQYJKoZIhvcNAQEFBQADgYEAtCu4nUhVVxYUntneD9+h8Mg9q6q+auN KyExzyLwaxlAoo7TJHidbtS4J5iNmZgXL0FkbFFBjvSfpJIlJ00zbhNYS5f6Guo EDmFJl0ZxBHjJnyp378OD8uTs7fLvjx79LjSTbNYiytVbZPQUQ5Yaxu2jXnimvw 3rrszlaEXAMPLE= -----END CERTIFICATE-----", "certificateChain": "-----BEGIN CERTIFICATE----- MIICiTCCAfICCQD6m7oRw0uXOjANBgkqhkiG9w 0BAQUFADCBiDELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAldBMRAwDgYDVQQHEwdTZ WF0dGxlMQ8wDQYDVQQKEwZBbWF6b24xFDASBgNVBAsTC0lBTSBDb25zb2xlMRIw EAYDVQQDEwlUZXN0Q2lsYWMxHzAdBgkqhkiG9w0BCQEWEG5vb25lQGFtYXpvbi5 jb20wHhcNMTEwNDI1MjA0NTIxWhcNMTIwNDI0MjA0NTIxWjCBiDELMAkGA1UEBh MCVVMxCzAJBgNVBAgTAldBMRAwDgYDVQQHEwdTZWF0dGxlMQ8wDQYDVQQKEwZBb WF6b24xFDASBgNVBAsTC0lBTSBDb25zb2xlMRIwEAYDVQQDEwlUZXN0Q2lsYWMx HzAdBgkqhkiG9w0BCQEWEG5vb25lQGFtYXpvbi5jb20wgZ8wDQYJKoZIhvcNAQE BBQADgY0AMIGJAoGBAMaK0dn+a4GmWIWJ21uUSfwfEvySWtC2XADZ4nB+BLYgVI k60CpiwsZ3G93vUEIO3IyNoH/f0wYK8m9TrDHudUZg3qX4waLG5M43q7Wgc/MbQ ITxOUSQv7c7ugFFDzQGBzZswY6786m86gpEIbb3OhjZnzcvQAaRHhdlQWIMm2nr AgMBAAEwDQYJKoZIhvcNAQEFBQADgYEAtCu4nUhVVxYUntneD9+h8Mg9q6q+auN KyExzyLwaxlAoo7TJHidbtS4J5iNmZgXL0FkbFFBjvSfpJIlJ00zbhNYS5f6Guo EDmFJl0ZxBHjJnyp378OD8uTs7fLvjx79LjSTbNYiytVbZPQUQ5Yaxu2jXnimvw 3rrszlaEXAMPLE= -----END CERTIFICATE-----" }, "endpointUri": "opc.tcp://203.0.113.2:49320", "securityPolicy": "BASIC256", "messageSecurityMode": "SIGN_AND_ENCRYPT", "identityProvider": { "type": "Anonymous" }, "nodeFilterRules": [] }, "measurementDataStreamPrefix": "" } ] } ``` # Set up OPC UA servers to trust the AWS IoT SiteWise Edge gateway If you choose a `messageSecurityMode` other than **None** when configuring your OPC UA source, you must enable your source servers to trust the AWS IoT SiteWise Edge gateway. The SiteWise Edge gateway generates a certificate that your source server might require. The process varies depending on your source servers. For more information, see the documentation for your servers. The following procedure outlines the basic steps. **To enable an OPC UA server to trust the SiteWise Edge gateway** 1. Open the interface for configuring your OPC UA server. 1. Enter the user name and password for the OPC UA server administrator. 1. Locate **Trusted Clients** in the interface, and then choose **AWS IoT SiteWise Gateway Client**. 1. Choose **Trust**. ## Exporting the OPC UA client certificate Some OPC UA servers require access to the OPC UA client certificate file to trust the SiteWise Edge gateway. If this applies to your OPC UA servers, you can use the following procedure to export the OPC UA client certificate from the SiteWise Edge gateway. Then, you can import the certificate on your OPC UA server. **To export the OPC UA client certificate file for a source** 1. Run the following command to change to the directory that contains the certificate file. Replace *sitewise-work* with the local storage path for the *aws.iot.SiteWiseEdgeCollectorOpcua* Greengrass work folder and replace *source-name* with the name of the data source. By default, the Greengrass work folder is */greengrass/v2/work/aws.iot.SiteWiseEdgeCollectorOpcua* on Linux and *C:/greengrass/v2/work/aws.iot.SiteWiseEdgeCollectorOpcua* on Microsoft Windows. ``` cd /sitewise-work/source-name/opcua-certificate-store ``` 1. The SiteWise Edge gateway's OPC UA client certificate for this source is in the `aws-iot-opcua-client.pfx` file. Run the following command to export the certificate to a `.pem` file called `aws-iot-opcua-client-certificate.pem`. ``` keytool -exportcert -v -alias aws-iot-opcua-client -keystore aws-iot-opcua-client.pfx -storepass amazon -storetype PKCS12 -rfc > aws-iot-opcua-client-certificate.pem ``` 1. Transfer the certificate file, `aws-iot-opcua-client-certificate.pem`, from the SiteWise Edge gateway to the OPC UA server. To do so, you can use common software such as the `scp` program to transfer the file using the SSH protocol. For more information, see [Secure copy](https://en.wikipedia.org/wiki/Secure_copy) on *Wikipedia*. **Note** If your SiteWise Edge gateway is running on Amazon Elastic Compute Cloud (Amazon EC2) and you're connecting to it for the first time, you must configure prerequisites to connect. For more information, see [Connect to your Linux instance using SSH](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/connect-to-linux-instance.html) in the *Amazon EC2 User Guide*. 1. Import the certificate file, `aws-iot-opcua-client-certificate.pem`, on the OPC UA server to trust the SiteWise Edge gateway. Steps can vary depending on the source server that you use. Consult the documentation for the server. # Filter data ingestion ranges with OPC UA You can control the way you ingest data with an OPC UA source by using scan mode and deadband ranges. These features let you control what kind of data to ingest, and how and when your server and SiteWise Edge gateway exchange this information. ## Collect or filter out data based on quality You can configure your data quality settings to control what data is collected from the OPC UA source. The data source includes the quality rating as metadata when it sends it. You can select one or all of the following options: + `Good` + `Bad` + `Uncertain` ### Handle NaN or null values SiteWise Edge supports the collection and handling of NaN and null values. + *NaN (Not a Number):* Represents undefined or unrepresentable numerical results. + *Null:* Indicates missing data. The IoT SiteWise OPC UA collector captures NaN and Null values with BAD or UNCERTAIN quality. These special values are written to the local stream, enabling more comprehensive data collection. ## Control data collection frequency with Scan mode You can configure your OPC UA scan mode to control the way you collect data from your OPC UA source. You can choose subscription or polling mode. + Subscription mode – The OPC UA source collects data to send to your SiteWise Edge gateway at the frequency defined by your scan rate. The server only sends data when the value has changed, so this is the maximum frequency your SiteWise Edge gateway receives data. + Polling mode – Your SiteWise Edge gateway polls the OPC UA source at a set frequency defined by your scan rate. The server sends data regardless of whether the value has changed, so your SiteWise Edge gateway always receives data at this interval. **Note** The polling mode option overrides your deadband settings for this source. ## Filter OPC UA data ingestion with deadband ranges You can apply a deadband to your OPC UA source property groups to filter out and discard certain data instead of sending it to the AWS Cloud. A deadband specifies a window of expected fluctuations in the incoming data values from your OPC UA source. If the values fall within this window, your OPC UA server won't send it to the AWS Cloud. You can use deadband filtering to reduce the amount of data you're processing and sending to the AWS Cloud. To learn how to set up OPC UA sources for your SiteWise Edge gateway, see [OPC UA data sources for AWS IoT SiteWise Edge gateways](configure-sources-opcua.md). **Note** Your server deletes all data that falls inside the window specified by your deadband. You can't recover this discarded data. ### Types of deadbands You can specify two types of deadbands for your OPC UA server property group. These let you choose how much data is sent to the AWS Cloud, and how much is discarded. + Percentage – You specify a window using a percentage of expected fluctuation in the measurement value. The server calculates the exact window from this percentage, and sends data to the AWS Cloud that exceeds falls outside the window. For example, specifying a 2% deadband value on a sensor with a range from -100 degrees Fahrenheit to \$1100 degrees Fahrenheit tells the server to send data to the AWS Cloud when the value changes by 4 degrees Fahrenheit or more. **Note** You can optionally specify a minimum and maximum deadband value for this window if your source server doesn't define engineering units. If an engineering unit range is not provided, the OPC UA server defaults to the full range of the measurement data type. + Absolute – You specify a window using exact units. For example, specifying a deadband value of 2 on a sensor tells the server to send data to the AWS Cloud when its value changes by at least 2 units. You can use absolute deadbanding for dynamic environments where fluctuations are regularly expected during normal operations. ### Deadband timeouts You can optionally configure a deadband timeout setting. After this timeout, the OPC UA server sends the current measurement value even if it is within the expected deadband fluctuation. You can use the timeout setting to ensure that AWS IoT SiteWise is ingesting a steady stream of data at all times, even when values do not exceed the defined deadband window. # Use OPC UA node filters in SiteWise Edge When you define OPC UA data sources for an SiteWise Edge gateway, you can define node filters. Node filters let you limit which data stream paths the SiteWise Edge gateway sends to the cloud. You can use node filters to reduce your SiteWise Edge gateway's startup time and CPU usage by only including paths to data that you model in AWS IoT SiteWise. By default, SiteWise Edge gateways upload all OPC UA paths except those that start with `/Server/`. You can use the `*` and `**` wildcard characters in your node filters to include multiple data stream paths with one filter. To learn how to set up OPC UA sources for your SiteWise Edge gateway, see [OPC UA data sources for AWS IoT SiteWise Edge gateways](configure-sources-opcua.md). **Note** AWS IoT SiteWise restarts your SiteWise Edge gateway each time you add or edit a source. Your SiteWise Edge gateway won't ingest data while it's updating source configuration. The time to restart your SiteWise Edge gateway depends on the number of tags on your SiteWise Edge gateway's sources. Restart time can range from a few seconds (for a SiteWise Edge gateway with few tags) to several minutes (for a SiteWise Edge gateway with many tags). The following table lists the wildcards that you can use to filter OPC UA data sources. **OPC UA node filter wildcards** | Wildcard | Description | | --- | --- | | \$1 | Matches a single level in a data stream path. | | \$1\$1 | Matches multiple levels in a data stream path. | **Note** If you configure a source with a broad filter and then later change the source to use a more restrictive filter, AWS IoT SiteWise stops storing data that doesn't match the new filter. **Example : Scenario using node filters** Consider the following hypothetical data streams: + `/WA/Factory 1/Line 1/PLC1` + `/WA/Factory 1/Line 1/PLC2` + `/WA/Factory 1/Line 2/Counter1` + `/WA/Factory 1/Line 2/PLC1` + `/OR/Factory 1/Line 1/PLC1` + `/OR/Factory 1/Line 2/Counter2` Using the previous data streams, you can define node filters to limit what data to include from your OPC UA source. + To select all nodes in this example, use `/` or `/**/`. You can include multiple directories or folders with the `**` wildcard characters. + To select all `PLC` data streams, use `/*/*/*/PLC*` or `/**/PLC*`. + To select all counters in this example, use `/**/Counter*` or `/*/*/*/Counter*`. + To select all counters from `Line 2`, use `/**/Line 2/Counter*`. # Converting unsupported data types Optionally enable data type conversion in AWS IoT SiteWise for simple arrays and DateTime data types. AWS IoT SiteWise doesn't support all OPC UA data types. When you send unsupported data to your AWS IoT Greengrass data stream, that data is lost. However, by converting the unsupported native data types to strings, you can ingest the data into AWS IoT SiteWise rather than discarding it. AWS IoT SiteWise serializes your converted data so that you can later use your own functions to convert the strings back to their original data type downstream, if needed. You can update your data type conversion settings for a data source at any time and each data source can have its own settings. When you add data sources in the AWS IoT SiteWise console, there are two checkboxes under **Data type conversion** in **Advanced Configuration**. You can indicate which data types to convert to strings. Additionally, the IoT SiteWise OPC UA collector can accept NaN or null values on the edge. + Convert array values with simple data types to JSON strings + Convert DateTime values to ISO 8601 strings ## Prerequisite + Use version 2.5.0 or later of the [IoT SiteWise OPC UA collector](https://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-opcua-collector-component.html). ## Limitations These are the limitations for OPC UA data type conversion to strings in AWS IoT SiteWise. + Complex data type conversion is not supported. + String limits after conversion are 1024 bytes. If the string is longer than 1024 bytes, the string is rejected by AWS IoT SiteWise. # Configure data source authentication for SiteWise Edge If your OPC UA server requires authentication credentials to connect, you can use AWS Secrets Manager to create and deploy a secret to your SiteWise Edge gateway. AWS Secrets Manager encrypts secrets on the device to keep your user name and password secure until you need to use them. For more information about the AWS IoT Greengrass secret manager component, see [Secret manager](https://docs.aws.amazon.com/greengrass/v2/developerguide/secret-manager-component.html) in the *AWS IoT Greengrass Version 2 Developer Guide*. For information about managing access to Secrets Manager secrets, see: + [ Who has permissions to your AWS Secrets Manager secrets](https://docs.aws.amazon.com/secretsmanager/latest/userguide/determine-acccess_examine-iam-policies.html). + [ Determining if a request is allowed or denied within an account](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_evaluation-logic.html#policy-eval-denyallow). ## Step 1: Create source authentication secrets You can use AWS Secrets Manager to create an authentication secret for your data source. In the secret, define **username** and **password** key-value pairs that contain authentication details for your data source. **To create a secret (console)** 1. Navigate to the [AWS Secrets Manager console](https://console.aws.amazon.com/secretsmanager/). 1. Choose **Store a new secret**. 1. Under **Secret type**, choose **Other type of secrets**. 1. Under **Key/value pairs**, do the following: 1. In the first input box, enter **username** and in the second input box enter the username. 1. Choose **Add row**. 1. In the first input box, enter **password** and in the second input box enter the password. 1. For **Encryption key**, select **aws/secretsmanager**, and then choose **Next**. 1. On the **Store a new secret** page, enter a **Secret name**. 1. (Optional) Enter a **Description** that helps you identify this secret, and then choose **Next**. 1. (Optional) On the **Store a new secret** page, turn on **Automatic rotation**. For more information, see [Rotate secrets](https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets.html) in the *AWS Secrets Manager User Guide*. 1. Specify a rotation schedule. 1. Choose a Lambda function that can rotate this secret, and then choose **Next**. 1. Review your secret configurations, and then choose **Store**. To authorize your SiteWise Edge gateway to interact with AWS Secrets Manager, the IAM role for your SiteWise Edge gateway must allow the `secretsmanager:GetSecretValue` action. You can use the **Greengrass core device** to search for the IAM policy. For more information about updating an IAM policy, see [Editing IAM policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-edit.html) in the *AWS Identity and Access Management User Guide*. **Example policy** Replace *secret-arn* with the Amazon Resource Name (ARN) of the secret that you created in the previous step. For more information about how to get the ARN of a secret, see [Find secrets in AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_search-secret.html) in the *AWS Secrets Manager User Guide*. **** ``` { "Version":"2012-10-17", "Statement":[ { "Action":[ "secretsmanager:GetSecretValue" ], "Effect":"Allow", "Resource":[ "arn:aws:secretsmanager:us-east-1:123456789012:secret/*" ] } ] } ``` ## Step 2: Deploy secrets to your SiteWise Edge gateway device You can use the AWS IoT SiteWise console to deploy secrets to your SiteWise Edge gateway. **To deploy a secret (console)** 1. Navigate to the [AWS IoT SiteWise console](https://console.aws.amazon.com/iotsitewise/). 1. In the navigation pane, choose **Gateways**. 1. From the **Gateways** list, choose the target SiteWise Edge gateway. 1. In the **Gateway configuration** section, choose the **Greengrass core device** link to open the AWS IoT Greengrass core associated with the SiteWise Edge gateway. 1. In the navigation pane, choose **Deployments**. 1. Choose the target deployment, and then choose **Revise**. 1. On the **Specify target** page, choose **Next**. 1. On the **Select components** page, in the **Public components** section, turn off **Show only selected components**. 1. Search for and choose the **aws.greengrass.SecretManager** component, and then choose **Next**. 1. From the **Selected components** list, choose the **aws.greengrass.SecretManager** component, and then choose **Configure component**. 1. In the **Configuration to merge** field, add the following JSON object. **Note** Replace *secret-arn* with the ARN of the secret that you created in the previous step. For more information about how to get the ARN of a secret, see [Find secrets in AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_search-secret.html) in the *AWS Secrets Manager User Guide*. ``` { "cloudSecrets":[ { "arn":"secret-arn" } ] } ``` 1. Choose **Confirm**. 1. Choose **Next**. 1. On the **Configure advanced settings** page, choose **Next**. 1. Review your deployment configurations, and then choose **Deploy**. ## Step 3: Add authentication configurations You can use the AWS IoT SiteWise console to add authentication configurations to your SiteWise Edge gateway. **To add authentication configurations (console)** 1. Navigate to the [AWS IoT SiteWise console](https://console.aws.amazon.com/iotsitewise/). 1. From the **Gateways** list, choose the target SiteWise Edge gateway. 1. From the **Data sources** list, choose the target data source, and then choose **Edit**. 1. On the **Add a data source** page, choose **Advanced configuration**. 1. For **Authentication configuration**, choose the secret that you deployed in the previous step. 1. Choose **Save**. # Partner data sources on SiteWise Edge gateways When using an AWS IoT SiteWise Edge gateway you can connect a partner data source to your SiteWise Edge gateway and receive data from the partner in your SiteWise Edge gateway and the AWS cloud. These partner data sources are AWS IoT Greengrass components that are developed in partnership between AWS and the partner. When you add a partner data source, AWS IoT SiteWise will create this component and deploy it on your SiteWise Edge gateway. **Note** You can add one data source for each partner in each gateway. To add a partner data source, do the following: 1. [Add a partner data source in SiteWise Edge](cpa-add-source.md) 1. Go to the partner’s web portal, where applicable, and configure the partner data source so it connects to the SiteWise Edge gateway. **Topics** + [Security](#cpa-security) + [Set up Docker on your SiteWise Edge gateway](cpa-install-docker.md) + [Add a partner data source in SiteWise Edge](cpa-add-source.md) + [SiteWise Edge gateway partner data source options](connect-partner-data-source.md) ## Security As part of the [Shared Responsibility Model](https://aws.amazon.com/compliance/shared-responsibility-model/) between AWS, our customers, and our partners the following describes who is responsible for the different aspects of security: **Customer responsibility** + Vetting the partner. + Configuring the network access given to the partner. + Monitoring for reasonable usage of the SiteWise Edge gateway machine resources (CPU, memory, and file system). **AWS responsibility** + Isolating the partner from the customer AWS cloud resources except those needed by the partner. In this case, AWS IoT SiteWise ingestion. + Restricting the partner solution to a reasonable usage of the SiteWise Edge gateway machine resources (CPU and memory). **Partner responsibility** + Using secure defaults. + Keeping the solution secure over time through patches and other appropriate updates. + Keeping customer data confidential. # Set up Docker on your SiteWise Edge gateway AWS IoT SiteWise provides a Docker image that allows you to run the SiteWise Edge application on various platforms and environments. This Docker image encapsulates all the necessary components and dependencies required to collect, process, and send data from your industrial equipment to the AWS Cloud. By using the Docker image, you can deploy and run the SiteWise Edge application on Docker-compatible hosts, such as servers, edge devices, or cloud-based container services. To add a partner data source, [Docker Engine](https://docs.docker.com/engine/) 1.9.1 or later must be installed on your local device. **Note** Version 20.10 is the latest version that is verified to work with the SiteWise Edge gateway software. ## Verify Docker is installed To verify Docker is installed, run the following command from a terminal connected to your SiteWise Edge gateway: ``` docker info ``` If the command returns a `docker is not recognized` result, or an older version of Docker is installed, [Install Docker Engine](https://docs.docker.com/engine/install/) before continuing. ## Set up Docker The system user that runs a Docker container component must have root or administrator permissions, or you must configure Docker to run it as a non-root or non-admistrator user. On Linux devices, you must add a `ggc_user` user to the `docker` group to call Docker commands without `sudo`. To add `ggc_user`, or the non-root user that you use to run Docker container components, to the `docker` group, run the following command: ``` sudo usermod -aG docker ggc_user ``` For more information, see [Linux post-installation steps for DockerEngine](https://docs.docker.com/engine/install/linux-postinstall/). # Add a partner data source in SiteWise Edge To connect a partner data source to your SiteWise Edge gateway, add it as a data source. When you add it as a data source, AWS IoT SiteWise will deploy a private AWS IoT Greengrass component to your SiteWise Edge gateway. ## Prerequisites To add a partner data source, you must do the following: + For EasyEdge and CloudRail, create an account with the partner, then bind the accounts. + [Set up Docker on your SiteWise Edge gateway](cpa-install-docker.md) ## Create a SiteWise Edge gateway with a partner data source If you want to create a new SiteWise Edge gateway, complete the steps in [Create a self-hosted SiteWise Edge gateway](create-gateway-ggv2.md). After you’ve created SiteWise Edge gateway follow the steps in [Add a partner data source to an existing SiteWise Edge gateway](#cpa-existing-gateway) to add a partner data source. ## Add a partner data source to an existing SiteWise Edge gateway 1. Navigate to the [AWS IoT SiteWise console](https://console.aws.amazon.com/iotsitewise/). 1. In the left navigation, choose **Edge gateways** in the **Edge** section. 1. Choose the SiteWise Edge gateway you want to connect the partner data source to. 1. Under **Data sources**, choose **Add data source**. 1. On the **Add data source** screen, choose a **Source type**, to select the partner that connects your SiteWise Edge gateway. Each data source has its own configuration options. There are two categories of data sources: AWS sources and Partner sources. Using a partner data source, you can select one source per gateway. For a list of data source partner integration options, see [SiteWise Edge gateway partner data source options](connect-partner-data-source.md). Note that you can add up to 100 OPC UA data sources (AWS sources). To get started with OPC UA data sources, see [OPC UA data sources for AWS IoT SiteWise Edge gateways](configure-sources-opcua.md). 1. Enter a name for the source. 1. Select your data source's tab below and follow the configuration procedure. ------ #### [ CloudRail ] Much of the CloudRail configuration is done in the CloudRail portal after saving the data source for your SiteWise Edge gateway. However, authorizing the connection is required. **Note** The CloudRail connection is only available on Linux. 1. [Create a CloudRail account](https://devices.cloudrail.com/signup) to get started with connecting to AWS IoT SiteWise. 1. Ensure that Docker is installed on your gateway. For more information, see [Set up Docker on your SiteWise Edge gateway](cpa-install-docker.md). 1. Read the **Authorize access and deployment** agreement, then choose **Authorize**. Checking the box grants the AWS partner access to your data source and allows AWS to deploy on the partner's component. **Note** The **Measurement Prefix – *optional*** is set within your CloudRail portal. **Note** Partner software is developed, maintained, and supported by the AWS partner. AWS is not responsible for the interface, configuration, or software. For more information, see [CloudRail](connect-partner-data-source.md#cp-cloudrail). ------ #### [ EasyEdge ] Much of the EasyEdge configuration is done in the EasyEdge portal after saving the data source for your SiteWise Edge gateway. However, authorizing the connection is required. **Note** The EasyEdge connection is only available on Linux. 1. [Create an EasyEdge account](https://accounts.easyedge.io/signup?partner=aws) to get started with connecting to AWS IoT SiteWise. 1. Ensure that Docker is installed on your gateway. For more information, see [Set up Docker on your SiteWise Edge gateway](cpa-install-docker.md). 1. Read the **Authorize access and deployment** agreement, then choose **Authorize**. Checking the box grants the AWS partner access to your data source and allows AWS to deploy on the partner's component. **Note** The **Measurement Prefix – *optional*** is set within your EasyEdge portal. **Note** Partner software is developed, maintained, and supported by the AWS partner. AWS is not responsible for the interface, configuration, or software. For more information, see [EasyEdge](connect-partner-data-source.md#cp-easyedge). ------ #### [ Litmus Edge ] You can activate the Litmus configuration in two ways. Activate Litmus Edge directly through AWS IoT SiteWise using information from the Litmus Edge Manager portal. Or, you can manually activate Litmus Edge for AWS IoT SiteWise through Litmus Edge Manager. **Note** The Litmus Edge connection is only available on Linux.   **To activate using a Litmus Edge activation code on AWS IoT SiteWise** Use this procedure when adding a Litmus Edge data source with a Litmus Edge activation code on the AWS IoT SiteWise console. 1. Select **Activate now using a code**. Additional configuration options appear. 1. Enter the Litmus Edge Manager to connect Litmus Edge to your SiteWise Edge gateway. For more information, see [Step 3a: Set Data and Device Management Endpoint](https://docs.litmus.io/edgemanager/quickstart-guide/activate-an-edge-device/step-3-activation-request) in the Litmus Edge Manager documentation. 1. Provide the Litmus Edge Manager activation code to activate Litmus Edge on AWS IoT SiteWise 1. Optionally, provide AWS IoT SiteWise with the **Litmus Edge Manager CA certificate**. The certificate prevents Litmus Edge from activating on an unauthorized Litmus Edge Manager. 1. Ensure that Docker is installed on your gateway. For more information, see [Set up Docker on your SiteWise Edge gateway](cpa-install-docker.md). **Note** AWS IoT SiteWise deploys the partner application as a Docker container. The application is deployed with `NET_ADMIN` capability so that the Litmus Edge Docker container can be managed through Litmus Edge Manager. Litmus Edge requires this privileged access to run on your devices. For more information about the Litmus Edge Docker requirements, see [Docker Installation](https://docs.litmus.io/litmusedge-v1/quickstart-guide/installation-and-deployments/docker-installation) in the *QuickStart Guide* in the Litmus Edge documentation. 1. Read the **Authorize access and deployment** agreement, then choose **Authorize**. Checking the box grants the AWS partner access to your data source and allows AWS to deploy on the partner's component.   **To activate manually through Litmus Edge** 1. Select **Activate later on Litmus Edge**. 1. Ensure that Docker is installed on your gateway. For more information, see [Set up Docker on your SiteWise Edge gateway](cpa-install-docker.md). **Note** AWS IoT SiteWise deploys the partner application as a Docker container. The application is deployed with `NET_ADMIN` capability so that the Litmus Edge Docker container can be managed through Litmus Edge Manager. Litmus Edge requires this privileged access to run on your devices. For more information about the Litmus Edge Docker requirements, see [Docker Installation](https://docs.litmus.io/litmusedge-v1/quickstart-guide/installation-and-deployments/docker-installation) in the *QuickStart Guide* in the Litmus Edge documentation. 1. Read the **Authorize access and deployment** agreement, then choose **Authorize**. Checking the box grants the AWS partner access to your data source and allows AWS to deploy on the partner's component. 1. After the deployment is complete, follow the [Access the Litmus Edge Web UI](https://docs.litmus.io/litmusedge/quickstart-guide/access-the-litmus-edge-web-ui) instructions in the Litmus Edge *QuickStart Guide* documentation. **Note** Partner software is developed, maintained, and supported by the AWS partner. AWS is not responsible for the interface, configuration, or software. For more information, see [Litmus Edge](connect-partner-data-source.md#cp-litmus). ------ 1. Choose **Save**. # SiteWise Edge gateway partner data source options AWS IoT SiteWise allows you to connect and ingest data from various partner data sources, such as industrial equipment, sensors, and other third-party systems. To connect a partner data source, you need to follow a few steps, including configuring the data source to send data to AWS IoT SiteWise, setting up the necessary permissions and authentication, and mapping the data to your asset models. This process ensures that your partner data is seamlessly integrated into your AWS IoT SiteWise environment, enabling you to monitor and analyze it alongside your other data sources. This section lists the available partners for third-party data source integration on SiteWise Edge gateways. Use the information below to configure a partner data source. **Note** You can add one data source for each partner in each gateway ## CloudRail **Portal:** [https://devices.cloudrail.com/](https://devices.cloudrail.com/) **Requirements** For more information on CloudRail requirements, see [FAQS](https://cloudrail.com/faqs/) on the CloudRail website. **CloudRail documentation:** [Edge Computing: SiteWise Edge](https://devices.cloudrail.com/documentation?service=AWSIoTSitewiseEdge#awsiotsitewiseEdge1) ## EasyEdge **Portal:** [https://studio.easyedge.io/](https://studio.easyedge.io/) **Requirements** [EasyEdge requirements](https://docs.easyedge.io/getting-started/requirements.html) – Information about EasyEdge requirements, including endpoints and ports required for configuring the firewall. **Note**: You'll need an EasyEdge account to access this documentation. **EasyEdge documentation:** [EasyEdge for AWS](https://www.easyedge.io/easyedge-for-aws/) ## Litmus Edge **Access to Litmus Edge Manager:** To access Litmus Edge, set up a [Litmus Edge Manager account](https://docs.litmus.io/edgemanager/quickstart-guide/access-to-litmus-edge-manager). **Requirements** [Litmus Edge Requirements ](https://docs.litmus.io/litmusedge/quickstart-guide/system-requirements) – Recommended configurations and system requirements to deploy Litmus Edge. **Litmus documentation:** + [Integration to AWS IoT SiteWise](https://docs.litmus.io/litmusedge-v1/litmusedge-with-aws-iot-sitewise) + [Litmus Edge Documentation](https://docs.litmus.io/litmusedge/)