AWS IoT Integration

The AWS IoT integration streams data from AWS IoT Core to ThingsBoard. AWS IoT Core acts as an MQTT broker — IoT devices publish messages to topics, and ThingsBoard subscribes to them. The connection uses mutual TLS: ThingsBoard authenticates with a client certificate and private key issued by AWS IoT, while AWS IoT validates the server identity using a Root CA certificate. Incoming messages are decoded by an uplink converter and stored as device telemetry and attributes in ThingsBoard.

You need an AWS account with IoT Core enabled. The setup involves creating an IoT policy, a thing (device), and a certificate that ThingsBoard will use to authenticate with AWS IoT Core.

A policy defines which IoT operations (connect, publish, subscribe, receive) are permitted.

1. In the AWS IoT console, go to Security ⇾ Policies and click Create policy.
2. Enter a Policy name and click JSON to switch the editor to JSON mode.
3. Paste the policy document below, replacing YOUR_REGION and YOUR_AWS_ID with your values.
4. Click Create.

{
  "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/*"]
    }
  ]
}

Go to Security ⇾ Policies and click Create policy Enter the policy name, then click JSON to switch the document editor to JSON mode Paste the policy document and replace YOUR_REGION and YOUR_AWS_ID with your actual values, then click Create Policy created successfully — it now appears in the policies list

A “thing” is the digital representation of a physical device in AWS IoT.

1. Go to All devices ⇾ Things and click Create things.
2. Select Create single thing and click Next.
3. Enter a Name for the device and click Next.
4. Select Auto-generate a new certificate (recommended) and click Next.
5. Attach the policy you created and click Create thing.
6. Download the required files:
   • Device certificate (*.pem.crt)
   • Private key (*-private.pem.key) — shown only once, save it immediately
   • Root CA certificate — download Amazon Root CA 1 (AmazonRootCA1.pem)
7. Click Done.

Go to All devices ⇾ Things and click Create things Select Create single thing and click Next Enter the thing name and click Next Select Auto-generate a new certificate (recommended) and click Next Check the policy you created and click Create thing Download the device certificate, private key, and Amazon Root CA 1 — the private key is only available here; click Done when finished

Each AWS account has a unique device data endpoint — the MQTT broker hostname that ThingsBoard will connect to. Copy it from the console under Settings ⇾ Device data endpoint; you will paste it into the ThingsBoard integration connection settings.

In the AWS IoT console, click Settings in the left navigation sidebar Copy the endpoint URL from the Device data endpoint section — you will need it in the ThingsBoard integration

The AWS IoT integration uses a generic uplink converter. The decoder function receives payload (JSON object decoded from the MQTT message) and metadata (includes topic and integrationName), and must return an object with deviceName, deviceType, and optionally attributes and telemetry.

1. Go to Integrations center ⇾ Data converters.
2. Click + Add data converter ⇾ Create new converter.
3. Set the type to Uplink and enter a name.
4. Paste the decoder script and click Add.

The example decoder below uses the topic tb/aws/iot/sensors/freezer-432 — it extracts deviceType from segment 4 (sensors) and deviceName from segment 5 (freezer-432), and maps the four payload fields to one attribute and three telemetry keys:

var data = decodeToJson(payload);
var topicParts = metadata.topic.split("/");
var deviceType = topicParts[3];
var deviceName = topicParts[4];

var result = {
    deviceName: deviceName,
    deviceType: deviceType,
    attributes: {
        state: data.val0,
    },
    telemetry: {
        temperature: data.val1,
        fan_ins: data.val2,
        fan_out: data.val3,
    }
};

return result;

var payloadStr = decodeToString(payload);
var data = JSON.parse(payloadStr);
var topicParts = metadata.topic.split("/");
var deviceType = topicParts[3];
var deviceName = topicParts[4];

var result = {
    deviceName: deviceName,
    deviceType: deviceType,
    attributes: {
        state: data.val0,
    },
    telemetry: {
        temperature: data.val1,
        fan_ins: data.val2,
        fan_out: data.val3,
    }
};

function decodeToString(payload) {
    return String.fromCharCode.apply(String, payload);
}

return result;

Adapting the decoder to your device:

• Different topic structure — change the segment indices in metadata.topic.split("/") to match the position of the device type and name in your topic path.
• Device name from payload — replace topicParts[4] with a payload field (e.g. data.deviceId) if the device name is in the message body rather than the topic.
• Different telemetry fields — add or rename keys in the telemetry object to match your payload structure.
• Update only keys — in Advanced decoding parameters, add attribute keys that should only be written when their value changes.

1. Go to Integrations center ⇾ Integrations and click +.
   • Set Integration type to AWS IoT.
   • Enable integration and Allow create devices or assets are on by default.
   • Click Next.
2. Uplink data converter:
   • Select existing — choose the previously created AWS IoT Uplink Converter from the list.
   • Click Next.
3. Downlink data converter:
   • Click Skip — the downlink converter is only needed for sending commands to devices and can be added later.
4. Connection:
   • Enter the AWS IoT endpoint.
   • Upload the CA certificate (AmazonRootCA1.pem), Device certificate (*.pem.crt), and Private key (*-private.pem.key). Leave Private key password blank unless the key is encrypted.
   • Add a Topic filter (e.g. tb/aws/iot/#) — the # wildcard matches all sub-topics. Select QoS level (default: At most once).
5. Click Add to create the integration.

Set Integration type to AWS IoT, enter a name, and click Next Select existing, choose the AWS IoT Uplink Converter, and click Next Skip the downlink converter — it can be added later Paste the AWS IoT endpoint and upload the CA certificate, device certificate, and private key Add the topic filter (e.g. tb/aws/iot/#), set QoS, and click Add to create the integration

Use the AWS IoT MQTT test client to send a test message:

1. Go to MQTT test client ⇾ Publish to a topic.
2. Enter the topic tb/aws/iot/sensors/freezer-432 and paste the payload below.
3. Click Publish.

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

After publishing, go to Entities ⇾ Devices — a new device named freezer-432 of type sensors is automatically created. Open it and check the Latest telemetry tab to see the decoded temperature, fan_ins, and fan_out values, and the Attributes tab for the state attribute.

Go to Integrations center ⇾ Integrations, open the AWS IoT integration, and check the Events tab to verify the message was received:

The Events tab shows the uplink events with status OK Click the message icon to inspect the full uplink payload — topic and decoded values are shown

To send messages from ThingsBoard to devices via AWS IoT, create a downlink converter and configure a rule chain.

1. Go to Integrations center ⇾ Integrations and open the AWS IoT integration.
2. Click Toggle edit mode.
3. In the Downlink data converter field, click Create new.
4. Enter a name, paste the encoder script, and click Add.
5. In Advanced settings, set the Downlink topic pattern to down/test.
6. Click Apply changes.

// 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;

// 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;

To send downlinks through the integration, modify the Root Rule Chain:

1. Go to Rule chains and open the Root Rule Chain.
2. Find the integration downlink node in the node library panel on the left. Drag it onto the canvas.
3. In the node configuration dialog, enter a name (e.g. “Downlink to AWS IoT”) and select your AWS IoT integration. Click Add.
4. Connect the message type switch node to the new integration downlink node using the Attributes Updated link type to trigger downlinks on shared attribute updates, and optionally also using the Post attributes link type to forward attribute post messages as downlinks. Apply changes.

1. In the AWS IoT MQTT test client, go to Subscribe to a topic, enter down/test, and click Subscribe.
2. In ThingsBoard, go to Entities ⇾ Devices, open device freezer-432, switch to the Attributes tab, and select scope Shared attributes.
3. Enter the key powerState and value on, then click Add to trigger the downlink.

In the AWS MQTT test client, enter down/test in the Subscribe to a topic tab and click Subscribe Open device freezer-432, go to Attributes ⇾ Shared attributes, and update the state attribute to idle — this triggers the downlink

Check the subscribed topic in the AWS MQTT test client — the downlink payload should appear:

• Integration Overview
• Uplink Converters
• Downlink Converters
• Rule Engine