Skip to content

Legacy AWS IoT Connector

Overview

This section provides a guide on connecting an ESF device to the Amazon AWS IoT platform using the legacy procedure.

Prerequisites

  • In order to connect a device to Amazon AWS IoT ESF version 3.3.0 or greater is required.
  • An Amazon AWS account is also needed.

Device registration

The first step involves the registration of the new device on AWS.

A guide on how to provision a Thing to AWS IoT is available here

Device configuration

The following steps should be performed on the device.

  1. Configure the SSL parameters.

1.1. Access the ESF Web UI Console, select the Settings entry in the left side menu and then click on SSL Configuration. Set Default protocol to TLSv1.2

1.2. Download to your local system the AWS CA available here and open it with your preferred text editor.

Select the Settings entry in the left side menu and then click on Server SSL Certificate.

Add a proper name for the certificate in the Storage Alias field and paste the Certificate in the proper area. Then click on the Apply button.

1.3. Open the ESF Web Console and enter select the Settings entry in the left side menu and then click on Device SSL Certificate, you should see this screen:

048d9f1-ESF_Device-SSL-Certs.png

Enter aws-ssl in the Storage Alias field.

1.4. The private key needs to be converted to the PKCS8 format, this step can be performed executing the following command on a Linux or OSX based machine:

openssl pkcs8 -topk8 -inform PEM -outform PEM -in xxxxxxxxxx-private.pem.key -out outKey.pem -nocrypt

where xxxxxxxxxx-private.pem.key is the file containing the private key downloaded at step 4.

1.5. Paste the contents of the obtained outKey.pem in the "Private Key" field.

1.6. Paste the contents of xxxxxxxxxx-certificate.pem.crt in the Certificate field.

1.7. Click the Apply button to confirm.

Restart ESF to reload the keystore.

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

1686e8a-ESF_CloudService.png

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

  • Factory -> org.eclipse.kura.cloud.CloudService
  • Cloud Service Pid -> org.eclipse.kura.cloud.CloudService-AWS

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

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

The mqtts protocol must be used, the value for the broker-url field derived from the URL above is the following: 

mqtts://a1rm1xxxxxxxxx.iot.us-east-1.amazonaws.com:8883/

2.3. Clear the value of the username and password fields.

2.4. Set a value for the topic.context.account-name and client-id.

  • Assign an arbitrary account name to topic.context.account-name (for example aws-test), this will be used by the CloudClient instances for building the topic structure.

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

2.5. In order for the previously added keys to be used for the SSL connection with the broker enter the Storage Alias defined in step 7.2 (e.g aws-ssl) as value for the ssl.certificate.alias field.

2.6. The setting lwt.topic under MqttDataTransport-AWS needs to be updated as well by entering a value not containing the $ character. This is required because of the fact that AWS IoT does not support topic names starting with $ (except for the $aws/ hierarchy).

2.7. Press the Apply button in the top left section to commit the changes to the MqttDataTransport-AWS.

2.8. Enter a name without the $ character for the topic.control-prefix setting in the CloudService-AWS tab, for example aws-control.

2.9. The ESF CloudService uses some well-known topics to allow remote device management and to report device state information, this features are not supported by default by AWS IoT, the following settings can be applied in the CloudService-AWS tab in order to avoid sending unnecessary messages:

  • republish.mqtt.birth.cert.on.gps.lock -> false
  • republish.mqtt.birth.cert.on.modem.detect -> false
  • enable.default.subscriptions -> false
  • birth.cert.policy -> Disable publishing

2.10. Click the Apply button to save the changes.

  1. Make sure the AWS CloudService instance is selected from the list in tho 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.

ESF CloudService uses the Kura protobuf format for payload encoding, and performs payload compression to reduce message size. For this reason it will not be possible to immediately visualize published message content using AWS console. It is possible to disable payload compression and switch to the JSON format by setting the following parameters in the CloudService-AWS tab:

  • encode.gzip -> false
  • payload.encoding -> Simple JSON