AWS IoT Integration

AWS IoT Core is a managed cloud service that acts as an MQTT message broker between IoT devices and the applications that consume their data. AWS IoT Integration connects ThingsBoard to AWS IoT Core over MQTT as a mutually authenticated client: it subscribes to a topic filter, decodes every message with an uplink converter, and stores the resulting telemetry and attributes in ThingsBoard.

ThingsBoard connects to AWS IoT Core as an MQTT client, authenticating with a client certificate and private key issued by AWS IoT. It subscribes to the topic filter configured on the integration and receives every message that devices publish under it; the uplink converter decodes each message into telemetry and attributes, and ThingsBoard provisions the target device automatically on the first message. If a downlink converter is configured, the Rule Engine can also push messages back through that same connection.

Before creating the integration, ensure:

• You have access to ThingsBoard PE or ThingsBoard Cloud with integration functionality enabled for your tenant.
• You have permissions to create integrations and data converters.
• You have an AWS account with AWS IoT Core enabled.
• Your account has permissions to create IoT policies, things, and certificates in that account.
• Outbound TCP port 8883 is open from the ThingsBoard server to your AWS IoT endpoint (*.iot.{region}.amazonaws.com).

Prepare the policy, thing, and certificates in the AWS IoT console before creating the integration in ThingsBoard. The connection uses mutual TLS: ThingsBoard authenticates with a client certificate and private key, and validates the broker with the Amazon Root CA certificate.

A policy defines which IoT operations (Connect, Publish, Subscribe, Receive) the certificate is permitted to perform. See AWS’s IoT policies documentation for details.

1. In the AWS IoT console, go to Security ⇾ Policies and click Create policy.
2. Enter a Policy name (e.g. tb_policy), then click JSON to switch the document 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. ThingsBoard authenticates with the certificate attached to it. See AWS’s Create AWS IoT resources documentation for details.

1. Go to All devices ⇾ Things and click Create things.
2. Select Create single thing and click Next.
3. Enter a Name for the thing (e.g. tb-bridge-01) 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)
   • 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 ThingsBoard connects to.

1. In the AWS IoT console, click Settings in the left navigation sidebar.
2. In the Device data endpoint section, copy the endpoint URL (e.g. a2ljyhf3dvidme-ats.iot.us-east-1.amazonaws.com) — you will need it when creating the integration.

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

Collect the values below before creating the ThingsBoard integration.

To set up the AWS IoT integration, first create an uplink data converter to process incoming messages, then create and configure the integration.

The uplink converter decodes incoming AWS IoT messages and maps them to the ThingsBoard data model. AWS IoT uses a generic uplink converter.

The decoder function receives:

• payload — the JSON object decoded from the MQTT message
• metadata — integrationName, the MQTT topic the message arrived on, and any key-value pairs configured in the integration’s Metadata settings Sample payload (published to topic tb/aws/iot/sensors/freezer-432):

{
    "ts": 1718020800000,
    "temperature": 25.3,
    "humidity": 62.8,
    "battery": 78.5,
    "fwVersion": "1.4.2",
    "location": {
        "latitude": 37.7749,
        "longitude": -122.4194
    }
}

1. Go to Integrations center ⇾ Data converters.
2. Click + Add data converter ⇾ Create new converter.

In the Add data converter dialog:

3. Converter type — leave Uplink (selected by default).
4. Integration type — in the search field, enter AWS IoT and select AWS IoT from the list.
5. Name — enter a converter name, for example AWS IoT Uplink Converter.
6. Main decoding configuration — a code editor with the function signature function decoder(payload, metadata) {. Paste the decoder function shown below. By default the editor opens in TBEL; use the TBEL / JS toggle (upper right) to switch languages.
7. Click Add.

The decoder function used in this tutorial derives deviceType and deviceName from the last two MQTT topic segments (here sensors and freezer-432), so it works for any topic depth, then maps the payload to fwVersion/location attributes and temperature/humidity/battery telemetry:

// AWS IoT devices publish to an MQTT topic, which the integration always
// provides in metadata. This example derives identity from the LAST two
// topic segments, so it works for any topic depth:
//
//   tb/aws/iot/sensors/freezer-432
//              ^^^^^^^ ^^^^^^^^^^
//              type    name
//
// Extract device information from the last two MQTT topic segments.
var topicParts = metadata.topic.split("/");
var n = topicParts.length;

// Use fallback values if the topic does not contain enough segments.
var deviceName = n > 0 ? topicParts[n - 1] : "AWS IoT Device";
var deviceType = n > 1 ? topicParts[n - 2] : "default";

// AWS IoT devices publish to an MQTT topic, which the integration always
// provides in metadata. This example derives identity from the LAST two
// topic segments, so it works for any topic depth:
//
//   tb/aws/iot/sensors/freezer-432
//              ^^^^^^^ ^^^^^^^^^^
//              type    name
//
// Extract device information from the last two MQTT topic segments.
var topicParts = metadata.topic.split("/");
var n = topicParts.length;

// Use fallback values if the topic does not contain enough segments.
var deviceName = n > 0 ? topicParts[n - 1] : "AWS IoT Device";
var deviceType = n > 1 ? topicParts[n - 2] : "default";

To adapt this converter 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 carried in the message body rather than the topic.
• Different telemetry fields — add or rename keys in the telemetry object to match your payload structure.
• Static attributes — add device properties from your payload to the attributes object, for example firmwareVersion: data.fw.
• 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:
   • Click Select existing and choose the previously created AWS IoT Uplink Converter from the list.
   • Click Next.
3. Downlink data converter:
   • Leave empty and click Skip — the downlink converter can be added later if needed.
4. Connection settings:
   • AWS IoT Endpoint — your AWS IoT device data endpoint (e.g. a2ljyhf3dvidme-ats.iot.us-east-1.amazonaws.com).
   • Credentials — for each file, click Browse file to upload it, or Use Secret storage to reference a stored secret:
     • CA certificate file — AmazonRootCA1.pem.
     • Certificate file — the device certificate (*.pem.crt).
     • Private key file — the 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

AWS IoT authentication is always certificate-based (mutual TLS). Each file can be supplied with Browse file or referenced from Secret storage with Use Secret storage:

• CA certificate file — the Amazon Root CA 1 (AmazonRootCA1.pem) certificate ThingsBoard uses to validate the AWS IoT broker.
• Certificate file — the device certificate (*.pem.crt) issued when you created the thing.
• Private key file — the private key (*-private.pem.key) for that certificate.
• Private key password — optional password, only if the private key is encrypted. The certificate must have the policy attached and its status must be Active in the AWS IoT console. See AWS’s X.509 client certificates documentation for details.

AWS IoT Endpoint

Your AWS IoT device data endpoint in the format {prefix}-ats.iot.{region}.amazonaws.com. Find it in the AWS IoT console under Settings ⇾ Device data endpoint. ThingsBoard connects to it over MQTT on port 8883.

Credentials

The client certificate, private key, and Amazon Root CA certificate used for the mutual-TLS MQTT connection. See Credentials above.

Topic Filters

The MQTT topics ThingsBoard subscribes to for incoming messages. Each topic filter has its own QoS, and you can add several with Add topic filter. Two wildcard types are supported:

• Single-level + — matches one topic level, e.g. tb/aws/iot/+/telemetry.
• Multi-level # — replaces the rest of the topic and must be the last symbol, e.g. tb/aws/iot/#. Use a namespace dedicated to ThingsBoard rather than a bare #, so the integration only receives the traffic it should:

See AWS’s MQTT topics documentation for details.

QoS

The MQTT quality of service level for each topic filter:

• 0 - At most once — default; fire-and-forget delivery, no acknowledgement.
• 1 - At least once — the broker redelivers until acknowledged; messages may be duplicated. AWS IoT Core does not support QoS 2.

Execute Remotely

When enabled, ThingsBoard generates an Integration key and Integration secret that allow the integration to run as a separate process outside the ThingsBoard cluster — useful when the AWS IoT endpoint is only reachable from a restricted network.

Advanced Settings

Publish a message to the subscribed topic using the AWS IoT MQTT test client or the AWS CLI.

{
  "ts": 1718020800000,
  "temperature": 25.3,
  "humidity": 62.8,
  "battery": 78.5,
  "fwVersion": "1.4.2",
  "location": {
    "latitude": 37.7749,
    "longitude": -122.4194
  }
}

aws iot-data publish \
--topic "tb/aws/iot/sensors/freezer-432" \
--cli-binary-format raw-in-base64-out \
--payload '{"ts":1718020800000,"temperature":25.3,"humidity":62.8,"battery":78.5,"fwVersion":"1.4.2","location":{"latitude":37.7749,"longitude":-122.4194}}'

Go to Integrations center ⇾ Integrations, open the AWS IoT integration, and check the Events tab. One Uplink event appears with status OK. Click … in the Message column to inspect the raw payload and the topic received from the broker.

Go to Integrations center ⇾ Data converters, click the uplink converter, and open its Events tab. Click … in the respective column to inspect each field:

• In — the raw payload passed to the converter.
• Out — the decoded result: deviceName, deviceType, attributes (fwVersion, and latitude/longitude when the payload includes a location), and telemetry (temperature, humidity, battery).
• Metadata — integrationName and the MQTT topic the message arrived on.

Go to Entities ⇾ Devices. The device freezer-432 of type sensors is automatically provisioned on the first message. Open it and check the Latest telemetry tab — you should see temperature, humidity, and battery — and the Attributes tab for fwVersion (and latitude/longitude if the payload included a location).

A downlink sends a Rule Engine message — a shared attribute update, an RPC command, or any other message you route to the integration — from ThingsBoard to AWS IoT. The integration publishes it to the downlink topic configured on the converter, where any subscribed device receives it.

The downlink converter encodes a Rule Engine message into the payload published to AWS IoT. AWS IoT uses a generic downlink converter.

The encoder function receives:

• msg — the JSON message payload from the Rule Engine
• msgType — the Rule Engine message type, e.g. ATTRIBUTES_UPDATED or POST_TELEMETRY_REQUEST
• metadata — key-value pairs with additional message data
• integrationMetadata — key-value pairs from the integration’s Metadata settings

1. Go to Integrations center ⇾ Data converters.
2. Click + Add data converter ⇾ Create new converter.
3. Converter type — switch the toggle to Downlink.
4. Integration type — enter AWS IoT in the search field and select it from the list.
5. Name — enter a converter name, for example AWS IoT Downlink Converter.
6. Main encoding configuration — paste the encoder function shown below.
7. Click Add.

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

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

To adapt this converter to your consumer:

• Different envelope — replace the data object with whatever structure the device expects; only contentType and data are required in the result.
• Pass the payload through unchanged — return data: JSON.stringify(msg) and drop the field mapping.
• Non-JSON payload — set contentType to TEXT for a plain string, or BINARY with a Base64-encoded string for raw bytes.
• Extra message types — branch on msgType to handle other Rule Engine message types you route to the integration.

1. Go to Integrations center ⇾ Integrations and open the AWS IoT integration.
2. Click Toggle edit mode.
3. In the Downlink data converter field, select AWS IoT Downlink Converter.
4. Expand the connection Advanced settings and set the Downlink topic pattern to tb/aws/iot/commands/${deviceName} — this publishes each command to a per-device topic under the same namespace as the uplink.
5. Click Apply changes.

The integration does not send anything on its own — a rule chain must forward messages to it.

1. Go to Rule chains and open the Root Rule Chain.
2. In the node palette on the left, search for integration downlink (under Action) and drag it onto the canvas.
3. In the Add rule node dialog, enter a Name (e.g. Downlink to AWS IoT integration), select your AWS IoT integration, and click Add.
4. Connect the Message Type Switch node to the new node using the Post attributes and Attributes Updated relations, so downlinks trigger whenever shared attributes are created or updated.
5. Click Apply changes.

1. In the AWS IoT console, go to MQTT test client ⇾ Subscribe to a topic, enter tb/aws/iot/commands/#, and click Subscribe.
2. In ThingsBoard, go to Entities ⇾ Devices and open freezer-432.
3. Open the Attributes tab, set the scope to Shared attributes, and click +.
4. Enter key powerState, keep type String, enter value on, and click Add.

Adding the attribute generates an Attributes Updated message that reaches the integration downlink node. The encoded payload appears on the tb/aws/iot/commands/freezer-432 topic in the MQTT test client within a second or two.

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 Downlink Converter Events

Go to Integrations center ⇾ Data converters, open the downlink converter, and check its Events tab. Click … in the respective column to inspect each field:

• In — the Rule Engine message passed to the encoder.
• Out — the encoded result: contentType, data, and metadata.

Check Downlink Subscribed Topic

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

• Integrations Overview — how ThingsBoard connects to external platforms and how uplink/downlink flow works
• Uplink Data Converter — full decoder function reference: input parameters, output fields, and scripting patterns
• Downlink Data Converter — full encoder function reference
• Integration Downlink Rule Node — forward Rule Engine messages to an integration
• Remote Integration — run the integration outside the ThingsBoard server to reach a broker on a restricted network
• TBEL scripting reference — built-in functions and operators for writing converter scripts
• Rule Engine — how rule chains route messages to nodes like the Integration Downlink node