AWS IoT Integration

AWS IoT Integration connects ThingsBoard to AWS IoT Core, the managed MQTT broker of AWS. ThingsBoard connects as an MQTT client over mutual TLS and subscribes to the topics you configure. An uplink data converter transforms each message into device or asset data, including telemetry and attributes. ThingsBoard can also publish downlink messages to AWS IoT Core for devices to consume.

Use AWS IoT Integration when:

• Devices already publish to AWS IoT Core and you want their data in ThingsBoard without changing the firmware.
• One subscription must serve many devices: the converter resolves each device from the topic or the payload.
• You need to send commands to devices through AWS IoT Core.

1. Receive data. A device publishes a message to AWS IoT Core. The integration is subscribed to that topic and receives the message.
2. Decode the payload. The uplink converter uses the payload and topic to identify the device or asset and extract attributes and telemetry.
3. Process the message. ThingsBoard processes the converted data through the Rule Engine. If Allow create devices or assets is enabled, ThingsBoard creates an entity that does not exist yet.
4. Send downlink data (optional). The Rule Engine passes a message to the integration. The downlink converter encodes it, and the integration publishes it to AWS IoT Core on the downlink topic.

• Access to ThingsBoard or ThingsBoard Cloud with integrations enabled for your tenant.
• Permission to create integrations and data converters.
• An AWS account with permission to create AWS IoT policies, things, and certificates.
• Outbound TCP port 8883 open from the ThingsBoard server (or the remote integration host) to AWS IoT Core.

In the AWS IoT console, create a policy, a thing with a certificate, and copy the device data endpoint. ThingsBoard authenticates with the certificate and its private key, and verifies AWS IoT Core with the Amazon Root CA certificate.

A policy lists the AWS IoT actions (Connect, Publish, Subscribe, Receive) that the certificate may perform. See AWS IoT Core policies.

1. Go to Manage ⇾ Security ⇾ Policies and click Create policy.
2. Enter a Policy name, for example thingsboard-integration-policy, and click JSON to switch the Policy document from Builder to the JSON editor.
3. Paste the policy below. Replace YOUR_REGION and YOUR_AWS_ID with your AWS Region code and account ID, for example eu-north-1 and 111122223333. The Region menu in the top-right corner of the console shows the Region name (for example, Europe (Stockholm)); open it to see the code next to the name. The account ID is in the account menu next to it.
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 and click JSON Paste the policy, replace YOUR_REGION and YOUR_AWS_ID, and click Create The policy appears in the list

A thing represents a device in AWS IoT. ThingsBoard connects with the certificate attached to it. See Create AWS IoT resources.

1. Go to Manage ⇾ All devices ⇾ Things and click Create things.
2. Select Create single thing and click Next.
3. Enter a Thing name, for example thingsboard-integration. Leave the Additional configurations and Device Shadow sections at their defaults, and click Next.
4. Select Auto-generate a new certificate (recommended) and click Next.
5. Select the policy you created and click Create thing.
6. In the Download certificates and keys window, click Download all, or download at least these three files:
   • Device certificate (*-certificate.pem.crt).
   • Private key file (*-private.pem.key).
   • Amazon Root CA 1 (AmazonRootCA1.pem, RSA 2048 bit key).
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 Select the policy and click Create thing Click Download all (or download the device certificate, private key, and Amazon Root CA 1), then click Done

The device data endpoint is the MQTT hostname of AWS IoT Core for your account and Region.

1. In the left menu of the AWS IoT console, go to Connect ⇾ Domain configurations.
2. In the row iot:Data-ATS, copy the Domain name, for example a312hmjca0kjxk-ats.iot.eu-north-1.amazonaws.com.

You now have everything the integration needs:

Create the uplink converter, assign it to a new AWS IoT integration, and publish a test message.

The uplink converter receives each MQTT message as a byte array plus its topic, resolves the target device, and returns its telemetry and attributes. AWS IoT Integration uses the Generic converter: you write the decoder in TBEL or JavaScript. For converter types and the full decoder reference, see Uplink data converter.

This guide uses a thermostat that publishes its readings to tb/aws/iot/telemetry/thermostat/Thermostat-01:

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

ts is the measurement time in milliseconds. Replace it with the current time, or remove it: without ts, ThingsBoard uses the time the message arrives.

Devices publish their data under tb/aws/iot/telemetry/ and receive commands under tb/aws/iot/commands/. Keep the two namespaces separate: the integration subscribes only to the data topics, so it does not receive its own downlink messages back as uplinks.

The topic structure tb/aws/iot/telemetry/{deviceType}/{deviceName} is a convention of this guide, not an AWS IoT requirement. If your devices publish to other topics, adapt the decoder and the topic filter. The decoder has no fallback values: a message whose topic has no device type or device name is rejected, and no device is created.

1. Go to Integrations ⇾ Data converters and click + Add data converter ⇾ Create new converter.

2. Converter type — keep Uplink.

3. Integration type — select AWS IoT.

4. Name — enter a name, for example AWS IoT Uplink Converter.

5. Main decoding configuration — the editor opens with the default AWS IoT template, which already takes the device name and type from the topic. Replace it with the decoder below. The decoder takes the device name and type from the last two topic segments (.../{deviceType}/{deviceName}), stores fwVersion and the location coordinates as attributes and temperature, humidity, and battery as telemetry, and uses the device timestamp ts if the payload has one. If the topic is missing or its last two segments are empty, the decoder stops with an error. The editor opens in TBEL; use the TBEL / JS toggle to switch to JavaScript.

   • TBEL (Recommended)
   • JavaScript

   /** Decoder **/
   
   // ThingsBoard passes the MQTT topic of each AWS IoT message in metadata.topic.
   // This example uses the last two topic segments to identify the device:
   //
   //   tb/aws/iot/telemetry/thermostat/Thermostat-01
   //                        ^^^^^^^^^^ ^^^^^^^^^^^^^
   //                        type       name
   
   // Get the MQTT topic and reject messages if it is missing or empty.
   var topic = metadata.topic;
   if (topic == null || topic.trim().isEmpty()) {
       raiseError("MQTT topic is missing or empty");
   }
   
   

   ▼Expand

   To adapt:

   • Other topic structure — change the indexes in topicParts[n - 1] and topicParts[n - 2], and change the topic filter to match. With the filter tb/aws/iot/telemetry/+/+, only topics with exactly two levels after tb/aws/iot/telemetry/ reach the decoder. With tb/aws/iot/telemetry/#, a topic such as tb/aws/iot/telemetry/Thermostat-01 would also reach it, and the decoder would take telemetry as the device type.
   • Device name in the payload — use a payload field instead, for example data.deviceId.
   • Other telemetry — add keys to telemetry, for example pressure: data.pressure.
   • Other device properties — add them to attributes, for example serialNumber: data.serialNumber.
   • Update-only keys — in Advanced decoding parameters, the Update only keys list of a new AWS IoT converter already contains fwVersion, latitude, and longitude: these keys are stored only when their value changes. Add other keys that rarely change, or remove keys that you want to store with every message.

6. Click Test decoder function and check the result (see Test the Decoder).

7. Click Add.

Decoder Inputs

The decoder signature is function decoder(payload, metadata): object | object[].

With a wildcard topic filter, topic holds the actual topic of the message, not the filter.

For field renaming, nested values, and non-JSON payloads, see Common scripting patterns.

Test the Decoder

Click Test decoder function below the editor. Set Payload content type to JSON and paste the sample payload. The Metadata already has a topic row with a sample AWS IoT topic; set it to the topic of your device:

Click Test. The Output panel shows:

{
  "deviceName": "Thermostat-01",
  "deviceType": "thermostat",
  "attributes": {
    "fwVersion": "1.4.2",
    "latitude": 37.7749,
    "longitude": -122.4194
  },
  "telemetry": {
    "ts": 1791901200000,
    "values": {
      "temperature": 25.3,
      "humidity": 62.8,
      "battery": 78.5
    }
  }
}

ts comes from the payload; without it, ts is the time of the test. The decoder needs the topic row: real messages always carry the topic. If you delete the row, the test fails with MQTT topic is missing or empty; with a topic such as thermostat or tb/aws/iot/telemetry/thermostat/, it fails with MQTT topic must contain device type and device name.

1. Go to Integrations ⇾ Integrations and click + Add integration.
2. Basic settings:
   • Integration type — select AWS IoT.
   • Name — enter a name, for example AWS IoT integration.
   • Enable integration and Allow create devices or assets — keep both on, so the device is created on its first uplink.
   • Click Next.
3. Uplink data converter:
   • Click Select existing and choose AWS IoT Uplink Converter.
   • Alternatively, click Create new to write a decoder here.
   • Click Next.
4. Downlink data converter:
   • Click Skip. Add a downlink converter later if you need to send commands to devices.
5. Connection:
   • AWS IoT Endpoint — paste the device data endpoint: the host name only, without https:// or a port.
   • CA certificate file, Certificate file, Private key file — upload AmazonRootCA1.pem, the *-certificate.pem.crt certificate, and the *-private.pem.key key. See Credentials.
   • Topic filters — replace the default # with tb/aws/iot/telemetry/+/+.
   • Leave the other parameters at their defaults. See Connection Settings for details.
6. Optionally, click Check connection to test the endpoint and the certificates before you save.
7. Click Add.

ThingsBoard always connects to AWS IoT Core on port 8883 over TLS, with a clean session.

Advanced settings

AWS IoT Integration supports only certificate (PEM) credentials. Upload each file (Browse file) or take it from Secrets storage.

The certificate must be Active and have the policy attached. See X.509 client certificates.

The integration subscribes to all topic filters when it connects. Subscribe to a dedicated namespace rather than #, so the integration receives only ThingsBoard traffic. Do not include the downlink topics in the filters: with tb/aws/iot/#, the integration would also receive its own commands from tb/aws/iot/commands/... and process them as uplinks.

ThingsBoard checks the filters when you save the integration: # must be the last level, and + must take a whole level.

This guide uses tb/aws/iot/telemetry/+/+: the integration receives only topics with a device type and a device name, in the structure the decoder expects. Messages on topics with fewer or more levels are not delivered to ThingsBoard and do not appear in the integration Events.

AWS IoT Core does not support QoS 2, so the integration does not offer it. If a subscription fails, for example because the policy denies iot:Subscribe for the filter, the integration shows an error status with the reason. See MQTT topics.

Publish a message to AWS IoT Core, then confirm that ThingsBoard decoded it and created the device.

Publish the sample payload to tb/aws/iot/telemetry/thermostat/Thermostat-01 with the AWS IoT MQTT test client or the AWS CLI. ts is the measurement time in milliseconds. Replace it with the current time, or remove it: without ts, ThingsBoard uses the time the message arrives.

• MQTT test client
• AWS CLI

1. In the AWS IoT console, go to Test ⇾ MQTT test client. The client connects automatically (Connection details: Connected). Open the Publish to a topic tab.
2. In Topic name, enter tb/aws/iot/telemetry/thermostat/Thermostat-01.
3. Paste the sample payload into Message payload.
4. Click Publish.

• Integration events — go to Integrations ⇾ Integrations, open the integration, and click the Events tab. The uplink appears with status OK. Click ⋅⋅⋅ in the Message column to see the topic and payload.
• Converter events — open AWS IoT Uplink Converter in Integrations ⇾ Data converters and click the Events tab. In shows the received payload, Out shows the decoded result, and Metadata shows the topic and integration name.
• Device — go to Devices & assets ⇾ Devices. The integration has created Thermostat-01 with type thermostat. Open it and confirm temperature, humidity, and battery on the Latest telemetry tab, and fwVersion, latitude, and longitude on the Attributes tab, in the Client attributes scope.

ThingsBoard publishes downlinks to AWS IoT Core when the Rule Engine routes a message to the integration — for example, after a shared attribute update. Downlinks are always published with QoS 1. The topic comes from the Downlink topic pattern: with the default ${topic}, it is the topic value in the downlink converter’s output metadata. If a placeholder of the pattern has no value in the output metadata, or the topic contains + or #, the downlink is not published and the integration Events tab shows a Downlink event with status ERROR.

The downlink converter turns a Rule Engine message into an MQTT payload. For the full encoder reference, see Downlink data converter.

The encoder returns:

• contentType — JSON, TEXT, or BINARY.
• data — the payload to publish.
• metadata — values for the Downlink topic pattern placeholders, for example topic. Use a topic outside the subscribed data topics, for example tb/aws/iot/commands/{deviceName}.

For RPC commands, msg.method and msg.params are available. msg.params is a string — use parseFloat(msg.params) or JSON.parse(msg.params) to get a number or an object.

1. Open the integration in Integrations ⇾ Integrations and click Toggle edit mode (pencil icon).
2. In the Downlink data converter field, click Create new. The Downlink converter type and AWS IoT integration type are preselected.
3. Enter a name, for example AWS IoT Downlink Converter.
4. Main encoding configuration — the editor opens with the default AWS IoT encoder, which is the encoder below. Keep it, or write your own. The editor opens in TBEL; use the TBEL / JS toggle to switch to JavaScript.
5. To record downlink events, click the debug icon next to the name, select All messages, and click Apply.
6. Click Add, then Apply changes.

Encoder used in this guide:

/** Encoder **/
// Publish the ThingsBoard message as JSON to the device command topic.
// metadata.topic is read by the integration when Downlink topic pattern is ${topic}.

// Get the device name without surrounding spaces and reject the message if it is missing or empty.
// The rule chain adds deviceName to the metadata, for example with an originator fields node.
var deviceName = metadata.deviceName != null ? metadata.deviceName.trim() : null;
if (deviceName == null || deviceName.isEmpty()) {
    raiseError("Message metadata has no deviceName");
}

var result = {
    // Specify the downlink payload format: JSON, TEXT, or BINARY.
    contentType: "JSON",

    // Serialize the incoming message and use it as the MQTT payload.
    data: JSON.stringify(msg),

    // Build a per-device command topic in the same namespace as the uplink.
    metadata: {
        topic: "tb/aws/iot/commands/" + deviceName
    }
};

return result;

/** Encoder **/
// Publish the ThingsBoard message as JSON to the device command topic.
// metadata.topic is read by the integration when Downlink topic pattern is ${topic}.

// Get the device name without surrounding spaces and reject the message if it is missing or empty.
// The rule chain adds deviceName to the metadata, for example with an originator fields node.
var deviceName = typeof metadata.deviceName === "string" ? metadata.deviceName.trim() : "";
if (!deviceName) {
    throw new Error("Message metadata has no deviceName");
}

var result = {
    // Specify the downlink payload format: JSON, TEXT, or BINARY.
    contentType: "JSON",

    // Serialize the incoming message and use it as the MQTT payload.
    data: JSON.stringify(msg),

    // Build a per-device command topic in the same namespace as the uplink.
    metadata: {
        topic: "tb/aws/iot/commands/" + deviceName
    }
};

return result;

To adapt:

• Other payload — build the object the device expects instead of msg, for example { "interval": msg.temperatureUploadFrequency }.
• Non-JSON payload — set contentType to TEXT for a plain string, or BINARY with a Base64-encoded string.
• Other message types — branch on msgType to handle other Rule Engine message types.
• Device name check — the encoder stops with the error Message metadata has no deviceName if the message has no deviceName in its metadata, so a command is never published to tb/aws/iot/commands/null. The rule chain adds deviceName with an originator fields node; see Configure the Root Rule Chain.

The encoder builds the topic from deviceName, so the rule chain first adds the device name to the message metadata.

1. Go to Data processing ⇾ Rule chains and open the Root Rule Chain.
2. From the Enrichment section, drag an originator fields node onto the canvas.
3. Enter a Name (for example, Retrieve device name) and map the source fields:
   • Name ⇾ deviceName
   • Add mapped originator fields to ⇾ Metadata
   • Click Add.
4. Connect the message type switch node to the originator fields node with the Attributes Updated relation.
5. From the Action section, drag an integration downlink node onto the canvas.
6. Enter a Name (for example, Downlink to AWS IoT integration), select your AWS IoT integration, and click Add.
7. Connect the originator fields node to the integration downlink node with the Success relation.
8. Click Apply changes.

Subscribe to the command topic, then update a shared attribute to trigger a downlink.

1. In the AWS IoT console, go to Test ⇾ MQTT test client, open the Subscribe to a topic tab, enter tb/aws/iot/commands/# in Topic filter, and click Subscribe. The note You cannot publish messages to a wildcard topic only means that you cannot publish to this filter from the same panel; receiving works.
2. In ThingsBoard, go to Devices & assets ⇾ Devices, select Thermostat-01, and open the Attributes tab.
3. Select Shared attributes and click +.
4. Set Key to temperatureUploadFrequency, Type to Integer, Value to 60, and click Add. ThingsBoard publishes the downlink.

• AWS IoT console, MQTT test client — the tb/aws/iot/commands/Thermostat-01 topic shows the payload:

  {"temperatureUploadFrequency":60}

  

• ThingsBoard, converter events — go to Integrations ⇾ Data converters, open the downlink converter, and select the Events tab. In shows the Rule Engine message, Out shows the encoded payload, and Metadata shows the topic and integration name.

To read debug events, open the integration or converter, click Events, and select an event: In is the received data, Out is the converter result, and Error holds the error text.

• Integrations overview — how integrations, converters, uplinks, and downlinks fit together.
• Uplink data converter — decoder inputs, output format, and scripting patterns.
• Downlink data converter — encoder reference.
• MQTT Integration — connect to any other MQTT broker.
• Remote Integration — run the integration outside the ThingsBoard cluster.
• Integration downlink node — forward Rule Engine messages to an integration.
• TBEL — built-in functions and syntax for converter scripts.