Industrial Automation Tech Note 50 - TNIA50
This document explains how to get Crimson® 3.1 devices to talk to Amazon Web Services (AWS) using the MQTT Connector. It assumes a basic knowledge of Crimson and its operation, and the ability to read and manipulate JSON. For more details on the Crimson Cloud Connectors, please consult the Crimson User Manual.
CR3000 HMIs / Data Acquisition (DA10 & DA30) / Graphite® HMI / Graphite Controllers
Use Case: AWS Connector
Transferring tag data to Amazon Web Services.
Build 3106.000 or higher
Step 1 - Creating an Account
If you do not have an AWS account, visit http://aws.amazon.com/free to create a free tier account. The free tier provides more than sufficient capacity for testing and may even be sufficient for limited deployments. If you move to a paid tier, be careful not to leave test devices configured in a manner that will run up your bill.
Step 2 - Accessing the IoT Core
Login to AWS and select the IoT Core service. Refer to the dashboard in Figure 1.
Step 3 - Creating a Policy
AWS uses Policies to control access to its IoT services. We must therefore create a policy that allows our Crimson devices to submit data to the cloud. To do this, select the Secure option in the left-hand menu and select the Policies option under that. A window will appear saying that you do not have any policies. Press the button labeled Create a Policy to create our new policy.
Referring to Figure 2, perform the following actions:
1. In the Name box, enter AllowAll
2. In the Action box, enter iot:*
3. The Resource ARN box will update to show a resource identifier.
4. Replace topic/replaceWithATopic at the end of the ARN with *
5. Under the Effect heading, check the Allow box.
6. Press the Create button to commit the change.
This policy allows anyone using a certificate to which it is assigned to perform any supported action on any resource in your IoT account. As you learn more about AWS, you might want to create more sophisticated policies to implement finer-grained control of access to your resources.
Step 4 - Creating a Type
AWS uses Types to group devices into categories. While not strictly necessary, we shall be creating a type to hold all our Crimson-based devices. To do this, select the Manage option in the left-hand menu and select the Types option under that. A window will appear saying that you do not have any types. Press the button labeled Create a Thing Type to create our new type.
Referring to Figure 3, perform the following actions:
1. In the Name box, enter CrimsonThing
2. In the Description box, enter any suitable description.
3. Press the Create Thing Type button to commit the change.
As you learn more about AWS, you might want to create different types to provide a finer-grained grouping of your devices. This will make it easier to search for and manage the devices associated with, for example, a particular site or a particular project.
Step 5 - Creating a Thing
AWS uses Things to represent devices. Each thing corresponds to a device that is pushing data to the cloud, and we shall be creating a Thing to hold the data submitted by our Crimson device. To do this, select the Manage option in the left-hand menu and select the Things option under that. A window will appear saying that you do not have any things. Press the button labeled Register a Thing to create our new thing.
Referring to Figure 4, select the Create a single thing option…
Referring to Figure 5, perform the following actions…
1. In the Name box, enter Thing01
2. From the Thing Type dropdown, select CrimsonThings
3. Skip the rest of the options and press the Next button.
A window will be displayed to allow you to configure the thing’s security settings…
Referring to Figure 6, select the Create Certificate button…
Referring to Figure 7, perform the following actions…
1. Click on the Download link next to the certificate and allow your browser to save the file.
2. Click on the Download link next to the private key and allow your browser to save the file.
3. Press the Activate button to activate the certificate.
When performing this step, take very careful note of where the certificate and key files are saved. If you lose them, you will have to create and attach a new certificate or delete this thing and start again. Your browser will typically save them to its Downloads folder, but you may want to move them to a more secure location.
You may now click on the Attach a Policy button to move to the next step…
Referring to Figure 8, perform the following steps…
1. From the list of policies, check the box next to the AllowAll policy we created earlier.
2. Press the Register Thing button to complete the process.
We have now created a thing called Thing01 to which we shall be pushing data. The thing has a certificate and a private key to identify it, and we have downloaded the associated files for import into Crimson. The thing’s certificate has been assigned a policy that allows it to perform any operations. We have also downloaded a root certificate that will authenticate the Amazon server to our device.
Step 6 - Finding the Server Host Name
In order for our device to interact with AWS, we need to find the name of the server to which our MQTT requests will be sent. To find the hostname, first ensure that you have Thing01 selected. This will already be the case if you have just completed the previous step, but if you have navigated away, you will have to return to the appropriate location by selecting the Manage option in the left-hand menu, selecting the Things option under that and then selecting Thing01. With Thing01 selected, select the Interact option from the left-hand menu.
Referring to Figure 9, even though we are using MQTT, the hostname we need is shown under the HTTPS section. Select this hostname in your browser and place it on to your clipboard so that you can take a copy. We shall be pasting this into Crimson when we first go to configure the Amazon MQTT connector.
Step 7 - Creating an Outline Database
You should now open Crimson 3.1 and create a new database for your device. Before we configure the Amazon Connector, we shall need to perform a few steps to create the infrastructure used for testing. Red Lion will soon be making these so-called outline databases available via its website and including them in the Crimson installation. In the meantime, to manually create an outline database, start by navigating to the Communications category and selecting the Ethernet 1 tab in the Network settings…
Referring to Figure 10, if the device is connected to a network that automatically allocates IP addresses via a DHCP server, you may leave these settings unchanged. If you are manually specifying an IP address, you must also define a default gateway and manually provide DNS servers. The gateway is necessary for your device to push data to the Internet and the DNS servers are used to convert the cloud server name into an IP address. The default server addresses of 126.96.36.199 and 188.8.131.52 will be suitable for most applications, but the DNS Mode must be explicitly set to Manual if the Port Mode is set to Manual Configuration.
Next, select the Time Manager settings within the Services group.
Referring to Figure 11, perform the following actions…
1. In the Control section, set the Enable Time Manager property to Yes.
2. In the Time Client section, set the Enable SNTP setting to Yes.
The other settings may be left at their default values. These settings enable time synchronization, allowing your device to set its real-time clock from the Internet. Having an accurate real-time clock is important not only for time-stamping data, but also for ensuring the correct operation of certain security algorithms. Once you have downloaded your outline database for the first time, select the Send Time option from the Link menu within Crimson to set the device’s time zone to that of your PC. If you need to set it to a different time zone, refer to the Crimson manuals for information on the time zone system variables.
Next navigate to the Data Tags category and press the New button five times…
Referring to Figure 12, select Tag5 in the Navigation Pane and then rename it to Status.
Next, navigate to the Display Pages category…
Referring to Figure 13, perform the following actions…
1. Select the Hello World text and press Delete to remove it from the screen.
2. In the Resource Pane, select the Data Tags category.
3. In the Resource Pane, click on Tag1 and, while holding down Shift + Ctrl, click on Status.
4. All five data tags should be selected.
5. Drag the resulting selection on to your display page.
6. Grab the bottom-right resizing handle and expand the data fields to a suitable size.
7. Click away from the data fields to deselect them.
8. Click on Tag1 and check the Data Entry box in the floating toolbar.
• Alternatively, right-click and select Data followed by Data Entry.
9. Repeat this operation for Tag2.
Your display page should now look like Figure 14.
Next, right-click on the page and select Properties…
Referring to Figure 15, perform the following actions…
1. Select the Actions tab.
2. Enter Tag3++,Tag4++ in the On Update box.
3. Press OK to save the changes.
Next, navigate to the Web Server category…
Referring to Figure 16, perform the following actions…
1. Select the Features tab.
2. In the Remove View section, set the Remote Control property to enabled.
You have now created an outline database. Press F9 to download this to your device, and if this is the first time you are doing so, select the Send Time option from the Link menu to set the device’s time and time zone. If the device has a display, you should be able to see the five tags. You will be able to edit the first two tags using the touchscreen, and the next two will be incrementing steadily as the display updates.
If your device does not have a display, open your web browser. In the address bar, enter the http:// followed by the IP address that you have allocated to your device to access the Crimson web server. Within the Crimson web server, select Remote View to view the device’s virtual display and again note the behavior of the tags.
Step 8 - Configuring the Amazon Connector
We are now in a position to configure and test the Amazon Connector. We shall be configuring it to talk to the thing that we created in earlier sections and pushing four of the data tags that we have created. The fifth tag will be used to display the connection status. Start by returning to the Communications section and select the Amazon MQTT settings in the Connectors section…
Referring to Figure 17, perform the following actions…
1. In the Control section, set the Enable Agent property to Yes.
2. In the MQTT Server section, set the Host Name 1 property to the hostname from Step 6.
3. In the MQTT Server section, set the Client ID property to Thing01
4. In the TLS Security section, set the Certificate File to the file you downloaded in Step 5.
5. In the TLS Security section, set the Private Key File to the file you downloaded in Step 5.
6. In the TLS Security section, set the Server CA File to the file as described below.
7. In the Diagnostics section, set the Status property to Status
When setting the three files, navigate to the correct folder and Crimson should offer you only the files that are appropriate in that context. If you are dealing with many things, you should make sure you select the files that are associated with the thing to which this device will be talking.
The Server CA file is used to validate that Crimson is talking to the correct server. Amazon has recently updated their server certificates, and it is quite a complex task to find the one that is appropriate to the server to which you will be attaching. We thus recommend that you use a file that contains all the possible server certificates that you may encounter. You can download this file from here, or you can copy the text in Appendix A into a text file and save it with the PEM extension. For builds of Crimson including and after the January 2019 Feature Release, you may simply leave the field empty and allow Crimson to use the combined server certificate file by default.
Next, select the Tag Data 1 tab…
Referring to Figure 18, perform the following actions…
1. In the Control section, set the Tag Writes property to Enabled.
2. Select the Data Tags category of the Resource Pane.
3. Drag Tag1 through Tag4 into the Contents field in the Editing Pane.
You have now configured Crimson to push Tag1 through Tag4 to the cloud once per second. Press F9 to download the database to your device and check the Status tag on your display or via the web browser. A value of 4 should be displayed, indicating that the cloud connection has been established and that data is being pushed. A value of 0 typically indicates an issue with network connectivity or with DNS, while a value of 1 indicates that the server name was resolved but that the connection could not be established. A value of 3 indicates that the connection has been made, but that data has not been transferred. If you do not see a value of 4, check each item in this note carefully and ensure your Crimson configuration matches your AWS settings.
Step 9 - Interacting with the Device
Now that we have configured Crimson to pass data to the cloud, we can view this data from the Amazon web console and optionally write data back to the device. Return to the IoT Core web page within the console. If you are not already within Thing01, select the Manage option in the left-hand menu and select the Things option under that. Click on Thing01 to display its settings and properties, and select Shadow from the left-hand menu…
Referring to Figure 19, note that the shadow state contains live data representing the tags in your device. The shadow is a persistent object that stores the values sent by the device, whether or not those values are included in the latest message. If you scroll down a little, you will be able to view the shadow more clearly…
As you can see, the shadow is a JSON fragment contains an object called reported. Within this object, a further object called tags contains the data tags being pushed by Crimson, and an object called device acts as a placeholder for yet-to-be-supported device status information. Refer to the Crimson User Manual for details on how the format of this JSON fragment can be adjusted to suit your application.
To write data to the device, we must edit the JSON fragment to contain an object called desired that contains its own tags object that in turn contains the values that we want to write. To modify the shadow, select the Edit option within the AWS console and click on the Shadow State to make the changes…
It is very important that you get the formatting right when editing the shadow. JSON is particularly finicky about commas and other punctuation. The portion that you are creating is shown in red below…
[balance ommitted for brevity]
Note the comma at the end of line immediately before the reported object and note the absence of commas at the end of the other lines. JSON requires commas only when another element follows within the current object. If you get this wrong, a red cross should appear warning you of your error.
Once you have edited the JSON, press click Save to commit the change. The value of Tag1 in your device should be updated both on the device display and in reported object in the shadow, and the corresponding entry in the desired object should be removed. If this does not happen, check your formatting and check that you have writes enabled in the corresponding tag set.
Append A – Combined Server Certificates
It is the customer's responsibility to review the advice provided herein and its applicability to the system. Red Lion makes no representation about specific knowledge of the customer's system or the specific performance of the system. Red Lion is not responsible for any damage to equipment or connected systems. The use of this document is at your own risk. Red Lion standard product warranty applies.
Red Lion Technical Support
If you have any questions or trouble contact Red Lion Technical Support by clicking here or calling 1-877-432-9908.
For more information: http://www.redlion.net/support/policies-statements/warranty-statement