With this connector, you can connect the DPS with your AWS IoT Core, allowing to:

• Receive data of your products connected to the AWS IoT Core broker.
• Send configuration parameters update or execute commands passing through the AWS IoT Device Shadow service.
• Perform firmware update by using the AWS IoT Core Jobs service.

Configuring the Connector

Once you have enabled the connector, you must go to your AWS IoT core administration page and configure a Message Routing rule.

A rule requires specifying the event to be listened, by defining a select statement which is applied on the incoming messages.

SQL statement
SELECT *, topic() as topic FROM '#'

Then within the rule, you must configure an action, and by default you can use the HTTPS Endpoint action, which requires the endpoint and an authorization header.  

Endpoint URL
https://aws-iot-core.servitly.com/data

Headers
Authorization: Basic Base64(<API_KEY>:<SECRET_KEY>)

API_KEY and SECRET_KEY are the public and secret keys of the API key configured in the AWS IoT Core plugin in Servitly.

Each time a message arrives to the AWS IoT Core, the endpoint is called by passing to it the event body.

AWS IoT Core MQTT Test Client

AWS IoT Core Event Body

{
  "ts": 1684165930999,
  "topic": "test-001/data",
  "data": {
    "temp": 25
  }
}

The topic used to post messages must be consistent with the thing mapping, otherwise the message is discarded. The topic must be in these formats:

<THING_ASSET_ID>/<METRIC_MAPPING_PATH>

<THING_ASSET_ID>/<THING_MAPPING_PATH>/<METRIC_MAPPING_PATH>

In the case, the topic or the payload are not compatible with Servitly, you can use an AWS Lambda function to convert them and finally invoke the Servitly data endpoint. 

Adapting Messages

In the case, your devices are already publishing data to the AWS IoT Core, but the topic and payload formats are not compatible with Servitly.

Within the Message Routing rule, you can reference an AWS Lambda function. Within the function is up to you to convert the topic and payload in order to be compliant with Servitly.

Here is an example of AWS Lambda you can use as a starting point. Note that, this example is based on NodeJS, and uses CommonJS modules, so you need to configure the index.js file instead of the *.mjs, which is based on ES modules.

const https = require('https');

exports.handler = async (payload, context) => {
    try {
        // console.debug(JSON.stringify(payload));
        let topic = payload.topic;
        let assetId = topic.substring(0, topic.indexOf("/"));
        let path = topic.substring(topic.indexOf("/") + 1);

        // Convert here the TOPIC and PAYLOAD

        await forwardData(assetId, path, payload, context);
    }catch (error) {
        console.error(error);
        context.fail(error);
    }

    function forwardData(assetId, path, payload, context) {
        // console.debug("ASSET_ID " + assetId);
        // console.debug("PATH " + path);
        // console.debug("PAYLOAD " + JSON.stringify(payload));

        const options = {
            hostname: 'aws-iot-core.servitly.com',
            path: '/data?assetId=' + assetId + "&path=" + encodeURIComponent(path),
            method: 'POST',
            port: 443,
            headers: {
                'Content-Type': 'application/json',
                'Authorization': 'Basic Base64('<API_KEY>:<API_SECRET>')'
            },
        };

        return new Promise((resolve, reject) => {
            const req = https.request(options, res => {
                if (res.statusCode < 300) {
                    resolve(res);
                } else {
                    reject(new Error("Error status " + res.statusCode));
                }
            });
            req.on('error', err => {
                reject(new Error(err));
            });
            req.write(JSON.stringify(payload));
            req.end();
        }).then(response => {
            // console.debug("Forward data completed " + response.statusCode);
            context.succeed();
        }).catch(error => {
            console.error("Forward data error " + JSON.stringify(error));
            context.fail(error);
        });
    }

};

AWS IoT Core Access

In order to send data to your AWS IoT Core connected devices, you need an AWS Access Key (to be configured in the AWS IoT Core plugin).

1. In the AWS account, an AWS IAM User must be set up with the policies described below.
2. For the IAM User, you must create an Access Key.
3. In the AWS IoT Core plugin, you need to enter the ID and Secret of the Access Key you created.

For more details about IAM users management, you can refer to this AWS guide.

IAM Identity Policies

AWS IoT Device Shadow

This policy is required to allow the AWS IoT Core plugin to invoke the Device Shadow API when a configuration parameter is updated or a command is executed. 

{
  "Version": "2012-10-17",     
  "Statement": [
     {
       "Effect": "Allow",
       "Action": "iot:UpdateThingShadow",
       "Resource": "arn:aws:iot:*:<aws-account-id>:thing/*"
     }
  ]
} 

AWS IoT Core Jobs

This policy is required to allow the AWS IoT Core plugin to invoke the Jobs API when a firmware update must be performed on the remote devices. 

{
  "Version": "2012-10-17",     
  "Statement": [
     {
       "Effect": "Allow",
       "Action": "iot:CreateJob",
       "Resource": [
         "arn:aws:iot:*:<aws-account-id>:thing/*",
         "arn:aws:iot:*:<aws-account-id>:job/*"
       ]
     }
  ]
}

Each plugin update may take a few minutes before it is propagated and used by the connector. 

Mapping Things

With the AWS IoT Core plugin enabled and configured, now you can start mapping DPS registered things to this new connector.

1. Enter the DPS application.
2. Select a thing you want to map.
3. Switch to the Connection tab.
4. Select the AWS IoT Core in the Connectors selection.
5. Provide the Asset ID, which must be that same used in the AWS IoT Core to register the device.
6. Press Save and wait a few minutes for the new mapped object to be detected and for data to start arriving.

Plugin Configuration

1. Go to the Integrations / Plugins page.
2. Select the IoT Connectors category.
3. Locate the AWS IoT Core card.
4. Click on the card switch to activate the plugin.
5. Configure the plugin properties and save.

Here is the list of all the properties that can be used in the plugin configuration.