# Use AWS IoT SiteWise Edge gateways
Use SiteWise Edge gateways
AWS IoT SiteWise Edge extends cloud capabilities to industrial edge environments, enabling local data processing, analysis, and decision-making. SiteWise Edge integrates with AWS IoT SiteWise and other AWS services to provide comprehensive industrial IoT solutions. Gateways serve as the intermediary between your industrial equipment and AWS IoT SiteWise.
SiteWise Edge gateways runs on two different deployment targets:
+ AWS IoT Greengrass V2
+ Siemens Industrial Edge
You can use a SiteWise Edge gateway to collect data at the edge and publish it to the cloud. For gateways running on AWS IoT Greengrass, you can also process data at the edge using asset models and assets.
The AWS IoT SiteWise Edge application on Siemens Industrial Edge supports integration between industrial equipment and AWS IoT SiteWise so that you can aggregate and process raw machine data and run analyses locally before sending refined data to the AWS Cloud.
## Key concepts of SiteWise Edge gateways
Gateway key concepts
SiteWise Edge has several useful features for edge computing in industrial environments.
**Local data collection and processing**
Supports data collection from industrial assets using protocols like OPC-UA and MQTT. Gateways run on AWS IoT Greengrass Core devices or Siemens Industrial Edge.
**Offline operation**
Continues collecting and processing data during internet outages, syncing with the cloud when connectivity is restored.
**Edge computing with AWS IoT Greengrass components**
Uses IoT SiteWise publisher to forward data to the cloud and AWS IoT SiteWise processor for local transformations and calculations. Both the publisher and processor are AWS IoT Greengrass V2 components. For more information on AWS IoT Greengrass components, see [AWS-provided components](https://docs.aws.amazon.com/greengrass/v2/developerguide/public-components.html).
**Integration with AWS IoT SiteWise to extend cloud features**
Works with the AWS IoT SiteWise cloud features, extending asset models, analytics, and dashboards to the edge.
For gateways with a data processing pack enabled, you can use AWS OpsHub for AWS IoT SiteWise to centrally manage your SiteWise Edge gateways. AWS OpsHub provides remote management and monitoring capabilities. For more information, see [Manage SiteWise Edge gateways using AWS OpsHub for AWS IoT SiteWise](manage-gateways-ggv2.md#opshub-app).
**Partner data source integration**
Connect a partner data source to your gateway and receive data from the partner in your SiteWise Edge gateway and the AWS cloud. For more information, see [Partner data sources on SiteWise Edge gateways](partner-data-sources.md).
**Local visualization on the edge**
Provides custom dashboards for real-time insights at the edge.
Monitor data locally in your facility using SiteWise Monitor portals on your local devices. For more information, see [Enabling your AWS IoT SiteWise portal at the edge](monitor-enable-edge.md).
## Benefits of implementing SiteWise Edge
SiteWise Edge offers numerous advantages that can significantly improve industrial operations and decision-making processes.
+ Real-time operational insights without cloud processing delays
+ Operational continuity in disconnected environments
+ Reduced bandwidth and storage costs through edge pre-processing
+ Increased reliability with the ability to make local, data-driven decisions
# Self-host an AWS IoT SiteWise Edge gateway with AWS IoT Greengrass V2
Self-host a gateway
Set up AWS IoT SiteWise Edge to collect, process, and visualize data from industrial equipment locally before sending it to the cloud. Self-host using AWS IoT Greengrass Version 2.
An AWS IoT SiteWise Edge gateway acts as the intermediary between your industrial equipment and AWS IoT SiteWise. Running on AWS IoT Greengrass Version 2, the SiteWise Edge gateway supports data collection and processing on premises.
There are two types of self-hosted gateways:
**MQTT-enabled, V3 gateway**
The MQTT-enabled, V3 gateway architecture provides improved data ingestion capabilities. It utilizes MQTT protocol for efficient data communication and offers configurable data destinations. These include options for buffered data ingestion using Amazon S3, as well as real-time data ingestion. You can implement path filters to subscribe to specific MQTT topics, enabling targeted data collection. Note that the MQTT-enabled, V3 gateway does not support the Data Processing Pack feature. For more information, see [MQTT-enabled, V3 gateways for AWS IoT SiteWise Edge](mqtt-enabled-v3-gateway.md).
**Classic streams, V2 gateway**
The Classic streams, V2 gateway represents the traditional AWS IoT SiteWise Edge gateway architecture. It is well-suited for existing SiteWise Edge deployments and users accustomed to the established workflow. While the Classic streams, V2 gateway supports the data processing pack, note that data generated by the data processing pack cannot be ingested through Amazon S3. Use the Classic streams, V2 gateway if you need to maintain compatibility with existing deployments or if you require the data processing pack functionality. For more information, see [Classic streams, V2 gateways for AWS IoT SiteWise Edge](classic-streams-v2-gateway.md).
**Topics**
+ [
# AWS IoT SiteWise Edge self-hosted gateway requirements
](configure-gateway-ggv2.md)
+ [
# Create a self-hosted SiteWise Edge gateway
](create-gateway-ggv2.md)
+ [
# Install the AWS IoT SiteWise Edge gateway software on your local device
](install-gateway-software-on-local-device.md)
+ [
# MQTT-enabled, V3 gateways for AWS IoT SiteWise Edge
](mqtt-enabled-v3-gateway.md)
+ [
# Classic streams, V2 gateways for AWS IoT SiteWise Edge
](classic-streams-v2-gateway.md)
+ [
# Add data sources to your AWS IoT SiteWise Edge gateway
](add-data-sources.md)
+ [
# AWS IoT Greengrass components for AWS IoT SiteWise Edge
](sw-edge-components.md)
+ [
# Filter assets on a SiteWise Edge gateway
](filter-assets-ggv2.md)
+ [
# Configure proxy support and manage trust stores for AWS IoT SiteWise Edge
](edge-apis-manage-trust-stores-proxy.md)
+ [
# Use AWS IoT SiteWise APIs on the edge
](edge-apis.md)
# AWS IoT SiteWise Edge self-hosted gateway requirements
Requirements
AWS IoT SiteWise Edge gateways run on AWS IoT Greengrass V2 as a set of AWS IoT Greengrass components that support data collection, processing, and publishing on premises. To configure a SiteWise Edge gateway that runs on AWS IoT Greengrass V2, create a gateway in the AWS Cloud and run the SiteWise Edge gateway software to set up your local device. When you use the AWS Management Console to create the SiteWise Edge gateway, an installation script is provided. Run this script on your target gateway device to set up necessary software and dependencies.
## Local device requirements
Local devices must meet the following requirements to install and run the SiteWise Edge gateway software.
+ Supports AWS IoT Greengrass V2 Core software version [v2.3.0](https://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-release-2021-06-29.html) or newer. For more information, see [Requirements](https://docs.aws.amazon.com/greengrass/v2/developerguide/setting-up.html#greengrass-v2-requirements) in the *AWS IoT Greengrass Version 2 Developer Guide*.
+ One of the following supported platforms:
+ OS: Ubuntu 20.04 or later
Architecture: x86\$164 (AMD64) or ARMv8 (Aarch64)
+ OS: Red Hat Enterprise Linux (RHEL) 8
Architecture: x86\$164 (AMD64) or ARMv8 (Aarch64)
+ OS: Amazon Linux 2
Architecture: x86\$164 (AMD64) or ARMv8 (Aarch64)
+ OS: Debian 11
Architecture: x86\$164 (AMD64) or ARMv8 (Aarch64)
+ OS: Windows Server 2019 and later
Architecture: x86\$164 (AMD64)
**Note**
ARM platforms support SiteWise Edge gateways with Data Collection Pack only. The data processing pack is not supported.
+ Minimum 4 GB RAM.
+ Minimum 10 GB disk space available for the SiteWise Edge gateway software.
+ Configure your local device to make sure that the proper ports are accessible. For a full list of the required outbound service endpoints, see [Required service endpoints for AWS IoT SiteWise Edge gateways](https://docs.aws.amazon.com/prescriptive-guidance/latest/endpoints-for-iot-sitewise-edge-gateways/required-endpoints.html).
+ Java Runtime Environment (JRE) version 11 or higher. Java must be available on the `PATH` environment variable on the device. To use Java to develop custom components, you must install a Java Development Kit (JDK). We recommend that you use [Amazon Corretto](https://docs.aws.amazon.com/corretto/) or [OpenJDK](https://openjdk.org/projects/jdk/).
### Amazon S3 buckets to allowlist for local devices
Configure your local device to provide firewall access the following Amazon S3 bucket. Configure access based on the respective regions for your devices.
| Region | Endpoint |
| --- | --- |
| Asia Pacific (Tokyo) | https://iot-sitewise-gateway-ap-northeast-1-785558802005.s3.ap-northeast-1.amazonaws.com |
| Asia Pacific (Seoul) | https://iot-sitewise-gateway-ap-northeast-2-310055672453.s3.ap-northeast-2.amazonaws.com |
| Asia Pacific (Mumbai) | https://iot-sitewise-gateway-ap-south-1-677656657204.s3.ap-south-1.amazonaws.com |
| Asia Pacific (Singapore) | https://iot-sitewise-gateway-ap-southeast-1-475191558554.s3.ap-southeast-1.amazonaws.com |
| Asia Pacific (Sydney) | https://iot-sitewise-gateway-ap-southeast-2-396319432685.s3.ap-southeast-2.amazonaws.com |
| Canada (Central) | https://iot-sitewise-gateway-ca-central-1-842060018567.s3.ca-central-1.amazonaws.com |
| China (Beijing) | https://iot-sitewise-gateway-cn-north-1-237124890262---s3---cn-north-1.amazonaws.com.rproxy.govskope.ca.cn |
| Europe (Frankfurt) | https://iot-sitewise-gateway-eu-central-1-748875242063.s3.eu-central-1.amazonaws.com |
| Europe (Ireland) | https://iot-sitewise-gateway-eu-west-1-383414315062.s3.eu-west-1.amazonaws.com |
| US East (N. Virginia) | https://iot-sitewise-gateway-us-east-1-223558168232.s3.us-east-1.amazonaws.com and https://iot-sitewise-gateway-us-east-1-223558168232.s3.amazonaws.com/ |
| US East (Ohio) | https://iot-sitewise-gateway-us-east-2-005072661813.s3.us-east-2.amazonaws.com |
| AWS GovCloud (US-West) | https://iot-sitewise-gateway-us-gov-west-1-599984565679.s3.us-gov-west-1.amazonaws.com/ |
| US West (Oregon) | https://iot-sitewise-gateway-us-west-2-502577205460.s3.us-west-2.amazonaws.com |
## Data processing pack requirements
**Note**
The data processing pack (DPP) feature is no longer availabke to new customers. Existing customers can continue to use the service as normal. For more information, see [Data processing pack availability change](https://docs.aws.amazon.com/iot-sitewise/latest/appguide/iotsitewise-dpp-availability-change.html).
+ If you plan to use the data processing pack at the edge with AWS IoT SiteWise, your local device must also meet the following requirements:
+ Has an x86 64 bit quad-core processor.
+ Has at least 16 GB of RAM.
+ Has at least 32 GB for RAM if using Microsoft Windows.
+ Had at least 256 GB of free disk space.
+ The local device must allow network inbound traffic on port 443.
+ The following ports are reserved for use by AWS IoT SiteWise: 80, 443, 3001, 4569, 4572, 8000, 8081, 8082, 8084, 8085, 8445, 8086, 9000, 9500, 11080, and 50010. Using a reserved port for traffic can result in a terminated connection.
**Note**
The AWS IoT Greengrass V2 Stream manager component has its own requirements. For more information, see [Configuration](https://docs.aws.amazon.com/greengrass/v2/developerguide/stream-manager-component.html#stream-manager-component-configuration) in the *AWS IoT Greengrass Version 2 Developer Guide*.
+ The minimum disk space and compute capacity requirements depend on a variety of factors that are unique to your implementation and use case.
+ The disk space required for caching data for intermittent internet connectivity depends on the following factors:
+ Number of data streams uploaded
+ Data points per data stream per second
+ Size of each data point
+ Communication speeds
+ Expected network downtime
+ The compute capacity required to poll and upload data depends on the following factors:
+ Number of data streams uploaded
+ Data points per data stream per second
## Configure permissions to use SiteWise Edge gateways
You must have the following permissions to use SiteWise Edge gateways:
**Note**
If you use the AWS IoT SiteWise console to create your SiteWise Edge gateway, these permissions are added for you.
+ The IAM role for your SiteWise Edge gateway must allow you to use an SiteWise Edge gateway on an AWS IoT Greengrass V2 device to process asset model data and asset data.
The role allows the following service to assume the role: `credentials.iot.amazonaws.com`.
**Permissions details**
The role must have the following permissions:
+ `iotsitewise` – Allows principals to retrieve asset model data and asset data at the edge.
+ `iot` – Allows your AWS IoT Greengrass V2 devices to interact with AWS IoT.
+ `logs` – Allows your AWS IoT Greengrass V2 devices to send logs to Amazon CloudWatch Logs.
+ `s3` – Allows your AWS IoT Greengrass V2 devices to download custom component artifacts from Amazon S3.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iotsitewise:BatchPutAssetPropertyValue",
"iotsitewise:List*",
"iotsitewise:Describe*",
"iotsitewise:Get*"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"iot:DescribeCertificate",
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:PutLogEvents",
"logs:DescribeLogStreams",
"s3:GetBucketLocation",
"s3:GetObject",
"iot:Connect",
"iot:Publish",
"iot:Subscribe",
"iot:Receive",
"iot:DescribeEndpoint"
],
"Resource": "*"
}
]
}
```
------
# Create a self-hosted SiteWise Edge gateway
Create a gateway
Use the AWS IoT SiteWise console or AWS CLI to create a self-hosted SiteWise Edge gateway. This procedure details how to create a self-hosted SiteWise Edge gateway that you'll install on your own hardware. For information about creating a SiteWise Edge gateway that runs on Siemens Industrial Edge, see [Host a SiteWise Edge gateway on Siemens Industrial Edge](sitewise-edge-on-siemens.md).
## Create a SiteWise Edge gateway
------
#### [ Console ]
1. Navigate to the [AWS IoT SiteWise console](https://console.aws.amazon.com/iotsitewise/).
1. In the navigation pane, choose **Edge gateways**.
1. Choose **Create gateway**.
1. For **Choose deployment target**, choose **self-hosted gateway**.
1. Select either **MQTT-enabled, V3 gateway** or **Classic streams, V2 gateway**. For more information on each option, see [Self-host an AWS IoT SiteWise Edge gateway with AWS IoT Greengrass V2](gw-self-host-gg2.md). The MQTT-enabled, V3 gateway is recommend for it's future-ready features.
1. In the **Gateway configuration** section, enter a name for your SiteWise Edge gateway or use the name generated by AWS IoT SiteWise.
1. Under **Greengrass device OS**, select the operating system of the device where you'll install this SiteWise Edge gateway.
**Note**
The data processing pack is only available on x86 platforms. It is only available on the Classic streams, V2 gateway
1. (Optional) To process and organize data at the edge, under **Edge capabilities**, select **Data Processing Pack**.
**Note**
To grant user groups in your corporate directory access to this SiteWise Edge gateway, see [Set up edge capability in SiteWise Edge](edge-data-collection-and-processing.md#using-sitewise-edge)
1. (Optional) Under **advanced configuration**, do the following:
1. For **Greengrass core device**, choose one of the following options:
+ **Default setup** – AWS automatically uses default settings to create a Greengrass core device in AWS IoT Greengrass V2.
1. Enter a name for the Greengrass core device or use the name generated by AWS IoT SiteWise.
+ **Advanced setup** – Choose this option if you want to use an existing Greengrass core device or to create one manually.
1. Choose a Greengrass core device or choose **Create Greengrass core device** to create one in the AWS IoT Greengrass V2 console. For more information, see [Setting up AWS IoT Greengrass V2 core devices](https://docs.aws.amazon.com/greengrass/v2/developerguide/setting-up.html) in the *AWS IoT Greengrass Version 2 Developer Guide*.
1. Choose **Create gateway**.
1. In the **Generate SiteWise Edge gateway installer** dialog box, choose **Generate and download**. AWS IoT SiteWise automatically generates an installer that you can use to configure your local device.
**Important**
You can't regenerate this file. Make sure that you save the installer file in a secure location because you'll use the file later.
------
#### [ AWS CLI ]
To create a self-hosted gateway by using the AWS CLI, provide a name for the gateway, specify the platform, and the gateway version. There are many other options that you can specify when creating a gateway. For more information, see [create-gateway](https://docs.aws.amazon.com/cli/latest/reference/iotsitewise/create-gateway.html) in the *AWS CLI Command Reference* for AWS IoT SiteWise
To use this example, replace the user input placeholders with your own information.
```
aws iotsitewise create-gateway \
--gateway-name your-gateway-name \
--gateway-platform greengrassV2={coreDeviceThingName=your-core-device-thing-name, coreDeviceOperatingSystem=LINUX_AMD64} \
--gateway-version 3 \
[--cli-input-json your-configuration]
```
+ `gateway-name` – A unique name for the gateway.
+ `gateway-platform` – Specifies the gateway platform configuration. For self-hosted gateways, enter `greengrassV2`. For more information, see [Options](https://docs.aws.amazon.com/cli/latest/reference/iotsitewise/create-gateway.html#options) in the create-gateway section of *AWS CLI Command Reference* for AWS IoT SiteWise.
+ `coreDeviceThingName` – The name of the AWS IoT thing for your AWS IoT Greengrass V2 core device.
+ `coreDeviceOperatingSystem` – The operating system of the core device in AWS IoT Greengrass V2. Specifying the operating system is required for `gateway-version 3` and not applicable for `gateway-version 2`. Options include: `LINUX_AARCH64`, `LINUX_AMD64`, and `WINDOWS_AMD64`
+ `gateway-version` – The version of the gateway.
+ To create an MQTT-enabled, V3 gateway, use `3` for the gateway version.
+ To create a Classic streams, V2 gateway, use `2` for the gateway version.
+ `cli-input-json` – A JSON file containing request parameters.
------
Now that you've created the SiteWise Edge gateway, [Install the AWS IoT SiteWise Edge gateway software on your local device](install-gateway-software-on-local-device.md).
# Install the AWS IoT SiteWise Edge gateway software on your local device
Install gateway software
After you've created an AWS IoT SiteWise Edge gateway, install the SiteWise Edge gateway software on your local device. SiteWise Edge gateway software can be installed on local devices that have Linux or Microsoft Windows server operating systems installed.
**Important**
Make sure that your local device connects to the internet.
------
#### [ Linux ]
The following procedure uses SSH to connect to your local device. Alternatively, you can use a USB flash drive or other tools to transfer the installer file to your local device. If you don't want to use SSH, skip to **Step 2: Install the SiteWise Edge gateway software** below.
**SSH prerequisites**
Before you connect to your device using SSH, complete the following prerequisites.
+ Linux and macOS - Download and install OpenSSH. For more information, see [https://www.openssh.com](https://www.openssh.com/).
**Step 1: Copy the installer to your SiteWise Edge gateway device**
The following instructions explain how to connect to your local device using an SSH client.
1. To connect to your device, run the following command in a terminal window on your computer, replacing *username* and *IP* with a username that has elevated privileges and IP address.
```
ssh username@IP
```
1. To transfer the installer file that AWS IoT SiteWise generated to your SiteWise Edge gateway device, run the following command.
**Note**
Replace *path-to-saved-installer* with the path on your computer that you used to save the installer file and the name of the installer file.
Replace *IP-address* with the IP address of your local device.
Replace *directory-to-receive-installer* with the path on your local device that you use to receive the installer file.
```
scp path-to-saved-installer.sh user-name@IP-address:directory-to-receive-installer
```
**Step 2: Install the SiteWise Edge gateway software**
In the following procedures, run the commands in a terminal window on your SiteWise Edge gateway device.
1. Give the installer file the execute permission.
```
chmod +x path-to-installer.sh
```
1. Run the installer.
```
sudo ./path-to-installer.sh
```
------
#### [ Windows Server ]
**Prerequisites**
You must have the following prerequisites to install the SiteWise Edge gateway software:
+ Microsoft Windows Server 2019 or later installed
+ Administrator privileges
+ PowerShell version 5.1 or later installed
+ SiteWise Edge gateway installer downloaded to the Windows Server where it will be provisioned
**Step 1: Run PowerShell as administrator**
1. On the Windows server where you want to install SiteWise Edge gateway, log in as administrator.
1. Enter **PowerShell** in the Windows search bar.
1. In the search results, open the context (right-click) menu on the Windows PowerShell app. Choose **Run as Administrator**.
**Step 2: Install the SiteWise Edge gateway software**
Run the following commands in a terminal window on your SiteWise Edge Gateway device.
1. Unblock the SiteWise Edge gateway installer.
```
unblock-file path-to-installer.ps1
```
1. Run the Installer.
```
./path-to-installer.ps1
```
**Note**
If the script execution is disabled on the system, change the script execution policy to `RemoteSigned`.
```
Set-ExecutionPolicy RemoteSigned
```
------
The next step depends on the *type* of self-hosted gateway you need. Continue to [MQTT-enabled, V3 gateways for AWS IoT SiteWise Edge](mqtt-enabled-v3-gateway.md) or [Classic streams, V2 gateways for AWS IoT SiteWise Edge](classic-streams-v2-gateway.md).
# MQTT-enabled, V3 gateways for AWS IoT SiteWise Edge
MQTT-enabled, V3 gateways
AWS IoT SiteWise can use MQTT-enabled, V3 gateways, representing a significant advancement in the SiteWise Edge gateway architecture. This gateway type leverages the MQTT (Message Queuing Telemetry Transport) protocol for data communication, providing enhanced flexibility and efficiency in industrial IoT deployments.
The MQTT-enabled, V3 gateway uses MQTT for data transfer, enabling a lightweight, publish-subscribe network protocol that efficiently transports messages between devices and the cloud. You can set up various data destinations, including real-time data ingestion directly into AWS IoT SiteWise and buffered data ingestion using Amazon S3. To enable precise data collection, you can implement path filters to subscribe to specific MQTT topics.
MQTT-enabled, V3 gateways come with a pre-configured real-time destination with filters set to "\$1" (all topics), which you can customize or remove as needed. To streamline data management, only one real-time destination can exist in each gateway.
The MQTT-enabled architecture differs significantly from the Classic streams, V2 gateway. While V2 uses a stream-based approach, V3 employs MQTT, offering more configurable data destinations and filtering options. However, note that V3 does not support the data processing pack, which is available in V2.
The MQTT-enabled, V3 gateway offers several advantages:
+ Improved scalability, due to MQTT's lightweight nature, enabling better handling of numerous devices and high-frequency data transmission.
+ Enhanced data control through path filters, enabling granular management of data collection and reducing unnecessary data transfer and processing.
+ Flexible data handling, allowing configuration between real-time processing and buffered storage based on specific needs.
+ Alignment with modern IoT communication standards, setting the stage for future enhancements and integrations.
Consider adopting the MQTT-enabled, V3 gateway for new deployments, especially when you require flexible data ingestion options and precise control over data collection.
**Note**
For existing deployments or scenarios requiring the data processing pack, the Classic streams, V2 gateway remains a viable option.
By offering both gateway types, AWS IoT SiteWise ensures that you can choose the solution that best fits your specific industrial IoT needs, whether you prioritize advanced MQTT capabilities or compatibility with existing systems.
## Destinations and path filters
View the following topics to learn more about destinations and path filters in MQTT-enabled gateways:
+ [Understand AWS IoT SiteWise Edge destinations](gw-destinations.md#source-destination)
+ [Add an AWS IoT SiteWise Edge real-time destination](destinations-real-time.md)
+ [Add an AWS IoT SiteWise buffered destination using Amazon S3](destinations-buffered.md)
+ [Understand path filters for AWS IoT SiteWise Edge destinationsUnderstand path filters](gw-destinations.md#destinations-path-filters)
+ [Add path filters to AWS IoT SiteWise Edge destinations](destinations-add-path-filters.md)
+ [Manage AWS IoT SiteWise Edge destinations](destinations-manage.md)
# Connect external applications to the EMQX broker
Connect external applications
This guide explains how to connect external applications to your AWS IoT SiteWise Edge gateway through an EMQX broker on your deployed MQTT-enabled, V3 gateway. External applications might include custom monitoring tools, third-party visualization software, or legacy systems that need to interact with your industrial data at the edge.
We'll cover the configuration steps for both Linux and Microsoft Windows environments, including EMQX deployment configuration, TLS setup for secure connections, and authorization rules to control access to specific topics.
**Note**
EMQX is not a vendor or supplier for AWS IoT SiteWise Edge.
**Important**
For securing connections to your gateway, we strongly recommend using certificate-based authentication through the AWS IoT Greengrass client device authentication feature. This method provides robust security through mutual TLS (mTLS) authentication. For more information, see [Connect client devices to core devices](https://docs.aws.amazon.com/greengrass/v2/developerguide/connect-client-devices.html) in the *AWS IoT Greengrass Version 2 Developer Guide*.
If you are not able to use certificate based authentication, follow this guide to setup authentication using usernames and passwords.
## Prerequisites
+ A SiteWise Edge MQTT-enabled, V3 gateway that has been deployed and is online
+ Access to the gateway host
+ Access to the AWS IoT SiteWise and AWS IoT Greengrass consoles
**Topics**
+ [
## Prerequisites
](#emqx-broker-prerequisites)
+ [
# Message payload format for the EMQX broker on AWS IoT SiteWise Edge
](connect-broker-payload-format.md)
+ [
# Configure the EMQX broker
](configure-emqx-broker.md)
+ [
# Connect an application to the EMQX broker on AWS IoT SiteWise Edge
](connect-app-to-broker.md)
+ [
# Set up authorization rules for AWS IoT SiteWise Edge in EMQX
](authorization-rules-emqx-broker.md)
# Message payload format for the EMQX broker on AWS IoT SiteWise Edge
Message payload format
For the IoT SiteWise publisher component to consume data from your external application and publish it to the AWS IoT SiteWise cloud, the payload sent to the broker must meet specific requirements.
Understanding the payload format is key to successful MQTT communication with AWS IoT SiteWise Edge. While the connection setup process is covered in later sections, we present the payload requirements first to help you plan your implementation.
## MQTT topic requirements
There are no restrictions on MQTT topic structure, including the number of levels or characters used. However, we recommend that the topic matches the `propertyAlias` field in the payload.
**Example property alias**
If the MQTT topic is `site1/line1/compressor1/temperature`, ensure the `propertyAlias` matches.
```
{
"assetId": "compressor_asset_01",
"propertyAlias": "site1/line1/compressor1/temperature",
"propertyId": "temperature_sensor_01",
"propertyValues": [
{
"quality": "GOOD",
"timestamp": {
"offsetInNanos": 0,
"timeInSeconds": 1683000000
},
"value": {
"doubleValue": 23.5
}
}
]
}
```
## JSON payload structure
The MQTT message payload are written in JSON and follow the `PutAssetPropertyValueEntry` message format defined in the [AWS IoT SiteWise API Reference](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_PutAssetPropertyValueEntry.html).
```
{
"assetId": "string",
"propertyAlias": "string",
"propertyId": "string",
"propertyValues": [
{
"quality": "string",
"timestamp": {
"offsetInNanos": number,
"timeInSeconds": number
},
"value": {
"booleanValue": boolean,
"doubleValue": number,
"integerValue": number,
"stringValue": "string"
}
}
]
}
```
**Note**
For a message to be considered valid, only one of the following conditions can be true:
The `propertyAlias` is set, or
Both `assetId` and `propertyId` are set
The `PutAssetPropertyValueEntry` has an `entryId` field that is not required in this context.
# Configure the EMQX broker
This section covers how to add usernames and passwords. It also covers how to establish a TLS connection from an external source using the added username and password. You can configure the EMQX broker using Linux or Microsoft Windows.
**Note**
To configure the broker, you need a core device that is setup with the default EMQX configuration in your MQTT-enabled, V3 gateway.
**Important**
After completing this procedure, we highly recommend configuring authorization rules. For more information, see [Set up authorization rules for AWS IoT SiteWise Edge in EMQX](authorization-rules-emqx-broker.md). Authorization rules for added users enhances security.
## Update the EMQX deployment configuration for authentication
**To update the EMQX deployment configuration for authentication**
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 gateway to configure.
1. In the **Edge gateway configuration** section, copy your **Greengrass core device** value. Save it for later use.
1. Open the [AWS IoT console](https://console.aws.amazon.com/iot/).
1. On the left navigation, under the **Manage** section, choose **Greengrass devices**, then **Deployments**.
1. Find the core device value you saved earlier and choose that link to open the deployment.
1. Choose the **Actions** dropdown button, then **Revise**.
1. Read the message that appears and then choose **Revise deployment**. The **Specify target** page appears.
1. Choose **Next** until you reach the **Configure components** step.
1. Select the `aws.greengrass.clientdevices.mqtt.EMQX` radio button.
1. Choose the **Configure component** button. A configuration page appears for the component.
1. Under **Configuration update**, choose **Reset to default configuration for component version: 2.\$1.\$1**.
1. Enter the following configuration in the **Configuration to merge** section based on your OS.
------
#### [ Linux ]
```
{
"emqxConfig": {
"authorization": {
"no_match": "allow"
},
"listeners": {
"tcp": {
"default": {
"enabled": true,
"enable_authn": false
}
},
"ssl": {
"default": {
"enabled": true,
"enable_authn": true,
"ssl_options": {
"verify": "verify_none",
"fail_if_no_peer_cert": false
}
}
}
},
"authentication": {
"enable": true,
"backend": "built_in_database",
"mechanism": "password_based",
"password_hash_algorithm": {
"iterations": 210000,
"mac_fun": "sha512",
"name": "pbkdf2"
},
"user_id_type": "username"
},
"dashboard": {
"listeners": {
"http": {
"bind": 18083
}
}
}
},
"authMode": "bypass",
"dockerOptions": "-p 8883:8883 -p 127.0.0.1:1883:1883 -p 127.0.0.1:18083:18083 -v emqx-data:/opt/emqx/data -e EMQX_NODE__NAME=emqx@local",
"requiresPrivilege": "true"
}
```
------
#### [ Windows ]
```
{
"emqxConfig": {
"authorization": {
"no_match": "allow"
},
"listeners": {
"tcp": {
"default": {
"enabled": true,
"enable_authn": false
}
},
"ssl": {
"default": {
"enabled": true,
"enable_authn": true,
"ssl_options": {
"verify": "verify_none",
"fail_if_no_peer_cert": false
}
}
}
},
"authentication": {
"enable": true,
"backend": "built_in_database",
"mechanism": "password_based",
"password_hash_algorithm": {
"iterations": 210000,
"mac_fun": "sha512",
"name": "pbkdf2"
},
"user_id_type": "username"
},
"dashboard": {
"listeners": {
"http": {
"bind": 18083
}
}
}
},
"authMode": "bypass",
"requiresPrivilege": "true"
}
```
The `dockerOptions` field is only for Linux gateways.
------
1. Choose **Confirm**.
1. Choose **Next** until you reach the **Review** step.
1. Choose **Deploy**.
1. After the deployment succeeds, proceed to the next step.
## Enable username and password authentication
This section shows you how to add usernames and passwords through the EMQX dashboard GUI.
**Note**
The EMQX-related instructions provided are for reference only. As EMQX documentation and features may change over time, and we do not maintain their documentation, we recommend consulting [EMQX's official documentation](https://docs.emqx.com/en/emqx/latest/) for the most current information.
------
#### [ EMQX Dashboard ]
**To enable username and password authentication through the EMQX dashboard**
1. Ensure that you are within the gateway host.
1. Open a browser window and visit [http://localhost:18083/](http://localhost:18083/).
1. Enter the default username of **admin** and the default password of **public**. For more information, see [EMQX Dashboard](https://docs.emqx.com/en/emqx/latest/dashboard/introduction.html#first-login) in the *EMQX Docs*.
1. After login, you are prompted to change your password. Update your password to continue to the EMQX Dashboard.
1. In the left navigation, choose the shield icon, then **Authentication**.
1. In the **Built-in Database** row, choose the **Users** button.
1. Choose the plus sign icon button to add users. An **Add** screen appears.
1. Enter a username and password for the user of the external application.
1. Choose **Save**. The username you chose appears in the **Authentication** page's table.
**Note**
Existing or default authorization rules apply to the new user. It's recommended to review and adjust them to your external application needs.
------
#### [ EMQX Management with Linux ]
Use the AWS IoT SiteWise EMQX CLI tool at `/greengrass/v2/bin/swe-emqx-cli`.
**To enable username and password authentication through EMQX Management using Linux**
1. Change the admin password by running the following command:
```
/greengrass/v2/bin/swe-emqx-cli admin change-pwd
```
1. When prompted, do the following:
1. Enter your current administrator user (default is `admin`) and password (default is `public`).
1. Enter and confirm your new password.
If successful, you see the following message:
```
admin password changed successfully
```
1. Add users for external applications by running the following command:
```
/greengrass/v2/bin/swe-emqx-cli users add
```
1. When prompted, do the following:
1. Enter the username for the new user.
1. Enter and confirm the password for the new user.
If successful, you see the following message:
```
User '[username]' created successfully
```
1. Verify user configuration by running the following command:
```
/greengrass/v2/bin/swe-emqx-cli users list
```
The output shows all configured users:
```
Users:
- [your-added-username]
Total users: 1
```
------
#### [ EMQX Management with Windows ]
Use the AWS IoT SiteWise EMQX CLI tool at one of the following locations:
+ PowerShell: `C:\greengrass\v2\bin\swe-emqx-cli.ps1`
+ Command Prompt: `C:\greengrass\v2\bin\swe-emqx-cli.bat`
**To enable username and password authentication through EMQX Management using Windows**
1. Change the admin password by running the following command:
```
C:\greengrass\v2\bin\swe-emqx-cli.ps1 admin change-pwd
```
1. When prompted, do the following:
1. Enter your current administrator user (default is `admin`) and password (default is `public`).
1. Enter and confirm your new password.
If successful, you see the following message:
```
admin password changed successfully
```
1. Add users for external applications by running the following command:
```
C:\greengrass\v2\bin\swe-emqx-cli.ps1 users add
```
1. When prompted, do the following:
1. Enter the username for the new user.
1. Enter and confirm the password for the new user.
If successful, you see the following message:
```
User '[username]' created successfully
```
1. Verify user configuration by running the following command:
```
C:\greengrass\v2\bin\swe-emqx-cli.ps1 users list
```
The output shows all configured users:
```
Users:
- [your-added-username]
Total users: 1
```
------
# Connect an application to the EMQX broker on AWS IoT SiteWise Edge
Connect an application
The EMQX broker uses Transport Layer Security (TLS) on port 8883 to encrypt all communications, ensuring your data remains protected during transmission. This section walks you through the steps to establish connections between your applications and the EMQX broker. Following these steps helps maintain the integrity and confidentiality of your industrial data. The connection process involves two main approaches: using automated IP discovery through components, or manually configuring DNS names and IP addresses as Subject Alternative Names (SANs) in your TLS certificates. Each method has its own advantages depending on your network setup and security requirements. This documentation will guide you through both options.
**Topics**
+ [
## Configure TLS for secure connections to the EMQX broker on AWS IoT SiteWise Edge
](#configure-tls-emqx-broker)
+ [
## Test the EMQX broker connection on AWS IoT SiteWise Edge
](#test-emqx-connection)
+ [
## Use your own CA
](#configure-tls-custom-ca)
+ [
## Open port 8883 for external firewall connections
](#emqx-firewall)
## Configure TLS for secure connections to the EMQX broker on AWS IoT SiteWise Edge
Configure TLS
By default, AWS IoT Greengrass generates a TLS server certificate for the EMQX broker that is signed by the core device certificate authority (CA). For more information, see [Connecting client devices to an AWS IoT Greengrass Core device with an MQTT broker](https://docs.aws.amazon.com/greengrass/v2/developerguide/connecting-to-mqtt.html).
### Retrieve the TLS certificate
To get the CA certificate run the following command on the gateway host:
------
#### [ Linux ]
Run the following command in a shell session on the gateway host:
```
/greengrass/v2/bin/swe-emqx-cli cert
```
This command displays the certificate location and prints the certificate's content.
You can alternatively save the certificate to a file using this command:
```
/greengrass/v2/bin/swe-emqx-cli cert --output /path/to/certificate.pem
```
------
#### [ Windows ]
Run the following command in a PowerShell session on the gateway host:
```
C:\greengrass\v2\bin\swe-emqx-cli.ps1 cert
```
This command displays the certificate location and prints the certificate's content.
You can alternatively save the certificate to a file using this command:
```
C:\greengrass\v2\bin\swe-emqx-cli.ps1 cert --output C:\path\to\certificate.pem
```
The CLI automatically locates the certificate regardless of the exact path on your system.
------
Copy the contents of the ca.pem file to the external application that you're connecting to the broker. Save it as `BrokerCoreDeviceCA.pem`.
### Add custom DNS names/IP addresses to the TLS server certificate
The subject alternative name (SAN) on the cert generated by AWS IoT Greengrass is `localhost`. When establishing a TLS connection from outside of the gateway host, the TLS verification step fails because the broker’s hostname does not match the hostname of `localhost` on the server certificate.
To address mismatched hostname issue, AWS IoT Greengrass provides two ways of managing core device endpoints. This section covers both options. For more detailed information, see [Manage core device endpoints](https://docs.aws.amazon.com/greengrass/v2/developerguide/manage-core-device-endpoints.html) in the *AWS IoT Greengrass Version 2 Developer Guide*.
+ To connect to the EMQX broker using the core device's IP address, use the Automated IP discovery section.
+ To connect to the EMQX broker using a DNS name instead of IP address, you use the Manual management section.
------
#### [ Automated IP discovery ]
This option allows your core device to automatically discover its IP address and add it as a Subject Alternative Name (SAN) to the broker certificate.
1. Add the `aws.greengrass.clientdevices.IPDetector` component to your core device’s deployment.
1. Deploy the changes to your device
1. Wait for deployment to complete.
After the deployment completes, you can establish a secure TLS connection using the broker's IP address.
The IP address is automatically added as a SAN to the broker certificate.
------
#### [ Manual DNS and IP Configuration ]
You can manually add DNS names and IP addresses as Subject Alternative Names (SANs) to your TLS certificate. This method is useful when you have configured a DNS name for your gateway host.
**Important**
If you are using the IPDetector component, remove it from your deployment before proceeding. The IPDetector component overrides manual endpoint configurations.
**To manually configure endpoints**
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 gateway to configure.
1. In the **Edge gateway configuration** section, choose your **Greengrass core device** url. The core device's page appears.
1. Choose the **Client devices** tab.
1. Choose **Manage endpoints**.
1. In the Manage endpoints dialog box, enter the DNS name(s) and any IP addresses you want to add as SANs. Use port 8883.
1. Choose **Update**.
The broker's TLS server certificate updates automatically to include your new endpoints.
**To verify the TLS server certificate update using Linux**
1. Start a shell session on your gateway host.
```
docker exec emqx openssl x509 -in ./data/cert.pem -text -noout | grep -A1 "Subject Alternative Name"
```
1. The command returns an output similar to the following:
```
X509v3 Subject Alternative Name:
DNS:endpoint_you_added, DNS:localhost
```
1. Verify that your endpoint appears in the list of SANs.
**To verify the TLS server certificate update using Windows**
1. Start a shell session on your gateway host.
```
(Get-PfxCertificate -FilePath "C:\greengrass\v2\work\aws.greengrass.clientdevices.mqtt.EMQX\v2\data\cert.pem").Extensions | Where-Object { $_.Oid.FriendlyName -eq "Subject Alternative Name" } | ForEach-Object { "Subject Alternative Name:", ($_.Format($true) -split "`n")[0..1] }
```
1. The command returns an output similar to the following:
```
Subject Alternative Name:
DNS Name=your-endpoint
DNS Name=localhost
```
1. Verify that the endpoint you added is in the list of SANs.
------
## Test the EMQX broker connection on AWS IoT SiteWise Edge
Test the connection
After configuring your EMQX broker with TLS certificates and authentication credentials, it's important to verify that your setup works correctly. Testing the connection helps ensure that your security configurations are properly implemented and that clients can successfully establish encrypted connections to the broker. This section demonstrates how to test your broker connection using the Mosquitto command line interface (CLI) client, a widely-used MQTT client tool that supports TLS encryption and authentication.
### Use Mosquitto CLI client to test the EMQX broker connection
In this step we will use the mosquitto CLI client to test our setup and make sure we can connect successfully to the broker using the username and password we created earlier. To get the `BrokerCoreDeviceCA.pem` follow steps under Step 3: Setting up TLS.
```
mosquitto_sub -h hostname|ip address \
-p 8883 \
-t "#" \
-q 1 \
-u username -P password \
--cafile BrokerCoreDeviceCA.pem
```
**Note**
You may get an SSL:verify error if the hostname/IP address you are connecting to does not match the Subject Alternative Name (SAN) that is on the CA cert you're passing to the client. See "Adding custom DNS names/IP addresses to the TLS server cert" under Step 3: Setting up TLS for how to get a certificate with the correct SAN.
At this point, all users have access to publish and subscribe to all topics on the broker. Proceed to [Set up authorization rules for AWS IoT SiteWise Edge in EMQX](authorization-rules-emqx-broker.md).
## Use your own CA
AWS IoT Greengrass outlines how to configure your own client device auth component to use your own certificate authority (CA). The client device auth component (`aws.greengrass.clientdevices.Auth`) authenticates client devices and authorizes client device actions. For more information, see [Using your own certificate authority](https://docs.aws.amazon.com/greengrass/v2/developerguide/connecting-to-mqtt.html#use-your-own-CA) in the *AWS IoT Greengrass Version 2 Developer Guide*.
To use your own CA, add the `aws.greengrass.clientdevices.Auth` component to your deployment so that you can specify a custom configuration.
## Open port 8883 for external firewall connections
------
#### [ Linux ]
In your Linux host firewall rule, add an inbound rule for port 8883 to allow incoming connections from outside of the gateway host. If there are any firewalls in place, ensure that incoming TLS connections on port 8883 are allowed.
------
#### [ Windows ]
In your Microsoft Windows host firewall rule, add an inbound rule for port 8883 to allow incoming connections from outside of the gateway host. Ensure the rule is an allow rule, of type port, specifying port 8883. You can configure this according to your network configuration to allow connections from your external applications to the broker.
------
# Set up authorization rules for AWS IoT SiteWise Edge in EMQX
Set up authorization rules
EMQX supports adding authorization rules based on identifiers such as username, IP address or client ID. This is useful if you want to limit the number of external applications connecting to various operations or topics.
**Topics**
+ [
# Configure authorization using the built-in database with Linux
](add-auth-rules-database-emqx-broker-linux.md)
+ [
# Configure authorization using the built-in database with Windows
](add-auth-rules-database-emqx-broker-windows.md)
+ [
# Update the EMQX deployment configuration for authorization
](update-emqx-broker-authorization.md)
+ [
# Add authorization rules through the EMQX Dashboard for users
](add-rules-emqx-broker.md)
# Configure authorization using the built-in database with Linux
Configure authorization using Linux
When you configure authorization rules, there are two configuration choices that depend on your deployment setup.
+ **Docker** – If you're running a standard Docker installation without Litmus Edge, use the **Docker bridge gateway** configuration. This is typically the case when you've only deployed AWS IoT SiteWise components.
+ **Litmus Edge** – If you have Litmus Edge installed on your gateway, use the **Litmus Edge network subnet** configuration.
**Note**
If you initially configure the Docker bridge gateway and later install Litmus Edge, reconfigure the authorization rules using the Litmus Edge network subnet option to ensure proper communication between all components.
**To add basic authorization rules**
1. Verify that the EMQX broker is deployed and running.
1. Start a shell session on your gateway host.
------
#### [ Docker without Litmus Edge ]
For standard Docker installation without Litmus Edge, run:
```
/greengrass/v2/bin/swe-emqx-cli acl init
```
------
#### [ Litmus Edge network subnet ]
If you're using Litmus Edge, determine the Litmus Edge network subnet IP:
```
docker network inspect LitmusNetwork | grep IPAM -A9
```
Note the Subnet value from the output and run the following command. Replace `litmus_subnet_ip` with the Subnet value from the previous step.
```
/greengrass/v2/bin/swe-emqx-cli acl init litmus_subnet_ip
```
------
The tool automatically creates and applies authorization rules to allow connections from the provided IP address to the broker. It allows access to all topics. This includes the IoT SiteWise OPC UA collector and IoT SiteWise publisher.
1. Proceed to [Update the EMQX deployment configuration for authorization](update-emqx-broker-authorization.md).
# Configure authorization using the built-in database with Windows
Configure authorization using Microsoft Windows
This section covers configuring authorization rules using the built-in database for Windows deployments.
**To add basic authorization rules**
1. Verify that the EMQX broker is deployed and running.
1. Run the AWS IoT SiteWise EMQX CLI tool:
```
C:\greengrass\v2\bin\swe-emqx-cli.ps1 acl init
```
The tool automatically creates and applies ACL rules allowing connections from localhost (127.0.0.1) to the broker. It allows access to all topics. This includes the IoT SiteWise OPC UA collector and IoT SiteWise publisher.
1. Proceed to [Update the EMQX deployment configuration for authorization](update-emqx-broker-authorization.md).
# Update the EMQX deployment configuration for authorization
Update the deployment
**To update the EMQX deployment configuration for authorization**
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 gateway to configure.
1. In the **Edge gateway configuration** section, copy your **Greengrass core device** value. Save it for later use.
1. Open the [AWS IoT console](https://console.aws.amazon.com/iot/).
1. On the left navigation, under the **Manage** section, choose **Greengrass devices**, then **Deployments**.
1. Find the core device value you saved earlier and choose that link to open the deployment.
1. Choose the **Actions** dropdown button, then **Revise**.
1. Read the message that appears and then choose **Revise deployment**. The **Specify target** page appears.
1. Choose **Next** until you reach the **Configure components** step.
1. Select the `aws.greengrass.clientdevices.mqtt.EMQX` radio button.
1. Choose the **Configure component** button. A configuration page appears for the component.
1. Under **Configuration update**, choose **Reset to default configuration for component version: 2.\$1.\$1**.
1. Paste the following content in the **Configuration to merge** section based on your OS.
------
#### [ Linux ]
```
{
"emqxConfig": {
"authorization": {
"no_match": "deny",
"sources": [
{
"type": "built_in_database"
},
{
"type": "file",
"path": "data/authz/acl.conf"
}
]
},
"listeners": {
"tcp": {
"default": {
"enabled": true,
"enable_authn": false
}
},
"ssl": {
"default": {
"enabled": true,
"enable_authn": true,
"ssl_options": {
"verify": "verify_none",
"fail_if_no_peer_cert": false
}
}
}
},
"authentication": {
"enable": true,
"backend": "built_in_database",
"mechanism": "password_based",
"password_hash_algorithm": {
"iterations": 210000,
"mac_fun": "sha512",
"name": "pbkdf2"
},
"user_id_type": "username"
},
"dashboard": {
"listeners": {
"http": {
"bind": 18083
}
}
}
},
"authMode": "bypass",
"dockerOptions": "-p 8883:8883 -p 127.0.0.1:1883:1883 -p 127.0.0.1:18083:18083 -v emqx-data:/opt/emqx/data -e EMQX_NODE__NAME=emqx@local",
"requiresPrivilege": "true"
}
```
------
#### [ Windows ]
```
{
"emqxConfig": {
"authorization": {
"no_match": "deny",
"sources": [
{
"type": "built_in_database"
},
{
"type": "file",
"path": "C:\\greengrass\\v2\\work\\aws.greengrass.clientdevices.mqtt.EMQX\\v2\\data\\authz\\acl.conf"
}
]
},
"listeners": {
"tcp": {
"default": {
"enabled": true,
"enable_authn": false
}
},
"ssl": {
"default": {
"enabled": true,
"enable_authn": true,
"ssl_options": {
"verify": "verify_none",
"fail_if_no_peer_cert": false
}
}
}
},
"authentication": {
"enable": true,
"backend": "built_in_database",
"mechanism": "password_based",
"password_hash_algorithm": {
"iterations": 210000,
"mac_fun": "sha512",
"name": "pbkdf2"
},
"user_id_type": "username"
},
"dashboard": {
"listeners": {
"http": {
"bind": 18083
}
}
}
},
"authMode": "bypass",
"requiresPrivilege": "true"
}
```
------
1. Choose **Confirm**.
1. Choose **Next** until you reach the **Review** step.
1. Choose **Deploy**.
**Note**
From this point onward, you can't edit the ACL file to update the authorization rules. Alternatively, you can proceed to [Add authorization rules through the EMQX Dashboard for users](add-rules-emqx-broker.md) after a successful deployment.
# Add authorization rules through the EMQX Dashboard for users
Add authorization rules for users
You can add or update authorization rules using the EMQX Dashboard or the AWS IoT SiteWise EMQX CLI tool. The AWS IoT SiteWise EMQX CLI tool manages authorization using EMQX's built-in database.
**Note**
Adding authorization rules is an advanced configuration step that requires understanding of MQTT topic patterns and access control. For more information about creating authorization rules using EMQX's built-in database, see [Use Built-in Database](https://docs.emqx.com/en/emqx/latest/access-control/authz/mnesia.html) in the *EMQX Docs*.
**Note**
The EMQX-related instructions provided are for reference only. As EMQX documentation and features may change over time, and we do not maintain their documentation, we recommend consulting [EMQX's official documentation](https://docs.emqx.com/en/emqx/latest/) for the most current information.
------
#### [ EMQX dashboard ]
This procedure shows how you can add authorization rules on the EMQX dashboard.
The EMQX dashboard is only accessible from within the gateway host. If you try to connect from outside of the gateway host, you can't access the dashboard.
**To add authorization rules using the EMQX Dashboard**
1. Ensure that you are within the gateway host.
1. Open a browser window and visit [http://localhost:18083/](http://localhost:18083/).
1. Login to the the EMQX dashboard. This procedure assumes that you've changed your default login credentials to something of your choosing. For more information on intial setup, see [Enable username and password authentication](configure-emqx-broker.md#emqx-broker-username-password-auth).
1. Choose the shield icon, then **Authorization** from the dropdown menu.
1. Choose the **Permissions** button on the **Built-in Database** row.
1. In the Built-in Database authorization section, add or update the user authorization rules for your business needs. For more guidance on creating rules, see the [Use Built-in Database](https://docs.emqx.com/en/emqx/latest/access-control/authz/mnesia.html) section in the *EMQX Docs*.
------
#### [ AWS IoT SiteWise CLI tool using Linux ]
**To manage authorization rules using the AWS IoT SiteWise EMQX CLI tool in Linux:**
+ Add authorization rules for a user using the following format:
```
/greengrass/v2/bin/swe-emqx-cli auth add your-username your-action your-permission your-topic [your-action-permission-topic]
```
**Example Add authorization rules for a user**
This example shows how to add rules for a user named `system1`:
```
/greengrass/v2/bin/swe-emqx-cli auth add system1 \
publish allow "sensors/#" \
subscribe allow "control/#" \
all deny "#"
```
**Example : View authorization rules for a user**
To view authorization rules for the `system1` users, run the following command:
```
/greengrass/v2/bin/swe-emqx-cli auth list system1
```
**Example : View all existing authorization rules**
To view all of the authorization rules you currently have, run the following command:
```
/greengrass/v2/bin/swe-emqx-cli auth list
```
**Example : Delete all authorization rules for a user**
To delete all of the authorization rules applied to a particular user, run the following command:
```
/greengrass/v2/bin/swe-emqx-cli auth delete system1
```
You are prompted to confirm the deletion.
------
#### [ AWS IoT SiteWise CLI tool using Windows ]
**To manage authorization rules using the AWS IoT SiteWise EMQX CLI tool in Windows PowerShell:**
+ Add authorization rules for a user using the following format:
```
C:\greengrass\v2\bin\swe-emqx-cli.ps1 auth add your-username your-action your-permission your-topic [your-action-permission-topic]
```
**Example : Add authorization rules for a user**
This example shows how to add rules for a user named `system1`:
```
C:\greengrass\v2\bin\swe-emqx-cli.ps1 auth add system1 `
publish allow "sensors/#" `
subscribe allow "control/#" `
all deny "#"
```
**Example : View authorization rules for a user**
To view authorization rules for the `system1` users, run the following command:
```
C:\greengrass\v2\bin\swe-emqx-cli.ps1 auth list system1
```
**Example : View all existing authorization rules**
To view all of the authorization rules you currently have, run the following command:
```
C:\greengrass\v2\bin\swe-emqx-cli.ps1 auth list
```
**Example : Delete all authorization rules for a user**
To delete all of the authorization rules applied to a particular user, run the following command:
```
C:\greengrass\v2\bin\swe-emqx-cli.ps1 auth delete system1
```
You are prompted to confirm the deletion.
------
# Process and visualize data with SiteWise Edge and open-source tools
Process and visualize data at the Edge
Configure AWS IoT SiteWise Edge MQTT-enabled gateways with open-source tools for local processing and visualization to enhance your industrial data management capabilities.
With SiteWise Edge, you can create a local data processing pipeline using external, open-source tools. Use [Node-RED®](https://nodered.org/) to store time-series data with [InfluxDB®](https://www.influxdata.com/lp/influxdb-database/), and monitor operations through [Grafana®](https://grafana.com/) dashboards.
Node-RED processes and transforms your data flows, while InfluxDB provides time-series data storage. Grafana displays your real-time operational data. Use these tools with SiteWise Edge to synchronize data between your local environment and the AWS Cloud, giving you both immediate local insights and long-term cloud-based analytics capabilities.
**Note**
Node-RED®, InfluxDB®, and Grafana® are not vendors or suppliers for SiteWise Edge.
![\[A diagram that shows a few data sources and the turbine simulator connecting to the EMQX Broker to publish. Then the EMQX broker subscribes to the AWS IoT SiteWise Gateway and Node-RED. Node-RED feeds into InfluxDB, and then Influx DB into the Grafana Dashboard.\]](http://docs.aws.amazon.com/iot-sitewise/latest/userguide/images/gateway-open-source-overview.png)
**Note**
In this guide, we're using the open-source version of [Grafana](https://grafana.com/) for SiteWise Edge as opposed to the [Amazon Managed Grafana](https://docs.aws.amazon.com/grafana/latest/userguide/what-is-Amazon-Managed-Service-Grafana.html) service.
## Deployment options
You can deploy this solution using one of two approaches. With a Microsoft Windows manual setup, you control component configuration and integration with your infrastructure. With Linux, you can use Docker to deploy pre-configured components in containers.
Choose the method that meets your operational requirements.
+ [Set up open source integrations manually (Windows)](windows-manual-setup.md) – For custom configurations or existing infrastructure
+ [Set up open-source integrations with Docker (Linux)](linux-docker-setup.md) – For rapid deployment with pre-configured components
## Wind farm example overview
This guide uses a wind farm example to demonstrate how you can monitor wind speed for a turbine on a wind farm. This practical scenario illustrates common industrial monitoring needs where both local and cloud-based visibility are valuable for operational efficiency.
With this integration, you can:
+ Collect data from industrial equipment using an AWS IoT SiteWise Edge gateway
+ Process data locally with Node-RED, InfluxDB, and Grafana
+ Store data locally using InfluxDB
+ Monitor data in real time using Grafana dashboards
Throughout this guide, we use the example of a windfarm. We use Node-RED to simulate a turbine that generates wind speed data. Node-RED translates the data payload, publishes the data to the SiteWise Edge MQTT broker, subscribes to receive data from the broker, and stores the data locally in InfluxDB. This approach ensures that all of the operational data is available both locally for immediate access and in the cloud for further analytics. By implementing this pattern, you gain resilience against network disruptions while maintaining the ability to perform advanced analytics in the AWS Cloud. Grafana connects to InfluxDB for local monitoring, providing operators with real-time visibility into metrics without cloud dependencies. A SiteWise Edge MQTT-enabled gateway connects to the same MQTT broker to send data to AWS IoT SiteWise, creating a bridge between your edge operations and cloud-based services.
You can use your own data and configurations to create a similar workflow tailored to your specific industrial requirements, whether you're monitoring manufacturing equipment, utility infrastructure, or other industrial assets.
## Requirements for open-source integrations
Before implementing open-source integrations with SiteWise Edge, ensure your environment meets the necessary requirements.
+ **Hardware requirements** - Your gateway hardware must meet the requirements for SiteWise Edge gateways. For more information, see [AWS IoT SiteWise Edge self-hosted gateway requirements](configure-gateway-ggv2.md) for MQTT-enabled, V3 gateways and [Requirements for the AWS IoT SiteWise Edge application](siemens-app-gateway-requirements.md).
**Important**
When deploying additional open-source components, ensure your hardware meets the requirements for [InfluxDB](https://docs.influxdata.com/influxdb/v2/install/), [Node-RED](https://nodered.org/docs/getting-started/), and [Grafana](https://grafana.com/docs/grafana/latest/setup-grafana/installation/).
+ Your network configuration must support both local communication between components and cloud connectivity for SiteWise Edge.
+ All services must run on the same host.
## Security considerations
We recommend that you encrypt all communications between components, especially when accessing interfaces from non-local networks. Implement proper access controls for each component and follow AWS best practices for AWS IoT SiteWise Edge gateway configuration and AWS account security.
**Development environment**
This guide demonstrates Node-RED, InfluxDB, and Grafana running and accessed locally on a gateway host. For production deployments that require external access, implement security measures including TLS encryption, authentication, and authorization. Follow each application's security best practices.
**Third-party software**
This solution uses third-party software not maintained by AWS, including InfluxDB, Node-RED, Grafana, and the `node-red-contrib-influxdb` plugin. Before deployment, ensure these components comply with your organization's security requirements, compliance standards, and governance policies.
**Important**
This guide references and uses third-party software not owned or maintained by AWS. Before implementation, ensure that all components meet your security, compliance, and governance requirements. Keep all software updated with the latest security patches and follow best practices for securing your edge deployment.
InfluxDB, Node-RED, Grafana are not vendors or suppliers for SiteWise Edge.
## Other considerations
Consider these additional factors when implementing open-source integrations with SiteWise Edge.
+ Use the latest versions of all services, tools, and components.
+ Filter and aggregate data locally before cloud transmission to reduce AWS IoT SiteWise data ingestion costs. Configure appropriate data retention periods in InfluxDB and properly size your gateway hardware. For more information, see [AWS IoT SiteWise pricing](https://aws.amazon.com/iot-sitewise/pricing/).
+ Implement regular backup procedures for all data.
+ Monitor resource usage on your gateway and configure appropriate resource limits for each component. Implement data retention policies in InfluxDB to manage disk usage.
# Set up open source integrations manually (Windows)
Manual setup using Windows
Use this guide to manually create a time series bucket for wind speed data that connects with Grafana® and Node-RED®.
Manually install and configure Node-RED, InfluxDB®, and Grafana on Microsoft Windows to control your deployment configuration. You can store and manage time series data from your devices using InfluxDB.
## Manual setup prerequisites
Before you begin, complete these requirements:
**Note**
Run all services (SiteWise Edge, InfluxDB, Node-RED, and Grafana) on the same host.
+ Install an MQTT-enabled, V3 gateway. For more information, see [MQTT-enabled, V3 gateways for AWS IoT SiteWise Edge](mqtt-enabled-v3-gateway.md).
+ Install and run these services locally:
+ InfluxDB OSS v2. For installation steps, see [Install InfluxDB](https://docs.influxdata.com/influxdb/v2/install/).
+ Node-RED. For installation steps, see [Install Node-RED locally](https://nodered.org/docs/getting-started/local).
+ Grafana. For installation steps, see [Install Grafana](https://grafana.com/docs/grafana/latest/setup-grafana/installation/).
# Set up local storage with InfluxDB
With InfluxDB®, you can store time series data from your devices locally. The purpose of local storage capability is to maintain operational visibility during network disruptions and reduce latency for time-critical applications. You can perform analysis and visualization at the edge while still having the option to selectively forward data to the cloud.
In this section, you create a time series bucket for turbine wind speed data and generate an API token for Grafana® and Node-RED® connectivity. The InfluxDB bucket serves as a dedicated storage container for your time series data, similar to a database in traditional systems. The API token enables secure programmatic access to your data.
**To set up InfluxDB**
1. After completing the prerequisite steps and ensuring all tools are running on the same host, open your web browser and go to [http://127.0.0.1:8086](http://127.0.0.1:8086).
1. (Optional) Enable TLS encryption for enhanced security. For more information, see [Enable TLS encryption](https://docs.influxdata.com/influxdb/v2/admin/security/enable-tls/) in the *InfluxData Documentation*.
1. Create a time series InfluxDB bucket to store data from Node-RED. The bucket will serve as a dedicated container for your wind farm data, allowing you to organize and manage retention policies specific to this dataset. For more information, see [Manage buckets](https://docs.influxdata.com/influxdb/v2/admin/buckets/) in the *InfluxData Documentation*.
1. (Optional) Configure the data retention period for your edge location. Setting appropriate retention periods helps manage storage resources efficiently by automatically removing older data that's no longer needed for local operations.
For information about data retention, see [Data retention in InfluxDB](https://docs.influxdata.com/influxdb/v2/reference/internals/data-retention/) in the *InfluxData Documentation*.
1. Generate an API token for the bucket. This token will enable secure communication between InfluxDB and other components like Node-RED and Grafana. This way, only authorized services can read from or write to your data store. For more information, see [Create a token](https://docs.influxdata.com/influxdb/cloud/admin/tokens/create-token/) in the *InfluxData Documentation*.
After you complete these steps, you can store time series data in your InfluxDB instance, providing a foundation for local data persistence and analysis in your edge environment.
# Configure Node-RED flows for AWS IoT SiteWise data integration
Configure Node-RED flows
With Node-RED®, you can implement two flows to manage data between your devices and AWS IoT SiteWise. These flows work together to create a comprehensive data management solution that addresses both local and cloud data flow.
+ **Data publish flow** – Publishes to the cloud. The data publish flow sends data to AWS IoT SiteWise. This flow simulates a turbine device by generating sensor data, translating it to AWS IoT SiteWise format, and publishing to the SiteWise Edge MQTT broker. This enables you to leverage AWS IoT SiteWise's cloud capabilities for storage, analytics, and integration with other AWS services.
For more information, see [Configure the data publish flow](windows-nodered-data-publish-flow.md).
+ **Data retention flow** – Stores data at the edge. The data retention flow subscribes to the SiteWise Edge MQTT broker to receive data, translate it into InfluxDB® format, and stores it locally for monitoring. This local storage provides immediate access to operational data, reduces latency for time-critical applications, and ensures continuity during network disruptions.
For more information, see [Configure the data retention flow](windows-nodered-data-retention-flow.md).
These two flows work together to ensure data is both sent to AWS IoT SiteWise and stored locally for immediate access.
To access your Node-RED console, go to [http://127.0.0.1:1880](http://127.0.0.1:1880). For information about enabling TLS, see [Enable TLS encryption](https://docs.influxdata.com/influxdb/v2/admin/security/enable-tls/).
# Configure the data publish flow
The data publish flow uses three nodes to create a pipeline that sends your industrial data to the cloud. This flow is essential for enabling cloud-based analytics, long-term storage, and integration with other AWS services. First, simulated device data is sent to the SiteWise Edge MQTT broker. The gateway picks up the data from the broker which allows for transmission to the AWS IoT SiteWise cloud, where you can leverage powerful analytics and visualization capabilities.
+ **Data input** - Receives device data from your industrial equipment or simulators
+ **Data translator for AWS IoT SiteWise** - Translates data to AWS IoT SiteWise format to ensure compatibility with the SiteWise Edge gateway
+ **MQTT publisher** - Publishes data to SiteWise Edge MQTT broker, making it available to both local and cloud consumers
![\[A diagram showing the Node-RED data publishing flow. It sends simulated device data to the SiteWise Edge MQTT broker for pickup by SiteWise Edge Gateway and then onto the AWS IoT SiteWise Cloud.\]](http://docs.aws.amazon.com/iot-sitewise/latest/userguide/images/gateway-open-source-nodered-publish-flow.png)
## Configure the data input node
In this example, the data input node uses a simulated wind turbine device that generates wind speed data. This node serves as the entry point for your industrial data, whether it comes from simulated sources (as in our example) or from actual industrial equipment in production environments.
We use a custom JSON format for the data payload to provide a standardized structure that works efficiently with both local processing tools and the AWS IoT SiteWise cloud service. This format includes essential metadata like timestamps and quality indicators alongside the actual measurement values, enabling comprehensive data management and quality tracking throughout your pipeline. Import the inject node to receive simulated data in this standardized JSON format with timestamps, quality indicators, and values.
For more information on the Node-RED inject node, see the [Inject](https://nodered.org/docs/user-guide/nodes#inject) section in the *Node-RED Documentation*.
The turbine simulator generates wind speed data every second in this standardized JSON format:
**Example : Turbine data payload**
```
{
name: string, // Property name/identifier
timestamp: number, // Epoch time in nanoseconds
quality: "GOOD" | "UNCERTAIN" | "BAD",
value: number | string | boolean
}
```
This format provides several benefits:
+ The `name` field identifies the specific property or measurement, allowing you to track multiple data points from the same device
+ The `timestamp` in nanoseconds ensures precise time tracking for accurate historical analysis
+ The `quality` indicator helps you filter and manage data based on its reliability
+ The flexible `value` field supports different data types to accommodate various sensor outputs
**Example : Inject node of a turbine simulator**
```
[
{
"id": "string",
"type": "inject",
"z": "string",
"name": "Turbine Simulator",
"props": [
{
"p": "payload.timestamp",
"v": "",
"vt": "date"
},
{
"p": "payload.quality",
"v": "GOOD",
"vt": "str"
},
{
"p": "payload.value",
"v": "$random()",
"vt": "jsonata"
},
{
"p": "payload.name",
"v": "/Renton/WindFarm/Turbine/WindSpeed",
"vt": "str"
}
],
"repeat": "1",
"crontab": "",
"once": false,
"onceDelay": "",
"topic": "",
"x": 270,
"y": 200,
"wires": [
[
"string"
]
]
}
]
```
## Configure a node for data translation
The SiteWise Edge gateway requires data in a specific format to ensure compatibility with AWS IoT SiteWise cloud. The translator node is an important component that converts your input data to the required AWS IoT SiteWise payload format. This translation step ensures that your industrial data can be properly processed, stored, and later analyzed in the AWS IoT SiteWise cloud environment.
By standardizing the data format at this stage, you enable integration between your edge devices and the cloud service where you can use asset modeling, analytics, and visualization capabilities. Use this structure:
**Example : Payload structure for SiteWise Edge data parsing**
```
{
"propertyAlias": "string",
"propertyValues": [
{
"value": {
"booleanValue": boolean,
"doubleValue": number,
"integerValue": number,
"stringValue": "string"
},
"timestamp": {
"timeInSeconds": number,
"offsetInNanos": number
},
"quality": "GOOD" | "UNCERTAIN" | "BAD",
}]
}
```
**Note**
Match the `propertyAlias` to your MQTT topic hierarchy (for example, `/Renton/WindFarm/Turbine/WindSpeed`). This ensures that your data is properly associated with the correct asset property in AWS IoT SiteWise. For more information, see the "Data stream alias" concept in [AWS IoT SiteWise concepts](concept-overview.md).
1. Import the example function node for AWS IoT SiteWise payload translation. This function handles the conversion from your standardized input format to the AWS IoT SiteWise-compatible format, ensuring proper timestamp formatting, quality indicators, and value typing.
```
[
{
"id": "string",
"type": "function",
"z": "string",
"name": "Translate to SiteWise payload",
"func": "let input = msg.payload;\nlet output = {};\n\noutput[\"propertyAlias\"] = input.name;\n\nlet propertyVal = {}\n\nlet timeInSeconds = Math.floor(input.timestamp / 1000);\nlet offsetInNanos = (input.timestamp % 1000) * 1000000;\n\npropertyVal[\"timestamp\"] = {\n \"timeInSeconds\": timeInSeconds,\n \"offsetInNanos\": offsetInNanos,\n};\n\npropertyVal[\"quality\"] = input.quality\n\nlet typeNameConverter = {\n \"number\": (x) => Number.isInteger(x) ? \"integerValue\" : \"doubleValue\",\n \"boolean\": (x) => \"booleanValue\",\n \"string\": (x) => \"stringValue\", \n}\nlet typeName = typeNameConverter[typeof input.value](input.value)\npropertyVal[\"value\"] = {}\npropertyVal[\"value\"][typeName] = input.value;\n\noutput[\"propertyValues\"] = [propertyVal]\n\nreturn {\n payload: JSON.stringify(output)\n};",
"outputs": 1,
"timeout": "",
"noerr": 0,
"initialize": "",
"finalize": "",
"libs": [],
"x": 530,
"y": 200,
"wires": [
[
"string"
]
]
}
]
```
1. Verify that the JavaScript code translates wind speed data correctly. The function performs several important tasks:
+ Extracts the property name from the input and sets it as the propertyAlias
+ Converts the timestamp from milliseconds to the required seconds and nanoseconds format
+ Preserves the quality indicator for data reliability tracking
+ Automatically detects the value type and formats it according to AWS IoT SiteWise requirements
1. Connect the node to your flow, linking it between the data input node and the MQTT publisher.
For guidance on writing a function specific to your business needs, see [Writing Functions](https://nodered.org/docs/user-guide/writing-functions) in the *Node-RED Documentation*
## Configure the MQTT publisher
After translation, the data is ready for publication to the SiteWise Edge MQTT broker.
Configure the MQTT publisher with these settings to send data to the SiteWise Edge MQTT broker:
**To import the MQTT out node**
1. Import an MQTT out configuration node using `"type": "mqtt out"`. MQTT out nodes let you share a broker's configuration.
1. Enter key-value pairs for information relevant to MQTT broker connection and message routing.
Import the example `mqtt out` node.
**Example**
```
[
{
"id": "string",
"type": "mqtt out",
"z": "string",
"name": "Publish to MQTT broker",
"topic": "/Renton/WindFarm/Turbine/WindSpeed",
"qos": "1",
"retain": "",
"respTopic": "",
"contentType": "",
"userProps": "",
"correl": "",
"expiry": "",
"broker": "string",
"x": 830,
"y": 200,
"wires": []
},
{
"id": "string",
"type": "mqtt-broker",
"name": "emqx",
"broker": "127.0.0.1",
"port": "1883",
"clientid": "",
"autoConnect": true,
"usetls": false,
"protocolVersion": "5",
"keepalive": 15,
"cleansession": true,
"autoUnsubscribe": true,
"birthTopic": "",
"birthQos": "0",
"birthPayload": "",
"birthMsg": {},
"closeTopic": "",
"closePayload": "",
"closeMsg": {},
"willTopic": "",
"willQos": "0",
"willPayload": "",
"willMsg": {},
"userProps": "",
"sessionExpiry": ""
}
]
```
The example MQTT out node creates the MQTT connection with the following information:
+ Server: `127.0.0.1`
+ Port: `1883`
+ Protocol: `MQTT V5`
Then, the MQTT out node configures message routing with the following information:
+ Topic: `/Renton/WindFarm/Turbine/WindSpeed`
+ QoS: `1`
## Deploy and verify the nodes
After configuring the three data publish flow nodes, follow these steps to deploy the flow and verify that data is being transmitted correctly to AWS IoT SiteWise
**To deploy and verify connections**
1. Connect the three nodes as shown in the data publish flow.
![\[Data publish flow diagram showing input from turbine simulator to AWS IoT SiteWise to MQTT broker.\]](http://docs.aws.amazon.com/iot-sitewise/latest/userguide/images/gateway-open-source-nodered-publish-flow.png)
1. Choose **Deploy** to apply all node connection changes.
1. Navigate to the [AWS IoT SiteWise console](https://console.aws.amazon.com/iotsitewise/) and choose **Data streams**.
1. Ensure **Alias prefix** is selected in the dropdown menu. Then, search for the `/Renton/WindFarm/Turbine/WindSpeed` alias.
If you see the correct alias in your search, you have deployed the flow and verified data transmission.
# Configure the data retention flow
The data retention flow is can be used to maintain operational visibility at the edge. This is useful during network disruptions or when you need immediate access to your data. This flow subscribes to the MQTT broker to receive device data, converts it to InfluxDB® format, and stores it locally. By implementing this flow, you create a resilient local data store that operators can access without cloud dependencies, enabling real-time monitoring and decision-making at the edge.
The flow consists of three key components working together to ensure your data is properly captured and stored:
+ **MQTT subscription client** - Receives data from the broker, ensuring you capture all relevant industrial data
+ **InfluxDB translator** - Converts AWS IoT SiteWise payload to InfluxDB format, preparing the data for efficient time-series storage
+ **InfluxDB writer** - Handles local storage, ensuring data persistence and availability for local applications
![\[Node-RED data retention flow\]](http://docs.aws.amazon.com/iot-sitewise/latest/userguide/images/gateway-open-source-nodered-data-retention.png)
## Set up the MQTT subscription client
+ Configure the MQTT subscription client in Node-RED to receive data from the MQTT EMQX broker in AWS IoT SiteWise by importing the example below.
**Example : MQTT in node**
```
[
{
"id": "string",
"type": "mqtt in",
"z": "string",
"name": "Subscribe to MQTT broker",
"topic": "/Renton/WindFarm/Turbine/WindSpeed",
"qos": "1",
"datatype": "auto-detect",
"broker": "string",
"nl": false,
"rap": true,
"rh": 0,
"inputs": 0,
"x": 290,
"y": 340,
"wires": [
[
"string"
]
]
},
{
"id": "string",
"type": "mqtt-broker",
"name": "emqx",
"broker": "127.0.0.1",
"port": "1883",
"clientid": "",
"autoConnect": true,
"usetls": false,
"protocolVersion": "5",
"keepalive": 15,
"cleansession": true,
"autoUnsubscribe": true,
"birthTopic": "",
"birthQos": "0",
"birthPayload": "",
"birthMsg": {},
"closeTopic": "",
"closePayload": "",
"closeMsg": {},
"willTopic": "",
"willQos": "0",
"willPayload": "",
"willMsg": {},
"userProps": "",
"sessionExpiry": ""
}
]
```
This subscription ensures that all relevant data published to the broker is captured for local storage, providing a complete record of your industrial operations. The node uses the same MQTT connection parameters as the [Configure the MQTT publisher](windows-nodered-data-publish-flow.md#windows-nodered-mqtt-publisher-config) section, with the following subscription settings:
+ Topic – `/Renton/WindFarm/Turbine/WindSpeed`
+ QoS – `1`
For more information, see [Connect to an MQTT Broker](https://cookbook.nodered.org/mqtt/connect-to-broker) in the *Node-RED Documentation*.
## Configure the InfluxDB translator
InfluxDB organizes data using [tags](https://docs.influxdata.com/influxdb/v1/concepts/glossary/#tag) for indexing and [fields](https://docs.influxdata.com/influxdb/v1/concepts/glossary/#field) for values. This organization optimizes query performance and storage efficiency for time-series data. Import the example function node that contains JavaScript code to convert AWS IoT SiteWise payload to InfluxDB format. The translator splits the properties into two groups:
+ Tags – Quality and name properties for efficient indexing
+ Fields – Timestamp (in milliseconds since epoch) and value
**Example : Function node of translating to an InfluxDB payload**
```
[
{
"id": "string",
"type": "function",
"z": "string",
"name": "Translate to InfluxDB payload",
"func": "let data = msg.payload;\n\nlet timeInSeconds = data.propertyValues[0].timestamp.timeInSeconds;\nlet offsetInNanos = data.propertyValues[0].timestamp.offsetInNanos;\nlet timestampInMilliseconds = (timeInSeconds * 1000) + (offsetInNanos / 1000000);\n\nmsg.payload = [\n {\n \"timestamp(milliseconds_since_epoch)\": timestampInMilliseconds,\n \"value\": data.propertyValues[0].value.doubleValue\n },\n {\n \"name\": data.propertyAlias,\n \"quality\": data.propertyValues[0].quality\n }\n]\n\nreturn msg",
"outputs": 1,
"timeout": "",
"noerr": 0,
"initialize": "",
"finalize": "",
"libs": [],
"x": 560,
"y": 340,
"wires": [
[
"string"
]
]
}
]
```
For additional configuration options, see the [node-red-contrib-influxdb](https://github.com/mblackstock/node-red-contrib-influxdb) in the Node-RED GitHub repository.
## Set up the InfluxDB writer
The InfluxDB writer node is the final component in your data retention flow, responsible for storing your industrial data in the local InfluxDB database. This local storage is important for maintaining operational visibility during network disruptions and providing immediate access to data for time-critical applications.
1. Install the node-red-contrib-influxdb package through the Manage palette option. This package provides the necessary nodes for connecting Node-RED with InfluxDB.
1. Add an InfluxDB out node to your flow. This node will handle the actual writing of data to your InfluxDB database.
1. Configure the server properties to establish a secure connection to your InfluxDB instance:
1. Set Version to 2.0 - This specifies that you're connecting to InfluxDB v2.x, which uses a different API than earlier versions
1. Set URL to `http://127.0.0.1:8086` - This points to your local InfluxDB instance
1. Enter your InfluxDB authentication token. This secure token authorizes the connection to your database. You generated the token during the [Set up local storage with InfluxDB](windows-influxdb-setup.md) procedure.
1. Specify the storage location parameters to define where and how your data will be stored:
1. Enter your InfluxDB Organization name – The organization is a workspace for a group of users, where your buckets and dashboards belong. For more information, see [Manage organizations](https://docs.influxdata.com/influxdb/v2/admin/organizations/) in the *InfluxData Documentation*.
1. Specify the InfluxDB Bucket (for example, `WindFarmData`) – The bucket is equivalent to a database in traditional systems, serving as a container for your time series data
1. Set the InfluxDB Measurement (for example, `TurbineData`) – The measurement is similar to a table in relational databases, organizing related data points
**Note**
Find your organization name in the InfluxDB instance's left sidebar. The organization, bucket, and measurement concepts are fundamental to InfluxDB's data organization model. For more information, see the [InfluxDB documentation](https://docs.influxdata.com/influxdb/v2/admin/organizations/).
## Deploy and verify the retention flow
After configuring all components of the data retention flow, you need to deploy and verify that the system is working correctly. This verification ensures that your industrial data is being properly stored locally for immediate access and analysis.
1. Connect the three nodes as shown in the data retention flow diagram. This creates a complete pipeline from data subscription to local storage.
![\[Node-RED data retention flow\]](http://docs.aws.amazon.com/iot-sitewise/latest/userguide/images/gateway-open-source-nodered-data-retention.png)
1. Choose **Deploy** to apply your changes and activate the flow. This starts the data collection and storage process.
1. Use the InfluxDB Data Explorer to query and visualize your data. This tool allows you to verify that data is being properly stored and to create initial visualizations of your time series data.
In the Data Explorer, you should be able to see your wind speed measurements being recorded over time, confirming that the entire pipeline from data generation to local storage is functioning correctly.
For more information, see [Query in Data Explorer](https://docs.influxdata.com/influxdb/v2/query-data/execute-queries/data-explorer/) in the *InfluxData Documentation*.
With both the data publish flow and data retention flow deployed, you now have a complete system that sends data to the AWS IoT SiteWise cloud while maintaining a local copy for immediate access and resilience. This dual-path approach ensures that you get the benefits of cloud-based analytics and storage while maintaining operational visibility at the edge.
# Set up Grafana for SiteWise Edge
Grafana® lets you create local real-time monitoring dashboards for your industrial data. By visualizing the data stored in InfluxDB®, you can provide operators with immediate insights into equipment performance, process efficiency, and potential issues. This visibility at the edge is important for time-sensitive operations and maintaining continuity during network disruptions.
## Configure the data source
Connecting Grafana to your InfluxDB database creates a powerful visualization layer for your industrial data. This connection enables real-time monitoring dashboards that operators can use to make informed decisions without cloud dependencies.
1. Access your Grafana instance locally by navigating to [http://127.0.0.1:3000](http://127.0.0.1:3000) in your browser. If enabling TLS is required, you can refer to [Set up Grafana HTTPS for secure web traffic](https://grafana.com/docs/grafana/latest/setup-grafana/set-up-https/) in the *Grafana Labs Documentation*.
1. Add an InfluxDB data source pointing to the InfluxDB time series bucket where Node-RED writes data. For example, `WindFarmData`. This connection establishes the link between your stored data and the visualization platform.
1. For detailed instructions, see [Configure the InfluxDB data source](https://grafana.com/docs/grafana/latest/datasources/influxdb/configure-influxdb-data-source/) in the *Grafana Labs Documentation*.
### Create a Grafana dashboard for SiteWise Edge data
Creating a dashboard is the final step in building your local monitoring solution. Dashboards provide visual representations of your industrial data, making it easier to identify trends, anomalies, and potential issues at a glance.
+ Follow the guide to create a dashboard. For more information, see [Build your first dashboard](https://grafana.com/docs/grafana/latest/getting-started/build-first-dashboard/) in the *Grafana Labs Documentation*. This template assumes your bucket is named `WindFarmData` and measurement is `TurbineData`.
You can also use the quick start guide by importing the provided example dashboard template to quickly create a dashboard with a time series plot for the data that Node-RED generates in previous section. This template provides a starting point that you can customize to meet your specific monitoring needs.
```
{
"__inputs": [
{
"name": "DS_WINDFARM-DEMO",
"label": "windfarm-demo",
"description": "",
"type": "datasource",
"pluginId": "influxdb",
"pluginName": "InfluxDB"
}
],
"__elements": {},
"__requires": [
{
"type": "grafana",
"id": "grafana",
"name": "Grafana",
"version": "11.6.0-pre"
},
{
"type": "datasource",
"id": "influxdb",
"name": "InfluxDB",
"version": "1.0.0"
},
{
"type": "panel",
"id": "timeseries",
"name": "Time series",
"version": ""
}
],
"annotations": {
"list": [
{
"builtIn": 1,
"datasource": {
"type": "grafana",
"uid": "-- Grafana --"
},
"enable": true,
"hide": true,
"iconColor": "rgba(0, 211, 255, 1)",
"name": "Annotations & Alerts",
"type": "dashboard"
}
]
},
"editable": true,
"fiscalYearStartMonth": 0,
"graphTooltip": 0,
"id": null,
"links": [],
"panels": [
{
"datasource": {
"type": "influxdb",
"uid": "${DS_WINDFARM-DEMO}"
},
"fieldConfig": {
"defaults": {
"color": {
"mode": "palette-classic"
},
"custom": {
"axisBorderShow": false,
"axisCenteredZero": false,
"axisColorMode": "text",
"axisLabel": "",
"axisPlacement": "auto",
"barAlignment": 0,
"barWidthFactor": 0.6,
"drawStyle": "line",
"fillOpacity": 0,
"gradientMode": "none",
"hideFrom": {
"legend": false,
"tooltip": false,
"viz": false
},
"insertNulls": false,
"lineInterpolation": "linear",
"lineWidth": 1,
"pointSize": 5,
"scaleDistribution": {
"type": "linear"
},
"showPoints": "auto",
"spanNulls": false,
"stacking": {
"group": "A",
"mode": "none"
},
"thresholdsStyle": {
"mode": "off"
}
},
"mappings": [],
"thresholds": {
"mode": "absolute",
"steps": [
{
"color": "green"
},
{
"color": "red",
"value": 80
}
]
}
},
"overrides": []
},
"gridPos": {
"h": 8,
"w": 12,
"x": 0,
"y": 0
},
"id": 1,
"options": {
"legend": {
"calcs": [],
"displayMode": "list",
"placement": "bottom",
"showLegend": true
},
"tooltip": {
"hideZeros": false,
"mode": "single",
"sort": "none"
}
},
"pluginVersion": "11.6.0-pre",
"targets": [
{
"datasource": {
"type": "influxdb",
"uid": "${DS_WINDFARM-DEMO}"
},
"query": "from(bucket: \"WindFarmData\")\n |> range(start: v.timeRangeStart, stop: v.timeRangeStop)\n |> filter(fn: (r) => r[\"_measurement\"] == \"TurbineData\")\n |> filter(fn: (r) => r[\"_field\"] == \"value\")\n |> filter(fn: (r) => r[\"name\"] == \"/Renton/WindFarm/Turbine/WindSpeed\")\n |> filter(fn: (r) => r[\"quality\"] == \"GOOD\")\n |> aggregateWindow(every: v.windowPeriod, fn: mean, createEmpty: false)\n |> yield(name: \"mean\")",
"refId": "A"
}
],
"title": "Panel Title",
"type": "timeseries"
}
],
"schemaVersion": 41,
"tags": [],
"templating": {
"list": []
},
"time": {
"from": "now-6h",
"to": "now"
},
"timepicker": {},
"timezone": "browser",
"title": "demo dashboard",
"uid": "fejc0t08o6d4wb",
"version": 1,
"weekStart": ""
}
```
# Set up open-source integrations with Docker (Linux)
Docker setup using Linux
For a streamlined deployment process, you can use Docker to set up Node-RED®, InfluxDB®, and Grafana® on a Linux environment. This method uses pre-configured containers, allowing for rapid deployment and easier management of the components.
## Docker setup prerequisites
Before you begin, verify that have the following:
+ An MQTT-enabled, V3 gateway. For more information, see [MQTT-enabled, V3 gateways for AWS IoT SiteWise Edge](mqtt-enabled-v3-gateway.md).
+ The Docker Compose plugin. For installation steps, see [Install the Docker Compose plugin](https://docs.docker.com/compose/install/linux/) in the *Docker* Manuals documentation.
## Deploy the services
This deployment runs SiteWise Edge, InfluxDB, Node-RED, and Grafana on the same host.
### Set up the environment
1. Gain root access:
```
sudo -i
```
1. Create a .env file or export these environment variables:
```
export INFLUXDB_PASSWORD=your-secure-influxdb-password
export INFLUXDB_TOKEN=your-secure-influxdb-token
export GRAFANA_PASSWORD=your-secure-grafana-password
```
### Configure the Docker network
+ Create a bridge network using the name `SiteWiseEdgeNodeRedDemoNetwork`.
```
docker network create --driver=bridge SiteWiseEdgeNodeRedDemoNetwork
```
### Prepare the Docker Compose file
Copy the contents of the following YAML file to your SiteWise Edge gateway device.
#### Expand to view the Docker Compose YAML file example
```
services:
influxdb:
image: influxdb:latest
container_name: influxdb
ports:
- "127.0.0.1:8086:8086"
volumes:
- influxdb-storage:/.influxdbv2
environment:
- DOCKER_INFLUXDB_INIT_MODE=setup
- DOCKER_INFLUXDB_INIT_USERNAME=admin
- DOCKER_INFLUXDB_INIT_PASSWORD=${INFLUXDB_PASSWORD}
- DOCKER_INFLUXDB_INIT_ORG=iot-sitewise-edge
- DOCKER_INFLUXDB_INIT_BUCKET=WindFarmData
- DOCKER_INFLUXDB_INIT_RETENTION=0
- DOCKER_INFLUXDB_INIT_ADMIN_TOKEN=${INFLUXDB_TOKEN}
networks:
- SiteWiseEdgeNodeRedDemoNetwork
restart: unless-stopped
grafana:
image: grafana/grafana:latest
container_name: grafana
ports:
- "127.0.0.1:3000:3000"
volumes:
- grafana-storage:/var/lib/grafana
- ./grafana/provisioning:/etc/grafana/provisioning
environment:
- GF_SECURITY_ADMIN_USER=admin
- GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASSWORD}
- GF_INSTALL_PLUGINS=grafana-clock-panel,grafana-simple-json-datasource
- GF_PATHS_PROVISIONING=/etc/grafana/provisioning
- GF_PATHS_CONFIG=/etc/grafana/grafana.ini
- GF_LOG_LEVEL=info
configs:
- source: grafana_datasource
target: /etc/grafana/provisioning/datasources/influxdb.yaml
- source: grafana_preload_dashboard_config
target: /etc/grafana/provisioning/dashboards/dashboard.yml
- source: grafana_preload_dashboard
target: /etc/grafana/provisioning/dashboards/demo_dashboard.json
depends_on:
- influxdb
networks:
- SiteWiseEdgeNodeRedDemoNetwork
restart: unless-stopped
nodered:
build:
context: .
dockerfile_inline: |
FROM nodered/node-red:latest
RUN npm install node-red-contrib-influxdb
container_name: nodered
ports:
- "127.0.0.1:1880:1880"
volumes:
- node_red_data:/data
environment:
- NODE_RED_ENABLE_SAFE_MODE=false
- NODE_RED_ENABLE_PALETTE_EDIT=true
- NODE_RED_AUTO_INSTALL_MODULES=true
configs:
- source: nodered_flows
target: /data/flows.json
- source: nodered_settings
target: /data/settings.js
- source: nodered_flows_cred
target: /data/flows_cred.json
depends_on:
- influxdb
networks:
- SiteWiseEdgeNodeRedDemoNetwork
restart: unless-stopped
volumes:
influxdb-storage:
grafana-storage:
node_red_data:
networks:
SiteWiseEdgeNodeRedDemoNetwork:
external: true
configs:
grafana_datasource:
content: |
apiVersion: 1
datasources:
- name: windfarm-demo
type: influxdb
access: proxy
url: http://influxdb:8086
jsonData:
version: Flux
organization: iot-sitewise-edge
defaultBucket: WindFarmData
tlsSkipVerify: true
secureJsonData:
token: ${INFLUXDB_TOKEN}
editable: false
grafana_preload_dashboard_config:
content: |
apiVersion: 1
providers:
- name: "Dashboard provider"
orgId: 1
type: file
options:
path: /etc/grafana/provisioning/dashboards
grafana_preload_dashboard:
content: |
{
"annotations": {
"list": [
{
"builtIn": 1,
"datasource": {
"type": "grafana",
"uid": "-- Grafana --"
},
"enable": true,
"hide": true,
"iconColor": "rgba(0, 211, 255, 1)",
"name": "Annotations & Alerts",
"type": "dashboard"
}
]
},
"editable": true,
"fiscalYearStartMonth": 0,
"graphTooltip": 0,
"id": 1,
"links": [],
"panels": [
{
"datasource": {
"type": "influxdb",
"uid": "PEB0DCBF338B3CEB2"
},
"fieldConfig": {
"defaults": {
"color": {
"mode": "palette-classic"
},
"custom": {
"axisBorderShow": false,
"axisCenteredZero": false,
"axisColorMode": "text",
"axisLabel": "",
"axisPlacement": "auto",
"barAlignment": 0,
"barWidthFactor": 0.6,
"drawStyle": "line",
"fillOpacity": 0,
"gradientMode": "none",
"hideFrom": {
"legend": false,
"tooltip": false,
"viz": false
},
"insertNulls": false,
"lineInterpolation": "linear",
"lineWidth": 1,
"pointSize": 5,
"scaleDistribution": {
"type": "linear"
},
"showPoints": "auto",
"spanNulls": false,
"stacking": {
"group": "A",
"mode": "none"
},
"thresholdsStyle": {
"mode": "off"
}
},
"mappings": [],
"thresholds": {
"mode": "absolute",
"steps": [
{
"color": "green"
},
{
"color": "red",
"value": 80
}
]
}
},
"overrides": []
},
"gridPos": {
"h": 8,
"w": 12,
"x": 0,
"y": 0
},
"id": 1,
"options": {
"legend": {
"calcs": [],
"displayMode": "list",
"placement": "bottom",
"showLegend": true
},
"tooltip": {
"hideZeros": false,
"mode": "single",
"sort": "none"
}
},
"pluginVersion": "11.6.0",
"targets": [
{
"datasource": {
"type": "influxdb",
"uid": "PEB0DCBF338B3CEB2"
},
"query": "from(bucket: \"WindFarmData\")\n |> range(start: v.timeRangeStart, stop: v.timeRangeStop)\n |> filter(fn: (r) => r[\"_measurement\"] == \"TurbineData\")\n |> filter(fn: (r) => r[\"_field\"] == \"value\")\n |> filter(fn: (r) => r[\"name\"] == \"/Renton/WindFarm/Turbine/WindSpeed\")\n |> filter(fn: (r) => r[\"quality\"] == \"GOOD\")\n |> aggregateWindow(every: v.windowPeriod, fn: mean, createEmpty: false)\n |> yield(name: \"mean\")",
"refId": "A"
}
],
"title": "Wind Speed",
"type": "timeseries"
}
],
"preload": false,
"schemaVersion": 41,
"tags": [],
"templating": {
"list": []
},
"time": {
"from": "now-6h",
"to": "now"
},
"timepicker": {},
"timezone": "browser",
"title": "Demo Dashboard",
"uid": "eejtureqjo9a8c",
"version": 2
}
nodered_flows:
content: |
[
{
"id": "95fce448fdd43b47",
"type": "tab",
"label": "Demo Flow",
"disabled": false,
"info": ""
},
{
"id": "5f63740b66af3386",
"type": "mqtt out",
"z": "95fce448fdd43b47",
"name": "Publish to MQTT broker",
"topic": "/Renton/WindFarm/Turbine/WindSpeed",
"qos": "1",
"retain": "",
"respTopic": "",
"contentType": "",
"userProps": "",
"correl": "",
"expiry": "",
"broker": "5744207557fa19be",
"x": 830,
"y": 200,
"wires": []
},
{
"id": "8f2eb590d596679b",
"type": "function",
"z": "95fce448fdd43b47",
"name": "Translate to SiteWise payload",
"func": "let input = msg.payload;\nlet output = {};\n\noutput[\"propertyAlias\"] = input.name;\n\nlet propertyVal = {}\n\nlet timeInSeconds = Math.floor(input.timestamp / 1000);\nlet offsetInNanos = (input.timestamp % 1000) * 1000000;\n\npropertyVal[\"timestamp\"] = {\n \"timeInSeconds\": timeInSeconds,\n \"offsetInNanos\": offsetInNanos,\n};\n\npropertyVal[\"quality\"] = input.quality\n\nlet typeNameConverter = {\n \"number\": (x) => Number.isInteger(x) ? \"integerValue\" : \"doubleValue\",\n \"boolean\": (x) => \"booleanValue\",\n \"string\": (x) => \"stringValue\", \n}\nlet typeName = typeNameConverter[typeof input.value](input.value)\npropertyVal[\"value\"] = {}\npropertyVal[\"value\"][typeName] = input.value;\n\noutput[\"propertyValues\"] = [propertyVal]\n\nreturn {\n payload: JSON.stringify(output)\n};",
"outputs": 1,
"timeout": "",
"noerr": 0,
"initialize": "",
"finalize": "",
"libs": [],
"x": 530,
"y": 200,
"wires": [
[
"5f63740b66af3386"
]
]
},
{
"id": "4b78cbdea5e3258c",
"type": "inject",
"z": "95fce448fdd43b47",
"name": "Turbine Simulator",
"props": [
{
"p": "payload.timestamp",
"v": "",
"vt": "date"
},
{
"p": "payload.quality",
"v": "GOOD",
"vt": "str"
},
{
"p": "payload.value",
"v": "$$random()",
"vt": "jsonata"
},
{
"p": "payload.name",
"v": "/Renton/WindFarm/Turbine/WindSpeed",
"vt": "str"
}
],
"repeat": "1",
"crontab": "",
"once": false,
"onceDelay": "",
"topic": "",
"x": 270,
"y": 200,
"wires": [
[
"8f2eb590d596679b"
]
]
},
{
"id": "b658bf337ea2e316",
"type": "influxdb out",
"z": "95fce448fdd43b47",
"influxdb": "2f1c38495035d2e4",
"name": "Store data in InfluxDB",
"measurement": "TurbineData",
"precision": "",
"retentionPolicy": "",
"database": "",
"retentionPolicyV18Flux": "",
"org": "iot-sitewise-edge",
"bucket": "WindFarmData",
"x": 840,
"y": 340,
"wires": []
},
{
"id": "9432d39af35b202f",
"type": "function",
"z": "95fce448fdd43b47",
"name": "Translate to InfluxDB payload",
"func": "let data = msg.payload;\n\nlet timeInSeconds = data.propertyValues[0].timestamp.timeInSeconds;\nlet offsetInNanos = data.propertyValues[0].timestamp.offsetInNanos;\nlet timestampInMilliseconds = (timeInSeconds * 1000) + (offsetInNanos / 1000000);\n\nmsg.payload = [\n {\n \"timestamp(milliseconds_since_epoch)\": timestampInMilliseconds,\n \"value\": data.propertyValues[0].value.doubleValue\n },\n {\n \"name\": data.propertyAlias,\n \"quality\": data.propertyValues[0].quality\n }\n]\n\nreturn msg",
"outputs": 1,
"timeout": "",
"noerr": 0,
"initialize": "",
"finalize": "",
"libs": [],
"x": 560,
"y": 340,
"wires": [
[
"b658bf337ea2e316"
]
]
},
{
"id": "b689403d2c80816b",
"type": "mqtt in",
"z": "95fce448fdd43b47",
"name": "Subscribe to MQTT broker",
"topic": "/Renton/WindFarm/Turbine/WindSpeed",
"qos": "1",
"datatype": "auto-detect",
"broker": "5744207557fa19be",
"nl": false,
"rap": true,
"rh": 0,
"inputs": 0,
"x": 290,
"y": 340,
"wires": [
[
"9432d39af35b202f"
]
]
},
{
"id": "4f59bed8e829fc35",
"type": "comment",
"z": "95fce448fdd43b47",
"name": "Data Publish Flow",
"info": "dfgh",
"x": 270,
"y": 160,
"wires": []
},
{
"id": "b218c7fc58c8b6e7",
"type": "comment",
"z": "95fce448fdd43b47",
"name": "Data Retention flow",
"info": "",
"x": 270,
"y": 300,
"wires": []
},
{
"id": "5744207557fa19be",
"type": "mqtt-broker",
"name": "emqx",
"broker": "emqx",
"port": "1883",
"clientid": "",
"autoConnect": true,
"usetls": false,
"protocolVersion": "5",
"keepalive": 15,
"cleansession": true,
"autoUnsubscribe": true,
"birthTopic": "",
"birthQos": "0",
"birthPayload": "",
"birthMsg": {},
"closeTopic": "",
"closePayload": "",
"closeMsg": {},
"willTopic": "",
"willQos": "0",
"willPayload": "",
"willMsg": {},
"userProps": "",
"sessionExpiry": ""
},
{
"id": "2f1c38495035d2e4",
"type": "influxdb",
"hostname": "influxdb",
"port": 8086,
"protocol": "http",
"database": "",
"name": "InfluxDB",
"usetls": false,
"tls": "",
"influxdbVersion": "2.0",
"url": "http://influxdb:8086",
"timeout": "",
"rejectUnauthorized": false
}
]
nodered_flows_cred:
content: |
{
"2f1c38495035d2e4": {
"token": "${INFLUXDB_TOKEN}"
}
}
nodered_settings:
content: |
module.exports = {
flowFile: 'flows.json',
credentialSecret: false,
adminAuth: null,
editorTheme: {
projects: {
enabled: false
}
}
}
```
### Update the SiteWise Edge deployment
1. Navigate to the [AWS IoT console](https://console.aws.amazon.com/iot/)
1. Choose **Greengrass devices** in the left navigation menu under the **Manage** section, then **Core devices**.
1. Select the core device connected to your SiteWise Edge Gateway.
1. Choose the **Deployments** tab, then select the **Deployment ID** value.
1. Choose **Actions**, then select **Revise**.
1. Read the pop up message and then choose **Revise Deployment**.
1. In **Step 2 - Select components**, select the following components and then choose **Next**.
+ `aws.greengrass.clientdevices.mqtt.EMQX`
+ `aws.iot.SiteWiseEdgePublisher`
1. In **Step 3 - Configure components**, select the `aws.greengrass.clientdevices.mqtt.EMQX` component value and add the following network configuration:
```
{
"emqxConfig": {
"authorization": {
"no_match": "allow"
},
"listeners": {
"tcp": {
"default": {
"enabled": true,
"enable_authn": false
}
}
}
},
"authMode": "bypass",
"dockerOptions": "-p 127.0.0.1:1883:1883 --network=SiteWiseEdgeNodeRedDemoNetwork",
"requiresPrivilege": "true"
}
```
1. Choose **Next**.
1. In **Step 4 - Configure advanced settings**, choose **Next**.
1. Choose **Deploy**
### Launch the services
1. Start the services using the Docker Compose file. Run the following command under the directory containing the `compose.yaml` file.
```
docker compose up -d
```
1. Create an SSH tunnel to access the services:
```
ssh -i path_to_your_ssh_key -L 1880:127.0.0.1:1880 -L 3000:127.0.0.1:3000 -L 8086:127.0.0.1:8086 username@gateway_ip_address
```
This deployment creates the following services in the `SiteWiseEdgeNodeRedDemoNetwork network`:
**InfluxDB v2 (port 8086)**
Includes pre-configured organization (iot-sitewise-edge), WindFarmData InfluxDB bucket, and admin credentials
**Node-RED (port 1880)**
Includes InfluxDB nodes and pre-configured flows for AWS IoT SiteWise integration
**Grafana (port 3000)**
Includes admin user, InfluxDB datasource, and monitoring dashboard
### Access the services
After deployment, access the services using the following URLs and credentials:
**Note**
You can access each service from your host or the gateway machine.
**Service access details**
| Service | URL | Credentials |
| --- | --- | --- |
| Node-RED | [http://127.0.0.1:1880](http://127.0.0.1:1880) | No credentials required |
| InfluxDB | [http://127.0.0.1:8086](http://127.0.0.1:8086) | Username: admin Password: \$1INFLUXDB\$1PASSWORD |
| Grafana | [http://127.0.0.1:3000](http://127.0.0.1:3000) | Username: admin Password: \$1GRAFANA\$1PASSWORD |
## Verify the deployment
To ensure your deployment is successful, perform the following checks:
1. For Node-RED, verify the presence of two preloaded flows:
+ Data publish flow
+ Data retention flow
1. For AWS IoT SiteWise, in the AWS IoT SiteWise console, confirm the presence of a data stream with the alias `/Renton/WindFarm/Turbine/WindSpeed`.
1. For InfluxDB, use the Data Explorer to verify data storage in the `TurbineData` measurement within the `WindFarmData` bucket.
1. For Grafana, view the dashboard to confirm the display of time series data generated from Node-RED.
# Process data for open source integrations
The data can be processed (such as transformation or aggregation), at different stages using various tools, each serving different monitoring requirements.
## Process data with Node-RED nodes
Transform your data in real time using Node-RED® built-in processing nodes. Configure these nodes through the Node-RED console to create your data pipeline.
### Data transformation nodes
Transform individual data points, similar to Transforms in AWS IoT SiteWise, using these nodes:
+ **change node** - Performs simple value modifications on your data.
+ **function node** - Enables custom JavaScript transformations for complex data processing.
### Metrics calculation nodes
Combine multiple data points into a single output, similar to Metrics in AWS IoT SiteWise, using these nodes:
+ **batch node** - Groups multiple messages for batch processing.
+ **join node** - Combines multiple data streams into a single output.
+ **aggregator node** - Calculates aggregate metrics from multiple data points.
For additional node options, see the [Node-RED Library](https://flows.nodered.org/).
## Create InfluxDB tasks
While Node-RED excels at basic data processing with quick setup, complex metric calculations may become challenging in flow-based programming. InfluxDB® Tasks provide an alternative through scheduled Flux scripts for advanced processing needs.
Use InfluxDB Tasks for:
+ Statistical aggregations across large datasets
+ Mathematical operations on multiple properties
+ Derived measurements from multiple sources
### Task features
+ **Scheduled Execution** - Run tasks based on cron expressions
+ **Batch Processing** - Optimize operations for time-series data
+ **Error Recovery** - Automatically retry failed operations
+ **Monitoring** - Track execution through detailed logs
Manage tasks through the InfluxDB UI, API, or CLI. For more information, see [Process data with InfluxDB tasks](https://docs.influxdata.com/influxdb/cloud/process-data/).
## Use Grafana transformations
Transform data visualization in Grafana® without modifying the source data in InfluxDB. Grafana transformations apply only to the visualization layer.
+ **Visual Builder** - Create transformations without writing code
+ **Live Preview** - View transformation results in real time
+ **Multi-Source** - Process data from multiple database sources
+ **Storage Efficient** - Transform data at visualization time without storing intermediary results
For more information, see [Transform data](https://grafana.com/docs/grafana/latest/panels/transform-data/).
## Troubleshooting open-source integrations
For more information on troubleshooting topics related to open source integrations for SiteWise Edge gateways, see [Troubleshooting open-source integrations at the Edge](troubleshooting-gateway.md#open-source-troubleshooting).
# Classic streams, V2 gateways for AWS IoT SiteWise Edge
Classic streams, V2 gateways
Understand the features and limitations of Classic streams, V2 gateways for AWS IoT SiteWise Edge.
The Classic streams, V2 gateway maintains traditional functionality familiar from earlier AWS IoT SiteWise deployments before the introduction of MQTT-enabled, V3 gateways. These SiteWise Edge gateways are considered Classic streams, V2 gateways. They maintain backward compatibility and are functional with the data processing pack. While the Classic streams, V2 gateway offers reliable performance for existing setups, it has limitations compared to newer gateway options. Specifically, this gateway type is not fully compatible with the advanced features available in the MQTT-enabled, V3 gateway destination. To use the MQTT messaging protocol, you can create a new MQTT-enabled, V3 gateway. For more information, see [MQTT-enabled, V3 gateways for AWS IoT SiteWise Edge](mqtt-enabled-v3-gateway.md).
**Topics**
+ [
# Use packs to collect and process data in SiteWise Edge
](data-packs.md)
+ [
# Configure the AWS IoT SiteWise publisher component
](configure-publisher-component.md)
+ [
# Destinations and AWS IoT Greengrass stream manager
](destinations-gg-stream-manager.md)
+ [
# Configure edge capabilities on AWS IoT SiteWise Edge
](edge-data-collection-and-processing.md)
+ [
# Configure edge data processing for AWS IoT SiteWise models and assets
](edge-processing.md)
# Use packs to collect and process data in SiteWise Edge
Use packs
**Note**
The data processing pack (DPP) feature is no longer availabke to new customers. Existing customers can continue to use the service as normal. For more information, see [Data processing pack availability change](https://docs.aws.amazon.com/iot-sitewise/latest/appguide/iotsitewise-dpp-availability-change.html).
AWS IoT SiteWise Edge gateways use different packs to determine how to collect and process your data.
Currently, the following packs are available:
+ **Data collection pack** – Use this pack to collect your industrial data and route it to AWS Cloud destinations. By default, this pack is enabled automatically for your SiteWise Edge gateway.
+ **Data processing pack** – Use this pack to enable SiteWise Edge gateway communication with edge-configured asset models and assets. You can use edge configuration to control what asset data to compute and process on-site. You can then send your data to AWS IoT SiteWise or other AWS services. For more information about the data processing pack, see [Configure edge data processing for AWS IoT SiteWise models and assets](edge-processing.md).
## Upgrading packs
**Important**
Upgrading data processing pack versions from before (and including) 2.0.x to version 2.1.x will result in data loss of locally stored measurements.
SiteWise Edge gateways use different packs to determine how to collect and process your data. You can use the AWS IoT SiteWise console to upgrade packs.
**To upgrade packs (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. In the **Gateways** list, choose the SiteWise Edge gateway with the packs you want to upgrade.
1. In the **Gateway configuration** section, choose **Software updates available**.
1. On the Edit software versions page, choose **Updates**.
**Note**
You can only upgrade packs that are enabled. To find the list of packs that are enabled for this SiteWise Edge gateway, choose **Overview**, and then see the **Edge capabilities** section.
1. On the edit software versions page, in the **Gateway component updates** section, do the following:
+ To update the **OPC UA collector**, choose a version, and then choose **Deploy**.
+ To update the **Publisher**, choose a version, and then choose **Deploy**.
+ To update the **Data processing pack**, choose a version, and then choose **Deploy**.
1. When you're done deploying new versions, choose **Done**.
If you're experiencing problems upgrading the packs, see [Unable to deploy packs to SiteWise Edge gateways](troubleshooting-gateway.md#gateway-issue-ggv2-packs).
# Data processing pack availability change
**Note**
The data processing pack (DPP) feature is no longer availabke to new customers. Existing customers can continue to use the service as normal. For more information, see [Data processing pack availability change](https://docs.aws.amazon.com/iot-sitewise/latest/appguide/iotsitewise-dpp-availability-change.html).
For capabilities similar to AWS IoT data processing pack feature explore either [open-source alternatives](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/open-source-edge-integrations.html) or our [partner integrations](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/cpa-add-source.html). The AWS IoT SiteWise Data Processing Pack is a feature of AWS IoT SiteWise that provides data transformations, metrics, filtering, local storage and visualization at the edge.
**Note**
AWS IoT SiteWise and the AWS IoT SiteWise Edge data collection pack feature continues to be available, but the data processing pack feature is entering maintenance mode.
## Migration options
Explore these migration options for replacing the data processing pack functionality.
**Open-source alternatives**
Create local data processing pipelines using Node-RED for data transformation, InfluxDB for time-series storage, and Grafana for visualization. These tools work with MQTT-enabled, V3 gateways through MQTT to provide edge processing and local insights while synchronizing data with the AWS Cloud.
For more information, see [Process and visualize data with SiteWise Edge and open-source tools](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/open-source-edge-integrations.html).
**Partner integrations**
Connect industrial equipment and sensors through third-party partner data sources like CloudRail, EasyEdge, and Litmus Edge. These Greengrass components are developed in partnership with AWS and support over 200 industrial protocols for comprehensive data collection and processing.
For more information, see [Add a data source](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/cpa-add-source.html).
**MQTT-enabled, V3 gateways**
MQTT-enabled, V3 gateways use lightweight MQTT protocol for efficient data communication and offer flexible data destinations including real-time ingestion and buffered Amazon S3 ingestion. You can implement path filters for precise data collection and benefit from improved scalability and IoT standards alignment. MQTT-enabled, V3 gateways provide cloud-based data processing through AWS IoT SiteWise core services including asset models, computed properties, alarms, and historical data queries.
For more information, see [MQTT-enabled, V3 gateways for AWS IoT SiteWise Edge](mqtt-enabled-v3-gateway.md).
## Frequently asked questions
### Can I migrate gradually?
Yes, you can migrate gradually using any combination of the migration options. You can deploy MQTT-enabled, V3 gateways, open-source alternatives, or partner integrations alongside existing Classic streams, V2 gateways with the data processing pack. All options can send data to the same AWS IoT SiteWise environment.
### How long can I continue using the data processing pack?
The data processing pack remains available to existing customers in maintenance mode. You'll receive advance notice if any changes to availability are planned. Monitor AWS service announcements and your account notifications for updates.
# Configure the AWS IoT SiteWise publisher component
Configure the publisher
After you create an AWS IoT SiteWise Edge gateway and install the software, you can set up the publisher component so your SiteWise Edge gateway can export data to the AWS Cloud. Use the publisher component to enable additional features or configure default settings. For more information, see [AWS IoT SiteWise publisher](https://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-publisher-component.html) in the *AWS IoT Greengrass Version 2 Developer Guide*.
**Note**
The publisher configuration differs based on the type of gateway you're using. For Classic stream, V2 gateways, use the `iotsitewise:publisher:2` namespace. For MQTT-enabled, V3 gateways, use the `iotsitewise:publisher:3` namespace.
------
#### [ Console ]
1. Navigate to the [AWS IoT SiteWise console](https://console.aws.amazon.com/iotsitewise/).
1. In the navigation pane, choose **Edge gateways**.
1. Select the SiteWise Edge gateway for which you want to configure the publisher.
1. In the **Publisher configuration** section, choose **Edit**
1. For **Publishing order**, choose one of the following:
+ **Publish oldest data first** – The SiteWise Edge gateway publishes the oldest data to the cloud first by default.
+ **Publish newest data first** – The SiteWise Edge gateway publishes the newest data to the cloud first.
1. (Optional) If you don't want the SiteWise Edge gateway to compress your data, unselect **Activate compression when uploading data**.
1. (Optional) If you don't want to publish old data, choose **Exclude expired data** and do the following:
1. For **Cutoff period**, enter a value and choose a unit. The cutoff period must be between five minutes and seven days. For example, if the cutoff period is three days, data that's older than three days isn't published to the cloud.
1. (Optional) To set custom settings about how data is handled on your local device, choose **Local storage settings** and do the following:
1. For **Retention period**, enter a number and choose a unit. The retention period must be between one minute and 30 days, and greater than or equal to the rotation period. For example, if the retention period is 14 days, the SiteWise Edge gateway deletes any data at the edge that's older than the specified cutoff period after it's stored for 14 days.
1. For **Rotation period**, enter a number and choose a unit. The rotation period must be greater than one minute, and equal to, or less than, the retention period. For example, say the rotation period is two days, the SiteWise Edge gateway batches up and saves data that is older than the cutoff period to a single file. For self-hosted gateways through AWS IoT Greengrass V2, the SiteWise Edge gateway transfers a batch of data to the following local directory once every two days: `/greengrass/v2/work/aws.iot.SiteWiseEdgePublisher/exports`.
1. For **Storage capacity**, enter a value that is greater than or equal to 1. If the storage capacity is 2 GB, the SiteWise Edge gateway starts deleting data when more than 2 GB of data is stored locally.
1. Choose **Save**.
------
#### [ AWS CLI ]
Use the [UpdateGatewayCapabilityConfiguration](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_UpdateGatewayCapabilityConfiguration.html) API to configure the publisher.
Set the `capabilityNamespace` parameter to `iotsitewise:publisher:2`.
**Example : Publisher configuration for Classic Stream, V2 gateways**
The publisher namespace: `iotsitewise:publisher:2`
```
{
"SiteWisePublisherConfiguration": {
"publishingOrder": "TIME_ORDER",
"enableCompression": true,
"dropPolicy": {
"cutoffAge": "7d",
"exportPolicy": {
"retentionPeriod": "7d",
"rotationPeriod": "6h",
"exportSizeLimitGB": 10
}
}
},
"SiteWiseS3PublisherConfiguration": {
"accessRoleArn": "arn:aws:iam:123456789012:role/roleName",
"streamToS3ConfigMapping": [
{
"streamName": "S3_OPC-UA_Data_Collector",
"targetBucketArn": "arn:aws:s3:::amzn-s3-demo-bucket/dataCollector",
"publishPolicy": {
"publishFrequency": "10m",
"localSizeLimitGB": 10
},
"siteWiseImportPolicy": {
"enableSiteWiseStorageImport": true,
"enableDeleteAfterImport": true
}
}
]
}
}
```
The publisher provides the following configuration parameters that you can customize:
`SiteWisePublisherConfiguration`
`publishingOrder`
The order in which data is published to the cloud. The value of this parameter can be one of the following:
+ `TIME_ORDER` (**Publish oldest data first**) – The earliest data is published to the cloud first, by default.
+ `RECENT_DATA` (**Publish newest data first**) – The newest data is published to the cloud first.
`enableCompression`
Set this to `true` to compress data before publishing. Data compression can reduce bandwidth usage.
`dropPolicy`
(Optional) A policy that controls what data is published to the cloud.
`cutoffAge`
The maximum age of data to be published specified in days, hours, and minutes. For example, `7d` or `1d7h16m`. Data older than what you specify is not sent to AWS IoT SiteWise.
Data that is earlier than the cutoff period is not published to the cloud. The cutoff age must be between five minutes and seven days.
You can use `m`, `h`, and `d` when you specify a cutoff age. Note that `m` represents minutes, `h` represents hours, and `d` represents days.
`exportPolicy`
(Optional) A policy that manages data storage at the edge. This policy applies to data that is earlier than the cutoff age.
`retentionPeriod`
Your SiteWise Edge gateway deletes any data at the edge that is earlier than the cutoff period from the local storage after it is stored for the specified retention period. The retention period must be between one minute and 30 days, and greater than or equal to the rotation period.
You can use `m`, `h`, and `d` when you specify a retention period. Note that `m` represents minutes, `h` represents hours, and `d` represents days.
`rotationPeriod`
The time interval over which to batch up and save data that is earlier than the cutoff period to a single file. The SiteWise Edge gateway transfers one batch of data to the following local directory at the end of each rotation period: `/greengrass/v2/work/aws.iot.SiteWiseEdgePublisher/exports`. The rotation period must be greater than one minute, and equal to or less than the retention period.
You can use `m`, `h`, and `d` when you specify a rotation period. Note that `m` represents minutes, `h` represents hours, and `d` represents days.
`exportSizeLimitGB`
The maximum allowed size of data stored locally, in GB. If this quota is breached, the SiteWise Edge gateway starts deleting the earliest data until the size of data stored locally is equal to or less than the quota. The value of this parameter must be greater than or equal to 1.
`SiteWiseS3PublisherConfiguration`
`accessRoleArn`
The access role that gives AWS IoT SiteWise permission to manage the Amazon S3 bucket that you are publishing to.
`streamToS3ConfigMapping`
An array of configurations that maps a stream to an Amazon S3 configuration.
`streamName`
The stream to read from and publish to the Amazon S3 configuration.
`targetBucketArn`
The bucket ARN to publish to.
`publishPolicy`
`publishFrequency`
The frequency with which the SiteWise Edge gateway publishes to the Amazon S3 bucket.
`localSizeLimitGB`
The maximum size of the files written to local disk. If this threshold is breached, the publisher publishes all buffered data to its destination.
`siteWiseImportPolicy`
`enableSiteWiseStorageImport`
Set this to `true` to import data from an Amazon S3 bucket to AWS IoT SiteWise storage.
`enableDeleteAfterImport`
Set this to `true` to delete the file in the Amazon S3 bucket after ingestion into the AWS IoT SiteWise storage.
------
# Destinations and AWS IoT Greengrass stream manager
AWS IoT Greengrass stream manager
AWS IoT Greengrass stream manager allows you 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*.
**Example : Data stream message structure**
The following example shows the required data stream message structure transmitted by the AWS IoT Greengrass stream manager.
```
{
"assetId": "string",
"propertyAlias": "string",
"propertyId": "string",
"propertyValues": [
{
"quality": "string",
"timestamp": {
"offsetInNanos": number,
"timeInSeconds": number
},
"value": {
"booleanValue": boolean,
"doubleValue": number,
"integerValue": number,
"stringValue": "string"
}
}
]
}
```
**Note**
The data stream message must include either (`assetId` and `propertyId`) or `propertyAlias` in its structure.
`assetId`
(Optional) The ID of the asset to update.
`propertyAlias`
(Optional) The alias that identifies the property, such as an OPC UA server data stream path. For example:
```
/company/windfarm/3/turbine/7/temperature
```
For more information, see [ Manage data streams](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/manage-data-streams.html) in the *AWS IoT SiteWise User Guide*.
`propertyId`
(Optional) The ID of the asset property for this entry.
`propertyValues`
(Required) The list of property values to upload. You can specify up to 10 `propertyValues` array elements.
`quality`
(Optional) The quality of the asset property value.
`timestamp`
(Required) The timestamp of the asset property value.
`offsetInNanos`
(Optional) The nanosecond offset from `timeInSeconds`.
`timeInSeconds`
(Required) The timestamp date, in seconds, in the Unix epoch format. Fractional nanosecond data is provided by `offsetInNanos`.
`value`
(Required) The value of the asset property.
Only one of the following values can exist in the `value` field.
`booleanValue`
(Optional) Asset property data of type Boolean (`true` or `false`).
`doubleValue`
(Optional) Asset property data of type double (floating point number).
`integerValue`
(Optional) Asset property data of type integer (whole number).
`stringValue`
(Optional) Asset property data of type string (sequence of characters).
# Configure edge capabilities on AWS IoT SiteWise Edge
Configure edge capabilities
**Note**
The data processing pack (DPP) feature is no longer availabke to new customers. Existing customers can continue to use the service as normal. For more information, see [Data processing pack availability change](https://docs.aws.amazon.com/iot-sitewise/latest/appguide/iotsitewise-dpp-availability-change.html).
You can use AWS IoT SiteWise Edge to collect and temporarily store data so that you can organize and process device data locally. By enabling edge processing, you can choose to send only aggregated data to the AWS Cloud to optimize your bandwidth usage and cloud storage costs. Using AWS IoT SiteWise components with AWS IoT Greengrass, you can collect and process data at the edge before sending it to the AWS Cloud, or manage it on-premises using SiteWise Edge APIs.
Data collection happens through data packs and AWS IoT SiteWise components that run on AWS IoT Greengrass.
**Note**
AWS IoT SiteWise retains your edge data on your SiteWise Edge gateways up to 30 days. The retention period of your data is dependent on the available disk space of your device.
If your SiteWise Edge gateway has been disconnected from the AWS Cloud for 30 days, the [Data Processing Pack](configure-opcua-source.md) is automatically disabled.
**Topics**
+ [
## Set up edge capability in SiteWise Edge
](#using-sitewise-edge)
## Set up edge capability in SiteWise Edge
Set up edge capability
AWS IoT SiteWise provides the following packs that your SiteWise Edge gateway can use to determine how to collect and process your data. Select packs to enable edge capabilities for your SiteWise Edge gateway.
+ **Data collection pack** enables your SiteWise Edge gateway to collect data from multiple OPC UA servers, and then export the data from the edge to the AWS Cloud. It becomes active once you have added data sources to your SiteWise Edge gateway.
+ **Data processing pack** enables your SiteWise Edge gateway to process your equipment data at the edge. For example, you can use asset models to compute metrics and transforms. For more information about asset models and assets, see [Model industrial assets](industrial-asset-models.md).
**Note**
The data processing pack is only available on x86 platforms.
**To configure edge capabilities**
1. Navigate to the [AWS IoT SiteWise console](https://console.aws.amazon.com/iotsitewise/).
1. In the navigation pane, choose **Edge gateways**.
1. Select the SiteWise Edge gateway for which you want to activate edge capabilities.
1. In the **Edge capabilities** section, choose **Edit**
1. In the **Edge capabilities** section, select **Enable data processing pack (incurs additional charges)**.
1. (Optional) In the **Edge LDAP connection** section, you can grant user groups in your corporate directory access to this SiteWise Edge gateway. The user groups can use the Lightweight Directory Access Protocol (LDAP) credentials to access the SiteWise Edge gateway. Then they can use the AWS OpsHub for AWS IoT SiteWise application, AWS IoT SiteWise API operations, or other tools to manage the SiteWise Edge gateway. For more information, see [Manage SiteWise Edge gateways](manage-gateways-ggv2.md).
**Note**
You can also use the Linux or Microsoft Windows credentials to access the SiteWise Edge gateway. For more information, see [Access your SiteWise Edge gateway using Linux operating system credentials](manage-gateways-ggv2.md#linux-user-pool).
1. Select **Activated**.
1. For **Provider name**, enter a name for your LDAP provider.
1. For **Hostname or IP address**, enter the hostname or IP address of your LDAP server.
1. For **Port**, enter a port number.
1. For **Base distinguished name (DN)**, enter a distinguished name (DN) for the base.
The following attribute types are supported: commonName (CN), localityName (L), stateOrProvinceName (ST), organizationName (O), organizationalUnitName (OU), countryName (C), streetAddress (STREET), domainComponent (DC), and userid (UID).
1. For **Admin group DN**, enter a DN.
1. For **User group DN**, enter a DN.
1. Choose **Save**.
Now that you've activated edge capabilities on your SiteWise Edge gateway, you need to configure your asset model for the edge. Your asset model edge configuration specifies where your assets properties are computed. You can compute all properties at the edge, or you can configure your asset model properties separately. Asset model properties include [metrics](concept-overview.md#concept-metric), [transforms](concept-overview.md#concept-transform), and [measurements](concept-overview.md#concept-measurement).
For more information about asset properties, see [Define data properties](asset-properties.md).
After you create your asset model, you can then configure it for the edge. For more information about configuring your asset model for the edge, see [Create an asset model (console)](create-asset-models.md#create-asset-model-console).
**Note**
Asset models and dashboards are automatically synced between the AWS Cloud and your SiteWise Edge gateway every 10 minutes. You can also sync manually from the local SiteWise Edge gateway application.
# Configure edge data processing for AWS IoT SiteWise models and assets
Configure edge data processing
**Note**
The data processing pack (DPP) feature is no longer availabke to new customers. Existing customers can continue to use the service as normal. For more information, see [Data processing pack availability change](https://docs.aws.amazon.com/iot-sitewise/latest/appguide/iotsitewise-dpp-availability-change.html).
You can use AWS IoT SiteWise Edge to collect, store, organize and monitor equipment data locally. You can use SiteWise Edge so that you can model your industrial data and visualize it locally. You can process your data locally and send it to the AWS Cloud, or process it on-premises by using the AWS IoT SiteWise API.
With AWS IoT SiteWise Edge, you can process raw data locally and choose to send only aggregated data to the AWS Cloud to optimize your bandwidth usage and cloud storage costs.
**Note**
AWS IoT SiteWise retains your edge data on your SiteWise Edge gateways up to 30 days. The retention period of your data is dependent on the available disk space of your device.
If your SiteWise Edge gateway has been disconnected from the AWS Cloud for 30 days, the [Set up an OPC UA source in SiteWise Edge](configure-opcua-source.md) is automatically disabled.
## Configure an asset model for data processing on SiteWise Edge
Process data at the edge
You must configure your asset model for the edge before your can process your SiteWise Edge gateway data at the edge. Your asset model edge configuration specifies where your assets properties are computed. You can choose to compute all properties at the edge and send the results to the AWS Cloud, or customize where to compute each asset property separately. For more information, see [Configure edge data processing for AWS IoT SiteWise models and assets](#edge-processing).
Asset properties include metrics, transforms, and measurements:
+ Metrics are the asset's aggregated data over a specified period of time. You can compute new metrics by using existing metric data. AWS IoT SiteWise always sends your metrics to the AWS Cloud for long-term storage. AWS IoT SiteWise computes metrics on the AWS Cloud by default. You can configure your asset model to compute your metrics at the edge. AWS IoT SiteWise sends processed results to the AWS Cloud.
+ Transforms are mathematical expressions that map an asset property's data points from one form to another. Transforms can use metrics as input data and must be computed and stored at the same location as their inputs. If you configure a metric input to compute at the edge, AWS IoT SiteWise also computes its associated transform at the edge.
+ Measurements are formatted as raw data that your device collects and sends to the AWS Cloud by default. You can configure your asset model to store this data on your local device.
For more information about asset properties, see [Define data properties](asset-properties.md).
After you create your asset model, you can then configure it for the edge. For more information about configuring your asset model for the edge, see [Create an asset model (console)](create-asset-models.md#create-asset-model-console).
**Note**
Asset models and dashboards are automatically synced between the AWS Cloud and your SiteWise Edge gateway every 10 minutes. You can also sync manually from the [Manage SiteWise Edge gateways](manage-gateways-ggv2.md).
You can use the AWS IoT SiteWise REST APIs and the AWS Command Line Interface (AWS CLI) to query your SiteWise Edge gateway for data at the edge. Before you query your SiteWise Edge gateway for data at the edge, you must meet the following prerequisites:
+ Your credentials must be set for the REST APIs. For more information about setting credentials, see [Manage SiteWise Edge gateways](manage-gateways-ggv2.md).
+ The SDK endpoint must point to the IP address of your SiteWise Edge gateway. You can find more information in the documentation for your SDK. For example, see [Specifying Custom Endpoints](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/specifying-endpoints.html) in the *AWS SDK for Java 2.x Developer Guide*.
+ Your SiteWise Edge gateway certificate must be registered. You can find more information about registering your SiteWise Edge gateway certificate in the documentation for your SDK. For example, see the [Registering Certificate Bundles in Node.js](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/node-registering-certs.html) in the *AWS SDK for Java 2.x Developer Guide*.
For more information about querying data with AWS IoT SiteWise, see [Query data from AWS IoT SiteWise](query-industrial-data.md).
# Add data sources to your AWS IoT SiteWise Edge gateway
Add data sources
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
OPC UA data sources
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
Set up an OPC UA source
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)
Configure an OPC UA source (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)
Examples
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
Set up OPC UA servers to trust the 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
Filter data ingestion ranges
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
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
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
Use OPC UA node filters
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
Configure data source authentication
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
Partner data sources
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
Set up Docker on a 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
Add a partner data source
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
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/)
# AWS IoT Greengrass components for AWS IoT SiteWise Edge
Components for SiteWise Edge
SiteWise Edge uses AWS IoT Greengrass components to collect, process, and transmit industrial data at the edge. These components work together to enable local data processing and seamless integration with the AWS IoT SiteWise cloud service.
**IoT SiteWise publisher**
The IoT SiteWise publisher component (`aws.iot.SiteWiseEdgePublisher`)is responsible for:
+ Securely transmitting collected data to the AWS IoT SiteWise cloud service
+ Managing data buffering and retries during connectivity issues
For more information on configuring the publisher for SiteWise Edge, see [Configure the AWS IoT SiteWise publisher component](configure-publisher-component.md). And, for more information on the publisher component, see [IoT SiteWise publisher](https://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-publisher-component.html) in the *AWS IoT Greengrass Version 2 Developer Guide*.
**IoT SiteWise processor**
The IoT SiteWise processor component (`aws.iot.SiteWiseEdgeProcessor`) performs the following tasks:
+ Executing data transformations and calculations at the edge
+ Implementing asset property definitions and computations locally
+ Reducing data volume by aggregating or filtering data before transmission
For more information about the processor component, see [IoT SiteWise processor](https://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-processor-component.html) in the *AWS IoT Greengrass Version 2 Developer Guide*.
**IoT SiteWise OPC UA collector**
The IoT SiteWise OPC UA collector (`aws.iot.SiteWiseEdgeCollectorOpcua`) component is designed to:
+ Connect to OPC UA servers in industrial environments
+ Collect data from OPC UA data sources efficiently
+ Transform OPC UA data into a format compatible with AWS IoT SiteWise
For more information about OPC UA collector component, see [IoT SiteWise OPC UA collector](https://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-opcua-collector-component.html) in the *AWS IoT Greengrass Version 2 Developer Guide*.
**IoT SiteWise OPC UA data source simulator**
The IoT SiteWise OPC UA data source simulator component (`aws.iot.SiteWiseEdgeOpcuaDataSourceSimulator`) provides the following functionality:
+ Starts a local OPC UA server that generates sample data
+ Simulates a data source that can be read by the AWS IoT SiteWise OPC UA collector component on an AWS IoT SiteWise gateway
+ Enables exploration of AWS IoT SiteWise features using the generated sample data
This component is particularly useful for testing and development purposes, allowing you to simulate industrial data sources without the need for physical equipment.
For more information about the data source simulation component, see [IoT SiteWise OPC UA data source simulator](https://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-opcua-data-source-simulator-component.html) in the *AWS IoT Greengrass Version 2 Developer Guide*.
These AWS IoT Greengrass components work to enable SiteWise Edge functionality. The IoT SiteWise publisher ensures data is reliably sent to the cloud, the IoT SiteWise processor handles local computations and data optimization, and the IoT SiteWise OPC UA collector facilitates integration with common industrial protocols.
**Note**
To use these components, you must have AWS IoT Greengrass V2 or later installed on your edge devices. Proper configuration of each component is important for optimal performance of SiteWise Edge.
# Filter assets on a SiteWise Edge gateway
Filter assets
You can use edge filtering to more efficiently manage your assets by sending only a subset of assets to a specific SiteWise Edge gateway for use in data processing. If your assets are arranged in a tree, or parent-child, structure, you can set up an IAM policy attached to a SiteWise Edge gateway’s IAM role that only allows the root of the tree, or parent, and its children to be sent to a specific SiteWise Edge gateway.
**Note**
If you’re arranging existing assets into a tree structure, after you’ve created the structure, go into each existing asset that you added to the structure and choose **Edit** and then choose **Save** to make sure AWS IoT SiteWise recognizes the new structure.
## Set up edge filtering
Set up edge filtering on your SiteWise Edge gateway by adding the following IAM policy to the SiteWise Edge gateway’s IAM role, replacing ** with the ID of the root asset you want to send to the SiteWise Edge gateway.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": [
"iotsitewise:DescribeAsset",
"iotsitewise:ListAssociatedAssets"
],
"Resource": "arn:aws:iotsitewise:*:*:asset/*",
"Condition": {
"StringNotLike": {
"iotsitewise:assetHierarchyPath": "/*"
}
}
}
]
}
```
------
If there are assets currently on your SiteWise Edge gateway that you'd like to remove, log into your SiteWise Edge gateway and run the following command to force the SiteWise Edge gateway to sync with AWS IoT SiteWise by deleting the cache.
```
sudo rm /greengrass/v2/work/aws.iot.SiteWiseEdgeProcessor/sync-app/sync_resource_bundles/edge.json
```
# Configure proxy support and manage trust stores for AWS IoT SiteWise Edge
Proxy support and trust stores
In AWS IoT SiteWise Edge, configure and manage trust stores to set up proxy support for your edge devices. First, set up proxy configuration, then configure trust stores. You can configure trust stores either during gateway installation or manually after your gateway is established.
+ **Proxies** – Facilitate connectivity between your edge devices and AWS services in various network environments.
+ **Trust stores** – Ensure secure connections by managing trusted certificates. Proper configurations help you comply with your network security policies, enable communication in restricted network environments, and optimize data transfer between edge devices and cloud services.
SiteWise Edge utilizes multiple trust stores for different component types, ensuring secure and efficient data flow from your edge devices to the cloud. You can configure trust stores and proxies on an existing gateway or during the installation process when creating a new gateway.
## Requirements for trust store and proxy configurations
Requirements
Before you configure a trust store or install SiteWise Edge with proxy settings, ensure that you meet the prerequisites. There are varied implementation requirements based on your component usage and functionality requirements.
**Proxy support requirements**
+ The URL of your proxy server. The URL should include the user info, the port number for the host. For example, `scheme://[userinfo@]host[:port]`.
+ `scheme` – Must be HTTP or HTTPS
+ (Optional) `userinfo` – User name and password information
+ `host` – The host name or IP address of the proxy server
+ `port` – The port number
+ A list of addresses to bypass the proxy.
+ (Optional) The proxy CA certificate file if you're using an HTTPS proxy with a self-signed certificate.
**Trust store requirements**
+ For full data processing pack functionality with HTTPS proxy, you should update all three trust stores.
+ If you only use the IoT SiteWise OPC UA collector and IoT SiteWise publisher, update the certificates AWS IoT Greengrass Core and Java trust stores to the latest version.
## Best practices for trust store and proxy server edge configurations
Best practices
For ongoing maintenance and to maintain the highest level of security in your edge environment:
+ Regularly review and update proxy settings to align with your network security requirements.
+ Monitor gateway connectivity and data flow to ensure proper proxy communication
+ Maintain and update trust stores according to your organization's certificate management policies
+ You can implement and follow our recommended best practices for secure communication in edge environments, such as:
+ Document your proxy and trust store configurations for operational visibility
+ Follow your organization's security practices for credential management
These practices help maintain secure and reliable operations for your SiteWise Edge gateways while remaining aligned with your broader security policies.
# Configure proxy settings during AWS IoT SiteWise Edge gateway installation
Configure proxy settings during installation
You can configure AWS IoT SiteWise Edge to work with a proxy server during gateway installation. The installation script supports both HTTP and HTTPS proxies and can automatically configure trust stores for secure proxy connections.
When you run the installation script with proxy settings, it performs several important tasks:
+ Validates the proxy URL format and parameters to ensure they are correctly specified.
+ Downloads and installs required dependencies through the configured proxy.
+ If a proxy CA certificate is provided, it's appended to the AWS IoT Greengrass root CA certificate and imported into the Java KeyStore.
+ Configures AWS IoT Greengrass (which SiteWise Edge uses) to use the proxy for all outbound connections.
+ Completes the SiteWise Edge installation with the appropriate proxy and trust store configurations.
**To configure proxy settings when installing gateway software**
1. Create a SiteWise Edge gateway. For more information, see [Create a self-hosted SiteWise Edge gateway](create-gateway-ggv2.md) and [Install the AWS IoT SiteWise Edge gateway software on your local device](install-gateway-software-on-local-device.md).
1. Run the installation script with the appropriate proxy settings for your environment. Replace the placeholders with your specific proxy information
Replace each of the following items:
+ `-p`, `--proxy-url` – The URL of the proxy server. The URL must be either `http` or `https`.
+ `-n`, `--no-proxy` – A comma-separated list of addresses to bypass the proxy.
+ (Optional)`-c`, `--proxy-ca-cert` – Path to the proxy CA certificate file.
+ (Optional)`-j`, `--javastorepass` – The Java KeyStore password. The default password is `changeit`.
------
#### [ Linux ]
For Linux systems, use the following command structure:
```
sudo ./install.sh -p proxy-url -n no-proxy-addresses [-c proxy-ca-cert-path] [-j javastorepass]
```
------
#### [ Windows ]
For Microsoft Windows systems using PowerShell, use this command structure:
```
.\install.ps1 -ProxyUrl proxy-url -NoProxyAddresses no-proxy-addresses [-ProxyCaCertPath proxy-ca-cert-path] [-JavaStorePass javastorepass]
```
------
## Troubleshooting during proxy-enabled installation
For more information on resolving trust store issues related to a SiteWise Edge gateway, see [Proxy-enabled installation issues](troubleshooting-gateway.md#troubleshoot-proxy-during-installation).
# Manually configure trust stores for HTTPS proxy support in AWS IoT SiteWise Edge
Manually configure trust stores for HTTPS proxy support
When configuring AWS IoT SiteWise Edge components to connect through an HTTPS proxy, add the proxy server's certificate to the appropriate trust stores. SiteWise Edge uses multiple trust stores to secure communications. There are three trust stores and your use of them depends upon the SiteWise Edge component type in your gateway implementation.
Trust stores are automatically updated during the installation process when proxy settings are provided.
+ [Configure an AWS IoT Greengrass Core component trust store](#manage-trust-stores-proxy_greengrass-core-components) – The AWS IoT Greengrass root CA certificate is included in the trust stores to verify the authenticity of AWS services.
This trust store helps AWS IoT Greengrass components securely communicate with AWS services through the proxy while verifying the authenticity of those services.
+ [Configure a Java-based component trust store](#manage-trust-stores-proxy_java-based-components) – The Java KeyStore (JKS) is the main trust store used by Java-based components for SSL/TLS connections.
Java applications rely on the JKS to establish secure connections. For example, if you're using the IoT SiteWise publisher or IoT SiteWise OPC UA collector, which are Java-based, you'll need to configure this trust store. This ensures these components can securely communicate through the HTTPS proxy when sending data to the cloud or collecting data from OPC UA servers.
+ [System-level component trust store configuration](#manage-trust-stores-proxy_system-level-components) – When using HTTPS proxies, their certificates must be added to the appropriate trust stores to enable secure connections.
When using HTTPS proxies, their certificates must be added to the appropriate trust stores to enable secure connections. This is necessary because system-level components, often written in languages like Rust or Go, rely on the system's trust store rather than Java's JKS. For example, if you're using system utilities that need to communicate through the proxy (like for software updates or time synchronization), you'll need to configure the system-level trust store. This ensures these components and utilities can establish secure connections through the proxy.
## Configure an AWS IoT Greengrass Core component trust store
AWS IoT Greengrass Core components
For AWS IoT Greengrass Core functions that use Amazon's root CA:
1. Locate the certificate file at `/greengrass/v2/AmazonRootCA1.pem`
1. Append the HTTPS proxy root certificate (self-signed) to this file.
```
-----BEGIN CERTIFICATE-----
MIIEFTCCAv2gAwIQWgIVAMHSAzWG/5YVRYtRQOxXUTEpHuEmApzGCSqGSIb3DQEK
\nCwUAhuL9MQswCQwJVUzEPMAVUzEYMBYGA1UECgwP1hem9uLmNvbSBJbmMuMRww
... content of proxy CA certificate ...
+vHIRlt0e5JAm5\noTIZGoFbK82A0/nO7f/t5PSIDAim9V3Gc3pSXxCCAQoFYnui
GaPUlGk1gCE84a0X\n7Rp/lND/PuMZ/s8YjlkY2NmYmNjMCAXDTE5MTEyN2cM216
gJMIADggEPADf2/m45hzEXAMPLE=
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIDQTCCAimgF6AwIBAgITBmyfz/5mjAo54vB4ikPmljZKyjANJmApzyMZFo6qBg
ADA5MQswCQYDVQQGEwJVUzEPMA0tMVT8QtPHRh8jrdkGA1UEChMGDV3QQDExBBKW
... content of root CA certificate ...
o/ufQJQWUCyziar1hem9uMRkwFwYVPSHCb2XV4cdFyQzR1KldZwgJcIQ6XUDgHaa
5MsI+yMRQ+hDaXJiobldXgjUka642M4UwtBV8oK2xJNDd2ZhwLnoQdeXeGADKkpy
rqXRfKoQnoZsG4q5WTP46EXAMPLE
-----END CERTIFICATE-----
```
### Configure HTTPS proxy on an established gateway
You can add proxy support to an established gateway by connecting to port 443 instead of port 8883. For more information on using a proxy server, see [Connect on port 443 or through a network proxy](https://docs.aws.amazon.com/greengrass/v2/developerguide/configure-greengrass-core-v2.html#configure-alpn-network-proxy) in the *AWS IoT Greengrass Version 2 Developer Guide*. If you create a new gateway, you can set the proxy configuration during gateway installation. For more information, see [Configure proxy settings during AWS IoT SiteWise Edge gateway installation](manage-trust-stores-proxy_config.md).
When you use an HTTPS proxy with AWS IoT Greengrass on SiteWise Edge, the software automatically chooses between HTTP and HTTPS for proxy connections based on the provided URL.
**Important**
Update all required trust stores before attempting to connect through an HTTPS proxy.
## Configure a Java-based component trust store
Java-based components
For IoT SiteWise publisher, IoT SiteWise OPC UA collector, and Java services in the data processing pack, the default Java trust store location is `$JAVA_HOME/jre/lib/security/cacerts`
**To add a certificate**
1. Create a file to store the proxy server's certificate, such as `proxy.crt`.
**Note**
Create the file ahead of time using the proxy server's certificate.
1. Add the file to Java's trust store using the following command:
```
sudo keytool -import -alias proxyCert -keystore /usr/lib/jvm/java-11-openjdk-amd64/lib/security/cacerts -file proxy.crt
```
1. When prompted, use the default password: `changeit`
## System-level component trust store configuration
System-level components
For components written in Rust, Go, and other languages that use the system trust store:
------
#### [ Linux ]
Linux systems: Add certificates to `/etc/ssl/certs/ca-certificates.crt`
------
#### [ Windows ]
Microsoft Windows systems: To configure the trust store, follow the [Certificate Store](https://learn.microsoft.com/en-us/windows-hardware/drivers/install/certificate-stores) procedure in the *Microsoft Ignite* documentation.
Windows offers multiple certificate stores, including separate stores for User and Computer scopes, each with several sub-stores. For most SiteWise Edge setups, we recommend adding certificates to the `COMPUTER | Trusted Root Certification Authorities` store. However, depending on your specific configuration and security requirements, you might need to use a different store.
------
## Troubleshooting trust store issues
For more information on resolving trust store issues related to a SiteWise Edge gateway, see [Trust store issues](troubleshooting-gateway.md#troubleshoot-trust-stores).
# Use AWS IoT SiteWise APIs on the edge
Use APIs
AWS IoT SiteWise provides a subset of its APIs, along with edge-specific APIs, enabling seamless interaction with asset models and their associated assets deployed at the edge. These asset models must be configured to run on the edge. For more information, see [Configure an asset model for data processing on SiteWise Edge](edge-processing.md#process-gateway-data-edge) for detailed instructions on this setup process.
After you configure these APIs, you can retrieve comprehensive data about your asset models and individual assets. Retrieving asset model, asset, dashboard, portal and project information can help you monitor deployed portals and dashboards, and access asset data collected at the edge level. This provides a central host in your network for interactions with AWS IoT SiteWise without requiring a web API call.
**Topics**
+ [
# All available AWS IoT SiteWise Edge device APIs
](edge-apis-available.md)
+ [
# Edge-only APIs for use with AWS IoT SiteWise edge devices
](edge-local-apis.md)
+ [
# Enable CORS on AWS IoT SiteWise Edge APIs
](enable-cors-edge-apis.md)
+ [
# Configure session timeouts for AWS IoT SiteWise Edge
](edge-apis-session-timeout.md)
+ [
# Tutorial: List asset models on an AWS IoT SiteWise Edge gateway
](edge-apis-tutorial.md)
# All available AWS IoT SiteWise Edge device APIs
All available APIs
AWS IoT SiteWise provides a variety of APIs to use on edge devices so that you can complete tasks locally on the device. Some of the available edge APIs include retrieving asset models, creating and updating asset properties, and sending data streams to the cloud. By leveraging these APIs, you can build solutions that can operate in environments with intermittent or limited network connectivity.
## Available AWS IoT SiteWise APIs
The following AWS IoT SiteWise APIs are available on edge devices:
+ [ListAssetModels](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_ListAssetModels.html)
+ [DescribeAssetModel](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeAssetModel.html)
+ [ListAssets](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_ListAssets.html)
+ [DescribeAsset](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeAsset.html)
+ [DescribeAssetProperty](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeAssetProperty.html)
+ [ListAssociatedAssets](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_ListAssociatedAssets.html)
+ [GetAssetPropertyAggregates](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_GetAssetPropertyAggregates.html)
+ [GetAssetPropertyValue](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_GetAssetPropertyValue.html)
+ [GetAssetPropertyValueHistory](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_GetAssetPropertyValueHistory.html)
+ [ListDashboards](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_ListDashboards.html)
+ [ListPortals](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_ListPortals.html)
+ [ListProjectAssets](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_ListProjectAssets.html)
+ [ListProjects](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_ListProjects.html)
+ [DescribeDashboard](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeDashboard.html)
+ [DescribePortal](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribePortal.html)
+ [DescribeProject](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_DescribeProject.html)
## Available edge-only APIs
The following APIs are used locally on devices on the edge:
+ [Authenticate](edge-local-apis.md#edge-local-apis-authenticate) – Use this API to get the SigV4 temporary credentials that you'll use to make API calls.
# Edge-only APIs for use with AWS IoT SiteWise edge devices
Edge-only APIs
In addition to the AWS IoT SiteWise APIs that are available on the edge, there are edge-specific ones. Those edge-specifc APIs are described below.
## Authenticate
Gets the credentials from the SiteWise Edge gateway. You'll need to add local users or connect to your system using LDAP or a Linux user pool. For more information about adding users, see [LDAP](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/manage-gateways-ggv2.html#opshub-app) or [Linux user pool](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/manage-gateways-ggv2.html#opshub-app).
### Request syntax
```
POST /authenticate HTTP/1.1
Content-type: application/json
{
"username": "string",
"password": "string",
"authMechanism": "string"
}
```
### URI request Parameters
The request does not use any URI parameters.
### Request body
The request accepts the following data in JSON format.
**username**
The username used to validate the request call.
Type: String
Required: Yes
**password**
The password of the user requesting credentials.
Type: String
Required: Yes
**authMechanism**
The authentication method to validate this user in the host.
Type: String
Valid values: `ldap`, `linux`, `winnt`
Required: Yes
### Response syntax
```
HTTP/1.1 200
Content-type: application/json
{
"accessKeyId": "string",
"secretAccessKey": "string",
"sessionToken": "string",
"region": "edge"
}
```
### Response elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format.
**accessKeyId**
The access key ID that identifies the temporary security credentials.
Length Constraints: Minimum length of 16. Maximum length of 128.
Pattern: `[\w]*`
**secretAccessKey**
The secret access key that can be used to sign requests.
Type: String
**sessionToken**
The token that users must pass to the service API to use the temporary credentials.
Type: String
**region**
The region you are targeting for API calls.
Type: CONSTANT - `edge`
### Errors
**IllegalArgumentException**
The request was rejected because the provided body document was malformed. The error message describes the specific error.
HTTP Status Code: 400
**AccessDeniedException**
The user doesn't have valid credentials based on the current Identity Provider. The error message describes the authentication Mechanism.
HTTP Status Code: 403
**TooManyRequestsException**
The request has reached it's limit of authentication attempts. The error message contains the quantity of time to wait until new attempts of authentication are made.
HTTP Status Code: 429
# Enable CORS on AWS IoT SiteWise Edge APIs
Enable CORS
Enabling CORS (Cross-Origin Resource Sharing) on AWS IoT SiteWise Edge APIs allows web applications to directly communicate with the APIs across different domains. This enables seamless integration, real-time data exchange, and cross-domain data access without intermediary servers or workarounds. CORS settings can be configured to specify allowable origins, ensuring controlled cross-origin access.
**Note**
CORS is available for version 3.3.1 and later of the This feature is available for version 3.3.1 and later of the `aws.iot.SiteWiseEdgeProcessor` component. For more information, see [AWS IoT SiteWise processor](https://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-processor-component.html) in the *AWS IoT Greengrass Version 2 Developer Guide*.
**To enable CORS on SiteWise Edge APIs**
1. Navigate to the [AWS IoT SiteWise console](https://console.aws.amazon.com/iotsitewise/).
1. In the navigation pane, choose **Edge gateways**.
1. Select the SiteWise Edge gateway for which you want to enable CORS. You can enable CORS on the AWS IoT Greengrass V2 deployment type.
1. In the **Gateway configuration** section, choose the associated **Greengrass core device**.
1. In the **Deployments** tab, under **Greengrass devices**, select the appropriate deployment link.
1. Under **Actions** choose **Revise**, then **Revise deployment**.
**Important**
Creating a revised CORS enabled configuration replaces the device’s current configuration.
1. In **Step 1, Specify target**, provide an optional **Name** to identify the deployment.
1. In **Step 2, Select components - optional**, you can leave all current selections as-is and choose **Next**.
1. In **Step 3, Configure components - optional**, select **aws.iot.SiteWiseEdgeProcessor**, and choose **Configure component**.
1. In the Configuration update section, under Configuration to merge, enter the following JSON:
```
{
"AWS_SITEWISE_EDGE_ACCESS_CONTROL_ALLOW_ORIGIN": "*"
}
```
**Note**
Using `*` as the value for `AWS_SITEWISE_EDGE_ACCESS_CONTROL_ALLOW_ORIGIN` allows all origins. For production environments, it's recommended to specify exact origin URLs for better security.
1. Choose **Confirm**.
1. Choose **Next** to proceed through remaining steps until you arrive at **Step5, Review**.
1. Review your configuration changes, then choose **Deploy** to apply the changes to your SiteWise Edge gateway.
**Note**
Alternatively, you can enable CORS by setting global the environmental variable `AWS_SITEWISE_EDGE_ACCESS_CONTROL_ALLOW_ORIGIN` to `*` on your AWS IoT SiteWise gateway.
**Note**
For authenticated proxy, `userinfo` must be included in the `url` field in the proxy configuration rather than as a separated `username` and `password` fields.
After the deployment is complete, CORS is enabled on your SiteWise Edge API, allowing specified origins to make cross-origin requests to the API.
# Configure session timeouts for AWS IoT SiteWise Edge
Configure session timeouts
SiteWise Edge allows you to configure session timeouts for the SiteWise Edge API. This feature enhances security by automatically terminating inactive sessions after a specified time-period. This section guides you through the process of configuring the session timeout using the AWS IoT SiteWise console.
**Note**
Session timeout configuration is available for version 3.4.0 and later of the `aws.iot.SiteWiseEdgeProcessor` component. For more information, see [AWS IoT SiteWise processor](https://docs.aws.amazon.com/greengrass/v2/developerguide/iotsitewise-processor-component.html) in the *AWS IoT Greengrass Version 2 Developer Guide*.
**To configure a session timeout for a SiteWise Edge gateway**
1. Navigate to the [AWS IoT SiteWise console](https://console.aws.amazon.com/iotsitewise/).
1. In the navigation pane, choose **Edge gateways**.
1. Choose the SiteWise Edge gateway where you want to configure the session timeout.
**Note**
You can configure the session timeout on the AWS IoT Greengrass V2 deployment type.
1. In the **Gateway configuration** section, choose the associated **Greengrass core device**.
1. In the **Deployments** tab, under **Greengrass devices**, select the appropriate deployment link.
1. Under **Actions** choose **Revise**. Read the warning, and then choose **Revise deployment**.
**Important**
Creating a revised session timeout configuration replaces the device's current configuration.
1. In **Step 1, Specify target**, provide an optional **Name** to identify the revised deployment, and then choose **Next**.
1. In **Step 2, Select components - optional**, you can leave all current selections as-is and choose **Next**.
1. In **Step 3, Configure components - optional**, select **aws.iot.SiteWiseEdgeProcessor**, and choose **Configure component**.
1. In the **Configuration update** section, under **Configuration to merge**, enter the following JSON:
```
{
"AWS_SITEWISE_EDGE_SESSION_TIMEOUT_MINUTES": "240"
}
```
1. Set the value for `AWS_SITEWISE_EDGE_SESSION_TIMEOUT_MINUTES` in minutes. Session timeout values can be from 1 minute to 10080 minutes (7 days). The default value is 240 minutes (4 hours).
1. Choose **Confirm**.
1. Choose **Next** to proceed through remaining steps until you arrive at Step 5, **Review**.
1. Review your configuration changes, then choose **Deploy** to apply the changes to your SiteWise Edge gateway.
**Note**
Alternatively, you can configure the session timeout by setting the global environmental variable **AWS\$1SITEWISE\$1EDGE\$1SESSION\$1TIMEOUT\$1MINUTES** to your desired value (in minutes) on your SiteWise Edge gateway.
After the deployment is complete, the new session timeout configuration is applied to your SiteWise Edge API.
# Tutorial: List asset models on an AWS IoT SiteWise Edge gateway
Tutorial: Get a list of asset models
You can use a subset of the available AWS IoT SiteWise APIs along with edge-specific APIs to interact with asset models and their assets on the edge. This tutorial will walk you through getting temporary credentials to an AWS IoT SiteWise Edge gateway and getting a list of the asset models on the SiteWise Edge gateway.
## Prerequisites
In the steps of this tutorial you can use a variety of tools. To use these tools, make sure you have the corresponding prerequisites installed.
To complete this tutorial, you need the following:
+ A deployed and running [AWS IoT SiteWise Edge self-hosted gateway requirements](configure-gateway-ggv2.md)
+ Access to your SiteWise Edge gateway in the same network over port 443.
+ [OpenSSL](https://www.openssl.org/) installed
+ (AWS OpsHub for AWS IoT SiteWise) The [AWS OpsHub for AWS IoT SiteWise application](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/manage-gateways-ggv2.html#opshub-app)
+ (curl) [curl](https://ec.haxx.se/install/) installed
+ (Python) [urllib3](https://urllib3.readthedocs.io/en/stable/index.html) installed
+ (Python) [Python3](https://www.python.org/downloads/) installed
+ (Python) [Boto3](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html) installed
+ (Python) [BotoCore](https://botocore.amazonaws.com/v1/documentation/api/latest/index.html) installed
## Step 1: Get a SiteWise Edge gateway service signed certificate
To establish a TLS connection to the APIs available at the SiteWise Edge gateway, you need a trusted certificate. You can generate this certificate using a OpenSSL or AWS OpsHub for AWS IoT SiteWise.
------
#### [ OpenSSL ]
**Note**
You need [OpenSSL](https://www.openssl.org/) installed to run this command.
Open a terminal and run the following command to get a signed certificate from the SiteWise Edge gateway. Replace `` with the IP of the SiteWise Edge gateway.
```
openssl s_client -connect :443 /dev/null | openssl x509 -outform PEM > GatewayCert.pem
```
------
#### [ AWS OpsHub for AWS IoT SiteWise ]
You can use AWS OpsHub for AWS IoT SiteWise. For more information, see [Manage SiteWise Edge gateways](manage-gateways-ggv2.md).
------
The absolute path to the downloaded SiteWise Edge gateway certificate is used in this tutorial. Run the following command to export the complete path of your certificate, replacing `` with the path to the certificate:
```
export PATH_TO_CERTIFICATE=''
```
## Step 2: Get your SiteWise Edge gateway hostname
**Note**
You need [OpenSSL](https://www.openssl.org/) installed to run this command.
To complete the tutorial you'll need the hostname of your SiteWise Edge gateway. To get the hostname of your SiteWise Edge gateway, run the following, replacing `` with the IP of the SiteWise Edge gateway:
```
openssl s_client -connect :443 /dev/null | grep -Po 'CN = \K.*'| head -1
```
Run the following command to export the hostname for use later, replacing `` with the hostname of your SiteWise Edge gateway:
```
export GATEWAY_HOSTNAME=''
```
## Step 3: Get temporary credentials for your SiteWise Edge gateway
Now that you have the signed certificate and the hostname of your SiteWise Edge gateway, you need to get temporary credentials so you can run APIs on the gateway. You can get these credentials through AWS OpsHub for AWS IoT SiteWise or directly from the SiteWise Edge gateway using APIs.
**Important**
Credentials expire every 4 hours, so you should get the credentials just before using the APIs on your SiteWise Edge gateway. Don't cache credentials for longer than 4 hours.
### Get temporary credentials using AWS OpsHub for AWS IoT SiteWise
**Note**
You need the [AWS OpsHub for AWS IoT SiteWise application](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/manage-gateways-ggv2.html#opshub-app) installed.
To use AWS OpsHub for AWS IoT SiteWise application to get your temporary credentials do the following:
1. Log into the application.
1. Choose **Settings**.
1. For **Authentication**, choose **Copy credentials**.
1. Expand the option that fits your environment and choose **Copy**.
1. Save the credentials for use later.
### Get temporary credentials using the SiteWise Edge gateway API
To use the SiteWise Edge gateway API to get the temporary credentials you can use a Python script or curl, first you'll need to have a user name and password for your SiteWise Edge gateway. The SiteWise Edge gateways use SigV4 authentication and authorization. For more information about adding users, see [LDAP](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/manage-gateways-ggv2.html#opshub-app) or [Linux user pool](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/manage-gateways-ggv2.html#opshub-app). These credentials will be used in the following steps to get the local credentials on your SiteWise Edge gateway that are needed to use the AWS IoT SiteWise APIs.
------
#### [ Python ]
**Note**
You need [urllib3](https://urllib3.readthedocs.io/en/stable/index.html) and [Python3](https://www.python.org/downloads/) installed.
**To get the credentials using Python**
1. Create a file called **get\$1credentials.py** and the copy the following code into it.
```
'''
The following demonstrates how to get the credentials from the SiteWise Edge gateway. You will need to add local users or connect your system to LDAP/AD
https://docs.aws.amazon.com/iot-sitewise/latest/userguide/manage-gateways-ggv2.html#create-user-pool
Example usage:
python3 get_credentials.py -e https:// -c -u '' -p '' -m ''
'''
import urllib3
import json
import urllib.parse
import sys
import os
import getopt
"""
This function retrieves the AWS IoT SiteWise Edge gateway credentials.
"""
def get_credentials(endpoint,certificatePath, user, password, method):
http = urllib3.PoolManager(cert_reqs='CERT_REQUIRED', ca_certs= certificatePath)
encoded_body = json.dumps({
"username": user,
"password": password,
"authMechanism": method,
})
url = urllib.parse.urljoin(endpoint, "/authenticate")
response = http.request('POST', url,
headers={'Content-Type': 'application/json'},
body=encoded_body)
if response.status != 200:
raise Exception(f'Failed to authenticate! Response status {response.status}')
auth_data = json.loads(response.data.decode('utf-8'))
accessKeyId = auth_data["accessKeyId"]
secretAccessKey = auth_data["secretAccessKey"]
sessionToken = auth_data["sessionToken"]
region = "edge"
return accessKeyId, secretAccessKey, sessionToken, region
def print_help():
print('Usage:')
print(f'{os.path.basename(__file__)} -e -c -u -p -m -a ')
print('')
print('-e, --endpoint edge gateway endpoint. Usually the Edge gateway hostname.')
print('-c, --cert_path path to downloaded gateway certificate')
print('-u, --user Edge user')
print('-p, --password Edge password')
print('-m, --method (Optional) Authentication method (linux, winnt, ldap), default is linux')
sys.exit()
def parse_args(argv):
endpoint = ""
certificatePath = None
user = None
password = None
method = "linux"
try:
opts, args = getopt.getopt(argv, "he:c:u:p:m:", ["endpoint=","cert_path=", "user=", "password=", "method="])
except getopt.GetoptError:
print_help()
for opt, arg in opts:
if opt == '-h':
print_help()
elif opt in ("-e", "--endpoint"):
endpoint = arg
elif opt in ("-u", "--user"):
user = arg
elif opt in ("-p", "--password"):
password = arg
elif opt in ("-m", "--method"):
method = arg.lower()
elif opt in ("-c", "--cert_path"):
certificatePath = arg
if method not in ['ldap', 'linux', 'winnt']:
print("not valid method parameter, required are ldap, linux, winnt")
print_help()
if (user == None or password == None):
print("To authenticate against edge user, password have to be passed together, and the region has to be set to 'edge'")
print_help()
if(endpoint == ""):
print("You must provide a valid and reachable gateway hostname")
print_help()
return endpoint,certificatePath, user, password, method
def main(argv):
# get the command line args
endpoint, certificatePath, user, password, method = parse_args(argv)
accessKeyId, secretAccessKey, sessionToken, region=get_credentials(endpoint, certificatePath, user, password, method)
print("Copy and paste the following credentials into the shell, they are valid for 4 hours:")
print(f"export AWS_ACCESS_KEY_ID={accessKeyId}")
print(f"export AWS_SECRET_ACCESS_KEY={secretAccessKey}")
print(f"export AWS_SESSION_TOKEN={sessionToken}")
print(f"export AWS_REGION={region}")
print()
if __name__ == "__main__":
main(sys.argv[1:])
```
1. Run **get\$1credentials.py** from the terminal replacing `` and `` with the credentials you created.
```
python3 get_credentials.py -e https://$GATEWAY_HOSTNAME -c $PATH_TO_CERTIFICATE -u '' -p '' -m 'linux'
```
------
#### [ curl ]
**Note**
You need [curl](https://ec.haxx.se/install/) installed.
**To get the credentials using curl**
1. Run the following command from the terminal replacing and with the credentials you created.
```
curl --cacert $PATH_TO_CERTIFICATE --location \
-X POST https://$GATEWAY_HOSTNAME:443/authenticate \
--header 'Content-Type: application/json' \
--data-raw '{
"username": "",
"password": "",
"authMechanism": "linux"
}'
```
The response should look like the following:
```
{
"username": "sweuser",
"accessKeyId": "",
"secretAccessKey": "",
"sessionToken": "",
"sessionExpiryTime": "2022-11-17T04:51:40.927095Z",
"authMechanism": "linux",
"role": "edge-user"
}
```
1. Run the following command from your terminal.
```
export AWS_ACCESS_KEY_ID=
export AWS_SECRET_ACCESS_KEY=
export AWS_SESSION_TOKEN=
export AWS_REGION=edge
```
------
## Step 4: Get a list of the asset models on the SiteWise Edge gateway
Now that you have a signed certificate, your SiteWise Edge gateway hostname, and temporary credentials for your SiteWise Edge gateway, you can use the `ListAssetModels` API to get a list of the asset models on your SiteWise Edge gateway.
------
#### [ Python ]
**Note**
You need [Python3](https://www.python.org/downloads/), [Boto3](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html), and [BotoCore](https://botocore.amazonaws.com/v1/documentation/api/latest/index.html) installed.
**To get the the list of asset models using Python**
1. Create a file called **list\$1asset\$1model.py** and the copy the following code into it.
```
import json
import boto3
import botocore
import os
# create the client using the credentials
client = boto3.client("iotsitewise",
endpoint_url= "https://"+ os.getenv("GATEWAY_HOSTNAME"),
region_name=os.getenv("AWS_REGION"),
aws_access_key_id=os.getenv("AWS_ACCESS_KEY_ID"),
aws_secret_access_key=os.getenv("AWS_SECRET_ACCESS_KEY"),
aws_session_token=os.getenv("AWS_SESSION_TOKEN"),
verify=os.getenv("PATH_TO_CERTIFICATE"),
config=botocore.config.Config(inject_host_prefix=False))
# call the api using local credentials
response = client.list_asset_models()
print(response)
```
1. Run **list\$1asset\$1model.py** from the terminal.
```
python3 list_asset_model.py
```
------
#### [ curl ]
**Note**
You need [curl](https://ec.haxx.se/install/) installed.
**To get the list of asset models using curl**
Run the following command from the terminal.
```
curl \
--request GET https://$GATEWAY_HOSTNAME:443/asset-models \
--cacert $PATH_TO_CERTIFICATE \
--aws-sigv4 "aws:amz:edge:iotsitewise" \
--user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
-H "x-amz-security-token:$AWS_SESSION_TOKEN"
```
The response should look like the following:
```
{
"assetModelSummaries": [
{
"arn": "arn:aws:iotsitewise:{region}:{account-id}:asset-model/{asset-model-id}",
"creationDate": 1.669245291E9,
"description": "This is a small example asset model",
"id": "{asset-model-id}",
"lastUpdateDate": 1.669249038E9,
"name": "Some Metrics Model",
"status": {
"error": null,
"state": "ACTIVE"
}
},
.
.
.
],
"nextToken": null
}
```
------
# Host a SiteWise Edge gateway on Siemens Industrial Edge
Host a gateway on Siemens Industrial Edge
Host your gateway on Siemens Industrial Edge using the AWS IoT SiteWise Edge application. Just as with AWS IoT Greengrass V2, you can optimize manufacturing processes or improve operational workflows using the SiteWise Edge on Siemens Industrial Edge.
You can ingest data from your Siemens Industrial Edge device to your AWS account by running a SiteWise Edge gateway on the device. To do this, request access to the AWS IoT SiteWise Edge application from the SiteWise Edge support team. Then, create a SiteWise Edge gateway resource with a deployment target of **Siemens Industrial Edge device - new**. Next, download the configuration file, and upload it to your application through the Siemens Industrial Edge Management portal. For more information about running applications on Siemens Industrial Edge, including how to set up the required Siemens resources, see [What is Industrial Edge?](https://docs.eu1.edge.siemens.cloud/) in the Siemens documentation.
**Note**
Siemens is not a vendor or supplier for SiteWise Edge. The Siemens Industrial Edge Marketplace is an independent marketplace.
**Topics**
+ [
## Security
](#sa-security)
+ [
## Siemens Secure Storage and the AWS IoT SiteWise Edge application
](#sa-secure-storage)
+ [
## Destinations for Siemens Industrial Edge devices
](#siemens-destinations)
+ [
## Migrate from the preview application
](#sa-migrate)
+ [
## Troubleshooting
](#sa-troubleshoot)
+ [
## AWS IoT SiteWise Edge application changelog
](#sa-changelog)
+ [
# Requirements for the AWS IoT SiteWise Edge application
](siemens-app-gateway-requirements.md)
+ [
# Create a gateway for Siemens Industrial Edge
](sa-create-config.md)
+ [
# Create a Siemens Databus user for the application
](sa-databus-user.md)
+ [
# Access the AWS IoT SiteWise Edge application
](sa-get-app.md)
+ [
# Install the application onto a Siemens device
](sa-install-app.md)
+ [
# Update the AWS IoT SiteWise Edge application configuration
](sa-update-config.md)
+ [
# AWS IoT SiteWise – Data generated by the use of this service
](sa-data-legal.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.
+ Physically securing the device running SiteWise Edge.
**AWS responsibility**
+ Isolating the partner from the customer AWS Cloud resources.
**Partner responsibility**
+ Using secure defaults.
+ Keeping the solution secure over time through patches and other appropriate updates.
+ Keeping customer data confidential.
+ Vetting other applications available in the partner marketplace.
## Siemens Secure Storage and the AWS IoT SiteWise Edge application
To protect credentials and secrets required to run the AWS IoT SiteWise Edge application, Siemens Industrial Edge provides mechanisms to securely store the credentials on the device. The AWS IoT SiteWise Edge application won't run on a device if it doesn't have support for securely storing these credentials. Run failures caused by missing Secure Storage support are logged in log files.
The following minimum OS versions are required to install and run the AWS IoT SiteWise Edge application. Upgrade your devices to the latest versions to install the application.
+ **For virtual devices:** IEVD version 1.19 or above
+ **For physical devices:** IED-OS version 2.2 or above
The AWS IoT SiteWise Edge application on Siemens Industrial Edge will not run until you have upgraded your device.
## Destinations for Siemens Industrial Edge devices
When using the AWS IoT SiteWise Edge application on Siemens Industrial Edge, destinations help prepare data before sending it to AWS IoT SiteWise for further analysis and distribution. You can configure data destination settings for buffered data ingestion using Amazon S3 or use real-time data ingestion. Both allow you to subscribe to MQTT topics using path filters on the Siemens Industrial Edge device deployment target.
The Siemens Industrial Edge deployment target on your gateway supports two primary data handling methods:
+ **AWS IoT SiteWise real-time settings** - Data is sent directly to AWS IoT SiteWise as it's collected
+ **AWS IoT SiteWise buffered using Amazon S3 settings** - Data is collected and stored temporarily in batches before being sent to Amazon S3
For more information about configuring these options, see [Add an AWS IoT SiteWise buffered destination using Amazon S3](destinations-buffered.md) and [Add an AWS IoT SiteWise Edge real-time destination](destinations-real-time.md).
### Prefixes for path filters
Path filters for gateways using Siemens Industrial Edge deployment targets combine both the topic and data stream name to create a unique identifier for your data. The combined topic with data stream name is called a **prefix** in Siemens Industrial Edge gateways. This differs from self-hosted gateways where path filters are based solely on MQTT topics.
**Example Path filter structure for Siemens data streams**
A typical path filter for a Siemens data stream includes both the topic path and the data stream name:
```
ie/d/device1/application1/datastream1
```
Where:
+ `ie/d/` is the required prefix for Siemens data streams
+ `device1/application1` represents the hierarchical path
+ `datastream1` is the specific data stream name
**Note**
When working with Siemens Industrial Edge data streams, ensure that you include both the metadata (`ie/m/`) and data (`ie/d/`) topics in your path filters to receive complete information about your data streams.
#### Destinations and path filters
View the following topics to learn more about destinations and path filters in MQTT-enabled gateways:
+ [Understand AWS IoT SiteWise Edge destinations](gw-destinations.md#source-destination)
+ [Add an AWS IoT SiteWise Edge real-time destination](destinations-real-time.md)
+ [Add an AWS IoT SiteWise buffered destination using Amazon S3](destinations-buffered.md)
+ [Understand path filters for AWS IoT SiteWise Edge destinationsUnderstand path filters](gw-destinations.md#destinations-path-filters)
+ [Add path filters to AWS IoT SiteWise Edge destinations](destinations-add-path-filters.md)
+ [Manage AWS IoT SiteWise Edge destinations](destinations-manage.md)
## Migrate from the preview application
If you ran SiteWise Edge on Siemens Industrial Edge during the preview phase, you'll need to upgrade from the preview version, version 1.0.1, to the latest version. Do the following to migrate:
1. Create new SiteWise Edge gateways. For more information, see [Create a gateway for Siemens Industrial Edge](sa-create-config.md).
1. Create a new Siemens Databus user for each new gateway. For more information, see [Create a Siemens Databus user for the application](sa-databus-user.md).
1. Uninstall the version 1.0.1 AWS IoT SiteWise Edge gateway application on your IED.
**Note**
Prepare for interruptions to data flow as you reconfigure the AWS IoT SiteWise assets previously used by the preview version of the AWS IoT SiteWise Edge application. While the data history is preserved, there is potential for data loss while you reinstall the new gateway.
1. Delete the SiteWise Edge gateways you created during the preview in the [AWS IoT SiteWise console](https://console.aws.amazon.com/iotsitewise/home?region=us-east-1#/gateway).
1. Install the AWS IoT SiteWise Edge gateway application on IED using the new gateway configuration file. For more information, see [Install the application onto a Siemens device](sa-install-app.md).
**Important**
Installing the new gateway overwrites the preview version of the SiteWise Edge application. It isn't possible to go back to version 1.0.1 after installing the current version.
After configuring the new gateway and Siemens Databus user, your data flows to your properties.
You can also upgrade your SiteWise Edge application from version directly. However, a new gateway configuration is still necessary.
## Troubleshooting
To troubleshoot the SiteWise Edge gateway on your Siemens Industrial Edge device, see [Troubleshooting the AWS IoT SiteWise Edge application on Siemens Industrial Edge](troubleshooting-gateway.md#troubleshoot-siemens-app).
You can also access [AWS re:Post](https://repost.aws) to find answers to your questions.
## AWS IoT SiteWise Edge application changelog
The following table describes the changes in each version of the AWS IoT SiteWise Edge application.
| **Version** | **Changes** |
| --- | --- |
| 3.0.1 | Bug fixes and improvements [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot-sitewise/latest/userguide/sitewise-edge-on-siemens.html) |
| 3.0.0 | New features [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot-sitewise/latest/userguide/sitewise-edge-on-siemens.html) Bug fixes and improvements [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot-sitewise/latest/userguide/sitewise-edge-on-siemens.html) |
| 2.0.1 | Bug fixes and improvements [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot-sitewise/latest/userguide/sitewise-edge-on-siemens.html) |
| 2.0.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot-sitewise/latest/userguide/sitewise-edge-on-siemens.html) |
| 1.0.1 | Initial release |
# Requirements for the AWS IoT SiteWise Edge application
Requirements
To run AWS IoT SiteWise Edge on Siemens Industrial Edge, you need the following:
+ A [Siemens Digital Exchange Platform](https://www.dex.siemens.com/) account.
+ A Siemens Industrial Edge Hub (iehub) account.
+ A Siemens Industrial Edge Management instance.
+ The IE App Configuration Service. To learn more, see [https://docs.eu1.edge.siemens.cloud/get_started_and_operate/industrial_edge_management/how_to_setup_operate/vm/operation/app_projects/app_configurations/ie_application_configuration_service/installing_the_ie_acs_manually.html](https://docs.eu1.edge.siemens.cloud/get_started_and_operate/industrial_edge_management/how_to_setup_operate/vm/operation/app_projects/app_configurations/ie_application_configuration_service/installing_the_ie_acs_manually.html) in the *Siemens Industrial Edge Management* documentation.
+ Access to version 2.0.1 or higher of the AWS IoT SiteWise Edge application. For more information, see [Access the AWS IoT SiteWise Edge application](sa-get-app.md).
+ Either a Siemens Industrial Edge Device (IED) or a Siemens Industrial Edge virtual Device (IEVD).
+ A minimum of 15 GB disk space for hardware requirements.
+ 1 GB of RAM with an additional 1 GB of swap memory.
+ Device configuration to allow outbound traffic on ports 443 and 8883.
+ A x86-64 bit processor.
+ Siemens Industrial Edge Management version 1.13.10 or higher.
+ Device conformance to Siemens Secure Storage requirements.
+ On virtual devices, IEVD version 1.19 or above.
+ On physical devices, IED-OS version 2.2 or above.
+ The latest version of Docker Compose.
+ Docker Engine version 18.091 or higher.
+ Required domain access. For more information, see [AWS IoT SiteWise endpoints](endpoints-and-quotas.md#endpoints).
# Create a gateway for Siemens Industrial Edge
Create a gateway
After you have the proper Siemens accounts and IEM instances, you can create a SiteWise Edge gateway of deployment type **Siemens Industrial Edge device**.
**Note**
Ensure that you meet all requirements for running a device on Siemens Industrial Edge Management. For more information, see [Requirements for the AWS IoT SiteWise Edge application](siemens-app-gateway-requirements.md).
**To create the configuration file**
1. Navigate to the [AWS IoT SiteWise console](https://console.aws.amazon.com/iotsitewise/).
1. In the navigation pane, choose **Edge gateways**.
1. Choose **Create gateway**.
1. For **Deployment type**, choose **Siemens Industrial Edge device**.
1. Enter a name for your SiteWise Edge gateway or use the name generated by AWS IoT SiteWise.
1. (Optional) Under **advanced configuration**, do the following:
1. Enter a name for your AWS IoT Core Thing or use the name generated by AWS IoT SiteWise.
1. Choose **Create gateway**.
1. In the **Generate SiteWise Edge gateway configuration file** dialog box, choose **Generate and download**. AWS IoT SiteWise automatically generates a configuration file that you will use to configure the AWS IoT SiteWise Edge application.
**Important**
Keep your gateway configuration file as a backup in the event that you need to restore your AWS IoT SiteWise Edge application instance. You can securely save your SiteWise Edge gateway configuration file in [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) for this purpose. Secrets Manager securely stores, manages, and retrieves sensitive information. If you misplace or delete this configuration file, you won't be able to reconnect your AWS IoT SiteWise Edge application instance to its original gateway if you need to recover it. You'll need to create both a new gateway and a new configuration file.
# Create a Siemens Databus user for the application
Create a Siemens Databus user
AWS IoT SiteWise Edge on Siemens Industrial Edge ingests data from the Siemens Databus application. To connect SiteWise Edge to the Siemens Databus, you need a Siemens Databus user that provides access to the data you want to securely transfer to AWS IoT SiteWise. To start, create a Siemens Databus user and then provide the credentials to the SiteWise Edge application.
**To create a Siemens Databus user**
1. In your Siemens Industrial Edge Management instance, choose **Edge Management** in the **Platform Applications** section.
1. Choose the **Data connections** icon.
1. Select **Databus**. A list of your connected devices appears.
1. Select the device to connect to the AWS IoT SiteWise Edge application.
1. Choose **Launch**. The Databus Configurator for your selected device appears.
1. Create a user for your Edge device under **Users**. For more information on creating a user, see [Users](https://docs.eu1.edge.siemens.cloud/get_started_and_operate/industrial_edge_management/operation/iam/03_user-management.html) in the *Siemens Industrial Edge Management* documentation.
1. Select the topics for which this Siemens Databus should have access. These topics restrict what AWS IoT SiteWise Edge can access.
**Important**
All topics that a Siemens Databus user has access to are published to AWS IoT SiteWise.
**Note**
Siemens Databus users need access to both data and metadata topics. Topics that start with `ie/d` are data topics. And topics that start with `ie/m` are metadata topics. Share topics in pairs so that SiteWise Edge has access to both data and metadata for each respective topic.
![\[A screenshot displaying the Siemens topic types. The image circles the portion of the file path that starts with "ie/d" and "ie/m," respectively.\]](http://docs.aws.amazon.com/iot-sitewise/latest/userguide/images/gateway-sa-topics.png)
1. Set appropriate permissions for your Siemens Databus configuration.
After creating your Siemens Databus configuration, you can install the AWS IoT SiteWise Edge application on your Siemens Industrial Edge Management. For more information, see [Install the application onto a Siemens device](sa-install-app.md).
You can also optionally configure destinations and path filters for your Siemens Industrial Edge gateway. For more information, see [Destinations and path filters](gw-destinations.md).
# Access the AWS IoT SiteWise Edge application
Access the application
To gain access to the AWS IoT SiteWise Edge application on Siemens Industrial Edge, [send an email](mailto:aws-iot-swe-siemens-app-support@amazon.com?subject=Access request for SiteWise Edge on Siemens Industrial Edge) requesting access to the SiteWise Edge support team.
Include the following information in your email:
+ Your name and contact information
+ Company name
+ Siemens Industrial Edge tenant ID
# Install the application onto a Siemens device
Install the application
After you gain access to the AWS IoT SiteWise Edge application by emailing the SiteWise Edge support team for Siemens Industrial Edge, assign the application to an instance of Siemens Industrial Edge Management. Then, you can install the AWS IoT SiteWise Edge application on your device.
**To install the AWS IoT SiteWise Edge application**
1. Verify that the Docker digest provided within Siemens Industrial Edge Management matches the latest version listed in the [AWS IoT SiteWise Edge application changelog](sitewise-edge-on-siemens.md#sa-changelog).
For more information on locating the Docker digest value for Siemens, see the [Managing an app](https://docs.eu1.edge.siemens.cloud/get_started_and_operate/industrial_edge_device/operation/management.html#managing-an-app) in the *Siemens Industrial Edge Device* of the Siemens documentation.
Siemens Industrial Edge Management supports one version of the AWS IoT SiteWise Edge application at a time. Take this step to ensure that you're using the latest version of the application before installing the AWS IoT SiteWise Edge application on your Siemens Industrial Edge device.
1. Assign the **AWS IoT SiteWise Edge** application to Siemens Industrial Edge Management. For more information, see [Managing an app](https://docs.eu1.edge.siemens.cloud/get_started_and_operate/industrial_edge_management/how_to_setup_operate/vm/operation/my_installed_apps/managing_an_app.html) in the *Industrial Edge Management* section of the Siemens documentation.
1. Within **Edge Management**, browse the catalog for the **AWS IoT SiteWise Edge** and choose it.
1. Choose **Install**.
**Note**
If a **Contact Us** button displays, choose it, and follow the steps to request access to the AWS IoT SiteWise Edge application on Siemens Industrial Edge. For more information, see [Access the AWS IoT SiteWise Edge application](sa-get-app.md).
1. Select **Databus\$1Configuration** in the Schema Configurations options.
1. Enter the **Username** and **Password** for the Databus configuration. For more information on creating a Siemens Databus user, see [Create a Siemens Databus user for the application](sa-databus-user.md).
1. Choose the small, round gray checkmark icon next to **Databus\$1Configuration** to turn the icon color green.
**Note**
The input configurations only apply if the checkmark icon changes from gray to green. Otherwise, the input configuration is ignored.
![\[A screenshot of the Siemens Databus Configurator screen displaying an unfinished process, with a circled gray checkmark icon.\]](http://docs.aws.amazon.com/iot-sitewise/latest/userguide/images/gateway-sa-gray-checkmark.png)
![\[A screenshot of the Siemens Databus Configurator screen displaying a finished process, with a circled green checkmark icon.\]](http://docs.aws.amazon.com/iot-sitewise/latest/userguide/images/gateway-sa-green-checkmark.png)
1. Choose **Next** to move onto **Other Configurations** where you can upload your gateway configuration file.
1. Choose **SiteWise\$1Edge\$1Gateway\$1Config** as the location to upload the gateway configuration file.
**Note**
Ensure that you choose **SiteWise\$1Edge\$1Gateway\$1Config** rather than **SiteWise\$1Edge\$1Support\$1Config\$1Optional**.
1. Select the device to install the application.
1. Choose **Install now**.
You can optionally configure the publisher component to export data to the AWS Cloud. For more information, see [configure the AWS IoT SiteWise publisher component](configure-publisher-component.md).
To configure destinations for your Siemens Industrial Edge gateway, see [Destinations and path filters](gw-destinations.md).
# Update the AWS IoT SiteWise Edge application configuration
Update an installed application configuration
There are a few things to consider when updating an AWS IoT SiteWise Edge application configuration on **Siemens Industrial Edge**.
**Note**
Any change to the AWS IoT SiteWise Edge application configuration requires a restart of the application.
**Reasons to restart the AWS IoT SiteWise Edge application**
+ A new Siemens Databus user for the AWS IoT SiteWise Edge application.
+ A change to the gateway configuration file (your **SiteWise\$1Edge\$1Gateway\$1Config** file).
+ A proxy configuration update (which also requires a full IEVD reboot)
+ To enable debug logs for debugging issues
## Restarting the application
1. In your Siemens Industrial Edge Management instance, choose **Edge Management** in the **Platform Applications** section.
1. Choose **My Installed Apps**.
1. Select the AWS IoT SiteWise Edge application.
1. Choose **Restart**.
# AWS IoT SiteWise – Data generated by the use of this service
Data generated by the use of this service
AWS IoT SiteWise on Siemens Industrial Edge extends cloud capabilities to industrial edge environments, enabling local data processing, analysis, and decision-making. SiteWise Edge integrates with AWS IoT SiteWise and other AWS services to provide comprehensive industrial AWS IoT solutions.
Types of Data
SiteWise Edge application on Siemens Industrial Edge generates data about application performance, usage, and interactions with other AWS services, specifically Amazon S3.
Data Volume and Collection
The amount of data generated varies based on how you use your application and services.
Data Storage
Data from your application is stored securely on AWS servers. It is stored in machine-readable formats.
Data Access
You can access your data through your AWS account. You can download a copy of your data following instructions listed in this user guide [SiteWise Edge on Siemens](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/sitewise-edge-on-siemens.html). For configuration data for the application, you can follow the instructions in this user guide [Query Industrial Data](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/query-industrial-data.html). Further instructions for bulk data access and export, is available on [Running Bulk Operations Export](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/running-bulk-operations-export.html).
Data Management
To learn more about your applications' data practices, please review our [Service Terms](https://aws.amazon.com/service-terms/), [Privacy Notice](https://aws.amazon.com/privacy/), and [Service documentation](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/what-is-sitewise.html) which includes materials on how to manage your data.
Data Deletion
For information about data retention and deletion options, visit these pages in the user guide – [manage data storage](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/manage-data-storage.html), [delete data streams](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/delete-data-streams-method.html) and [delete models and assets](https://docs.aws.amazon.com/iot-sitewise/latest/userguide/delete-assets-and-models.html).
Data sharing with others
You can authorize third parties to access your AWS resources via our [Identify and Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_common-scenarios_third-party.html) processes. AWS shares personal data with third parties in limited cases included in the [AWS Privacy Notice](https://aws.amazon.com/privacy/).
Need Help?
Visit [Customer Support](https://aws.amazon.com/contact-us/) to reach our support team. This is without prejudice to your right to lodge a complaint under applicable law.
Data Holder
Amazon Web Services EMEA SARL, 38 Avenue John F. Kennedy, L-1855, Luxembourg
# Destinations and path filters
Destinations in AWS IoT SiteWise Edge provide a flexible and efficient way to manage how your industrial data flows from edge devices to the cloud. This section explains how to configure destinations, use path filters to route specific data streams, and choose the right destination type for your use case.
You can use destinations and path filters on self-hosted MQTT-enabled, V3 gateways and gateways used in conjunction with AWS IoT SiteWise Edge application hosted on Siemens Industrial Edge. Destinations and path filters do not work with Classic Streams, V2 gateways.
**Topics**
+ [
## Understand AWS IoT SiteWise Edge destinations
](#source-destination)
+ [
## Understand path filters for AWS IoT SiteWise Edge destinations
](#destinations-path-filters)
+ [
# Add an AWS IoT SiteWise Edge real-time destination
](destinations-real-time.md)
+ [
# Add an AWS IoT SiteWise buffered destination using Amazon S3
](destinations-buffered.md)
+ [
# Add path filters to AWS IoT SiteWise Edge destinations
](destinations-add-path-filters.md)
+ [
# Manage AWS IoT SiteWise Edge destinations
](destinations-manage.md)
## Understand AWS IoT SiteWise Edge destinations
Understand destinations
Use AWS IoT SiteWise Edge destinations to determine where to send your source data. You can choose your data destination based on specific characteristics you need, like cost-effectiveness, low latency, or storage requirements. Integrate device data captured by AWS IoT SiteWise, our partners, or custom applications to publish and subscribe to path filters (topics) at the edge. You can then model, transfer, and store your device data in the cloud.
**Note**
For full use of all destination features on self-hosted gateways, upgrade to the latest versions of the IoT SiteWise publisher and IoT SiteWise OPC UA collector. Stream support is continued on Classic streams, V2 gateways to maintain compatibility with existing setups. For more information, see [Classic streams, V2 gateways for AWS IoT SiteWise Edge](classic-streams-v2-gateway.md)
**Topics**
+ [
### How SiteWise Edge destinations enhance data management
](#how-destinations-work)
+ [
### Destination types
](#destination-types)
+ [
### Compare destination functionality between gateway versions
](#destinations-vs-publisher-component)
+ [
### Destination limitations
](#destinations-limitiations)
+ [
### Use cases for SiteWise Edge destinations
](#destinations-use-cases)
### How SiteWise Edge destinations enhance data management
Export data from the edge to AWS IoT SiteWise in real time, or in batches using Amazon S3.
Destinations enhance flexibility and scalability in your AWS IoT SiteWise environment. Destinations implement a centralized data management model, where sources publish data to a central system. Destinations determine where your data is sent using path filters. Destinations can subscribe to multiple path filters.
MQTT-enabled gateways, whether self-hosted or running on Siemens Industrial Edge, use MQTT for local communication and come with a default real-time destination which has filters set to `#`. This means that, by default, all messages on all topics are published to the AWS IoT SiteWise real-time destination. For more information, see [Understand path filters for AWS IoT SiteWise Edge destinationsUnderstand path filters](#destinations-path-filters). You can add one real-time destination in each gateway.
### Destination types
When configuring a destination for your gateway, you have two main options: real-time configuration using AWS IoT SiteWise, and a buffered configuration using Amazon S3. Each destination type has its own set of settings and considerations.
**AWS IoT SiteWise real-time settings**
Choose this to send data directly to AWS IoT SiteWise hot-tier storage to facilitate ingesting and monitoring data in real-time. The real-time settings manage data flow, particularly when a gateway experiences connectivity issues with the cloud. During connection loss, data is temporarily stored locally on the gateway. Once the connection is re-established, the stored data is automatically sent to the cloud.
You can adjust various aspects of the data publishing process, such as the maximum amount of data to be stored locally, the rate at which data is sent to the cloud upon reconnection, and when to delete data after the storage reaches its capacity.
For more information on AWS IoT SiteWise storage tiers, see, [Manage data storage in AWS IoT SiteWise](manage-data-storage.md).
**AWS IoT SiteWise buffered using Amazon S3 settings**
This destination type allows you to buffer data locally on the gateway and periodically send it to an Amazon S3 bucket in batches. The data is stored in the efficient Parquet format, which is optimized for analytical workloads. Once the data is in Amazon S3, you can import it into AWS IoT SiteWise for storage, processing, and analysis.
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 SiteWise and Amazon S3 or you can choose to delete it automatically from Amazon S3.
### Compare destination functionality between gateway versions
The destinations feature in MQTT-enabled gateways streamlines data flow management. Destinations simplify data management through centralized configuration of data routing to various endpoints. This approach eliminates the need for complex individual stream setups, making the overall system more flexible and easier to manage.
By comparison, the Classic streams, V2 gateway, SiteWise Edge transmits data from data sources to publishers via AWS IoT Greengrass streams, configuring data destinations individually for each data source.
With the AWS IoT SiteWise destination feature, the publisher routing configuration is consolidated. Destination configuration allows you to manage destinations and path filters in a centralized manner. You can easily add a destination, manage path filters, delete unnecessary filters or destinations, depending on your needs.
Additionally, the destinations feature utilizes MQTT (Message Queuing Telemetry Transport), an industry-standard protocol widely used in industrial IoT applications. This adoption of MQTT helps AWS IoT SiteWise to facilitate easier integration with various devices and systems.
### Destination limitations
Limitations
Current limitations for destinations on SiteWise Edge gateways include:
+ The data processing pack isn't supported on MQTT-enabled gateways.
+ Data type support is limited to AWS IoT SiteWise data types. For information on enabling data type conversion, see [Converting unsupported data types](string-conversion.md).
### Use cases for SiteWise Edge destinations
Use cases
SiteWise Edge destinations are utilized in diverse applications. Here are some key examples:
**Industrial automation***Real-time monitoring and predictive maintenance*
In industrial settings, sensors and devices on the factory floor can publish data to SiteWise Edge. Destinations can be configured to filter and route relevant data, enabling real-time monitoring and analysis of machine performance. You can subscribe to relevant MQTT topics using path filters, process the data, and then publish the processed data. In this way, you can selectively route processed data to AWS cloud analytic services or on-premises systems. Manufacturers can then implement predictive maintenance strategies, optimize production processes, and reduce downtime.
**Smart buildings***Energy efficiency and occupancy optimization*
Building automation systems generate data streams to monitor and control various aspects of a building, such as HVAC systems, lighting, and access control. With SiteWise Edge, these data streams can be ingested, processed, and routed to different destinations. Facility managers can configure destinations to filter and forward relevant data, enabling advanced capabilities like energy efficiency measures and occupancy optimization while ensuring data privacy and compliance.
These use cases demonstrate how the Destinations feature in SiteWise Edge can be leveraged across various industries to ingest, process, and route data efficiently. This enables advanced capabilities such as real-time monitoring, predictive maintenance, energy efficiency, and remote diagnostics while ensuring data privacy and compliance.
## Understand path filters for AWS IoT SiteWise Edge destinations
Understand path filters
**Topics**
+ [
### Path filter requirements
](#path-filter-requirements)
+ [
### Best practices for path filters
](#create-effective-path-filters)
+ [
### Path filters for OPC UA servers
](#path-filters-opcua)
+ [
### Special characters in path filter names
](#path-filters-special-characters)
Each destination is configured to route data to AWS IoT SiteWise or Amazon S3. Path filters allow you to select specific data to filter when receiving MQTT messages for a destination. Path filters represent the logical names of your data streams, acting as subscriptions to desired MQTT topics.
In MQTT, data is organized into topics, which are hierarchical strings separated by forward slashes (`/`). For example, a device might publish temperature data to the topic `home/livingroom/sensor1/temperature`. Here, `home/livingroom/sensor1` represents the path or logical name of the sensor, and `temperature` is the data type being published.
You can use path filters to subscribe to specific topics or a range of topics using wildcards (`+` and `#`). The `+` wildcard matches a single level in the topic hierarchy. For example, `home/+/sensor1/temperature` would match `home/livingroom/sensor1/temperature` and `home/bedroom/sensor1/temperature`. The `#` wildcard, when used at the end of a filter, matches multiple levels.
You can also use a variety of characters typically not allowed in the MQTT specification within a path filter name. These characters don't function as wildcards when used within a name. AWS IoT SiteWise converts these characters using encoding to ensure MQTT compliance while preserving your original naming structure. This feature is particularly useful for accommodating existing naming conventions from other systems. For more information, see [Special characters in path filter names](#path-filters-special-characters).
By carefully selecting the appropriate path filters, you can control which data is sent to a specific destination. Tailor the data flow to your IoT system's requirements using path filters.
### Path filter requirements
When entering path filters using the AWS IoT SiteWise console, keep the following in mind:
+ Path filters are delimited by a new line, with each line representing a separate path filter.
+ Individual path filters can have between 1 and 65,535 bytes.
+ A path filter can't be blank.
+ Null values (U\$10000) are not allowed.
+ You can enter up to 100 path filters or 65,535 characters at a time, whichever limit is reached first.
+ The overall limit is 20,000 path filters for all the destinations on a gateway combined.
+ You can use `%`, `#`, `+`, and `$` characters within path filter names, however AWS IoT SiteWise automatically converts them to URI encoding.
### Best practices for path filters
When creating path filters for your AWS IoT SiteWise destinations, consider the following strategies to effectively manage your data.
+ Structure your filters to mirror your device hierarchy. For example, in a manufacturing setting, `factory/+/machine/#`, captures data from all machines across different production lines.
+ Use specific levels for device types, locations, or functions. For example, `factory/assembly-line/robot/temperature`. Or, in smart agriculture, `farm/+/crop/+/moisture`, to monitor moisture levels for various crops across different fields.
+ Leverage wildcards strategically: Use `+` for variations at a single level and `#` to capture all subsequent levels. For example, `building/+/+/energy-consumption`, tracks energy usage across different zones and floors in a building. This assumes the first `+` captures all floors and the second `+` captures all zones.
+ Balance specificity and flexibility by creating filters that are specific enough to capture relevant data but flexible enough to accommodate future changes. For example, `site/+/equipment-type/+/measurement` allows for addition of new sites or equipment types without changing the filter structure.
Test your filters thoroughly to ensure they capture the intended data and align with your IoT system's architecture and goals.
### Path filters for OPC UA servers
For OPC UA servers, your path filters must correspond to the OPC UA tag names. The final level of your path filter must match the OPC UA tag name exactly. For example, if your OPC UA tag is `Device1.Temperature`, your path filter might be `factory/line1/Device1.Temperature`. You can use wildcards in the preceding levels, such as `factory/+/Device1.Temperature` to capture the tag across multiple production lines. If you have special characters within your path filter names, see [Special characters in path filter names](#path-filters-special-characters) for more information.
### Special characters in path filter names
AWS IoT SiteWise accommodates characters commonly used in industrial protocols like OPC UA, which are typically not allowed in standard MQTT topic names. This feature facilitates smoother integration of industrial systems with MQTT-based architectures.
**Note**
While our special character handling is helpful for integration and migration, it's recommended to align with standard MQTT naming conventions for new implementations when possible to ensure broader compatibility.
When receiving data from industrial sources, AWS IoT SiteWise normalizes topic names using URI encoding for special characters:
+ `%` becomes `%25` (encoded first as the escape character)
+ `#` becomes `%23`
+ `+` becomes `%2B`
+ `$` becomes `%24` (only when at the start of a topic)
This encoding ensures that source data containing these special MQTT characters can be safely used as MQTT topic names while preserving the original industrial naming conventions.
**Example : Special characters in path filter names**
Here are examples of how industrial topic names might appear in AWS IoT SiteWise path filters:
+ `Factory1/Line#2/Sensor+3` becomes `Factory1/Line%232/Sensor%2B3`
+ `Plant%A/Unit$1/Temp` becomes `Plant%25A/Unit%241/Temp`
+ `Site1/#Section/+Node` becomes `Site1/%23Section/%2BNode`
When creating subscriptions or viewing topic names in AWS IoT SiteWise, you'll see the original, unencoded versions. The encoding is handled automatically to ensure MQTT compliance.
# Add an AWS IoT SiteWise Edge real-time destination
Add a real-time destination
The real-time destination type enables you to stream IoT data directly from your devices and gateways into AWS IoT SiteWise storage in real-time. This option is ideal for use cases that require immediate ingestion and processing of data as it is generated, without the need for batching or buffering. You can only have one real-time destination configured in each gateway, as it streams data continuously to AWS IoT SiteWise.
**Note**
Duplicate TQVs may result in double charging.
**To add a real-time destination**
Use the AWS IoT SiteWise console or AWS CLI to add a real-time destination to your SiteWise Edge MQTT-enabled gateway.
------
#### [ Console ]
1. Open the [AWS IoT SiteWise console](https://console.aws.amazon.com/iotsitewise/).
1. In the navigation pane, choose **Edge gateways**.
1. Select the gateway to which you want to add a destination.
1. In the **Destinations** section, choose **Add destination**.
1. On the **Add destination** page, enter **Destination details**:
1. A name for your destination in the **Destination name** field.
1. Select the **AWS IoT SiteWise real-time** for the **Destination type**.
1. Configure the gateway publishing order by setting the **Publishing order** to either **Publish older data first** or **Publish newest data first**. By default, the gateway publishes the oldest data first.
1. Use **Maximum batch wait time** to set a maximum time for the publisher to wait before sending a batch of data to AWS IoT SiteWise. This setting applies for each alias. The data is stored locally until either:
+ The set time has elapsed, or
+ 10 time-quality-value (TQV) entries are received for the alias
Whichever condition is met first triggers the batch to be sent to the cloud.
1. To compress uploaded data, select the **Activate compression when uploading data** check box. Letting the gateway compress your data prior to uploading it to the cloud reduces bandwidth usage.
1. To filter out expired publisher data, select the **Exclude expired data** check box. This selection only sends active and current data to AWS IoT SiteWise.
1. In the **Cutoff period** field, enter the frequency at which data should be considered expired within your dataset. You can determine if the data is counted in terms of minutes or days. The minimum cutoff period is five minutes. The maximum cutoff period is seven days.
1. Optionally configure the **Local storage settings**:
1. Set the **Retention period** frequency – The amount of time the gateway locally stores data that is older than the cutoff period. The minimum retention period is one minute.
The maximum retention period is 30 days and greater than or equal to the rotation period.
1. Set the **Rotation period** – The time interval to specify when saving data that is older than the cutoff period for a single file. The gateway transfers one batch of data to the following local directory at the end of each rotation period: `/greengrass/v2/work/aws.iot.SiteWiseEdgePublisher/exports`.
The retention must be greater than one minute and equal to the retention period.
1. Provide the **Storage capacity (GB)** value to set the maximum size of data stored locally in GB. If the data exceeds the determined maximum local storage size, the gateway starts deleting the oldest data first. The gateway continues to delete until the size of data stored locally is equal to or less than the quota.
The storage capacity must be greater than or equal to one GB.
1. Add path filters to your destination. For more information see, [Add path filters to AWS IoT SiteWise Edge destinations](destinations-add-path-filters.md).
For more information, see [Destination types](gw-destinations.md#destination-types).
------
#### [ AWS CLI ]
**Example : Create a new AWS IoT SiteWise real-time destination**
Use the [UpdateGatewayCapabilityConfiguration](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_UpdateGatewayCapabilityConfiguration.html) API to configure the publisher.
Set the `capabilityNamespace` parameter to `iotsitewise:publisher:3`.
```
{
"sources": [
{
"type": "MQTT"
}
],
"destinations": [
{
"type": "SITEWISE_REALTIME",
"name": "your-destination-name",
"config": {
"publishingOrder": "TIME_ORDER",
"enableCompression": true,
"maxBatchWaitTime": "10s"
},
"filters": [
{
"type": "PATH",
"config": {
"paths": [
"#"
]
}
}
]
}
]
}
```
To update an existing AWS IoT SiteWise real-time destination, first use the `DescribeGatewayCapabilityConfiguration` API to find the `destinationId`.
**Example : Update an AWS IoT SiteWise real-time destination**
Use the [UpdateGatewayCapabilityConfiguration](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_UpdateGatewayCapabilityConfiguration.html) API to configure the publisher.
Set the `capabilityNamespace` parameter to `iotsitewise:publisher:3`.
```
{
"sources": [
{
"type": "MQTT"
}
],
"destinations": [
{
"id": "your-existing-destination-id",
"type": "SITEWISE_REALTIME",
"name": "your-destination-name",
"config": {
"publishingOrder": "TIME_ORDER",
"enableCompression": true,
"dropPolicy": {
"cutoffAge": "7d",
"exportPolicy": {
"retentionPeriod": "7d",
"rotationPeriod": "6h",
"exportSizeLimitGB": 10
}
},
"maxBatchWaitTime": "10s"
},
"filters": [
{
"type": "PATH",
"config": {
"paths": [
"#"
]
}
}
]
}
]
}
```
The following configuration options are specific to gateways using the `iotsitewise:publisher:3` namespace.
`sources`
Defines data sources to transfer of data from your industrial equipment to AWS IoT SiteWise. For MQTT-enabled gateways, use `MQTT`.
Type: Array of objects
Required: Yes
`destinations`
Defines where to send data. Destinations are either real-time or buffered using Amazon S3. At least one destination object is required, but you can add an empty array. You can have one real-time destination for each gateway. For more information, see [Understand AWS IoT SiteWise Edge destinations](gw-destinations.md#source-destination).
Type: Array of objects
Required: Yes
`id`
The unique identifier for the destination. You can either provide an existing destination ID or leave it blank. If you do not specify an ID then a UUID is generated by default.
Type: String
Required: No
`type`
Type of destination. Options include: `SITEWISE_REALTIME` and `SITEWISE_BUFFERED`.
+ `SITEWISE_REALTIME` – Send data directly to AWS IoT SiteWise storage in real-time.
+ `SITEWISE_BUFFERED` – Send data to Amazon S3 in batches in Parquet format, and then import into AWS IoT SiteWise storage.
Type: String
Required: Yes
`name`
A unique name for the destination.
Type: String
Required: Yes
`config`
Configuration specific to the destination type in JSON format. The configuration varies between real-time and buffered destinations.
Type: Object
Required: Yes
publishingOrder
Determines the order in which data is published. Data publishes based on its timestamp. Options include `TIME_ORDER` and `RECENT_DATA`.
+ `TIME_ORDER` (default) – Publishes older data first.
+ `RECENT_DATA` – Publishes newest data first.
Type: String
Required: No
enableCompression
When set to `true`, enables data compression before sending to AWS IoT SiteWise. Letting the gateway compress your data prior to uploading it to the cloud reduces bandwidth usage. The default value is `true`.
Type: Boolean
Required: No
dropPolicy
Defines how to handle older data.
Type: object
Required: No
+ `cutoffAge`
The maximum age of data to be published specified in days, hours, and minutes. For example, `7d` or `1d7h16m`. Data older than what you specify is not sent to AWS IoT SiteWise.
Data that is earlier than the cutoff period is not published to the cloud. The cutoff age must be between five minutes and seven days.
You can use `m`, `h`, and `d` when you specify a cutoff age. Note that `m` represents minutes, `h` represents hours, and `d` represents days.
Type: String
Required: Yes
+ `exportPolicy`
Defines how to handle data that exceeds the cutoff age.
Type: Object
Required: No
+ `retentionPeriod`
Your SiteWise Edge gateway deletes any data at the edge that is earlier than the cutoff period from the local storage after it is stored for the specified retention period. The retention period must be between one minute and 30 days, and greater than or equal to the rotation period.
You can use `m`, `h`, and `d` when you specify a retention period. Note that `m` represents minutes, `h` represents hours, and `d` represents days.
Type: String
Required: No
+ `rotationPeriod`
The time interval over which to batch up and save data that is earlier than the cutoff period to a single file. The SiteWise Edge gateway transfers one batch of data to the following local directory at the end of each rotation period: `/greengrass/v2/work/aws.iot.SiteWiseEdgePublisher/exports`. The rotation period must be greater than one minute, and equal to or less than the retention period.
You can use `m`, `h`, and `d` when you specify a rotation period. Note that `m` represents minutes, `h` represents hours, and `d` represents days.
Type: String
Required: No
+ `exportSizeLimitGB`
The maximum allowed size of data stored locally, in GB. If this quota is breached, the SiteWise Edge gateway starts deleting the earliest data until the size of data stored locally is equal to or less than the quota. The value of this parameter must be greater than or equal to 1.
Type: Integer
Required: No
`maxBatchWaitTime`
Sets a maximum time for the publisher to wait before sending a batch of data to AWS IoT SiteWise. This setting applies for each alias. The data is stored locally until either:
+ The set time has elapsed, or
+ 10 time-quality-value (TQV) entries are received for the alias
Use `m`, `h`, and `d` to specify a cutoff time. Note that `m` represents minutes, `h` represents hours, and `d` represents days.
Type: String
Required: No
`filters`
Filters to apply to the data. At least one filter is required.
Type: String
Required: Yes
`type`
Type of filter. Use `PATH`.
Type: String
Required: Yes
`config`
Configuration specific to the filter type in JSON format. At least one object is required, but the array can be empty.
Type: Object
Required: Yes
+ `paths`
An array of path filters. For more information, see [Understand path filters for AWS IoT SiteWise Edge destinationsUnderstand path filters](gw-destinations.md#destinations-path-filters). The default path is `#`.
Type: Array of strings
Required: Yes
------
# Add an AWS IoT SiteWise buffered destination using Amazon S3
Add a buffered destination using Amazon S3
The buffered destination type allows you to save on ingestion costs into AWS IoT SiteWise if you don't need the data in real-time. It enables you to temporarily store your IoT data in an Amazon S3 bucket before importing it into AWS IoT SiteWise. Or, you can simply upload your data to S3 for storage, regardless of whether you plan to import it to AWS IoT SiteWise. This is useful for batching and buffering data from your devices and gateways before ingesting it into AWS IoT SiteWise. With this option, data is uploaded to the specified S3 bucket in Parquet format at a configured frequency. You can then import this data into AWS IoT SiteWise storage for further analysis and processing.
**To add a destination buffered using Amazon S3**
Use the AWS IoT SiteWise console or AWS CLI to add a destination that buffers data using Amazon S3 to your SiteWise Edge gateway.
------
#### [ Console ]
Use the AWS Management Console to add an AWS IoT SiteWise destination buffered using Amazon S3.
1. Open the [AWS IoT SiteWise console](https://console.aws.amazon.com/iotsitewise/).
1. In the navigation pane, choose **Edge gateways**.
1. Select the gateway to which you want to add a destination.
1. In the **Destinations** section, choose **Add destination**.
1. On the **Add destination** page, enter **Destination details**:
1. A name for your destination in the **Destination name** field.
1. Select **AWS IoT SiteWise buffered using Amazon S3** for **Destination type**. AWS IoT SiteWise buffered using Amazon S3 sends data to Amazon Simple Storage Service in batches, in Parquet format, and then imports the data into AWS IoT SiteWise storage.
1. Enter the Amazon S3 URL for the location where you want to store your gateway data. You can browse for the path by choosing **Browse S3**. Once a bucket is added, you can also view the bucket by choosing **View**.
1. Specify how often your gateway should upload data to Amazon S3 by entering a time frame and selecting a time increment for **Data upload frequency**. The frequency value should be greater than 0 and less than or equal to 30 days.
1. In **Data storage settings**, determine what to do with your gateway data after importing it to AWS IoT SiteWise. There are two decisions to make regarding data storage:
+ If you want to copy imported data into AWS IoT SiteWise storage, select the **Copy data to storage** check box. This option duplicates the imported data from your configured Amazon S3 bucket into AWS IoT SiteWise storage.
+ If you choose to import your data from your Amazon S3 bucket into AWS IoT SiteWise storage, you can also specify whether the imported data should be deleted after the import is complete. Select the **Delete data from Amazon S3** check box to delete the imported date from the configured Amazon S3 bucket after importing it to AWS IoT SiteWise storage.
1. Add path filters to your destination. For more information see, [Add path filters to AWS IoT SiteWise Edge destinations](destinations-add-path-filters.md).
------
#### [ AWS CLI ]
**Example : Create a new AWS IoT SiteWise destination buffered using Amazon S3**
Use the [UpdateGatewayCapabilityConfiguration](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_UpdateGatewayCapabilityConfiguration.html) API to configure the publisher.
Set the `capabilityNamespace` parameter to `iotsitewise:publisher:3`.
```
{
"sources": [
{
"type": "MQTT"
}
],
"destinations": [
{
"type": "SITEWISE_BUFFERED",
"name": "your-s3-destination-name",
"config": {
"targetBucketArn": "arn:aws:s3:::amzn-s3-demo-bucket/Optional/SomeFolder",
"publishPolicy": {
"publishFrequency": "15m",
"localSizeLimitGB": 10
},
"siteWiseImportPolicy": {
"enableSiteWiseStorageImport": true,
"enableDeleteAfterImport": true,
"bulkImportJobRoleArn": "arn:aws:iam::123456789012:role/your-role-name"
}
},
"filters": [
{
"type": "PATH",
"config": {
"paths": [
"#"
]
}
}
]
}
]
}
```
**Example : Update an AWS IoT SiteWise destination buffered using Amazon S3**
To update an existing AWS IoT SiteWise real-time destination, first use the `DescribeGatewayCapabilityConfiguration` API to find the `destinationId`.
The publisher namespace: `iotsitewise:publisher:3`
```
{
"sources": [
{
"type": "MQTT"
}
],
"destinations": [
{
"id": "your-existing-destination-id",
"type": "SITEWISE_BUFFERED",
"name": "your-s3-destination-name",
"config": {
"targetBucketArn": "arn:aws:s3:::amzn-s3-demo-bucket/Optional/SomeFolder",
"publishPolicy": {
"publishFrequency": "15m",
"localSizeLimitGB": 10
},
"siteWiseImportPolicy": {
"enableSiteWiseStorageImport": true,
"enableDeleteAfterImport": true,
"bulkImportJobRoleArn": "arn:aws:iam::123456789012:role/your-role-name"
}
},
"filters": [
{
"type": "PATH",
"config": {
"paths": [
"#"
]
}
}
]
}
]
}
```
The following configuration options are specific to MQTT-enabled gateways using the `iotsitewise:publisher:3` namespace.
`sources`
Defines data sources to transfer of data from your industrial equipment to AWS IoT SiteWise. For MQTT-enabled gateways, use `MQTT`.
Type: Array of objects
Required: Yes
`destinations`
Defines where to send data. Destinations are either real-time or buffered using Amazon S3. At least one destination object is required, but you can add an empty array. You can have one real-time destination for each gateway. For more information, see [Understand AWS IoT SiteWise Edge destinations](gw-destinations.md#source-destination).
Type: Array of objects
Required: Yes
`id`
The unique identifier for the destination. You can either provide an existing destination ID or leave it blank to have a new ID automatically generated for the destination.
Type: String
Required: No
`type`
Type of destination. Options include: `SITEWISE_REALTIME` and `SITEWISE_BUFFERED`. Choose `SITEWISE_BUFFERED`.
+ `SITEWISE_REALTIME` (default) – Send data directly to AWS IoT SiteWise storage in real-time. For more information, see [Add an AWS IoT SiteWise Edge real-time destination](destinations-real-time.md).
+ `SITEWISE_BUFFERED` – Send data to Amazon S3 in batches in Parquet format, and then import into AWS IoT SiteWise storage.
Type: String
Required: Yes
`name`
A unique name for the destination.
Type: String
Required: Yes
`config`
Configuration specific to the destination type in JSON format. The configuration varies between real-time and buffered destinations.
Type: Object
Required: Yes
`targetBucketArn`
The bucket ARN to publish to. Choose the same AWS Region for both AWS IoT SiteWise and Amazon S3. If a prefix is chosen, it must have between 1-255 characters.
AWS IoT SiteWise, including the gateway, will have access to the entire specified S3 bucket. We recommend using a dedicated bucket for buffered data ingestion.
Type: String
Required: Yes
`publishPolicy`
Details of the publishing policy.
Type: Object
Required: Yes
`publishFrequency`
The frequency with which the SiteWise Edge gateway publishes to the Amazon S3 bucket. Data upload frequency to Amazon S3 must be greater than 0 minutes and less than or equal to 30 days. You can use `m`, `h`, and `d` when you specify a publishing frequency age. Note that `m` represents minutes, `h` represents hours, and `d` represents days. The default value is 15 minutes.
Type: String
Required: Yes
`localSizeLimitGB`
The maximum size of the files written to local disk in GB. If this threshold is breached, the publisher publishes all buffered data to its destination.
Type: Integer
Required: Yes
`siteWiseImportPolicy`
Details of the import policy for importing data to AWS IoT SiteWise.
Type: Object
Required: Yes
`enableSiteWiseStorageImport`
Set this to `true` to import data from an Amazon S3 bucket to AWS IoT SiteWise storage. It initially makes a copy of the data in AWS IoT SiteWise. Then, if you set `enableDeleteAfterImport` to true, the data in S3 deletes after copying to AWS IoT SiteWise. Pricing implications apply. The default value is `true`.
Type: Boolean
Required: Yes
`enableDeleteAfterImport`
Set this to `true` to delete the file in the Amazon S3 bucket after ingestion into the AWS IoT SiteWise storage. The default value is `true`.
Type: Boolean
Required: Yes
`bulkImportJobRoleArn`
The ARN of the IAM role that AWS IoT SiteWise assumes to read buffered data from Amazon S3 during data ingestion. This role is used when an edge device calls on AWS IoT SiteWise APIs to initiate the bulk import process.
If `enableSiteWiseStorageImport` is set to `true`, this parameter is required.
Type: String
Required: No
------
Add path filters for your destination. For more information, see [Add path filters to AWS IoT SiteWise Edge destinations](destinations-add-path-filters.md).
# Add path filters to AWS IoT SiteWise Edge destinations
Add path filters
Add path filters to a destination. Path filters use MQTT topic syntax, where `#` is a wildcard character that matches any number of levels, and `+` is a wildcard character that matches a single level. You can add multiple destinations to a gateway, each with its own set of path filters subscribed to your equipment telemetry.
Siemens Industrial Edge gateways use a prefix for compatibility. For more information, see [Prefixes for path filters](sitewise-edge-on-siemens.md#siemens-path-filters).
------
#### [ Console ]
**To add path filters**
1. Open the [AWS IoT SiteWise console](https://console.aws.amazon.com/iotsitewise/).
1. In the navigation pane, choose **Edge gateways**.
1. Select the gateway to which you want to add path filters.
1. In the **Path filters** section under **Add destination**, choose **Add path filter**.
1. Enter the path filter that you want this destination to subscribe to. You can use wildcard characters (`#` and `+`) to subscribe to multiple paths.
1. Choose **Add path filter** to add the path filter to the list.
1. Repeat steps to add additional path filters, if needed.
1. Once you have added all of the required path filters, choose **Create**.
------
#### [ AWS CLI for self-hosted gateways ]
**Example : Path filter configuration**
```
{
"destinations": [
{
...
}
],
"filters": [
{
"type": "PATH",
"config": {
"paths": [
"home/+/sensor1/temperature",
"home/livingroom/sensor1/temperature",
"home/livingroom/sensor1/temperature",
"building/#"
]
}
}
]
}
```
------
#### [ AWS CLI for Siemens IEgateways ]
**Example : Prefix configuration for path filters**
Capture all data by using both the data (`ie/d`) and metadata (`ie/m`) prefixes for each path filter.
```
{
"destinations": [
{
...
}
],
"filters": [
{
"type": "PATH",
"config": {
"paths": [
"ie/d/home/+/sensor12/temperature",
"ie/m/home/livingroom/sensor12/temperature",
"ie/d/home/livingroom/sensor13/temperature2",
"ie/m/home/livingroom/sensor13/temperature2",
"ie/d/building/#",
"ie/m/building/#"
]
}
}
]
}
```
------
**Note**
Copy path filters between destinations by downloading list of path filters. For more information, see [Download all path filters in a destination (console)](destinations-manage.md#destinations-download-list).
## Upload path filters in bulk
To upload path filters in bulk, use a CSV or text file. AWS IoT SiteWise automatically removes exact duplicates when you upload files. For example, `windfarm/site1/` and `windfarm/site1/` are exact duplicates that AWS IoT SiteWise catches because the string is exactly the same. Partial duplicates are not removed and result in additional charges. For example, `windfarm/#` and `windfarm/site1` are overlapping topics because `windfarm/site1` is already encompassed by `windfarm/#`.
**Note**
Avoid duplicates to prevent additional charges. The uploaded file must be in either .csv or .txt format. It can't contain any headers and should consist of a single column. In the column, list your path filters, with each filter on a separate line. No other information should be included in the file.
**File upload requirements**
These are additional path filter requirements.
+ You can upload one .csv or .txt file. Other file formats are not supported.
+ CSV (.csv) files cannot have headers and should only contain one column.
+ You can have one path filter on each line.
+ The uploaded files cannot be empty.
+ When using `#` as a wildcard, it must be the last character in the topic filter. For example, `topic/#` or as a standalone character at a particular topic level. However, note that `#` can also be used as a regular character within a topic level name, such as `factory/machine#1/topic`. For more information see [Special characters in path filter names](gw-destinations.md#path-filters-special-characters)
+ You can also use the `+` character. For example, use `factory/+/temp` to get all temperatures for factories instead of `factory/machine2/temp` and `factory/machine3/temp` individually.
# Manage AWS IoT SiteWise Edge destinations
Manage destinations
After adding destinations, you can perform various operations to manage them, such as editing destination configurations, deleting destinations, and managing path filters.
## Edit a destination
Select the radio button next to the destination in the table and choose the **Edit** button to edit a destination.
------
#### [ Console ]
**To edit a destination using the AWS IoT SiteWise console**
1. Open 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 appropriate gateway.
1. In the **Destinations** section, choose destination you want to edit and then choose **Edit**.
1. Modify the destination and then choose **Save**.
------
#### [ AWS CLI ]
**To edit a destination using AWS CLI**
+ You can edit a destination by modifying the JSON capability configuration information.
```
aws iotsitewise update-gateway-capability-configuration \
--gateway-id your-gateway-id \
--capability-namespace "iotsitewise:publisher:3" \
--capability-configuration '{
"sources": [
{
"type": "MQTT"
}
],
"destinations": [
{
"id": "your-existing-destination-id",
"type": "SITEWISE_REALTIME",
"name": "your-updated-destination-name",
"config": {
"publishingOrder": "TIME_ORDER",
"enableCompression": true,
"dropPolicy": {
"cutoffAge": "10d",
"exportPolicy": {
"retentionPeriod": "10d",
"rotationPeriod": "6h",
"exportSizeLimitGB": 10
}
},
"maxBatchWaitTime": "15s"
},
"filters": [
{
...
}
]
}
]
}'
```
**Note**
You can't update the destination `type` or `capability-namespace`. For example, you can't switch from a type of `SITEWISE_REALTIME` to `SITEWISE_BUFFERED`. You can have one real-time destination for each MQTT-enabled gateway.
------
## Delete a destination
If you no longer need a destination, you can delete it from your SiteWise Edge gateway.
------
#### [ Console ]
**To delete a destination using the AWS IoT SiteWise console**
1. Open 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 appropriate gateway.
1. In the **Destinations** section, choose destination you want to delete and then choose **Delete**. A confirmation screen appears.
1. To confirm your choice to delete the destination, type "delete" in the confirmation box.
------
#### [ AWS CLI ]
**To delete a destination using AWS CLI**
+ Delete the gateway capability configuration by specifying the gateway ID and modifying the capability configuration to remove the destination you want to delete.
```
aws iotsitewise update-gateway-capability-configuration \
--gateway-id your-gateway-id \
--capability-namespace "iotsitewise:publisher:3" \
--capability-configuration '{
"sources": [
{
"type": "MQTT"
}
],
"destinations": []
}'
```
**Note**
The destinations array can be empty (`[]`), but the destinations object itself must be included in the capability configuration.
------
## Download all path filters in a destination (console)
Download a CSV file containing all of your path filters in the AWS IoT SiteWise console. You can use a downloaded list of path filters to easily share path filter lists between gateway destinations.
**To download a CSV file of all path filters using the AWS IoT SiteWise console**
1. Open 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 gateway containing your path filters.
1. Choose either **Add destination** or **Edit destination**.
1. Navigate to the **Path filters** section and choose **Download CSV**.
**Note**
The CSV file includes all path filters in a particular destination, regardless of which ones you selected from the list of path filters.
## Edit a path filter
You can edit individual path filters to refine which data your destination receives.
------
#### [ Console ]
Using the AWS IoT SiteWise console, you can edit each individual path filter within each respective text box.
**To edit a path filter using the AWS IoT SiteWise console**
1. Open 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 gateway containing your path filters.
1. Select the appropriate destination.
1. Choose **Edit**.
1. Choose the text box for the row containing the path filter that you want to edit.
1. Update the path filter's text, ensuring that the edited path filter's checkbox is selected.
1. Choose **Save**.
------
#### [ AWS CLI ]
To edit path filters for a destination using the AWS CLI, first retrieve the current configuration, modify it, and then update it using the `update-gateway-capability-configuration` command.
**To edit a path filter using AWS CLI**
1. Retrieve the current capability configuration:
```
aws iotsitewise describe-gateway-capability-configuration \
--gateway-id your-gateway-id \
--capability-namespace "iotsitewise:publisher:3" \
--query "capabilityConfiguration"
```
1. Edit the JSON to modify the path filters as needed.
1. Update the capability configuration with the modified path filters:
```
aws iotsitewise update-gateway-capability-configuration \
--gateway-id your-gateway-id \
--capability-namespace "iotsitewise:publisher:3" \
--capability-configuration json-containing-your-updated-path-filters
```
------
## Delete a path filter
You can delete path filters for a destination to control the data it receives from MQTT sources and data processing pipelines.
------
#### [ Console ]
**To delete a path filter using the AWS IoT SiteWise console**
1. Open 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 gateway containing your path filters.
1. Select the appropriate destination.
1. Choose **Edit**.
1. On the **Edit destination** screen, in the **Path filters** section, select one or more the path filters to delete.
1. Choose **Delete**. A deletion confirmation message appears. If want to proceed with deleting the path filters, choose **Delete** on the confirmation screen.
------
#### [ AWS CLI ]
**To delete a destination using AWS CLI**
+ Delete a path filter by removing it from the capability configuration.
```
aws iotsitewise update-gateway-capability-configuration \
--gateway-id your-gateway-id \
--capability-namespace "iotsitewise:publisher:3" \
--capability-configuration '{
"sources": [
{
"type": "MQTT"
}
],
"destinations": [
{
"id": "your-destination-id",
"type": "SITEWISE_REALTIME",
"name": "your-destination-name",
"config": {
...
},
"filters": [
{
"type": "PATH",
"config": {
"paths": [
"/path1",
"/path2",
"/delete-a-path-to-remove-it"
]
}
}
]
}
]
}
```
**Note**
The filters array can be empty (`[]`), but the filters object itself must be included in the capability configuration.
------
# Manage SiteWise Edge gateways
Manage gateways
You can use the AWS IoT SiteWise console and API operations to manage AWS IoT SiteWise Edge gateways. You can also use the [AWS OpsHub for AWS IoT SiteWise for Windows](https://aws-iot-sitewise.s3.amazonaws.com/gateway/OpsHub+for+AWS+IoT+SiteWise.exe) application to manage some aspects of your SiteWise Edge gateway from your local device.
We highly recommend that you use the AWS OpsHub for AWS IoT SiteWise application to monitor the disk usage on your local device. You can also monitor the `Gateway.AvailableDiskSpace` and `Gateway.UsedPercentageDiskSpace` Amazon CloudWatch metrics and create alarms to get notified when the disk space is getting low. For more information about Amazon CloudWatch alarms, see [Create a CloudWatch alarm based on a static threshold](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/ConsoleAlarms.html).
Make sure that your device has enough space for upcoming data. When you're about to run out of space on your local device, the service automatically deletes a small amount of data with the oldest timestamps to make room for upcoming data.
To check if the service deleted your data, do the following:
1. Sign in to the AWS OpsHub for AWS IoT SiteWise application.
1. Choose **Settings**.
1. For **Logs**, specify a time range, and then choose **Download**.
1. Unzip the log file.
1. If the log file contains the following message, the service deleted your data: *number* bytes of data have been deleted to prevent SiteWise Edge gateway storage from running out of space.
## Manage your SiteWise Edge gateway with the AWS IoT SiteWise console
You can use the AWS IoT SiteWise console to configure, update, and monitor all SiteWise Edge gateways in your AWS account.
You can view your SiteWise Edge gateways by navigating to the **Edge Gateways** page in the [AWS IoT SiteWise console](https://console.aws.amazon.com/iotsitewise/). To access the **Edge gateway details** page for a specific gateway, choose the name of an Edge gateway.
From the **Overview** tab of the **Edge gateway details** page, you can do the following:
+ In the **Data sources** section, update data source configuration and configure additional data sources
+ Choose **Open CloudWatch metrics** to view the number of data points ingested per data source in the CloudWatch metrics console
+ In the **Edge capabilities** section, add data packs to your SiteWise Edge gateway by clicking **Edit**
+ In the **Gateway configuration** section, view the connectivity status of your SiteWise Edge gateways
+ In the **Publisher configuration** section, view the SiteWise Edge gateway sync status and configuration of the AWS IoT SiteWise publisher component
From the **Updates** tab of the **Edge gateway details** page, you can see the current component and pack versions that are deployed to the Edge gateway. This is also where you deploy new versions, when they're available.
## Manage SiteWise Edge gateways using AWS OpsHub for AWS IoT SiteWise
You use the AWS OpsHub for AWS IoT SiteWise application to manage and monitor your self-hosted SiteWise Edge gateways. This application provides the following monitoring and management options:
+ Under **Overview**, you can do the following:
+ View SiteWise Edge gateway details that help you get insights into your SiteWise Edge gateway device data, identify issues, and improve the SiteWise Edge gateway's performance.
+ View SiteWise Monitor portals that monitor the data from local servers and equipment at the edge. For more information, see [What is AWS IoT SiteWise Monitor](https://docs.aws.amazon.com/iot-sitewise/latest/appguide/what-is-monitor-app.html) in the *AWS IoT SiteWise Monitor Application Guide*.
+ Under **Health**, there's a dashboard that displays data from your SiteWise Edge gateway. Domain experts, such as process engineers, can use the dashboard to see an overview of SiteWise Edge gateway behavior.
+ Under **Assets**, view assets deployed to the local device and the last value collected or computed for asset properties.
+ Under **Settings**, you can do the following:
+ If the Data Processing Pack is installed, view the SiteWise Edge gateway configuration information and sync resources with the AWS Cloud.
+ Download the authentication files that you can use to access the SiteWise Edge gateway by using other tools.
+ Download logs that you can use to troubleshoot the SiteWise Edge gateway.
+ View the AWS IoT SiteWise components deployed to the SiteWise Edge gateway.
**Important**
The following are required to use AWS OpsHub for AWS IoT SiteWise:
Your local device and the AWS OpsHub for AWS IoT SiteWise application must be connected to the same network.
The data processing pack must be enabled.
**To manage SiteWise Edge gateways using AWS OpsHub**
1. Download and install the [AWS OpsHub for AWS IoT SiteWise for Windows](https://aws-iot-sitewise.s3.amazonaws.com/gateway/OpsHub+for+AWS+IoT+SiteWise.exe) application.
1. Open the application.
1. If you don't have local credentials set up for your gateway, follow the steps under [Access your SiteWise Edge gateway using local operating system credentials](#create-user-pool) to set them up.
1. You can sign in to your SiteWise Edge gateway with your Linux or Lightweight Directory Access Protocol (LDAP) credentials. To sign in to your SiteWise Edge gateway, do one of the following:
------
#### [ Linux ]
1. For **Hostname or IP address**, enter the hostname or IP address of your local device.
1. For **Authentication**, choose **Linux**.
1. For **User name**, enter the user name of your Linux operating system.
1. For **Password**, enter the password of your Linux operating system.
1. Choose **Sign in**.
------
#### [ LDAP ]
1. For **Hostname or IP address**, enter the hostname or IP address of your local device.
1. For **Authentication**, choose **LDAP**.
1. For **User name**, enter your LDAP's user name.
1. For **Password**, enter your LDAP's password.
1. Choose **Sign in**.
------
## Access your SiteWise Edge gateway using local operating system credentials
Besides Lightweight Directory Access Protocol (LDAP), you can use the Linux or Windows credentials to access your self-hosted SiteWise Edge gateway.
**Important**
To access your SiteWise Edge gateway with Linux credentials, you must activate the data processing pack for your SiteWise Edge gateway.
### Access your SiteWise Edge gateway using Linux operating system credentials
The following steps assume that you use a device with Ubuntu. If you use a different Linux distribution, consult the relevant documentation for your device.
**To create a Linux user pool**
1. To create an admin group, run the following command.
```
sudo groupadd --system SWE_ADMIN_GROUP
```
Users in the `SWE_ADMIN_GROUP` group can allow admin access for the SiteWise Edge gateway.
1. To create a user group, run the following command.
```
sudo groupadd --system SWE_USER_GROUP
```
Users in the `SWE_USER_GROUP` group can allow read-only access for the SiteWise Edge gateway.
1. To add a user to the admin group, run the following command. Replace *user-name* and *password* with the user name and password that you want to add.
```
sudo useradd -p $(openssl passwd -1 password) user-name
```
1. To add a user to either `SWE_ADMIN_GROUP` or `SWE_USER_GROUP`, replace *user-name* with the the user name that you added in the previous step.
```
sudo usermod -a -G SWE_ADMIN_GROUP user-name
```
You can now use the user name and password to sign in to the SiteWise Edge gateway on the AWS OpsHub for AWS IoT SiteWise application.
### Access your SiteWise Edge gateway using Windows credentials
The following steps assume that you use a device with Windows.
**Important**
Security is a shared responsibility between AWS and you. Create a strong password policy with at least 12 characters and a combination of uppercase, lowercase, numbers, and symbols. Additionally, set the Windows Firewall rules to allow incoming traffic on port 443 and to block incoming traffic on all other ports.
**To create a Windows Server user pool**
1. Run PowerShell as the administrator.
1. On the Windows server where you want to install SiteWise Edge Gateway, log in as administrator.
1. Enter **PowerShell** in the Windows search bar.
1. In the search results, right click on the Windows PowerShell app. Choose **Run as Administrator**.
1. To create an admin group, run the following command.
```
net localgroup SWE_ADMIN_GROUP /add
```
You must be a user in the `SWE_ADMIN_GROUP` group to allow admin access for the SiteWise Edge gateway.
1. To create a user group, run the following command.
```
net localgroup SWE_USER_GROUP /add
```
You must be a user in the `SWE_USER_GROUP` group to allow ready-only access for the SiteWise Edge gateway.
1. To add user, run the following command. Replace *user-name* and *password* with the user name and the password that you want to create.
```
net user user-name password /add
```
1. To add a user to the admin group, run the following command. Replace *user-name* with the user name that you want to add.
```
net localgroup SWE_ADMIN_GROUP user-name /add
```
You can now use the user name and password to sign in to the SiteWise Edge gateway on the AWS OpsHub for AWS IoT SiteWise application.
## Manage the SiteWise Edge gateway certificate
You can use SiteWise Monitor and third-party applications, such as Grafana, on your SiteWise Edge gateway devices. These applications require a TLS connection to the service. SiteWise Edge gateways currently use a self-signed certificate. If you use a browser to open the applications, such as a SiteWise Monitor portal, you might receive a warning for untrusted certificate.
The following shows how to download the trusted certificate from the AWS OpsHub for AWS IoT SiteWise application.
1. Sign in to the application.
1. Choose **Settings**.
1. For **Authentication**, choose **Download certificate**.
The following assumes that you use Google Chrome or FireFox. If you use a different browser, consult the relevant documentation for your browser. To add the certificate that you downloaded in the previous step to a browser, do one of the following:
+ If you use Google Chrome, follow the [Set up certificates](https://support.google.com/chrome/a/answer/3505249?hl=en) in the *Google Chrome Enterprise Help documentation*.
+ If you use Firefox, follow the [To Load the Certificate into the Mozilla or Firefox Browser](https://docs.oracle.com/cd/E19528-01/819-4639/gaesv/index.html) in the *Oracle documentation*.
## Change the version of SiteWise Edge gateway component packs
You can use the AWS IoT SiteWise console to change the version of component packs on your SiteWise Edge gateways.
**To change the version of a SiteWise Edge gateway component pack**
1. Navigate to the [AWS IoT SiteWise console](https://console.aws.amazon.com/iotsitewise/).
1. In the left navigation pane, choose **Gateways**.
1. Select the SiteWise Edge gateway that you would like to change the pack versions for.
1. Under **Gateway configuration**, choose **View software versions**.
1. On the **Edit software versions** page, for the pack you want to update the version of, select the version you want to deploy and choose **Deploy**.
1. Choose **Done**.
## List SiteWise Edge gateways
------
#### [ Console ]
**To list SiteWise Edge gateways**
1. Navigate to the [AWS IoT SiteWise console](https://console.aws.amazon.com/iotsitewise/).
1. In the navigation pane, choose **Edge gateways**.
1. View the list of all your SiteWise Edge gateways.
------
#### [ AWS CLI ]
To list your gateways using AWS CLI, follow these steps:
+ Use the list-gateways command to view all your gateways:
```
aws iotsitewise list-gateways
```
This command returns a list of your gateways with their IDs, names, and other information.
You can also specify pagination parameters:
```
aws iotsitewise list-gateways --max-results 10 --next-token your-token
```
For more information, see [list-gateways](https://docs.aws.amazon.com/cli/latest/reference/iotsitewise/list-gateways.html) in the AWS CLI Command Reference.
------
## Describe a SiteWise Edge gateway
------
#### [ Console ]
**To view gateway details**
1. Navigate to the [AWS IoT SiteWise console](https://console.aws.amazon.com/iotsitewise/).
1. In the navigation pane, choose **Edge gateways**.
1. Choose the name of the gateway you want to view details for.
1. View the gateway details on the **Edge gateway details** page.
------
#### [ AWS CLI ]
To get detailed information about a specific gateway using AWS CLI, follow these steps:
+ Use the describe-gateway command with the gateway ID:
```
aws iotsitewise describe-gateway --gateway-id a1b2c3d4-5678-90ab-cdef-1a1a1EXAMPLE
```
This command returns detailed information about the gateway.
For more information, see [describe-gateway](https://docs.aws.amazon.com/cli/latest/reference/iotsitewise/describe-gateway.html) in the AWS CLI Command Reference.
------
## Create a SiteWise Edge gateway
------
#### [ Console ]
**To create a SiteWise Edge gateway**
1. Navigate to the [AWS IoT SiteWise console](https://console.aws.amazon.com/iotsitewise/).
1. In the navigation pane, choose **Edge gateways**.
1. Choose **Create gateway**.
1. Enter a name for your gateway.
1. Select the Greengrass group for your gateway.
1. Optionally, add tags to your gateway.
1. Choose **Create**.
------
#### [ AWS CLI ]
To create a new IoT SiteWise gateway using AWS CLI, follow these steps:
+ Use the create-gateway command to create a new gateway:
```
aws iotsitewise create-gateway \
--gateway-name "NewSiteWiseGateway" \
--gateway-platform '{
"greengrass": {
"groupArn": "arn:aws:greengrass:us-east-1:123456789012:group/a1b2c3d4-5678-90ab-cdef-1a1a1EXAMPLE"
}
}' \
--tags '{
"Environment": "Production",
"Location": "Factory1"
}'
```
This command returns the new gateway's ID and ARN:
```
{
"gatewayId": "a1b2c3d4-5678-90ab-cdef-1a1a1EXAMPLE",
"gatewayArn": "arn:aws:iotsitewise:us-east-1:123456789012:gateway/a1b2c3d4-5678-90ab-cdef-1a1a1EXAMPLE"
}
```
For more information, see [create-gateway](https://docs.aws.amazon.com/cli/latest/reference/iotsitewise/create-gateway.html) in the AWS CLI Command Reference.
------
## Update a SiteWise Edge gateway
------
#### [ Console ]
**To update a SiteWise Edge gateway**
1. Navigate to the [AWS IoT SiteWise console](https://console.aws.amazon.com/iotsitewise/).
1. In the navigation pane, choose **Edge gateways**.
1. Select the gateway you want to update.
1. Choose **Edit**.
1. Update the gateway name or other settings as needed.
1. Choose **Save**.
------
#### [ AWS CLI ]
To update an existing gateway using AWS CLI, follow these steps:
+ Use the update-gateway command to update a gateway's name:
```
aws iotsitewise update-gateway \
--gateway-id a1b2c3d4-5678-90ab-cdef-1a1a1EXAMPLE \
--gateway-name "UpdatedGatewayName"
```
This command produces no output when successful.
For more information, see [update-gateway](https://docs.aws.amazon.com/cli/latest/reference/iotsitewise/update-gateway.html) in the AWS CLI Command Reference.
------
## Update gateway capability configuration
------
#### [ Console ]
**To update gateway capability configuration**
1. Navigate to the [AWS IoT SiteWise console](https://console.aws.amazon.com/iotsitewise/).
1. In the navigation pane, choose **Edge gateways**.
1. Choose the name of the gateway you want to update.
1. In the **Data sources** section, choose **Edit**.
1. Update the data source configuration as needed.
1. Choose **Save**.
------
#### [ AWS CLI ]
To update a gateway's capability configuration using AWS CLI, follow these steps:
+ Use the update-gateway-capability-configuration command to update the capability configuration:
```
aws iotsitewise update-gateway-capability-configuration \
--gateway-id a1b2c3d4-5678-90ab-cdef-1a1a1EXAMPLE \
--capability-namespace "iotsitewise:opcuacollector:1" \
--capability-configuration '{
"sources": [
{
"name": "OPC-UA Server",
"endpoint": {
"certificateTrust": {
"type": "TrustAny"
},
"endpointUri": "opc.tcp://10.0.0.1:4840",
"securityPolicy": "NONE",
"messageSecurityMode": "NONE",
"identityProvider": {
"type": "Anonymous"
}
},
"measurementDataStreamPrefix": ""
}
]
}'
```
This command returns the capability namespace and sync status:
```
{
"capabilityNamespace": "iotsitewise:opcuacollector:1",
"capabilitySyncStatus": "CONFIGURING"
}
```
For more information, see [update-gateway-capability-configuration](https://docs.aws.amazon.com/cli/latest/reference/iotsitewise/update-gateway-capability-configuration.html) in the AWS CLI Command Reference.
------
## Tag gateway resources
------
#### [ Console ]
**To tag a gateway resource**
1. Navigate to the [AWS IoT SiteWise console](https://console.aws.amazon.com/iotsitewise/).
1. In the navigation pane, choose **Edge gateways**.
1. Choose the name of the gateway you want to tag.
1. Choose the **Tags** tab.
1. Choose **Manage tags**.
1. Choose **Add new tag** and enter a key and value for each tag.
1. Choose **Save**.
------
#### [ AWS CLI ]
To add tags to a gateway using AWS CLI, follow these steps:
+ Use the tag-resource command to add tags to a gateway:
```
aws iotsitewise tag-resource \
--resource-arn "arn:aws:iotsitewise:us-east-1:123456789012:gateway/a1b2c3d4-5678-90ab-cdef-1a1a1EXAMPLE" \
--tags '{
"Department": "Operations",
"Project": "FactoryAutomation"
}'
```
This command produces no output when successful.
For more information, see [tag-resource](https://docs.aws.amazon.com/cli/latest/reference/iotsitewise/tag-resource.html) in the AWS CLI Command Reference.
------
## List tags for a gateway
------
#### [ Console ]
**To list tags for a gateway**
1. Navigate to the [AWS IoT SiteWise console](https://console.aws.amazon.com/iotsitewise/).
1. In the navigation pane, choose **Edge gateways**.
1. Choose the name of the gateway you want to view tags for.
1. Choose the **Tags** tab.
1. View the list of tags associated with the gateway.
------
#### [ AWS CLI ]
To list the tags associated with a gateway using AWS CLI, follow these steps:
+ Use the list-tags-for-resource command to list tags for a gateway:
```
aws iotsitewise list-tags-for-resource \
--resource-arn "arn:aws:iotsitewise:us-east-1:123456789012:gateway/a1b2c3d4-5678-90ab-cdef-1a1a1EXAMPLE"
```
This command returns the tags associated with the gateway:
```
{
"tags": {
"Environment": "Production",
"Location": "Factory1",
"Department": "Operations",
"Project": "FactoryAutomation"
}
}
```
For more information, see [list-tags-for-resource](https://docs.aws.amazon.com/cli/latest/reference/iotsitewise/list-tags-for-resource.html) in the AWS CLI Command Reference.
------
## Remove tags from a gateway
------
#### [ Console ]
**To remove tags from a gateway**
1. Navigate to the [AWS IoT SiteWise console](https://console.aws.amazon.com/iotsitewise/).
1. In the navigation pane, choose **Edge gateways**.
1. Choose the name of the gateway you want to remove tags from.
1. Choose the **Tags** tab.
1. Choose **Manage tags**.
1. Choose the remove icon (X) next to each tag you want to remove.
1. Choose **Save**.
------
#### [ AWS CLI ]
To remove tags from a gateway using AWS CLI, follow these steps:
+ Use the untag-resource command to remove tags from a gateway:
```
aws iotsitewise untag-resource \
--resource-arn "arn:aws:iotsitewise:us-east-1:123456789012:gateway/a1b2c3d4-5678-90ab-cdef-1a1a1EXAMPLE" \
--tag-keys '["Project", "Department"]'
```
This command produces no output when successful.
For more information, see [untag-resource](https://docs.aws.amazon.com/cli/latest/reference/iotsitewise/untag-resource.html) in the AWS CLI Command Reference.
------
## Update the version of an AWS IoT SiteWise component
Update the AWS IoT SiteWise gateway component on your AWS IoT Greengrass core device to ensure your access to the latest features, performance improvements, and security patches.
**To update an AWS IoT SiteWise component on AWS IoT Greengrass**
1. Navigate to the [AWS IoT SiteWise console](https://console.aws.amazon.com/iotsitewise/).
1. In the left navigation pane, choose **Edge gateways**.
1. Select the gateway to edit and choose **Edit**.
1. In **Edge Capabilities**, under **Software versions**, choose **Software updates available**. The **Edit software versions** page appears.
1. Choose the component version.
**Note**
It's recommend to select the latest version available. Keeping gateway components up-to-date helps you maintain optimal functionality for industrial data collection and processing.
1. Choose **Deploy**. This starts an AWS IoT Greengrass V2 deployment to update the AWS IoT SiteWise component on the gateway.
## Delete a SiteWise Edge gateway
------
#### [ Console ]
**To delete the SiteWise Edge gateway**
1. Navigate to the [AWS IoT SiteWise console](https://console.aws.amazon.com/iotsitewise/).
1. In the navigation pane, choose **Edge gateways**.
1. Choose the gateway you want to delete.
1. Choose **Delete**.
1. To confirm you want to delete the gateway, type "delete" and then choose **Delete** in the window that appears.
------
#### [ AWS CLI ]
To delete a gateway using AWS CLI, follow these steps:
1. List your gateways to identify the gateway ID of the gateway you want to delete.
```
aws iotsitewise list-gateways
```
This command returns a list of your gateways with their IDs, names, and other information:
```
{
"gatewaySummaries": [
{
"gatewayId": "a1b2c3d4-5678-90ab-cdef-1a1a1EXAMPLE",
"gatewayName": "ExampleCorpGateway",
"gatewayCapabilitySummaries": [
{
"capabilityNamespace": "iotsitewise:opcuacollector:1",
"capabilitySyncStatus": "IN_SYNC"
}
],
"creationDate": 1588369971.457,
"lastUpdateDate": 1588369971.457
}
]
}
```
1. Delete the gateway by specifying its ID:
```
aws iotsitewise delete-gateway --gateway-id a1b2c3d4-5678-90ab-cdef-1a1a1EXAMPLE
```
This command produces no output when successful.
**Note**
When you delete a gateway, some of the gateway's files remain in your gateway's file system.
1. To verify that the gateway has been deleted, you can list your gateways again:
```
aws iotsitewise list-gateways
```
The deleted gateway should no longer appear in the list.
For more information, see [delete-gateway](https://docs.aws.amazon.com/cli/latest/reference/storagegateway/delete-gateway.html) in the AWS CLI Command Reference.
------
# Back up and restore SiteWise Edge gateways
Back up and restore gateways
This topic covers how to restore SiteWise Edge gateways and backup your metric data. If you are experiencing issues with a broken SiteWise Edge gateway on the same machine and need to troubleshoot the issue, please read the AWS IoT SiteWise documentation [ Troubleshooting SiteWise Edge gateway issues](https://docs.aws.amazon.com//iot-sitewise/latest/userguide/troubleshooting-gateway.html#troubleshoot-gateway-issues).
**Note**
The guidance covered in this topic is for SiteWise Edge gateways installed on AWS IoT Greengrass V2 version 2.1.0 or higher.
## Daily backups of metric data
Creating a back up is important, if you would like to transfer or restore the data on a new machine. Backing up your data greatly reduces the risk of loss of operating data during a transfer or restoration process.
This section applies to gateways that use the data processing pack. For more information on the data processing pack, see [Configure an asset model for data processing on SiteWise Edge](edge-processing.md#process-gateway-data-edge).
The **influxdb** folder path is as follows:
------
#### [ Linux ]
`/greengrass/v2/work/aws.iot.SiteWiseEdgeProcessor/influxdb `
------
#### [ Windows ]
`C:\greengrass\v2\work\aws.iot.SiteWiseEdgeProcessor\influxdb`
------
We recommend that you backup the whole folder with everything underneath it.
We recommend that you periodically backup your metric data from the 1.0 SiteWise Edge to either an external hard drive or to the AWS cloud.
## Restore a SiteWise Edge gateway
Before attempting to restore a SiteWise Edge gateway, ensure that all edge devices connected to the gateway are stopped or disconnected.
Use the following procedure to a restore a SiteWise Edge gateway:
1. Use the installation script downloaded when you create SiteWise Edge gateway to restore the SiteWise Edge gateway on the new machine. Read the [Installing the SiteWise Edge gateway software on your local device](https://docs.aws.amazon.com//iot-sitewise/latest/userguide/install-gateway-software-on-local-device.html) procedure to setup the SiteWise Edge gateway.
If you lose or cannot find the installation script, please contact [AWS Customer Support](https://aws.amazon.com/contact-us/).
1. Once the SiteWise Edge gateway has been installed, log into the [AWS IoT Greengrass console](https://console.aws.amazon.com/greengrass).
1. To redeploy the components, navigate to **Manage** then under **AWS IoT Greengrass devices** select **Core devices**.
1. In the **AWS IoT Greengrass core devices** table select the core device corresponding to your SiteWise Edge gateway.
1. Once on the device page, open the **Deployments** tab and select your **Deployment ID**, this will open the **Deployments** page with your selected ID.
1. Once you are on the **Deployments** page, in the top right press the **Actions** button, and select the **Revise** option. to initiate a new deployment. Configure the deployment. If you would like to keep the deployment as it is, skip to **Review** and **Deploy**.
1. Wait for the **Deployment Status** to become `Completed`.
**Note**
It will also take a few minutes for all components on the SiteWise Edge to fully setup and running.
## Restore AWS IoT SiteWise data
Use the following procedure to restore data on a new machine.
1. Copy the `influxdb` folder to the new machine.
1. Stop the SiteWise EdgeProcessor component, by running the following command in your terminal:
------
#### [ Linux ]
sudo `/greengrass/v2/bin/greengrass-cli component stop -n aws.iot.SiteWiseEdgeProcessor`
------
#### [ Windows ]
`C:\greengrass\v2\bin\greengrass-cli component stop -n aws.iot.SiteWiseEdgeProcesso`
------
1. Locate the path where you backed up your data, and run the following command:
------
#### [ Linux ]
`sudo yes | sudo cp -rf /greengrass/v2/work/aws.iot.SiteWiseEdgeProcessor/influxdb `
------
#### [ PowerShell ]
`Copy-Item -Recurse -Force \* C:\greengrass\v2\work\aws.iot.SiteWiseEdgeProcessor\`
------
#### [ Windows ]
`robocopy C:\greengrass\v2\work\aws.iot.SiteWiseEdgeProcessor\ /E`
------
1. Restart the SiteWiseEdgeProcessor component:
------
#### [ Linux ]
`sudo /greengrass/v2/bin/greengrass-cli component restart -n aws.iot.SiteWiseEdgeProcessor`
------
#### [ Windows ]
`C:\greengrass\v2\bin\greengrass-cli component restart -n aws.iot.SiteWiseEdgeProcessor`
------
## Validate successful backups and restorations
Use this procedure validate your backed-up data and SiteWise Edge gateway restorations.
**Note**
This procedure requires that you have installed AWS OpsHub for AWS IoT SiteWise. For more information see, [Managing SiteWise Edge gateways using AWS OpsHub for AWS IoT SiteWise](https://docs.aws.amazon.com//iot-sitewise/latest/userguide/manage-gateways-ggv2.html).
1. Open AWS OpsHub for AWS IoT SiteWise.
1. On the SiteWise Edge Gateway **Settings** page, check the status of each component listed in the **Components** table. Verify that the status color is green and the readout displays **RUNNING**.
1. Validate your past data on the portal dashboard to check that the past data and the new data are both properly setup. There will be a downtime between past and new data. You should except to see a duration where no data points are collected.
If you run into issues with backing up or restoring a SiteWise Edge gateway see the following troubleshooting topics [Troubleshooting an AWS IoT SiteWise Edge gateway](https://docs.aws.amazon.com//iot-sitewise/latest/userguide/troubleshooting-gateway.html).
# Legacy gateways (AWS IoT Greengrass Version 1)
**Note**
SiteWise Edge gateways running on AWS IoT Greengrass V1 are available only if you started using this feature before July 29, 2021. For more information on running an AWS IoT SiteWise gateway using AWS IoT Greengrass V2, see [Self-host an AWS IoT SiteWise Edge gateway with AWS IoT Greengrass V2](gw-self-host-gg2.md).
SiteWise Edge gateways now exclusively run on AWS IoT Greengrass V2, providing enhanced functionality and improved performance for your industrial IoT applications. This latest version AWS IoT Greengrass V2 represents an architectural evolution, built on a modern component-based framework that enables modular software deployment. It streamlines installation through a unified installer while offering developers greater flexibility in deploying custom components and conducting local testing. The component-based model allows for more efficient resource management and introduces a simplified configuration approach through component recipes. This design facilitates better dependency handling between components, supports continuous deployment practices, and provides enhanced CLI capabilities for local development. Additionally, AWS IoT Greengrass V2 centralizes configuration management through AWS IoT Core and delivers improved logging and monitoring features, all protected by a more granular security permissions model.
For more information on getting started with SiteWise Edge gateways using AWS IoT Greengrass V2, [AWS IoT SiteWise Edge self-hosted gateway requirements](configure-gateway-ggv2.md). These resources provide step-by-step instructions on setting up your gateways, configuring data sources, and managing your industrial IoT infrastructure.
**Note**
As AWS continues to innovate and improve its IoT services, it's recommended to stay updated with the latest features and enhancements. Regularly check the AWS IoT SiteWise and AWS IoT Greengrass documentation for new capabilities that can further optimize your industrial IoT solutions.