You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Next »

Prerequisites

Before being able to access the AMI you must have completed the installation process here. Once the AMI in AWS Marketplace has been used to create an EC2 instance you are ready to continue this quickstart guide.

Summary

Sparkplug SiteWise Bridge (SSB) is an application that connects to an MQTT Server (such as AWS IoT Core) and consumes MQTT Sparkplug messages from Edge devices.  These messages must be formatted as Sparkplug Templates. Sparkplug Templates are defined in the Sparkplug Specification. These Templates are used to create the Models in AWS SiteWise automatically with no additional coding or configuration.  Then multiple instances of these Templates generate the Assets and start to populate with real time data sent on change only, thus significantly reducing the amount of data being sent to the cloud.  For further details on AWS SiteWise terminology, refer to the AWS SiteWise documentation here. For further details on Eclipse Sparkplug, refer to the Eclipse Sparkplug resources.

This Quickstart document covers how Sparkplug SiteWise Bridge can be used to consume MQTT Sparkplug data and create and update SiteWise Asset Models and Assets. This will show how to configure Sparkplug SiteWise Bridge as well as show how to use Inductive Automation's Ignition platform along with Cirrus Link's MQTT modules to publish device data to an MQTT Server. This data will ultimately be consumed by Sparkplug SiteWise Bridge to create and update the SiteWise components. This tutorial will use the AWS IoT Core MQTT Server implementation. However, SSB does work with any MQTT v3.1.1 compliant MQTT Server.

It is also important to note that Ignition in conjunction with Cirrus Link's MQTT Transmission module converts Ignition User Defined Types (UDTs) to Sparkplug Templates. This is done automatically by the MQTT Transmission module. So, much of this document will refer to UDTs rather than Sparkplug Templates since that is what they are in Ignition. More information on Inductive Automation's Ignition platform can be found here. Additional information on Cirrus Link's MQTT Transmission module can be found here.

Sparkplug SiteWise Bridge Setup

Before configuring Sparkplug SiteWise Bridge (SSB), you must register a 'thing' connection in AWS IoT Core. Begin by browsing to AWS IoT Core in your AWS account. Make sure you are in the same AWS region that you have already deployed SSB to. Begin by expanding 'Secure' and click 'Policies' as shown below.

Now click the 'Create a policy' button. This will bring up the following page.

Set the following parameters for the policy.

  • Name
    • Some friendly name you will remember
  • Actions
    • Set to: iot:Connect,iot:Publish,iot:Subscribe,iot:Receive
    • Note this will be used for both a publisher connection (Ignition) and a subscriber (SSB)
  • Resource ARN
    • Set to: arn:aws:iot:AWS_REGION:ACCOUNT_ID:*
    • In the above, replace the following.
      • AWS_REGION: one of the following (where you set up SSB): us-east-1, us-west-2, eu-central-1, or eu-west-1
      • ACCOUNT_ID: Your AWS Account ID
  • Effect
    • Set to 'Allow'

Finally click 'Create' in the lower right. This will show the newly created policy.

At this point a 'thing' can be created. We'll use the policy a bit later in the procedure. To create the thing, expand 'Manage' on the left navigation panel and click 'Things' as shown below.

Click 'Register a thing'. This will bring up the page below.

Now click 'Create a single thing'. This will open the following page. Give your thing a name (such as SSB) and then click 'Next'.

This will bring up the following page. Click the 'One-click certificate creation' option shown below.

This will bring up the page similar to what is shown below. At this point, you must download the UUID.cert.pem file and the UUID.private.key file. These will both be used in the SSB configuration to connect to AWS IoT later. These files will not be accessible later and must be downloaded now. In addition, there is a link to download the root CA for AWS IoT. Make sure to download this as well. The 'RSA 2048 bit key: Amazon Root CA 1' is the preferred root certificate to download.

At this point you should have three files where 'UUID' will be some UUID specific to your thing. Do not proceed until you have all three files.

  • UUID.cert.pem
  • UUDT.private.key
  • AmazonRootCA1.pem

Once you have these, click the 'Activate' button. Then, click the 'Attach a policy' button. This will bring up the following page.

Now select the 'SSB_Policy' and finally click 'Register Thing'. At this point, you should see your newly provisioned 'thing' as shown below.

Now we need to get the AWS IoT Core Endpoint. Do so by selecting 'Settings' from the left navigation panel as shown below.

When selected, your AWS IoT Endpoint will be displayed. Note it for future use when configuring SSB.

With AWS IoT now properly provisioned and SSB installed, SSB must be configured. To configure it, you must be able to access it via SSH. Ensure you can access it via the Access Instructions here. Once you can access it, you must copy the three certificate files you captured when provisioning the AWS IoT Core thing. Again, these files are:

  • UUID.cert.pem
  • UUDT.private.key
  • AmazonRootCA1.pem

On the target EC2 instance, run the following command to create a directory to hold the certificates.

mkdir /opt/ssb/conf/certs

Now copy the three files to the /opt/ssb/conf/certs directory. When done, it should look similar to what is shown below.

Now, modify the file /opt/ssb/conf/ssb.properties file. Set the following:

  • mqtt_server_url
  • mqtt_ca_cert_chain_path
    • The path to the AWS root CA certificate
  • mqtt_client_cert_path
    • The path to the AWS thing certificiate
  • mqtt_client_private_key_path
    • The path to the AWS thing private key

When complete, it should look similar to what is shown below.

Now the service can be restarted to pick up the new configuration. Do so by running the following command.

sudo /etc/init.d/ssb restart

At this point, SSB should connect to AWS IoT Core and be ready to receive MQTT Sparkplug messages. Verify by running the following command.

tail -f /opt/ssb/log/wrapper.log

After doing so, you should see something similar to what is shown below. Note the last line is 'MQTT Client connected to ...'. That denotes we have successfully configured SSB and properly provisioned AWS IoT Core.

Edge Setup with Ignition and MQTT Transmission

At this point Sparkplug SiteWise Bridge is configured and ready to receive data. To get data flowing into SSB we'll set up Inductive Automation's Ignition platform along with the MQTT Transmission module from Cirrus Link. Begin by downloading Ignition here.

https://inductiveautomation.com/downloads

Installation of Ignition is very straigtforward and fast. There is a guide to do so here.

https://docs.inductiveautomation.com/display/DOC80/Installing+and+Upgrading+Ignition

With Ignition installed, MQTT Transmission must be installed as well as a plugin to Ignition. Get MQTT Transmission for your version of Ignition here.

https://inductiveautomation.com/downloads/third-party-modules

Now use the procedure below to install the MQTT Transmission module.

https://docs.inductiveautomation.com/display/DOC80/Installing+or+Upgrading+a+Module

With Ignition and MQTT Transmission installed, we can configure the MQTT Transmission module to connect to AWS IoT Core using the same certificates that we provisioned earlier. Begin by clicking 'Get Desginer' in the upper right hand corner of the Ignition Gateway Web UI as shown below.

Now launch the Ignition Designer using the Designer Launcher as shown below.

Once it is launched, you should see something similar to what is shown below. Note the Tag Browser has been expanded and the automatically created example tags have been highlighted.

Begin by deleting these two tags (Example Tag and MQTT Quickstart). Then click the 'UDT Definitions' tab as shown below. We will use this view to create a very simple UDT definition.

Now, click the '+' icon in the upper left corner of the tag browser as shown below and select 'New Data Type'

This will open the following dialog box.

Change the name of the tag to Motor as shown below. Also, note the highlighted 'new member tag' icon in the middle of the dialog. We'll use this to create some member tags.

Now use the 'new member tag' button to create a new 'memory tag' as shown below.

Then, set the following parameters for the new memory tag.

  • Name
    • Set to 'Temperature'
  • Date Type
    • Set to 'Float'
  • Engineering Units
    • Set to 'Celsius'

Now create two additional member tags with the following configuration.

  • Amps
    • Memory tag
    • Data Type = Integer
  • RPMs
    • Memory tag
    • Data Type = Integer

When complete, the UDT definition should look as follows.

Now switch back to the 'Tags' tab of the Tag Browser. Right click on the 'PLC 1' folder and select 'New Tag → Data Type Instance → Motor' as shown below.


Now set the name to 'My Motor' as shown below and click OK.

Now, set some values under the instance as shown below.

At this point, our tags are configured. A UDT definition will map to a SiteWise Asset Model and UDT instances in Ignition will map to SiteWise Assets. But, before this will happen we need to point MQTT Transmission to AWS IoT Core. To do so, browse back to the Ignition Gateway Web UI and select MQTT Transmission → Settings from the left navigation panel as shown below.

Now select the 'Transmitters' tab as shown below.

Now click the 'edit' button to the right of the 'Example Transmitter'. Scroll down to the 'Convert UDTs' option and uncheck it as shown below. This will also un-grey the 'Publish UDT Defintions' option. Leave it selected as shown below.

Then select the 'Servers' tab and 'Certificates' tab as shown below.

Now upload the three certificate files that were acquired during the AWS IoT thing provisioning. Upload all three to the MQTT Transmission configuration. When done, you should see something similar to what is shown below.

Now switch to the 'Servers' and 'Settings' tab. Delete the existing 'Chariot SCADA' pre-seeded MQTT Server Definition. Then create a new one with the following configuration.

  • Name
    • AWS IoT
  • URL
  • CA Certificate File
    • The AWS Root CA certificate
  • Client Certificate File
    • The AWS client certificate for your provisioned 'thing'
  • Client Private Key File
    • The AWS client private key for your provisioned 'thing'

When complete, you should see something similar to the following. However, the 'Connected' state should show '1 of 1' if everything was configured properly.

At this point, data should be flowing into AWS SiteWise. By tailing the log in SSB you should see something similar to what is shown below. This shows SSB receiving the messages published from Ignition/MQTT Transmission. When SSB receives the Sparkplug MQTT messages, it creates and updates asset models and assets in SiteWise. The log below is also a useful debugging tool if things don't appear to work as they should.

At this point, the asset models and assets have been created in AWS SiteWise as well. To see them, browse to the AWS Web Console and go to IoT SiteWise. Then click 'Models' using the left side pop-out navigation panel as shown below.

At this point you should have a 'Motor' Asset Model in SiteWise that corresponds to the Motor UDT definition that was created in Ignition. If you click the 'Measurements' tab you should also see the different UDT members that were added to the definition in Ignition.

Using the pop-out navigation panel on the left, now click the 'Assets'. Here you should see something similar to what is shown below. This asset represents the UDT instance that was created in Ignition. On the measurements tab you should see the values associated with these UDT member tags as shown below.

Additional Resources

  • Due to the multiple different systems involved in a Sparkplug SiteWise Bridge deployment there are caveats with regard to ensuring compatibility between supported features: SSB: Mappings and Constraints
  • No labels

New to MQTT? Start Here!