ESF Cloud Connector for AWS IoT Core

The ESF Cloud Connector for AWS IoT Core is a specific ESF Cloud Connector based on the AWS IoT SDK v2.0.
This connector uses the ESF APIs and the AWS IoT SDK to simplify the application development and connectivity to AWS IoT Core. Furthermore, it supports out of the box Classic Device Shadows and Named Device Shadows, allowing the mapping of ESF Assets to AWS IoT Core in a seamless end-to-end integration.

🚧

The ESF Cloud Connector for AWS IoT Core is available for ESF 6.1.0+ only.

Installation

The following steps should be performed on the device:

Install the new ESF Cloud Connector for AWS IoT Core in the Packages tab.

1. Click on Packages in the left panel, you should see this screen:

1.1. Drag the ESF Cloud Connector for AWS IoT Core deployment package from the Eclipse Marketplace™ to this window.

Cloud Connection Creation

1. Click on Cloud Connections in the left panel, you should see this screen:

1.1. Click on the New Connection button at the top of the page and set the following parameters in the dialog:

• Factory -> com.eurotech.framework.aws.mqtt.cloudconnection.AwsCloudEndpoint
• Cloud Service Pid -> com.eurotech.framework.aws.mqtt.cloudconnection.AwsCloudEndpoint-AWS

Press the Apply button to confirm and then select the newly created CloudService instance from the list.

Configuration

The following steps are needed to properly configure the just created AWS Cloud Connection.

MqttDataTransport Configuration

1. Set the broker URL in the MqttDataTransport-AWS tab, it can be obtained from the AWS IoT Web Console clicking on the Settings entry in the bottom left section of the page, the URL will look like the following:

a1rm1xxxxxxxxx.iot.us-east-1.amazonaws.com

📘

A secure connection to the AWS IoT Core broker is established by default.
The AWS IoT Core service does not support unencrypted connections.

2. Set a value for the client-id field.

• Enter the thing name in the client-id field (in this example kura-gateway).

3. Ensure the setting for lwt.topic under MqttDataTransport-AWS does not contain the $ character. This is required because of the fact that AWS IoT Core does not support topic names starting with $ (except for the $aws/ hierarchy).

📘

The following steps use the keys and certificates generated during the provisioning phase in AWS IoT Core service.

4. Enter the xxxxxxxx.certificate.pem.crt certificate to the Device Certificate field.
5. Enter the xxxxxxxx.private.pem.key private key to the Device Private Key field.
6. Copy the AWS CA available here to the Broker CA Certificate field.

7. Press the Apply button in the top left section to commit the changes.

AwsDataService Configuration

Please refer to the DataService Configuration page to get more details on the configuration parameters available for this service.
Make the use-case specific changes to the service and click the Apply button to save them.

AwsCloudEndpoint Configuration

It is possible to change the gzip payload compression by changing the value of the encode.gzip parameter. This property defaults to false.

Connect Device

Make sure the AWSCloudEndpoint instance is selected from the list in the top section of the page and click on the Connect button, if the connection to AWS IoT platform succeeds the Status of the instance will be reported as Connected.

Managing Publishers and Subscribers

This custom connection to the AWS IoT Core service contains specific subscribers and publishers with their own distinct behavior.

• ThingPublisher - specific for telemetry data. It allows the user to specify the target topic for the data managed by this subscriber.
• ShadowPublisher - specific publisher for AWS Thing classic and named shadows. Here more references to the possible shadow operations supported by this publisher.
• ThingSubscriber - a generic subscriber component that allows to subscribe to configurable MQTT topics.
• ShadowSubscriber - subscribes to the predefined AWS shadow topics as explained here.

Shadow Topics

Shadow topics are limited and defined by AWS (see here for more information). These tables lists the topics used by the shadow publisher and subscriber.

Shadow Publisher

Shadow Subscriber

Creating and Managing ThingPublisher and ThingSubscriber

1. From the Cloud Connections tab in the left panel, select the AWS connection and then click on the New Pub/Sub at the top of the page.
2. Select the com.eurotech.framework.aws.mqtt.cloudconnection.publisher.AwsThingPublisher from the drop-down. Give a unique name to the publisher instance in the New Publisher/Subscriber PID field, such as thing.publisher, then click the Apply button to create the AwsThingPublisher.

3. Click on the New Pub/Sub button again and select the com.eurotech.framework.aws.mqtt.cloudconnection.subscriber.AwsThingSubscriber from the drop-down. Give a unique name to the subscriber instance in the New Publisher/Subscriber PID field, such as thing.subscriber, then click the Apply button to create the AwsThingSubscriber.
4. Select the thing.publisher instance and define a topic to publish to, e.g. test-topic. With this publisher the user can also decide the publishing QoS. By default the publisher sets the QoS to 0.
5. Select the thing.subcriber instance and define a topic to subscribe to. This will be any message sent from the AWS IoT Core broker filtered by this defined topic. Let's use the wildcard # under our published topic, e.g. test-topic/#. This will receive any sub-topic under the test-topic topic.

❗️

AWS Reserved Topic Starting Character

Do not attempt to publish or subscribe to any topic beginning with the $ identifier. This will result in a terminated connection by the AWS IoT Core broker since this is considered a reserved identifier by AWS IoT Core.

❗️

Reserved Topics

Do not attempt to publish to any of the following topics using the Thing publisher. This will erroneously identify your message as a Shadow message instead of a Thing message and lead it to being published on the reserved shadow topics with undefined behavior.

".+" represents 1 or more of any character(s)

• shadow/get
• shadow/update
• shadow/delete
• shadow/name/.+/get
• shadow/name/.+/update
• shadow/name/.+/delete

Device Shadow Management

AWS IoT Core maintains a "shadow" for each device registered to its service. More information on device shadows can be found here.

1. Follow the same procedure as in previous paragraph to create a new shadow publisher and subscriber.
2. Select the com.eurotech.framework.aws.mqtt.cloudconnection.publisher.AwsShadowPublisher from the drop-down. Give a unique name to the shadow publisher instance in the New Publisher/Subscriber PID field, such as shadow.publisher, then click the Apply button to create the AwsShadowPublisher.
3. Select the com.eurotech.framework.aws.mqtt.cloudconnection.subscriber.AwsShadowSubscriber from the drop-down. Give a unique name to the shadow subscriber instance in the New Publisher/Subscriber PID field, such as shadow.subscriber, then click the Apply button to create the AwsShadowSubscriber.
4. When selecting the shadow.publisher instance, as depicted in the following image, the user can configure the shadow topic from the available options:

See the section Shadow Topics above for the specific topics each function subscribes to.

5. Enter a Shadow Name if desired. Classic shadows will be used if Shadow Name is left blank.

6. Select the shadow.subscriber instance and define the shadow topic for the device to subscribe to. Once again, this is a predetermined list understood by AWS IoT Core. Select the get option from the drop-down.

See the section Shadow Topics above for the specific topics each function subscribes to.

7. Enter a Shadow Name if desired. Classic shadows will be used if Shadow Name is left blank.

Initiate MQTT Traffic from Device

An efficient way to communicate with a cloud platform in ESF is by creating components in ESF Wires to send and receive MQTT data.

1. Click on Wire Graph in the left panel of the ESF Admin Webpage, you should see this screen:

2. Select the Timer component and add to the graph. Give this timer component a unique name, e.g. timer1.
3. Select the Publisher component and add to the graph. This will be an AwsShadowPublisher so give this a unique name for the shadow topic that will be published to, e.g. shadow.get.publisher.
4. Select the Subscriber component and add to the graph. This will be an AwsShadowSubscriber so give this a unique name for the shadow topic subscribing to, e.g. shadow.get.subscriber.
5. Select the Logger component and add to the graph. This will be for the shadow.get.subscriber to notify when a message is received on the specified AWS shadow get response topic. Give the logger a unique name, e.g. logger1.
6. Select shadow.get.publisher and set its CloudPublisher.target to the pid of the shadow.publisher instance created previously.
7. Set the publish.position to Basic to publish the basic information of our device to AWS IoT Core.

8. Select the shadow.get.subscriber and set its CloudSubscriber.target to the pid of the shadow.get.subscriber instance created previously.
9. Select the logger1 instance and set its log.verbosity to VERBOSE to log all information received from AWS IoT Core for this device.
10. The timer interval default to interrupting every 10 seconds, that should be fine for these purposes but you can change the interval by selecting timer1 and changing the simple.interval period. It is highly recommended NOT to change the interval type from SIMPLE.
11. Connect the timer1 output to the shadow.get.publisher input and connect the shadow.get.subscriber output to the logger1 input.
12. Click the Apply button to save the changes.

📘

You may disconnect the Timer output from the Publisher input at any time to stop publishing to listeners. You may also create multiple Publisher and Subscriber instances and connect them to the respective components to publish or subscribe to multiple topics.

Subscriber Wire Record Metrics

Several metrics are available in the wire records produced by the subscribers.

Raw MQTT Message Metric

📘

ESF 7.0.0 or Greater Only

The Raw MQTT Message Metric feature is only available in ESF version 7.0.0 or greater.

📘

Wire Graph Only

The Raw MQTT Message Metric is only available when using the subscriber in the Wire Graph.

Thing subscribers (but not shadow subscribers) can output the raw MQTT message that was received as a wire record metric. To enable this:

1. Select the thing subscriber on the Wire Graph
2. Enter a metric name into the Set property from message body property. This will be the metric name used in the wire record.
3. Set Body property type to String.
4. Apply the changes

The raw MQTT message that was received will now be output in the wire record as a metric with the name entered into the Set property from message body.

📘

The Set property from message body property is only available when selecting a subscriber wire graph component. This property will not be shown in the subscriber properties on the cloud connections page.