Page History

Prerequisites

• Ignition with Google Cloud Injector Module installed
  • Review the Cirrus Link Module Installation documentation for installation details.
• Ignition Designer installed
  • Review the Inductive Automation documentation for Launching Designer against the Ignition gateway
• Knowledge of Ignition and Module installation process: Cloud and MQTT Module Installation.
• An existing AWS account with an active Kinesis Stream and/or DynamoDB Database.
  
  • Documentation on creating a Kinesis Stream can be found here.
    • If using a Firehose stream, its source must be "Direct PUT or other sources"
  • Documentation on creating a DynamoDB Database table can be found here.
    • DynamoDB Database tables ideally should be created with the following settings:

      • Primary partition key: UUID 

      GROUP_EDGE_ID

      • (String)

      • Primary sort key:

      TIMESTAMP

      • GROUP_EDGE_ID (String)

Summary

This tutorial will provide step-by-step instructions for the following:

• Installing the Ignition Gateway Industrial Application Platform with the AWS Injector Module
• Configuring the AWS Injector Module Configuring the AWS Injector Module to connect to a Kinesis Stream
• Configuring the AWS Injector Module to connect to a DynamoDB Database
• Publishing live Tag data and events to the connected Kinesis Stream and DynamoDB Database. 

Upon completion of this module you will have an Ignition Gateway connected and publishing live Tag data to AWS.

Architecture

Tutorial

Anchor
step1 step1

Step 1:

...

Configure the AWS Injector Modules

Once you have Ignition and the AWS Injector Module installed and running we can setup the configuration to connect to AWS.

Navigate to the AWS Injector Module configuration section from the left side bar in the Ignition Gateway.

Image Added

Anchor
step1a step1a

Create an AWS Kinesis Stream Setting

From the Kinesis tab, click on the "Create new AWS Kinesis Stream Setting..." link to bring up the following configuration form:

Image Added

Set the following parameters:

• Setting Name
  • This can be any unique identifier. For this tutorial we will use "TestSetting".
• AWS Access Key
  • This is the Access Key used to authenticate to your AWS account 
• Password
  • This is the Secret Key used to authenticate to your AWS account
• Region
  • This is the AWS Region that your Kinesis Stream is in
• Stream Name
  • This is the name of the Kinesis Stream that you wish to connect to.  This is shown below in the AWS Kinesis Streams console.
    Image Added

Click on "Create New Kinesis Stream Setting" to finish creating the new configuration setting.

Image Added

Anchor
step1b step1b

Create an AWS DynamoDB Database Setting

From the DynamoDB tab, click on the "Create new DynamoDB Setting..." link to bring up the following configuration form:

Image Added

Set the following parameters:

• Setting Name
  • This can be any unique identifier. For this tutorial we will use "TestSetting".
  • Note that this only has to be unique among DynamoDB Settings so we can configure with the same used for the Kinesis Stream.
• AWS Access Key
  • This is the Access Key used to authenticate to your AWS account 
• Password
  • This is the Secret Key used to authenticate to your AWS account
• Region
  • This is the AWS Region that your DynamoDB Database is in
• Table Name
  • This is the name of the DynamoDB Database Table to connect to.  This is shown below in the AWS DynamoDB console.
    Image Added

Click on "Create New DynamoDB Setting" to finish creating the new configuration setting.

Image Added

Now the AWS Injector module is connected to a Kinesis Stream and/or a DynamoDB Database, we have to determine if there are are changes needed to the Tag Agent tab to be able to push data.

If you already have Ignition tags defined, for example from the Ignition OPC UA Server, then depending on the depth of your tag tree you may need to configure the Sparkplug Settings. 

Once the Tag Agent is setup as needed, you can jump to Step 3: Publishing data.

If you do not have Ignition tags defined we will do that in the next step with a tag tree depth that requires no additional Sparkplug settings.

Step 2: Create tags to be published in Designer

When the AWS Injector module is installed in Ignition, an Edge Node folder is automatically created in the 'default' Ignition tag provider.Image Added

Create a tree structure under this folder as shown below with some memory tags - this folder structure creates the same hierarchy that is described in the Sparkplug B specification of Group ID, Edge ID, and Device ID.

Image Added

Anchor
step3 step3

Step 3: Publishing data

When the AWS Injector module is installed in Ignition, an AWS Injector tag provider is automatically created. This folder will contain both information tags about the module's version and state, as well as control tags for refreshing the module and Tag Agents.

Ignition is an Industrial Application Platform that can be used to create SCADA and HMI solutions. A fully functional Ignition system can be downloaded and run in trial mode. Using Ignition as a tool in this way, we can install the Sparkplug MQTT Modules and observe everything working.

Go to the Inductive Automation download page and download the desired Ignition installer for Windows, Linux or MacOS;
https://inductiveautomation.com/downloads/ignition

Once the Ignition installer has been downloaded, follow the instructions provided by Inductive Automation to install and startup Ignition.

Step 2: Download and Install the Cirrus Link AWS Injector Module

Go to the Inductive Automation download page again and scroll down to the Third Party modules section. Find the Cirrus Link modules section and download the AWS Injector Module.
https://inductiveautomation.com/downloads/ignition.  The download links should look similar to what is shown below.

(placeholder for image)

Step 3: Configure the MQTT Modules

Once you have Ignition installed and running, and the AWS Injector module downloaded, browse to the Ignition Gateway console (e.g. http://localhost:8088).  Login using the default credentials of admin/password.  Click on Configuration tab and then click on the Modules tab on the left side of the page.  Scroll to the bottom of the Modules section and click on the Download/Upgrade modules button.  When prompted, select the AWS Injector module from the file browser and install it.  When complete, the Ignition Gateway Web UI module section should look similar to what is shown below:

Image Removed

Select the "AWS INJECTOR" → "Settings" link on the lower left of the page to navigate to the AWS Injector Module's configuration page.

Image Removed

 A detailed explanation of each configuration tab can be found here.  For this tutorial, we will be adding new Kinesis Stream and DynamoDB Database Settings.  You may optionally choose to skip one of the following two sections if you do not wish to setup a Kinesis Stream endpoint or a DynamoDB Database.

Create an AWS Kinesis Stream Setting

With the Kinesis tab selected, Click on the "Create new AWS Kinesis Stream Setting..." link to bring up the following configuration form:

Image Removed

For the Setting Name you can enter any unique identifier, we will use "TestSetting".  For the AWS credentials, you will need to enter your Access Key and Secret Key used to authenticate to your AWS account as well as the region that your Kinesis Stream is in.  The Set can be left as Default.  Finally, the Stream Name will be the name of the Kinesis Stream that you wish to connect to.  This is shown below in the AWS Kinesis Streams console.

Image Removed

Click on "Create New Kinesis Stream Setting" to finish creating the new configuration setting.

Image Removed

Create an AWS DynamoDB Database Setting

Select the DynamoDB tab to bring up the DynamoDB Database Settings page.

Image Removed

 Click on the "Create new DynamoDB Setting..." link to bring up the following configuration form:

Image Removed

For the Setting Name you can enter any unique identifier. We will again use "TestSetting" as it must only be unique among DynamoDB Settings.  For the AWS credentials, you will need to enter your Access Key and Secret Key used to authenticate to your AWS account as well as the region that your DynamoDB Database is in.  The Set can be left as Default.  Finally, the Table Name will be the name of the DynamoDB Table that you wish to connect to.  For example, this is shown below in the AWS DynamoDB console.

Image Removed

Click on "Create New DynamoDB Setting" to finish creating the new configuration setting.

Image Removed

Use Default Tag Agent Settings

Now the AWS Injector module is connected to a Kinesis Stream and/or a DynamoDB Database and ready to push Tag data you can click on the "Tag Agents" tab you will see that out-of-the-box the AWS Injector module will have one default Tag Agent defined.  For this tutorial we will not need to make any configuration changes to the Tag Agents.

Image Removed

The Default Tag Agent will monitor tags that are in the "Edge Nodes" folder of the "default" Tag Provider.  In the next step we go into more detail about the tags in this folder.

Step 4: Use Ignition Designer to Examine the Initial Tag Structure

With Ignition running and the AWS Injector module loaded and configured we can now open the Ignition Designer to create/observe the initial Tag structure.  Regardless of the OS Ignition is running on, there is a “Get Designer” button on the Ignition Gateway Console. From here you can launch your Designer on any machine.  This is shown below.  The default credentials for the designer are the same as the Gateway Console, admin/password.  

Image Removed

Once you have logged into the Designer enter a new project name and open the project. The project name that we used for this tutorial is simply called “test”.

Image Removed

After Designer opens, you will see the default Designer screen as shown below.

With the AWS Injector module installed in Ignition, a new folder is created under the "All Providers" folder and is called “AWS Injector”. This folder will contain both information tags about the module's version and state, as well as control tags for refreshing the module and it's Tag Agents.

Image Removed

Next, we need to create a folder structure where we will create a virtual Edge device and some tags to be sent by the AWS Injector module.  When the AWS Injector module is installed in Ignition, a folder is automatically created in the Ignition tag structure with the following path:

• All Providers/default/Edge Nodes

Image Removed

Step 5: Use Ignition Designer to Create New Tags

For this tutorial, right click on the Edge Nodes folder and create a new folder called Tutorial Group. Then right click on the Tutorial Group folder and create another new folder called Tutorial Edge Node.  Finally, right click on the Tutorial Edge Node folder and create another new folder called Tutorial Device. This folder structure creates the same hierarchy that is described in the Sparkplug B specification of Group ID, Edge ID, and Device ID.

With this folder structure in place, now we can create some memory tags of various data types to publish. Right click on the Tutorial Device folder and select ’New Tag’/’Memory Tag’. In the tag editor change the Name of the tag to “Boolean001”, and change the Data Type to Boolean. Follow this same procedure for new memory tags called “Integer001” of type Integer, “Float001” of type Float, and “String001” of type String. The resulting folder structure should look as follows.

Image Removed

Step 6: Use Ignition Designer to Send Tag Data (Current Tag Values)

Now that we have a folder structure with some tags we can refresh the AWS Injector module.  Make sure that the Ignition Designer has read/write communications turned on by selecting Project/Comm Read/Write.Image Removedturned on by selecting the Project/Comm Read/Write button highlighted in the image below. Image Added

To refresh the default Tag Agent with the folder structure we’ve created, open the folder "All Providers/AWS Injector /AWS Injector ControlControl" and click on the Refresh Boolean. Note the Boolean tag will not change to true. This is really a one-shot and as a result, the tag will not change to true.

Image Removed

on the Refresh Boolean. When this happens, the Tag Agent will scan the "Edge Nodes" folder and find the new Memory Tags that we have created, construct messages representing messages representing those tags with their current values and send the messages to the Kinesis Stream and/or DynamoDB Database that we have configured.

...

the messages to the Kinesis Stream and/or DynamoDB Database that we have configured.

Image Added

Sending tag data to the Kinesis Stream

The AWS Injector Tag Agent will push two JSON messages to the Kinesis Stream.  The format of these messages closely follows the Sparkplug B Specification's payload structure.

...

{
  "topic": {
    "namespace": "spBv1.0",
    "groupId": "Tutorial Group",
    "edgeNodeId": "Tutorial Edge Node",
    "deviceId": "Tutorial Device"
  },
  "payload": {
    "timestamp": 1504739061501,
    "metrics": [
      {
        "name": "Boolean001",
        "timestamp": 1504739061546,
        "dataType": "Boolean",
        "properties": {
          "Quality": {
            "type": "Int32",
            "value": 192
          }
        },
        "value": true
      },
      {
        "name": "String001",
        "timestamp": 1504739061546,
        "dataType": "String",
        "properties": {
          "Quality": {
            "type": "Int32",
            "value": 192
          }
        },
        "value": "onetwothree"
      },
      {
        "name": "Integer001",
        "timestamp": 1504739061546,
        "dataType": "Int32",
        "properties": {
          "Quality": {
            "type": "Int32",
            "value": 192
          }
        },
        "value": 123
      },
      {
        "name": "Float001",
        "timestamp": 1504739061546,
        "dataType": "Float",
        "properties": {
          "Quality": {
            "type": "Int32",
            "value": 192
          }
        },
        "value": 1.23
      }
    ],
    "seq": 1
  }
}

Sending

...

tag data to the DynamoDB Table

The AWS Injector Tag Agent will insert two items into the DynamoDB Database table.  The columns of these items represent different elements of the Sparkplug B Specification's payload structure.

...

• EDGE_NODE_ID
  • The Sparkplug Edge Node ID.
• GROUP_ID
  • The Sparkplug Group ID.
• GROUP_EDGE_ID
  • A combination of the Group ID and Edge Node ID, (used as the Primary Partition Key).
• TIMESTAMP
  • A "timestamp" for when the payload was constructed
• TOPIC
  • The Sparkplug topic.
• bdSeq
  • A  sequence number to track the "session" of the Tag Agent.
• Any Edge Node tags defined in the "Tutorial Edge Node" folder In (in our example we have none).

It will look something like this:

...

It will look something like this:

Step

...

4: Use Ignition Designer to Publish Tag Data (Live Tag Values Changes)

Now we can change the values of the new Memory Tags and generate messages that contain the Tag change events.Click  Click on the value of the "Boolean001" Memory Tag to change it's value.

Sending Live Tag Data to the Kinesis Stream

The following message will be constructed to represent this Tag change event and pushed to the Kinesis Stream:

{
  "topic": {
    "namespace": "spBv1.0",
    "groupId": "Tutorial Group",
    "edgeNodeId": "Tutorial Edge Node",
    "deviceId": "Tutorial Device"
  },
  "payload": {
    "timestamp": 1504740884529,
    "metrics": [
      {
        "name": "Boolean001",
        "timestamp": 1504740883526,
        "dataType": "Boolean",
        "value": false
      }
    ],
    "seq": 2
  }
}

Sending Live Tag Data to the DynamoDB Database

The following item will be constructed to represent this Tag change event and inserted into the DynamoDB Database table

Step

...

5: AWS Applications

It is beyond the scope of this tutorial to show how to design an application in AWS to handle the data flowing into the Kinesis Stream and/or DynamoDB Database.  For additional information on developing applications to consume this data see https://aws.amazon.com/.