AWS IoT Integration

Overview
AWS IOT
- Create Policy
- Create Things and Certificates
ThingsBoard setup
Advanced usage: Create Downlink Converter
Video tutorial
Next steps

Overview

AWS IoT Integration allows to stream data from AWS IoT Backend to ThingsBoard and converts device payloads to the ThingsBoard format. AWS IoT will be primarily responsible for receiving all messages (as a broker - messaging server), filtering them, deciding who is interested, and then sending the message to all subscribers, in our case of integration.

AWS IOT

You should already have an AWS account prepared, on which perform a few settings. To establish a correct and secure connection between the service and ThingsBoard, you need to create Policies, devices, and certificates for them.

Create Policy

A policy is an object in AWS that, when associated with an entity or resource, defines their permissions. Permissions in the policies determine whether the request is allowed or denied. Most policies are stored in AWS as JSON documents.

To add a new policy, choose Security - Policies in the main menu, and select the Create Policy button.

You will be redirected to the policy creation page, where you must specify the Policy Name and switch to JSON type.

In the field for the Policy document, you need to paste the code below with your unique profile ID.

For example of policy document:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iot:Publish",
        "iot:Receive"
      ],
      "Resource": [
        "arn:aws:iot:YOUR_REGION:YOUR_AWS_ID:topic/*"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "iot:Subscribe"
      ],
      "Resource": [
        "arn:aws:iot:YOUR_REGION:YOUR_AWS_ID:topicfilter/*"
      ]
    },
    {
      "Effect": "Allow",
      "Action": [
        "iot:Connect"
      ],
      "Resource": [
        "arn:aws:iot:YOUR_REGION:YOUR_AWS_ID:client/*"
      ]
    }
  ]
}

Your region is listed in the URL when you are signed in to your AWS IoT account.
For example: https:// eu-west-1 .console.aws.amazaon.com

After that, click the Create button. The policy will be added to the list, and you will receive the Successfully created policy tb_policy message.

Create Things and Certificates

A Thing is a digital representation of a physical device or logical entity in AWS IoT.

You can create a conditional device in several steps, but for it need to go to the appropriate section. On the left, choose the All devices category - then Things item. This page will display all your devices if you don’t have them yet. At the top right, select the Create thing button to proceed to adding a device.

Consider the example of adding a single device, select the corresponding option the Create single thing, and then Next button.

In the first stage, we will set the Name for the device, and at your discretion, additional parameters. Then press the Next button to move to the following step.

At this stage, select the Auto-generate a new certificate. Certificates and keys will be available for download after confirming the addition of the device, so just click the next button.

At the last stage, select your previously added policy and confirm the creation of a thing (device) with the Create thing button.

Upon completion, you will see an additional window with the possibility to download certificates and keys.

The list of files that are required to configure the integration:

Device certificate (*.pem.crt)
Private key (*-private.pem.key)
Root CA certificate (*.pem)

AWS additionally requires you to save your Public key file for yourself, so please download that as well.

After saving the required, click the Done.

ThingsBoard setup

Create Uplink Converter

Before creating the integration, you need to create an Uplink converter in Data converters. Uplink is necessary in order to convert the incoming data from the device into the required format for displaying them in ThingsBoard. Click on the “plus” and on “Create new converter”. To view the events, enable Debug. In the function decoder field, specify a script, for it copy the example Uplink converter, or use own configuration to parse and transform data.

One can use either TBEL (ThingsBoard expression language) or JavaScript to develop user defined functions. We recommend utilizing TBEL as it’s execution in ThingsBoard is much more efficient compared to JS.

TBELRecommended

JavaScript

Example for the Uplink converter:

// decode payload to JSON
var data = decodeToJson(payload);
var topicParts = metadata.topic.split("/");
var deviceType = topicParts[0];
var deviceName = topicParts[1];
// Result object with device attributes/telemetry data
var result = {
   deviceName: deviceName,
   deviceType: deviceType,
   attributes: {
       state: data.val0,
   },
   telemetry: {
       temperature: data.val1,
       fan_ins: data.val2,
       fan_out: data.val3,
   }
};

return result;

Example for the Uplink converter:

// decode payload to JSON
var payloadStr = decodeToString(payload);
var data = JSON.parse(payloadStr);
var topicParts = metadata.topic.split("/");
var deviceType = topicParts[0];
var deviceName = topicParts[1];
// Result object with device attributes/telemetry data
var result = {
   deviceName: deviceName,
   deviceType: deviceType,
   attributes: {
       state: data.val0,
   },
   telemetry: {
       temperature: data.val1,
       fan_ins: data.val2,
       fan_out: data.val3,
   }
};
/** Helper functions **/

function decodeToString(payload) {
    return String.fromCharCode.apply(String, payload);
}
function decodeToJson(payload) {
   // covert payload to string and then parse string to JSON
   return JSON.parse(decodeToString(payload));
}
return result;

You can change the decoder function while creating the converter or after creating it. If the converter has already been created, then click on the “pencil” icon to edit it.

Create Integration

Go to Integrations section and click Add new integration button. Name it “AWS IoT Integration”, select type AWS IoT.

The next steps is to add the recently created Uplink converter.

For now, leave the “Downlink data converter” field blank.

Enter AWS IoT Endpoint. You can find it in your AWS account if you go to Settings - Device data endpoint.

Download the previously generated certificates and key.

Add a Topic Filter tb/aws/iot/#. You can also select QoS level. We use QoS level 0 (At most once) by default.
Click Add to create an integration.

Send Uplink message

To send a test message, use the additional functionality of AWS IoT, the MQTT test client. In the main menu, go to MQTT test client, then select the Publish to a topic tab.

Example of topic:

tb/aws/iot/sensors/freezer-432

Example of payload:

{
    "val0": "loaded",
    "val1": -18,
    "val2": 1785,
    "val3": 548
}

To check if the message has arrived at AWS IoT integration open the events tab of integration.

Advanced usage: Create Downlink Converter

Let’s look at a simple example to test a connection and send a message. For it need to create a downlink Data converter. Then set the converter and topic in the AWS IoT integration.

TBELRecommended

JavaScript

An example of downlink converter:

// Encode downlink data from incoming Rule Engine message

// msg - JSON message payload downlink message json
// msgType - type of message, for ex. 'ATTRIBUTES_UPDATED', 'POST_TELEMETRY_REQUEST', etc.
// metadata - list of key-value pairs with additional data about the message
// integrationMetadata - list of key-value pairs with additional data defined in Integration executing this converter

/** Encoder **/
var data = {};

// Process data from incoming message and metadata
data.v0 = msg.state;
data.m0 = "att_upd_success";
data.devSerialNumber = metadata['ss_serialNumber'];

// Result object with encoded downlink payload
var result = {
    // downlink data content type: JSON, TEXT or BINARY (base64 format)
    contentType: "JSON",
    // downlink data
    data: JSON.stringify(data),
    // Optional metadata object presented in key/value format
    metadata: {
            type: "sensors/device/upload"
    }
};
return result;

An example of downlink converter:

// Encode downlink data from incoming Rule Engine message

// msg - JSON message payload downlink message json
// msgType - type of message, for ex. 'ATTRIBUTES_UPDATED', 'POST_TELEMETRY_REQUEST', etc.
// metadata - list of key-value pairs with additional data about the message
// integrationMetadata - list of key-value pairs with additional data defined in Integration executing this converter

/** Encoder **/
var data = {};

// Process data from incoming message and metadata
data.v0 = msg.state;
data.m0 = "att_upd_success";
data.devSerialNumber = metadata['ss_serialNumber'];

// Result object with encoded downlink payload
var result = {
    // downlink data content type: JSON, TEXT or BINARY (base64 format)
    contentType: "JSON",
    // downlink data
    data: JSON.stringify(data),
    // Optional metadata object presented in key/value format
    metadata: {
            type: "sensors/device/upload"
    }
};
return result;

Next, configure the conditions under which a message will be sent through the AWS IoT Downlink integration. To do this, you need to open the Rule Chain used for the device (in our case, the default Root Rule Chain), then add an integration downlink node, for link condition set the Attributes Updated.

To subscribe to a topic for receive messages from Thingsboard, use the AWS MQTT test client.

Now you can update the device attribute. To do this, open Device, Attributes tab, and choose Shared Attributes, then select any attribute, or add a new one to update it.

The result can be tracked on AWS page where you subscribed to the topic:

Video tutorial

See video tutorial below for step-by-step instruction how to setup AWS IoT Integration (Outdated interface).

Next steps

Getting started guides - These guides provide quick overview of main ThingsBoard features. Designed to be completed in 15-30 minutes.
Data visualization - These guides contain instructions on how to configure complex ThingsBoard dashboards.
Data processing & actions - Learn how to use ThingsBoard Rule Engine.
IoT Data analytics - Learn how to use rule engine to perform basic analytics tasks.
Hardware samples - Learn how to connect various hardware platforms to ThingsBoard.
Advanced features - Learn about advanced ThingsBoard features.