AWS IoT Integration

Overview
Create Uplink Converter
AWS IOT
- Create Policy
- Create Things and Certificates
Create Integration
Send uplink message
Advanced usage: Create Downlink Converter
Video tutorial (Outdated interface)
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.

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.

Example for the Uplink converter:

// decode payload to JSON
var payloadStr = decodeToString(payload);
var data = JSON.parse(payloadStr);
var topicPattern = 'tb/aws/iot/(.+)/(.+)';
var deviceName = metadata.topic.match(topicPattern)[2];
var deviceType = metadata.topic.match(topicPattern)[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) {
   // convert payload to string.
   var str = decodeToString(payload);

   // parse string to JSON
   var data = JSON.parse(str);
   return data;
}
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.

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.

Create Integration

If all of the above is done, then you can proceed to creating the AWS IoT integration. Please follow the screenshots.

You can find AWS IoT Endpoint if you go to Settings - Device data endpoint.

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.

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 (Outdated interface)

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

Next steps

入门指南 - 快速学习ThingsBoard相关功能。
安装指南 - 学习如何在各种操作系统上安装ThingsBoard。
可视化 - 学习如何配置复杂的ThingsBoard仪表板说明。
数据处理 - 学习如何使用ThingsBoard规则引擎。
数据分析 - 学习如何使用规则引擎执行基本的分析任务。
硬件样品 - 学习如何将各种硬件平台连接到ThingsBoard。
高级功能 - 学习高级ThingsBoard功能。

本页目录