Architecture details

User interface

User interface and messaging architecture detail

This solution creates a user interface to help you get data from on-premises equipment. To begin, you must define a AWS IoT Greengrass core device and a connection through this user interface. The AWS IoT Greengrass core device contains information about the AWS IoT thing and AWS IoT SiteWise gateway for the core device. The connection contains information about the equipment, the tags associated with the equipment, the protocol used, and the read frequency for the equipment data.

When you create the CloudFormation stack, you must provide an email address. The email address is used to generate the initial credentials to access the user interface. After the stack creates the Amazon Cognito user and the user interface, the user receives an email containing the web URL and the access credentials, including a temporary password. This web URL is also shown in the CloudFormation console, in the Outputs tab, under the value UIDomainName.

Note

When you initially log in to the interface, you will be prompted to change the auto-generated password.

AWS Lambda functions

Connection builder

The connection builder Lambda function validates and processes API requests from Amazon API Gateway. For a list of APIs, refer to REST API reference in this guide.

This Lambda function interacts with the connection DynamoDB table, the AWS IoT Greengrass core devices DynamoDB table, and the logs DynamoDB table. It also invokes the AWS IoT Greengrass deployer Lambda function to manage the AWS IoT Greengrass components and deployments and the AWS IoT SiteWise gateway configuration.

AWS IoT Greengrass deployer

The AWS IoT Greengrass deployer Lambda function manages the AWS IoT Greengrass. For OPC DA connections, this function creates a machine collector AWS IoT Greengrass component to read data from the OPC DA machine. For OPC UA connections, this function adds the machine details as a source for the AWS IoT SiteWise gateway.

This function also creates a publisher AWS IoT Greengrass component and configures MQTT proxy to subscribe and publish messages through the MQTT topics.

Once the machine collector and publisher AWS IoT Greengrass components are created, the AWS IoT Greengrass deployer Lambda function creates a deployment of the AWS IoT Greengrass core device to the industrial gateway running the AWS IoT Greengrass software.

For OPC DA and OSIsoft PI connections only, after the updates are deployed to the industrial gateway, a message to the m2c2/job/<connectionName> MQTT topic activates the OPC DA or OSIsoft PI machine collector AWS IoT Greengrass component to start reading data.

Messages consumer

The messages consumer Lambda function stores the messages in an Amazon Simple Queue Service (Amazon SQS) queue. The Amazon SQS queue gets data from the m2c2/info/<connectionName> and m2c2/error/<connectionName> IoT topics. The messages consumer Lambda function then subscribes to the SQS queue, processes the queue messages, and stores them in the messages DynamoDB table. These messages contain a time-to-live (TTL) attribute of one week, which identifies the length of time the message is stored.

AWS IoT Greengrass components

OPC Data Access (OPC DA) collector

The OPC DA collector AWS IoT Greengrass component is provisioned by the AWS IoT Greengrass deployer Lambda function and is deployed to the edge gateway when AWS IoT Greengrass deployed. This machine connector AWS IoT Greengrass component writes the connection configuration to the local gateway, establishes connectivity with the OPC DA server configuration specified in the connection configuration, and reads the telemetry data from the source machine. When it receives the data, it writes the data to the m2c2_<connectionName>_stream AWS IoT Greengrass Stream Manager stream.

OPC Unified Architecture (OPC UA) and AWS IoT SiteWise connector

This solution uses the AWS IoT SiteWise managed AWS IoT Greengrass components. These AWS IoT Greengrass components are aws.iot.SiteWiseEdgeCollectorOpcua and aws.iot.SiteWiseEdgePublisher. The aws.iot.SiteWiseEdgeCollectorOpcua AWS IoT Greengrass component connects to the OPC UA server, which is defined as a source in the AWS IoT SiteWise gateway. This function reads the telemetry data from the server and writes the data to the connection specific AWS IoT Greengrass stream.

The aws.iot.SiteWiseEdgePublisher AWS IoT Greengrass component is configured to read from the SiteWise_Stream AWS IoT Greengrass stream. If the job defined AWS IoT SiteWise as a destination, the publisher AWS IoT Greengrass component publishes the data to the SiteWise_Stream stream and the aws.iot.SiteWiseEdgePublisher AWS IoT Greengrass component forwards the data to AWS IoT SiteWise.

OSIsoft PI Web API collector

The OSIsoft PI Web API collector AWS IoT Greengrass component is provisioned by the Greengrass deployer Lambda function to the edge gateway when AWS IoT Greengrass is deployed. This machine connector AWS IoT Greengrass component writes the connection configuration to the local gateway, establishes connectivity with the OSIsoft PI server configuration specified in the connection configuration, and reads the telemetry data from the source machine. When this component receives the data, it writes output to the m2c2_<connectionName>_stream via the AWS IoT Greengrass stream manager. If you enabled basic authentication in the connector configuration, the solution provisions a new secret in AWS Secrets Manager. The solution then securely syncs and stores the secret on the edge devices using the Greengrass Secrets Manager component.

Modbus TCP collector

The Modbus TCP collector AWS IoT Greengrass component is provisioned by the Greengrass deployer Lambda function to the edge gateway when AWS IoT Greengrass is deployed. The Modbus TCP collector establishes a connection to a Modbus TCP server by a host parameter, which can be a URL or an IP address. The port is also designated. Once the machine connector AWS IoT Greengrass component establishes a connection, a configured JSON file tells the server what data to pull from the following commands:

• Read coils

• Read discrete inputs

• Read holding registers

• Read input registers

The solution writes the results from these reads to the m2c2_<connectionName>_stream via the AWS IoT Greengrass stream manager. You can configure the frequency at which it polls the Modbus TCP collector after deployment.

Publisher

The publisher AWS IoT Greengrass component manages the connectivity with the AWS resources to send data to the AWS Cloud, and reads the telemetry data from the AWS IoT Greengrass stream and sends it back to the AWS Cloud.

By default, the connection definition and configuration provided in the CloudFormation template, the publisher AWS IoT Greengrass component sends the data to Amazon Kinesis Data Streams. Amazon Kinesis Data Firehose retrieves the data from the stream, bundles batches of the data into GZIP files, and stores them in an Amazon S3 bucket. Optionally, you can connect to an existing Kinesis data stream in your AWS account and the publisher AWS IoT Greengrass component will publish the telemetry data to the Kinesis data stream.

When a connection is defined to send data to an AWS IoT topic, the publisher AWS IoT Greengrass component sends the data to the m2c2/data/<connectionName>/<machineName>/<tagName> MQTT topic in AWS IoT Core. Error messages are sent to the m2c2/error/<connectionName> MQTT topic and informational messages are sent to the m2c2/info/<connectionName> MQTT topic.

You can use an AWS IoT rules engine to subscribe to these MQTT topics to either store their data in your own data lake, in an Amazon S3 bucket, or you can initiate notifications using Amazon Simple Notification Service (Amazon SNS).

When a connection is defined to send the data to AWS IoT SiteWise, you must create an asset model and an asset to be able to consume, read, and analyze the data. Once you have an asset model and have created an asset, you must assign an alias to the asset measurements that matches the data that is coming in from your device. Data from OPC DA and OSIsoft PI uses the following alias naming convention: <siteName>/<area>/<process>/<machineName>/<tag>. If the data is from OPC UA, the alias is the full tag structure from the root. To learn more about modeling industrial assets in AWS IoT SiteWise, refer to Modeling industrial assets in the AWS IoT SiteWise User Guide.

When a connection is defined to send the data to Amazon Timestream, the publisher AWS IoT Greengrass component sends the data to Amazon Timestream table which is deployed when the solution CloudFormation stack is created. You can bring your existing Amazon Timestream database when you launch the solution CloudFormation stack. In that case, the CloudFormation template is going to provision an Amazon Timestream table in the existing database.

Solution workflow

This solution uses AWS IoT Greengrass to communicate with on-premises equipment using either the OPC DA or OPC UA protocols, or the OSIsoft PI Web API. After launching the CloudFormation template, the following workflow is set up to collect your telemetry data.

Workflow for the Machine to Cloud Connectivity Framework solution

1. Through the user interface, you register a AWS IoT Greengrass core device. You create a connection defining the telemetry data you want to collect from your on-premises hardware.

   • The hardware has to use either OPC DA or OPC-UA protocols.

   • A connection defines the details around the telemetry data being collected, including the name of the machine whose telemetry you are collecting, the protocol the source machine is using, the data collection-specific tags, and the location information of the machine.

2. The user interface activates the connection builder Lambda function to register a AWS IoT Greengrass core device and create a connection.

3. The connection builder Lambda function validates the connection configuration and invokes the Greengrass deployer Lambda function.

   • If the source uses an OPC DA protocol or OSIsoft PI Web API, the Greengrass deployer Lambda function creates a collector AWS IoT Greengrass component and uses the connection configuration to configure the collector AWS IoT Greengrass component.

   • If the source uses an OPC-UA protocol, the Greengrass deployer Lambda function creates an OPC-UA source in the SiteWise Gateway configuration.

   • The Greengrass deployer Lambda function creates the data publisher AWS IoT Greengrass component, including the machine location information as well as the data destination definition.

   • The AWS IoT Greengrass deployer Lambda function creates a deployment of the AWS IoT Greengrass core device to the industrial gateway.

4. The collector AWS IoT Greengrass component connects to the configured host and collects the data as defined in the connection configuration.

   • If the source uses an OPC DA protocol, the collector AWS IoT Greengrass component adds an alias and name to the telemetry information.

   • The alias and name follow the same format: <siteName>/<area>/<process>/<machineName>/<tag>

5. The collected telemetry is written to a Greengrass stream manager stream, one stream per connection.

   • Information messages or error messages from the OPC DA collector is published in IoT topics: m2c2/info/<connectionName> and m2c2/error/<connectionName>.

   • The information and error messages are accessible through the user interface.

6. The data publisher AWS IoT Greengrass component deployed with the connection reads the data from the connection stream.

7. Depending on the configured destination, the data publisher AWS IoT Greengrass component updates the data and forwards to the destination.

   • The default destination is Amazon Kinesis Data Streams. When sending data to a Kinesis data stream and the IoT topic, the publisher adds metadata to the telemetry with the connection information.

   • Optionally, you can provide your own Kinesis data stream instead of using the one created by the solution. Provide the name of the data stream that is in your AWS account when launching the CloudFormation stack (using the Name of the Existing Kinesis Data Stream parameter), and create your own consumer to read from the stream and send the data to your preferred destination.

   • Optionally, you can also send data to an AWS IoT topic, to AWS IoT SiteWise, or to Amazon Timestream.

     You can send your data to an AWS IoT topic and use IoT rules to interact with AWS services. For more information, refer to Rules for AWS IoT in the AWS IoT Developer Guide.

     You can send your data to AWS IoT SiteWise to monitor operations across facilities, quickly compute common industrial performance metrics, and create applications that analyze industrial equipment data to prevent costly equipment issues and reduce gaps in production.

     You can send your data to Amazon Timestream for time series data. Optionally, you can provide your own Amazon Timestream database instead of using the one created by the solution. Provide the name of the database that is in your AWS account when launching the CloudFormation stack (using the Name of the Existing Timestream Database parameter). The stack then creates an Amazon Timestream table in the existing database.

   • For sending data to AWS IoT SiteWise, the timestamp is transformed to milliseconds.

8. In the default configuration, when the data is sent to the Kinesis data stream, a Kinesis Data Firehose delivery stream takes that data, batches the data, and stores it in an Amazon S3 bucket. You can also choose to send your data to AWS IoT SiteWise or to AWS IoT Core, or to Amazon Timestream.

   • When sending the data to AWS IoT Core, the data is transmitted via the m2c2/data/<connectionName/<machineName>/<tagName> MQTT topic. You can specify where to send the data once it gets to AWS IoT Core by configuring your own rules engine in AWS IoT Core.

   • When sending your data to AWS IoT SiteWise, you must create an asset model and an asset to be able to consume, read, and analyze the data. Once you have an asset model and have created an asset, you must assign an alias to the asset measurements that matches the data transmitted from your device. If the data is from OPC DA, the alias is <siteName>/<area>/<process>/<machineName>/<tag>. If the data is from OPC UA, the alias is the full tag structure from the root. To learn more about modeling industrial assets in AWS IoT SiteWise, refer to Modeling industrial assets in the AWS IoT SiteWise User Guide.

   • When sending your data to Amazon Timestream, the data contains the metadata as dimensions.

Communicating with your AWS IoT Greengrass industrial gateway

The solution’s user interface (UI) communicates with the on-premises industrial gateway that is running AWS IoT Greengrass through the API. The UI issues command through the API and control signals on an IoT topic, for example, m2c2/job/<connectionName>.

The OPC DA collector AWS IoT Greengrass component reads the message sent to the topic and takes the appropriate action. The OPC-UA collector AWS IoT Greengrass component receives its configuration directly from AWS IoT SiteWise.

Getting data from on-premises equipment to AWS

You can define your data destination via the user interface. As shown in Figure 4, you can choose to send telemetry data to one or more of the following destinations: AWS IoT SiteWise, an IoT Topic, or Amazon Kinesis Data Streams, or Amazon Timestream, as shown in the following figure.

User interface - select the data destination

AWS CloudFormation parameters

This solution provides the following AWS CloudFormation parameters: Initial User Email, Logging Level, Name of the Existing Kinesis Data Stream, and Name of the Existing Timestream Database.

The Name of the Existing Kinesis Data Stream and Name of the Existing Timestream Database parameters are used to determine whether the necessary AWS resources are created on your behalf or if you are providing the necessary AWS resources. By default, these parameters are left empty, which means the solution automatically creates new AWS resources on your behalf.

The Logging Level parameter determines the level of logging detail you want when using the solution. The default logging level is ERROR. Additional logging levels include VERBOSE, DEBUG, INFO, and WARN.

The Initial User Email parameter creates the initial user that is authorized to log in to the solution’s user interface. This solution uses Amazon Cognito to create the user and a temporary password. When the initial user logs in to the UI for the first time, they must change the password in order to continue to the home page.

Name of the Existing Kinesis Data Stream

When you provide a data stream name value for this parameter, the solution uses the specified stream to push telemetry data. The solution does not create a new Kinesis data stream, a Kinesis Data Firehose delivery stream, or an S3 bucket. You are responsible for creating a consumer to pull messages from the data stream and manage the storage of that data.

Name of the Existing Amazon Timestream Database

When you provide a database name value for this parameter, the solution creates an Amazon Timestream table in the database. The solution does not create a new Amazon Timestream database.