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 and to AWS Greengrass. Furthermore, out-of-the-box, it supports Classic Device Shadows and Named Device Shadows. This allows ESF Assets to map to AWS IoT Core or to AWS Greengrass seamlessly.

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 Connections

The ESF Cloud Connector for AWS IoT Core provides two cloud connection factories:

• com.eurotech.framework.aws.mqtt.cloudconnection.AwsCloudEndpoint: allows the user to provide the configuration parameters and connect to AWS IoT Core and AWS Greengrass
• com.eurotech.framework.aws.mqtt.CoreDeviceDiscoveryCloudEndpoint: allows ESF to act as an AWS Thing to discover a Greengrass Core device to connect to as a gateway. When using this service, the ESF Gateway will negotiate with AWS and find a Greengrass core device based on the parameters passed to the service.

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

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.

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.

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. Update the keep-alive parameter. This value specifies the frequency (in seconds) for the periodic MQTT PING message

8. Update the timeout parameter. This value specifies the timeout (in seconds) used for all the interactions with the MQTT broker

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

CoreDeviceDiscoveryCloudEndpoint 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.CoreDeviceDiscoveryCloudEndpoint
• Cloud Service Pid -> com.eurotech.framework.aws.mqtt.CoreDeviceDiscoveryCloudEndpoint

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 with Core Device Discovery.

CoreDeviceDiscoveryCloudEndpoint Configuration

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

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

CoreDeviceDiscoveryService Configuration

The CoreDeviceDiscoveryService tab provides the following parameters. The input to these parameters is generated when a new AWS Thing is created from the AWS web console.

• Enabled: Enables or Disables the CoreDeviceDiscoveryService
• AWS Region: Aws region used for Greengrass.
• Thing Name: Name of the AWS Thing created in IoT Core.
• Device Certificate: Certificate of the AWS Thing created in IoT Core.
• Device Private Key: The private key for the AWS Thing created in IoT Core.
• Amazon CA Certificate: The CA certificate for AWS. Used to authenticate connections to Amazon's Cloud Platform.
• Keep-alive: This value specifies the frequency (in seconds) for the periodic MQTT PING message
• Timeout: This value specifies the timeout (in seconds) used for all the interactions with the MQTT broker
• LWT Topic: MQTT Last Will and Testament topic

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.

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.

1. Select the shadow.get.subscriber and set its CloudSubscriber.target to the pid of the shadow.get.subscriber instance created previously.
2. Select the logger1 instance and set its log.verbosity to VERBOSE to log all information received from AWS IoT Core for this device.
3. 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.
4. Connect the timer1 output to the shadow.get.publisher input and connect the shadow.get.subscriber output to the logger1 input.
5. Click the Apply button to save the changes.

Subscriber Wire Record Metrics

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

Raw MQTT Message Metric

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.