Configuring a gateway - AWS IoT SiteWise

The AWS IoT SiteWise service is currently in preview. Under preview service terms and conditions, the service is subject to change.

Configuring a gateway

A gateway serves as the intermediary between your OPC-UA servers and AWS IoT SiteWise. You can easily deploy the AWS IoT SiteWise gateway software on any platform that can run AWS IoT Greengrass. For more information, see Choosing a gateway platform.

To configure a gateway that runs on Amazon EC2, you can create the required dependencies from an AWS CloudFormation template. For more information, see Configuring gateway dependencies on Amazon Elastic Compute Cloud.

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 OPC-UA servers and the authority to configure firewall settings.

Setting up the gateway environment

In this procedure, you install AWS IoT Greengrass and configure your 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 gateway

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

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

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

  2. Ensure that the gateway connects to the internet.

  3. (Optional) To use the gateway without the mouse, keyboard, and monitor, do the following steps to set up ssh on the 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.

    You can use SSH to connect to the gateway from another computer by running the command ssh username@IPv4, where username is the user login and IPv4 is the IP address of the gateway.

    Run the following command to use a port other than the default port 22.

    ssh username@IPv4 -p port-number
  4. Download and install AWS IoT Greengrass Core software v1.10.0 or later, and create an AWS IoT Greengrass group for your 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 gateway to AWS IoT SiteWise.

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

  5. Run the following commands to install Java 8.

    sudo apt update sudo apt install openjdk-8-jre

    The AWS IoT SiteWise 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 AWS IoT SiteWise 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 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 AWS endpoints that the gateway uses. You can find these in the /greengrass/config/config.json file:

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

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

    • Using the same greengrass-id found for iotHost in the previous step, add greengrass-id.credentials.iot.region.amazonaws.com (port 443) to the allow list.

    If your firewall can't use DNS names, you must resolve the names (endpoints) to their associated IP addresses first (for example, nslookup greengrass.iot.region.amazonaws.com).

  10. If the AWS IoT Greengrass Core software isn't already running, run the following command to start the AWS IoT Greengrass Core software.

    cd /greengrass/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 gateway turns on. Consult the documentation for your 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 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.

    
                IAM "Policies" page screenshot.
  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.

    
                IAM "Roles" page screenshot.
  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.

    
                IAM "Select type of trusted entity" page screenshot.
  8. Search for the policy that you created (SiteWiseDemo), select the check box, and then choose Next: Tags.

    
                IAM "Attach permissions policies" page screenshot.
  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.

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

    
                IAM "The role SiteWiseDemo has been created" page screenshot.
  12. Choose the Trust relationships tab, and then choose Edit trust relationship.

    
                IAM "Summary" page screenshot of the "Trust relationships" tab.
  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 gateway environment.

    
                AWS IoT Greengrass "Greengrass Groups" page screenshot.
  3. In the left navigation pane, choose Settings. In the Group Role section, choose Add Role.

    
                AWS IoT Greengrass "Add Role" page screenshot.
  4. Choose the role that you created in Creating an IAM policy and role, and then choose Save.

    
                AWS IoT Greengrass "Your Group's IAM Role" page screenshot.
  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. AWS IoT SiteWise 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 Developer Guide.

    
                AWS IoT Greengrass "Stream manager" section screenshot.
  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. Connectors 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 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 gateway environment.

    
                AWS IoT Greengrass "Greengrass Groups" page screenshot.
  3. In the left navigation page, choose Connectors. On the Connectors page, choose Add a connector.

    
                AWS IoT Greengrass "Connectors" page screenshot.
  4. Choose IoT SiteWise from the list and choose Next.

    
                AWS IoT Greengrass "Select a connector" page screenshot.
  5. If your OPC-UA servers require authentication, you can create AWS Secrets Manager secrets with the server's user name and password. Then, you can attach each secrets to your Greengrass group and choose them under List of ARNs for OPC-UA 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.

    
                AWS IoT Greengrass "Configure a connector" page screenshot.
  6. If you set up your 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 gateway to AWS IoT SiteWise

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

To add the 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 gateway. Consider including the location of the gateway in the name so that you can easily identify it.

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

      
                      AWS IoT SiteWise "Add gateway" page screenshot.
    3. Choose Add gateway.

After your gateway creates, you can add a source for each OPC-UA server from which you want your gateway to ingest data. For more information, see Configuring data sources.

You can view CloudWatch metrics to verify that your gateway is connected to AWS IoT SiteWise. For more information, see Gateway metrics.