Configuring a AWS IoT Greengrass V1 SiteWise Edge gateway

A AWS IoT SiteWise Edge gateway serves as the intermediary between your industrial equipment and AWS IoT SiteWise. You can deploy the SiteWise Edge gateway software on any device that can run AWS IoT Greengrass. For more information, see Choosing a AWS IoT Greengrass V1 SiteWise Edge gateway device.

You can enable AWS IoT SiteWise to process data locally on your edge devices by using the data processing pack on your SiteWise Edge gateway. You do this when you add your SiteWise Edge gateway to AWS IoT SiteWise. For more information about processing data at the edge, see Enabling edge data processing.

Note

We recommend that you complete the following steps with someone who has IT administrative access to your local and corporate networks. These steps might require someone with knowledge of your industrial equipment and the authority to configure firewall settings.

Setting up the SiteWise Edge gateway environment

In this procedure, you install AWS IoT Greengrass and configure your SiteWise Edge gateway to use with AWS IoT SiteWise.

Note

This section includes instructions to install packages using the apt command. This is applicable to systems running Ubuntu or similar. If you aren't using a similar system, consult the documentation for your distribution and use the recommended package installer.

To set up the SiteWise Edge gateway

1. As appropriate, modify the BIOS settings of the SiteWise Edge gateway as follows.

   1. Ensure that the SiteWise Edge gateway automatically restarts after a potential power failure, if applicable.

   2. Ensure that the SiteWise Edge gateway won't hibernate or sleep, if applicable.

2. Ensure that the SiteWise Edge gateway connects to the internet.

3. (Optional) To use the SiteWise Edge gateway without the mouse, keyboard, and monitor, do the following steps to set up ssh on the SiteWise Edge gateway:

   1. If you haven't already installed the SSH package, run the following command.

      sudo apt install ssh

   2. Run the following command.

      service ssh status

   3. Search for Active: active (running) in the output to confirm that the SSH server is running,

   4. Press Q to exit.

   Run the following command to use SSH to connect to the SiteWise Edge gateway from another computer. Replace username with the user login and IP with the IP address of the SiteWise Edge gateway.

   ssh username@IP

   You can use the -p port-number argument to connect to a port other than the default port 22.

4. Download and install AWS IoT Greengrass Core software v1.10.2 or later, and create an AWS IoT Greengrass group for your SiteWise Edge gateway. To do so, follow the instructions in Getting started with AWS IoT Greengrass in the AWS IoT Greengrass Developer Guide.

   We recommend that you run the AWS IoT Greengrass device setup script to quickly get started. If you want to review AWS IoT Greengrass requirements and processes more closely, you can walk through the steps in Module 1 and Module 2 to set up AWS IoT Greengrass.

   Important

   Review the AWS Regions where AWS IoT SiteWise is supported. When you choose a Region for AWS IoT Greengrass, make sure that the Region also supports AWS IoT SiteWise. Otherwise, you can't connect your SiteWise Edge gateway to AWS IoT SiteWise.

   Before you continue to the next step, you should have AWS IoT Greengrass Core software installed on your SiteWise Edge gateway.

5. Run the following commands to install Java 8.

   sudo apt update
         sudo apt install openjdk-8-jre

   The SiteWise Edge gateway software that you install later in this guide uses a Java 8 runtime.

6. Run the following command to verify that Java installed successfully.

   java -version

7. The AWS IoT Greengrass Core software assumes a java8 directory. Run the following command to link your Java installation to that java8 directory.

   sudo ln -s /usr/bin/java /usr/bin/java8

8. Run the following command to create a /var/sitewise data directory and give the ggc_user permissions for that directory. AWS IoT SiteWise stores data in this directory. You created the ggc_user when you set up AWS IoT Greengrass earlier in this procedure.

   sudo mkdir /var/sitewise 
         sudo chown ggc_user /var/sitewise
         sudo chmod 700 /var/sitewise

   The /var/sitewise is the default directory that AWS IoT SiteWise uses. You can customize the directory path (for example, replace /var/sitewise with /var/custom/path/), but doing so requires extra steps after the SiteWise Edge gateway is created. For more information, see step 6 in Configuring the AWS IoT SiteWise connector.

9. If needed, ask your IT administrator to add the following endpoints and ports to your local network allow list:

   • Ports: 443, 8443, and 8883

     Important

     You can configure AWS IoT Greengrass Core to use only port 443 for all network communications. For more information, see Connect on port 443 or through a network proxy in the AWS IoT Greengrass Developer Guide.

   • The IP address of your SiteWise Edge gateway (port 443). To obtain the IP address, run the ip address or ifconfig command and note the inet value (for example, 203.0.113.0).

   • The AWS IoT SiteWise data endpoint: data.iotsitewise.region.amazonaws.com (port 443).

   • The following AWS endpoints that the SiteWise Edge gateway uses. You can find these in the /greengrass-root/config/config.json file. Replace greengrass-root with the root of your AWS IoT Greengrass installation.

     • ggHost: greengrass-ats.iot.region.amazonaws.com (ports 443, 8443, and 8883).

     • iotHost: prefix-ats.iot.region.amazonaws.com (ports 443, 8443, and 8883).

     For more information, see AWS IoT Greengrass endpoints and quotas.

10. If the AWS IoT Greengrass Core software isn't already running, run the following command to start the AWS IoT Greengrass Core software. Replace greengrass-root with the root of your AWS IoT Greengrass installation. The default greengrass-root is /greengrass.

    cd /greengrass-root/ggc/core
          sudo ./greengrassd start

    You should see this message: Greengrass successfully started with PID: some-PID-number

11. Configure the AWS IoT Greengrass Core software to automatically start when your SiteWise Edge gateway turns on. Consult the documentation for your SiteWise Edge gateway's operating system.

Creating an IAM policy and role

You must create an AWS Identity and Access Management (IAM) policy and role to allow the SiteWise Edge gateway to access AWS IoT SiteWise on your behalf.

To create an IAM policy and role

1. Navigate to the IAM console.

2. In the navigation pane, choose Policies, and then choose Create policy.

   

3. On the JSON tab, delete the current contents of the policy field, and paste the following policy into the field.

   {
           "Version": "2012-10-17",
           "Statement": [
             {
               "Effect": "Allow",
               "Action": "iotsitewise:BatchPutAssetPropertyValue",
               "Resource": "*"
             }
           ]
         }

   Note

   To improve security, you can specify an AWS IoT SiteWise asset hierarchy path in the Condition property. The following example is a trust policy that specifies an asset hierarchy path.

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

4. Choose Review policy.

5. Enter a name and description for the policy, and then choose Create policy.

6. In the navigation pane, choose Roles, and then choose Create role.

   

7. Under Select type of trusted entity, choose AWS service. Under Choose the service that will use the role, choose Greengrass as the service that will use the role, and then choose Next: Permissions.

   

8. Search for the policy that you created, select the check box, and then choose Next: Tags.

   

9. (Optional) Add tags to your role, and then choose Next: Review.

10. Enter a name and description for the role, and then choose Create role.

    

11. In the green banner, choose the link to your new role. You can also use the search field to find the role.

    

12. Choose the Trust relationships tab, and then choose Edit trust relationship.

    

13. Replace the current contents of the policy field with the following, and then choose Update Trust Policy.

    {
            "Version": "2012-10-17",
            "Statement": [
              {
                "Effect": "Allow",
                "Principal": {
                  "Service": "greengrass.amazonaws.com"
                },
                "Action": "sts:AssumeRole"
              }
            ]
          }

Configuring an AWS IoT Greengrass group

To attach an IAM role to a group and enable stream manager

1. Navigate to the AWS IoT Greengrass console.

2. In the left navigation pane, under Greengrass, choose Groups, and then choose the group that you created in Setting up the SiteWise Edge gateway environment.

   

3. In the left navigation pane, choose Settings. In the Group Role section, choose Add Role.

   

4. Choose the role that you created in Creating an IAM policy and role, and then choose Save.

   

5. On the Settings page, in the Stream manager section, choose Edit.

   Stream manager is a feature of AWS IoT Greengrass that enables your AWS IoT Greengrass Core to stream data to the AWS Cloud. SiteWise Edge gateways require that stream manager is enabled. For more information, see Manage data streams on the AWS IoT Greengrass Core in the AWS IoT Greengrass Version 1 Developer Guide.

   

6. Choose Enable, and then choose Save.

7. In the upper-left corner, choose Services to prepare for the next procedure.

Configuring the AWS IoT SiteWise connector

In this procedure, you configure the AWS IoT SiteWise connector on your Greengrass group. Components are prebuilt modules that accelerate the development lifecycle for common edge scenarios. For more information, see AWS IoT Greengrass connectors in the AWS IoT Greengrass Version 1 Developer Guide.

To configure the AWS IoT SiteWise connector

1. Navigate to the AWS IoT Greengrass console.

2. In the left navigation pane, under Greengrass, choose Groups, and then choose the group that you created in Setting up the SiteWise Edge gateway environment.

   

3. In the left navigation page, choose Connectors. On the Connectors page, choose Add a connector.

   

4. Choose IoT SiteWise from the list and choose Next.

   

5. If your server requires authentication, you can create AWS Secrets Manager secrets with the server's user name and password. Then, you can attach each secret to your Greengrass group and choose them under List of ARNs for username/password secrets. For more information about how to create and configure secrets, see Configuring source authentication. You can also add secrets to your connector later.

   

6. If you set up your SiteWise Edge gateway with a different path than /var/sitewise, enter that path for Local storage path.

7. (Optional) Enter a maximum disk buffer size for the connector. If the AWS IoT Greengrass core loses connection to the AWS Cloud, the connector caches data until it can successfully connect. If the cache size exceeds the maximum disk buffer size, the connector discards the oldest data from the queue.

8. Choose Add.

9. In the upper-right corner, in the Actions menu, choose Deploy.

10. Choose Automatic detection to start the deployment.

    If the deployment fails, choose Deploy again. If the deployment continues to fail, see AWS IoT Greengrass deployment troubleshooting.

Adding the SiteWise Edge gateway to AWS IoT SiteWise

In this procedure, you add your SiteWise Edge gateway's Greengrass group to AWS IoT SiteWise. After you register your SiteWise Edge gateway with AWS IoT SiteWise, the service can deploy your data source configurations to your SiteWise Edge gateway.

To add the SiteWise Edge gateway to AWS IoT SiteWise

1. Navigate to the AWS IoT SiteWise console.

2. Choose Add gateway.

3. On the Add SiteWise gateway page, do the following:

   1. Enter a Name for the SiteWise Edge gateway. Consider including the location of the SiteWise Edge gateway in the name so that you can easily identify it.

   2. For Greengrass group ID, choose the Greengrass group that you created earlier.

      

   3. (Optional) For Edge capabilities, choose Data processing pack. This enables communication between your SiteWise Edge gateway and any asset models and assets configured for the edge. For more information, see Enabling edge data processing.

      Important

      If you add the data processing pack to your SiteWise Edge gateway, you must configure and deploy the SiteWise Edge connector on your AWS IoT Greengrass group. Follow the next steps.

   4. Choose Add gateway.

4. If you add the data processing pack to your SiteWise Edge gateway, configure and deploy the AWS IoT SiteWise Data Processor connector on your AWS IoT Greengrass group. Follow the steps in Configuring the AWS IoT SiteWise connector to configure the AWS IoT SiteWise Data Processor connector:

   1. For Select a connector in the AWS IoT Greengrass console, choose AWS IoT SiteWise Data Processor.

   2. For Local storage path, enter the path to your SiteWise Edge gateway.

   3. Choose Add.

   4. In the upper-right corner, in the Actions menu, choose Deploy, and then choose Automatic detection to start the deployment.

After your SiteWise Edge gateway deploys, you can add a source for each piece of industrial equipment from which you want your SiteWise Edge gateway to ingest data. For more information, see Configuring data sources.

You can view Amazon CloudWatch metrics to verify that your SiteWise Edge gateway connects to AWS IoT SiteWise. For more information, see AWS IoT Greengrass Version 1 gateway metrics.