# CREATING AN AWS CONNECTION

# Creating a Connection

MQTT over TLS v1.2 connection is the transport protocol recommended by Amazon and its use is mandatory in ThingPark X IoT Flow to connect to AWS cloud platform. You need to create an instance of AWS connection first, before you can use it is an IoT Flow instance.

The creation of a connection establishes a bidirectional messaging transport link between ThingPark X IoT Flow and the cloud provider. Events and commands from multiple Devices will be multiplexed over this messaging transport link.

To do this, you need to use the “Connections” group resource:

  • POST/connections to create a new Connection instance
  • PUT/connections to update a Connection instance
  • DELETE/connections to delete a Connection instance

Note

We follow the REST-full API pattern, when updating configuration properties for a connection resource. Thus, you must also provide the whole configuration again.

Example for creation of a new connection instance :

POST /connections
 
{
"connectorId": "actility-aws-iot",
"name": "Test AWS Connection",
  "configuration": {
    "description": "AWS Europe Datacenter",
    "uplinkTopicPattern": "tpx/things/{DevEUI}/uplink",
    "downlinkTopicPattern": "tpx/things/{DevEUI}/downlink",
    "deviceType": "actilitytestsensor",
    "region": "eu-central-1",
    "accountPrefix": "a2shubactigr-ats",
    "secretAccessKey": "lymHcNdzddzerrZHnV5Q5YN/GTMFNiARtAj/7dz4358",
    "accessKeyId": "AKIAJUJWTO76B3XZGHYA",
    "certificateId": "arn:aws:iot:eu-central-1:101513775872:cert/8be79f58542e4f2345t45fgjb08424657ee1fea4554fa974",
    "certificate": "-----BEGIN CERTIFICATE-----xxx-----END CERTIFICATE-----",
    "privateKey": "-----BEGIN RSA PRIVATE KEY-----xxx-----END RSA PRIVATE KEY-----"
  }
}

The following table lists the properties applicable to a connection instance.

Property Configuration value
 
"connectorId"

Must be set to actility-aws-iot for AWS IoT cloud platform. 

"configuration/uplinkTopicPattern"

Defines a pattern of MQTT topic for Uplink messages.

Note

  • Ensure to be compliant with AWS topic semantics, e.g.:

    • tpx/things/{DevEUI}/uplink

For more information on available dynamic keywords, see the chapter about Keywords and patterns in the AWS documentation.

"configuration/downlinkTopicPattern"

    Defines a pattern of topic for the Downlink.

  • Ensure your pattern matches the AWS pattern

    e.g. tpx/things/{DevEUI}/uplink is matches AWS expression tpx/things/+/uplink

"configuration/deviceType"

AWS IoT Device type to be associated with the Devices processed by the connector. 

"configuration/region"

    Region of the AWS IoT datacenter:

  • eu-central-1 : EU(Frankfurt)
  • us-east-1 : US East (N. Virginia)
  • cn-north-1 : China (Beijing)

For more information see https://docs.aws.amazon.com/general/latest/gr/rande.html

"configuration/accountPrefix"

Account prefix of the AWS IoT account. 

"configuration/secretAccessKey"

Secret access key for accessing the AWS IoT account, required for registering Devices. 

"configuration/accessKeyId"

Id of the access key for accessing the AWS IoT account, required for registering Devices. 

"configuration/accessKeyId"

Id of the certificate registered in the AWS IoT account, required for registering Devices. 

"configuration/certificate"

Contents of the certificate file registered in the AWS IoT account, required for building the MQTT over TLS v1.2 connection. 

"configuration/privateKey"

Contents of the private key file registered in the AWS IoT account, required for building the MQTT over TLS v1.2 connection.

# Collecting Expected Information

# Account Prefix and Region

After you have created your AWS IoT account, you need to retrieve the parameter values that will be required to configure the AWS connector.

  1. Type :

https://eu-central-1.console.aws.amazon.com/iot/home?region=eu-central-1#/dashboard (opens new window) to open AWS IoT.

➡️ This looks like this:

img

  1. Click Settings.

➡️ This opens the page showing the Custom endpoint information. It looks like this:

img

Note

The Endpoint string has the following format accountPrefix.iot.region.amazonaws.com. If the accountPrefix does not end in ‘-ats’, follow the instructions for setting up your Amazon Trust Services (ATS) endpoint to avoid connection issues due to deprecated trust CAs. (opens new window)

  1. Copy the accountPrefix and region connector parameters (respectively 'a2shubp7zpiozr-ats' and 'eu-central-1' in the following example).

# Device Type

  1. Go back to the Manage section and click Types to access the list of Device types.

➡️ The page that opens displays all existing types of Devices. This looks like this:

img

  1. Click Create.

  2. In the Create a thing type’s page that displays type the name of the Device that you want to create, for example “demoType” This looks like this:

img

  1. Click Create thing type.

⮊ The Device type is created and appears in the Types’ page.

# Access Key Id and Secret Access Key

An Access key id and a Secret Access Key are required for the Device registration. To retrieve this information you must create a user.

  1. Click Services in the Banner.

  2. Click the (Identity and Access Management)IAM link as shown in the following capture.

img

  1. In the dashboard page that opens, click Users. This looks like this:

img

  1. Click Add user.

  2. In the Add user’s page that opens type a Username and select the Programmatic access as shown in the following capture:

img

  1. Click Next Permissions.

  2. In the Set Permissions’ page that opens click Attach existing policies directly as shown in the following capture:

img

  1. Click Create policy.

  2. In the Create Policy’s page that opens select the policies that you are interested in either by using the Visual Editor or the JSON editor as shown in the following capture.

Note

In this release the minimum rights that are granted to the policies are the following actions:

  • iot:ListThings
  • iot:CreateThing
  • iot:AttachThingPrincipal
    1. Creating the new policy using the Visual Editor is shown in the following capture.

img

    1. Creating the new policy using JSON format:Copy the JSON body and paste it in the JSON Editor.
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "iot:ListThings",
                "iot:CreateThing",
                "iot:DescribeThing",
                "iot:AttachThingPrincipal",
                "iot:Connect",
                "iot:Subscribe",
                "iot:Receive",
                "iot:Publish"
            ],
            "Resource": "*"
        }
    ]
}

This looks like this in the Editor:

img

  1. Click Review policy.

  2. In the Review page that opens click Create Policy.

img

  1. Close the Policy tab.

  2. On the Add user page, click Refresh.

  3. Select the policy that you created and click Next Tag as shown in the following capture:

img

  1. Leave the Tags’ pages as is and further click Next:Review until the Create User page displays as shown in the following capture.

img

  1. Click Create User.

➡️ A screen informing that you created the user displays.

In this screen, copy the Access key ID and the Secret access key or download those via the csv file as shown:

img

  1. Click Close.

# Certificate and Policy

A certificate is required for the registration of the TLS connection protocol (MQTT over TLS v1.2 connection) and the Device.

  1. Go to the dashboard and open the Certificates’ page.

  2. Click Create as shown in the following capture.

img

  1. In the Create a Certificate’s page, choose “One-click certificate creation (recommended)”.

  2. Click Create certificate.

  3. In the Certificate created! page that opens download the certificate file and the associated private key. You should see a page that looks like this.

img

  1. Click Activate.

  2. Click Attach a policy.

  3. In the Add authorization to certificate’s page that opens click Create new Policy.

img

  1. In the Create a policy’s page that opens type the policy name type a Name as displayed in the following capture.

  2. Set the actions that you have previously defined in Access Key Id and Secret Access Key
    That is:

  • iot:Publish
  • iot:Subscribe
  • iot:Connect
  • iot:Receive

img

Note

More actions can be added if Device Shadows are used or iot:*. All these actions can include all of them (temperature/luminosity/humidity).

  1. Add Statements, if need be.

  2. Click Create.

  3. Go back to the Certificates’ page and select your newly created certificate as illustrated in the following capture.

img

  1. Copy the certifiedId and put it in the connector’s properties as shown in Creating a connection That is:

img

  1. In the Actions’ menu select Attach policy and the policy that you previously created. This is shown in the following capture.

img

  1. Click Attach.

# Limitations

MQTT over TLS v1.2 connection is the recommended protocol by Amazon and is mandatory for use with ThingPark X IoT Flow.
Device shadows are not supported in the current ThingPark X IoT Flow release.
Uplinks are sent using QoS 0.
The Uplink rate is limited to 1000 msg/s max (connection pool can have max 10 mqtt clients).
The Downlink rate limited to 100 msg/s.
The number of Devices that you can use is unlimited.
For more information, see the following links:

  1. https://docs.aws.amazon.com/general/latest/gr/aws_service_limits.html#limits_iot Messages are not stored in the AWS cloud. If the connection has not been established during a short time, all downlink messages cannot flow to ThingPark, they are lost. This message is displayed: “The message broker maintains a list of all client sessions and the subscriptions for each session. When a message is published on a topic, the broker checks for sessions with subscriptions that map to the topic. The broker then forwards the publish message to all sessions that have a currently connected client.”

  2. https://docs.aws.amazon.com/iot/latest/developerguide/iot-message-broker.html
    This means that disconnected clients will not receive any uplinks/downlinks that were sent during the time they were offline. Things could change in the future AWS SDK for Java:
    https://docs.aws.amazon.com/iot/latest/developerguide/mqtt-persistent-sessions.html

# Displaying information to know if it worked

  1. Go to your AWS account, open the Test menu.
  2. Check if you are connected to the right endpoint (On the right of the window).
  3. Subscribe to a topic, for example: tpx/things/78AF580300000345/uplink

You should see something like that:

img

All received messages are displayed on the same window.

img

Last Updated: 1/18/2021, 10:22:26 AM

← Connecting to AWS GreenGrass →