Skip to end of metadata
Go to start of metadata

Prerequisites

  • Have an AWS account - see here: https://aws.amazon.com/
  • Knowledge of Ignition and Module installation process: Cirrus Link Module Installation
  • Have Ignition 8.1.4 or greater installed
  • Install one of following MQTT Modules into Ignition
    • MQTT Engine
      • v4.0.8 or later
    • MQTT Transmission
      • v4.0.8 or later

Abstract

This tutorial describes how to connect MQTT Engine or MQTT Transmission to Amazon Web Services (AWS) IoT Core.

AWS IoT does not support guaranteed in order delivery of QoS 0 messages which is not all that uncommon among horizontally scalable/clustered MQTT Servers. When connecting with MQTT Engine, you will need to apply a custom configuration property that allows 're-ordering' of messages that arrive out of order.


AWS IoT Core supports messages with a maximum message length of 128KB. If messages are received that exceed this limit AWS IoT Core will disconnect the client. 

Review our HowTo on ways to identify and resolve if this occurs

Provisioning the 'Thing'

Before configuring MQTT Engine or MQTT Transmission, 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 intend to connect the MQTT Module 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,iot:RetainPublish
    • Note this will be used for both a publisher connection (Ignition) and a subscriber (MQTT Engine and/or MQTT Transmission)
  • Resource ARN
    • Set to: arn:aws:iot:AWS_REGION:ACCOUNT_ID:*
    • In the above, replace the following.
      • AWS_REGION: The region MQTT Engine and/or MQTT Transmission will connect to like us-east-1, us-west-1, etc
      • 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 MQTT_Module) 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 policy attachment page, select the previously created policy so it will be attached to the 'thing' being created as shown below.

This will bring up the page similar to what is shown below. At this point, you must download the 'Device certificate' and 'Private key file' files. These will both be used in the MQTT Module 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.certificate.pem.crt
  • UUID.private.pem.key
  • AmazonRootCA1.pem

Once you have these, click the 'Create' button. This will bring up the following page showing the created 'Thing'.


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 the MQTT Module.

With AWS IoT now properly provisioned and the MQTT Module installed, the module can be configured. The three certificate files that were captured when provisioning the AWS IoT Core thing will be required. Again, these files are:

  • UUID.certificate.pem.crt
  • UUID.private.pem.key
  • AmazonRootCA1.pem

For this example we'll be using MQTT Engine. However, the steps are very similar for MQTT Transmission with regard to connection establishment. Using the Ignition Gateway Web UI, browse to the Igntion 'Config → MQTT Engine/Transmission settings page'. Now click the 'Certificates' tab as shown below:

Now click the 'Create new Certificate' link. Then upload one of the three files previously downloaded when creating the IoT Core 'Thing'. Once completed, your Certificates page should look similar to the following with all three files.

Now, click the 'Servers' tab as shown below.

If you are only going to be connecting to AWS IoT Core, edit the existing 'Chariot SCADA' setting. Otherwise, create a new MQTT Server Setting. This should bring up the following page.

Set the following.

  • Name
    • AWS IoT Core
  • URL
  • Username
    • Blank
  • Password
    • Blank
    • Note if a password was previously set, make sure to click the 'Change Password' checkbox and ensure the password fields are empty
  • CA Certificate File
    • The 'Root CA' that was downloaded from AWS IoT Core
  • Client Certificate File
    • The 'Client Cert' that was downloaded from AWS IoT Core
  • Client Private Key File
    • The 'Client Private Key' that was downloaded from AWS IoT Core.

Leave all other fields blank and submit the configuration. If everything was set up properly, the 'Status' should show 'Connected' when complete.


For MQTT Engine, you must also set the 'reordering timeout' due to timing issues related to IoT Core message delivery. To do this, set the Custom Properties on the MQTT Engine General tab to: { "reorderingTimeout" : 3000 } as shown below and save the changes.

This will allow MQTT Engine to buffer messages and reorder them should they be delivered out of order within a 3 second window. Generally 3 seconds seems to be plenty of time for the reordering with AWS IoT Core.



Additional Resources

  • No labels