ESF AWS Cloud Endpoint

The ESF AWS Cloud Endpoint 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.

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
   

   Hint

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

2. Enter the thing name in the client-id field (in this example kura-gateway). This will replace {thing_name} in the message topics (see Supported AWS Device Shadow MQTT Topics)

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

4. Enter the xxxxxxxx.certificate.pem.crt certificate to the Device Certificate field.

   Hint

   This step uses the keys and certificates generated during the provisioning phase in AWS IoT Core service. See section Single Thing Provisioning for reference.

5. Enter the xxxxxxxx.private.pem.key private key to the Device Private Key field.

   Hint

   This step uses the keys and certificates generated during the provisioning phase in AWS IoT Core service. See section Single Thing Provisioning for reference.

6. Copy the AWS CA 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

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. See Using device Shadows for 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.

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 at AWS IoT Device Shadow service.

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 Supported AWS Device Shadow MQTT Topics 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 Supported AWS Device Shadow MQTT Topics 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.

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.