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 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 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

The above URL is an example, and the us-east-1 part of the URL may vary depending on the geographical location.

📘

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 shadows. Here are 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 - subscribed to only one of the AWS predefined topics explained here.

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.

🚧

Topics that begin with a dollar sign ($) are reserved for use by AWS IoT. You can subscribe and publish to these reserved topics as they allow; however, you can't create new topics that begin with a dollar sign. Unsupported publish or subscribe operations to reserved topics can result in a terminated connection.

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:

📘

When the get option is selected, the publisher will publish a shadow get request to AWS IoT Core, which will return all information of the requested device, if the request is accepted by AWS IoT Core.

5. 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.

📘

When the get option is selected, the subscriber component will subscribe to <device>/shadow/get/accepted and <device>/shadow/get/rejected, which AWS IoT responds to following receipt of a shadow get request. See here for further explanation of AWS IoT Core shadow behavior.

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 timer1 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.