Configuring a Amazon IoT Greengrass V1 SiteWise Edge gateway

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.

Ensure that the SiteWise Edge gateway connects to the internet.

(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.

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

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

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

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.

Run the following command to verify that Java installed successfully.

java -version

The Amazon 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

Run the following command to create a /var/sitewise data directory and give the ggc_user permissions for that directory. Amazon IoT SiteWise stores data in this directory. You created the ggc_user when you set up Amazon 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 Amazon 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 Amazon IoT SiteWise connector.

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

If the Amazon IoT Greengrass Core software isn't already running, run the following command to start the Amazon IoT Greengrass Core software. Replace greengrass-root with the root of your Amazon 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

Configure the Amazon 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.

Navigate to the IAM console.

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

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": "*"
          }
        ]
      }

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

Choose Review policy.

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

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

Under Select type of trusted entity, choose Amazon 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.

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

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

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

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

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

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"
          }
        ]
      }

Navigate to the Amazon IoT Greengrass console.

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.

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

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

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

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

Choose Enable, and then choose Save.

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

Navigate to the Amazon IoT Greengrass console.

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.

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

Choose IoT SiteWise from the list and choose Next.

If your server requires authentication, you can create Amazon 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.

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

(Optional) Enter a maximum disk buffer size for the connector. If the Amazon IoT Greengrass core loses connection to the Amazon 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.

Choose Add.

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

Choose Automatic detection to start the deployment.

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

Navigate to the Amazon IoT SiteWise console.

Choose Add gateway.

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. Choose Add gateway.

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

1. For Select a connector in the Amazon IoT Greengrass console, choose Amazon 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.