AWS IoT SiteWise

Overview

The AWS IoT SiteWise connector provides a no-code integration of Sparkplug OT data with the AWS Cloud ecosystem, automatically creating Asset models and Assets to match your edge data model while continuously ingesting real-time data into the SiteWise time-series engine.

Features

• Automatic Asset model creation: Asset Models are created automatically in SiteWise using the Sparkplug template definitions (UDTs) created at the edge.

• Automatic Asset creation: Assets are created automatically from the Sparkplug template instances received from the edge nodes.

• Real-time data ingestion: The Sparkplug metrics received from the edge nodes are ingested in real-time into SiteWise Data streams and the corresponding Measurements inside the Assets are updated.

How It Works

Data Model

SparkPipe uses the Sparkplug template definitions (UDT definitions) to create the Models in IoT SiteWise and the Sparkplug template instances (UDT instances) to create the Assets in IoT SiteWise.

See the following example using N3uron and the resulting Asset Model and Asset in AWS IoT SiteWise.

SparkPipe creates a new Model to match the template definition, including tags, data types, units and description.

A new Asset is created for each template instance, the name of the asset contains the Sparkplug GroupID, EdgeNodeID and DeviceID as a prefix before the path of the instance.

Real-time data

SparkPipe creates a new data stream in AWS IoT SiteWise for each Sparkplug metric. A data stream serves as the source of data for an Asset measurement.

Supported data types

AWS IoT SiteWise only supports the following data types, see the official documentation:

• String: A string with up to 1024 bytes.

• Integer:  A signed 32-bit integer with range [-2,147,483,648, 2,147,483,647].

• Double:  A floating point number with range [-10^100, 10^100] and IEEE 754 double precision.

• Boolean: true or false.

To address this limitation, SparkPipe performs limited type conversions to fit the Sparkplug data types into AWS IoT SiteWise data types:

• Sparkplug String, UUID and Text → SiteWise String

• Sparkplug Int8, Int16, Int32, Int64, UInt8, UInt16, UInt32 and UInt64 → SiteWise Integer

• Sparkplug Float and Double → SiteWise Double

• Sparkplug Boolean → SiteWise Boolean

Configuration

The default configuration for the AWS IoT SiteWise connector:

...
# Connectors configuration
[connectors]
  name = "sitewise"

# AWS IoT SiteWise
[connectors.sitewise]
  # AWS IoT SiteWise region, by default uses the same region where SparkPipe is deployed
  aws_region = ""

  # AWS IAM credentials, leave empty to use IAM Role authentication
  aws_access_key_id = ""
  aws_secret_access_key = ""

Using IAM Role Authentication (Recommended)

This is the recommended method to configure and authorize SparkPipe to access the IoT SiteWise service within your AWS account. It involves creating an IAM role for SparkPipe, granting it the necessary permissions to access IoT SiteWise, and assigning this role to the SparkPipe EC2 instance.

• Step 1: Inside the AWS Console, go to IAM → Roles → Create role:

• Step 2: Select AWS Service as trusted entity type and EC2 as use case:

• Step 3: Search for the AWSIoTSiteWiseFullAccess permission:

• Step 4: Set a name to identify this role and optionally a description, then click on Create role:

• Step 5: Navigate to the EC2 console, select your SparkPipe instance and click on Actions → Security → Modify IAM role:

• Step 6: Select the previously created role and click on Update IAM role:

• Step 7: Configure the connector using the following configuration in the config.toml file, SparkPipe will automatically use the EC2 IAM role assigned to the instance:

...
# Connectors configuration
[connectors]
  name = "sitewise"

# AWS IoT SiteWise
[connectors.sitewise]
  # AWS IoT SiteWise region, by default uses the same region where SparkPipe is deployed
  aws_region = ""

  # AWS IAM credentials, leave empty to use IAM Role authentication
  aws_access_key_id = ""
  aws_secret_access_key = ""

Using IAM API Credentials

In this configuration you’ll need to create a new IAM user with the AWSIoTSiteWiseFullAccess policy attached, then generate an access key pair.

• Step 1: Inside the AWS Console, go to IAM → Users → Create user:

• Step 2: Inside the AWS Console, go to IAM → Users → Create user:

• Step 3: Select Attach policies directly, search for the AWSIoTSiteWiseFullAccess policy and click on Next:

• Step 4: Review and click on Create user:

• Step 5: Select the previously created user:

• Step 6: Click on Create access key:

• Step 7: Select Application running on an AWS compute service as use case, confirm and click on Next:

• Step 8: Set a description (optional) and click on Create access key:

• Step 9: Copy the Access key and the Secret access key, then click Done:

• Step 10: Configure the connector using the following configuration in the config.toml file:

...
# Connectors configuration
[connectors]
  name = "sitewise"

# AWS IoT SiteWise
[connectors.sitewise]
  # AWS IoT SiteWise region, by default uses the same region where SparkPipe is deployed
  aws_region = "us-east-1"

  # AWS IAM credentials, leave empty to use IAM Role authentication
  aws_access_key_id = "AKIAIOSFODNN7EXAMPLE"
  aws_secret_access_key = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"