The Things Stack Community Integration

The Things Stack Community Integration connects ThingsBoard to The Things Network (TTN), the public community LoRaWAN network that runs on The Things Stack. ThingsBoard connects to the MQTT server of your The Things Stack application as an MQTT client, subscribes to the uplinks of its devices, and passes each one to an uplink data converter, which turns it into telemetry and attributes. For downlink, ThingsBoard publishes messages to the downlink topic of the device on the same connection.

Use The Things Stack Community Integration when:

• Your LoRaWAN devices are registered in an application on The Things Network, for example on the eu1, nam1, or au1 cluster.
• You want ThingsBoard to create a device for every end device of the application, with no extra setup per device.
• You need to send downlinks from ThingsBoard to those devices, for example when a shared attribute changes.

For a private The Things Industries deployment, use the The Things Stack Industries integration instead.

1. Connect and subscribe. The integration connects to the MQTT server of your cluster, for example eu1.cloud.thethings.network:8883, with the application ID and an API key, and subscribes to v3/+/devices/+/up.
2. Receive data. A device sends an uplink through a gateway. The Things Stack publishes it as a JSON message to the uplink topic of the device.
3. Decode the payload. The uplink converter takes the device payload and the network details out of the message, such as the DevEUI, the frame port, and the signal quality. The decoder turns the payload into telemetry and attributes. If Allow create devices or assets is on, ThingsBoard creates the device on its first uplink.
4. Send a downlink (optional). The Rule Engine passes a message to the integration. The downlink converter encodes it, and ThingsBoard publishes it right away to v3/{application ID}@ttn/devices/{device ID}/down/push. The Things Stack queues it and sends it to the device.

• Access to ThingsBoard Cloud with integrations enabled for your tenant. ThingsBoard must be able to open an outbound connection to the MQTT server of The Things Stack, on port 8883.
• Permission to create integrations and data converters, and to edit rule chains for downlink.
• A The Things Network account with access to The Things Stack Console.
• A LoRaWAN device and gateway are optional: this guide simulates uplinks in the console.

In The Things Stack, devices belong to an application. The integration reads the uplinks of every device in one application, and authenticates with an API key of that application.

Here you create the application, its API key, and a test end device. Open the console of the cluster you use, for example Europe 1 (eu1), and keep the cluster ID: you need it for the integration.

1. Sign in to The Things Stack Console and select your cluster.
2. Go to Applications and click + Add application.
3. Enter an Application ID, for example my-thingsboard. It must be unique on the cluster.
4. Click Create application. The Application overview page opens.

ThingsBoard uses the API key as the MQTT password.

1. In the application, go to API keys in the left menu and click + Add API key.
2. Enter a Name, for example ThingsBoard.
3. Select Grant individual rights and select:
   • Read application traffic (uplink and downlink)
   • Write downlink application traffic
4. Click Create API key.
5. Copy the key and store it securely. The console shows it only once.

Open API keys in your TTN application and click + Add API key. Enter a key name, then grant the required permissions. For ThingsBoard integration, enable Read application traffic (uplink and downlink) and Write downlink application traffic. Review the selected permissions and click Create API key. Copy and securely store the generated API key. The key is displayed only once and cannot be retrieved after this dialog is closed.

The guide registers a test device with ABP (Activation by Personalization), so you can simulate uplinks right away, without a join. For real devices, use OTAA (Over-the-Air Activation): see the The Things Stack device registration guide.

1. In the application, go to End devices and click + Register end device.
2. Under Input method, select Enter end device specifics manually.
3. Select the Frequency plan, for example Europe 863-870 MHz (SF9 for RX2 - recommended), the LoRaWAN version, for example LoRaWAN Specification 1.0.0, and the Regional Parameters version, for example TS002 Technical Specification 1.0.0.
4. Click Show advanced activation, LoRaWAN class and cluster settings and set Activation mode to Activation by personalization (ABP).
5. Under Provisioning information, click Generate for DevEUI, Device address, AppSKey, and NwkSKey. ThingsBoard names the device after the DevEUI, so do not leave it empty.
6. Enter the End device ID, for example thermostat-a. ThingsBoard stores it as the device label and uses it to address downlinks.
7. Click Register end device.

Open End devices in your TTN application and click + Register end device. Select Enter end device specifics manually, then configure the Frequency plan, LoRaWAN version, and Regional Parameters version. Expand the advanced activation settings, select Activation by personalization (ABP), and scroll to the Provisioning information section. Generate or enter the required values for DevEUI, Device address, AppSKey, and NwkSKey. Specify an End device ID (for example, thermostat-a), then click Register end device.

Create the uplink converter, then the integration with the MQTT credentials of your application.

The Things Stack Community Integration uses the Typed uplink converter. ThingsBoard selects it for this integration type, and you cannot change it later. The converter takes the device payload and the network details out of The Things Stack message, then runs your decoder on the payload only. The device name, profile, and label come from patterns in the converter settings, not from the decoder. See Typed uplink converter.

Write the decoder yourself as below, or take a ready-made one for your device model from the Library.

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

2. Converter type — keep Uplink.

3. Integration type — select The Things Stack Community.

4. Keep Create new selected.

5. Name — enter a name, for example TTN Uplink Converter.

6. Main decoding configuration:

   • Entity type — keep Device.
   • Device name — keep Device $eui. $eui is replaced with the DevEUI from the message, so the example device is named Device 70B3D57ED80054FE. You can use any key from Decoder Inputs as $key, for example $deviceId.
   • The editor holds the default decoder: the body of function payloadDecoder(payload, metadata). Keep it. It reads a serial number, battery level, temperature, and saturation from fixed byte positions. Use the TBEL / JS toggle to switch to JavaScript.
   • TBEL (Recommended)
   • JavaScript

   /**
    * Decodes the incoming payload and returns a structured object containing telemetry data and attributes.
    *
    * @param {byte[]} input - The raw payload received as an array of bytes.
    * @returns {Object} output - The structured output with decoded telemetry and attributes.
    */
   
   function decodePayload(input) {
       // Initialize the output object with empty attributes and telemetry for clarity.
       var result = { attributes: {}, telemetry: {}};
   
       // Detect input type and normalize to byte array
       var bytes;
   
       if (metadata.payloadFormat == 'JSON') {
           // payloadFormat is 'JSON' when The Things Network payload formatters are configured on the application or device level.
           // In that case, decoded_payload is a JSON object produced by your formatter.
           // This template assumes the formatter returns { "bytes": [...] } with the raw byte array.
           // If your formatter returns pre-decoded values in a different structure,
           // update this section to extract the values directly from 'parsed' instead.
   

   ▼Expand

   The decoder expects this byte layout:

   Bytes	Key	Stored as	Value
   0–3	sn	attribute	Serial number
   4	battery	telemetry	Battery level
   5–6	temperature	telemetry	Raw value ÷ 100
   7	saturation	telemetry	Saturation

7. Advanced decoding parameters — keep the defaults:

   • Device profile name — $applicationId. The device gets a profile named after the application, for example my-thingsboard.
   • Device label — $deviceId. The device label is the end device ID, for example thermostat-a. The downlink in this guide reads it.
   • Customer name and Device group name — empty.
   • Telemetry — fCnt, data, decoded, latitude, longitude, altitude, rssi, snr, and channel.
   • Attributes — eui, devAddr, fPort, bandwidth, spreadingFactor, codeRate, frequency, brandId, modelId, hardwareVersion, firmwareVersion, attributes, and tenantId.
   • Update only keys list — the same keys as Attributes. They are stored only when their value changes.

   The Telemetry and Attributes lists add network keys from Decoder Inputs to the decoder output. They do not filter it: every key the decoder returns is stored. A key that the message does not carry, or that the decoder already returns, is skipped.

8. Click Test payload decoder and check the result (see Test the Decoder).

9. Click Add.

To adapt:

• Byte layout — change the offset and length in each parseBytesToInt() call, and rename or add keys to match your device.
• Payload formatter — if The Things Stack decodes the payload, metadata.payloadFormat is JSON and payload holds the formatter result. Read the values from parsed instead of parsed.bytes, for example values: { temperature: parsed.temperature }.
• Device name — change the Device name pattern, for example to $deviceId, or set result.name in the decoder.
• Network keys — remove keys from Telemetry or Attributes that you do not need, for example data, which stores the raw payload as a Base64 string.

Use the Converters Library

The Converters library holds ready-made decoders for devices of vendors such as Milesight, Elsys, Decentlab, and Bosch.

1. Go to Integrations ⇾ Data converters and click + Add data converter ⇾ Create new converter.
2. Converter type — keep Uplink.
3. Integration type — select The Things Stack Community.
4. Click Library.
5. Vendor — select the manufacturer of your device.
6. Model — select the device model. ThingsBoard fills in the Name from the vendor and model, and loads the decoder.
7. Review the decoder and the Advanced decoding parameters, then click Add.

A library decoder is written for one device model and its payload layout. Some library entries are written as Generic converters: they get the whole The Things Stack message as payload, parse it themselves, and show only Update only keys list in Advanced decoding parameters. Their test button is Test decoder function. To test such a decoder, paste the full uplink message from Decoder Inputs as the payload.

Decoder Inputs

The Things Stack publishes each uplink as a JSON message. This one comes from the example device, with the payload 00 BC 61 4E 5F 09 29 50:

{
  "end_device_ids": {
    "device_id": "thermostat-a",
    "application_ids": {
      "application_id": "my-thingsboard"
    },
    "dev_eui": "70B3D57ED80054FE",
    "dev_addr": "260B1234"
  },
  "correlation_ids": ["as:up:01JB8Y2P3Q4R5S6T7V8W9X0YZA"],
  "received_at": "2026-10-22T09:15:30.512Z",
  "uplink_message": {
    "f_port": 1,
    "f_cnt": 12,
    "frm_payload": "ALxhTl8JKVA=",
    "rx_metadata": [
      {
        "gateway_ids": {
          "gateway_id": "my-gateway"
        },
        "rssi": -62,
        "channel_rssi": -62,
        "snr": 9.5
      }
    ],
    "settings": {
      "data_rate": {
        "lora": {
          "bandwidth": 125000,
          "spreading_factor": 7
        }
      },
      "frequency": "868100000"
    },
    "received_at": "2026-10-22T09:15:30.498Z"
  }
}

The converter passes the decoder two variables:

Network keys that the converter reads from the message. A key is missing if its field is missing or null:

The converter also reads correlationIds, rxMetadata, sessionKeyId, codeRate, dataRateIndex, consumedAirtime, attributes, and the other fields of uplink_message. Check the Metadata of a converter event for the full list.

• payloadFormat — BINARY when payload holds the raw bytes, JSON when it holds the formatter result.
• ts — the time of uplink_message.received_at in milliseconds, for example 1792660530498. If it is missing, received_at, and if that is missing too, the current time.

Test the Decoder

1. Click Test payload decoder below the editor.
2. Click Updated RAW payload, paste the message from Decoder Inputs, and apply it. ThingsBoard unwraps it: the payload becomes ALxhTl8JKVA= with Payload content type Binary (Base64), and Metadata fills with the network keys.
3. Click Test.

Decoder output shows the object returned by the decoder:

{
  "attributes": {
    "sn": 12345678
  },
  "telemetry": {
    "ts": 1792660530498,
    "values": {
      "battery": 95,
      "temperature": 23.45,
      "saturation": 80
    }
  }
}

Converter output shows the data ThingsBoard stores: the device name Device 70B3D57ED80054FE, the profile my-thingsboard, the label thermostat-a, the decoded keys, and the network keys from the Telemetry and Attributes lists, such as rssi, snr, fCnt, eui, and fPort. If the output is empty or shows an error, fix the decoder and test again.

1. Go to Integrations ⇾ Integrations and click + Add integration.
2. Basic settings:
   • Integration type — select The Things Stack Community.
   • Name — keep the default The Things Stack Community integration or enter your own.
   • 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 TTN Uplink Converter.
   • Alternatively, click Create new to write a decoder here, or Library to take one from the Converters library.
   • Click Next.
4. Downlink data converter:
   • Click Skip. Add a downlink converter later if you need to send downlinks.
5. Connection:
   • Host type — keep Region.
   • Region — the ID of your cluster, for example eu1. ThingsBoard adds .cloud.thethings.network, shown next to the field.
   • Port — keep 8883.
   • Username — the application ID followed by @ttn, for example my-thingsboard@ttn.
   • Password — the API key.
   • Keep Enable SSL and Use API v3 on.
   • Leave the other parameters at their defaults. See Connection Settings for details.
6. Optionally, click Check connection to test the connection to the MQTT server.
7. Click Add.

The integration connects and subscribes right away.

The integration always connects with a clean session.

Simulate an uplink in The Things Stack Console, then confirm that ThingsBoard decoded it and created the device.

1. In The Things Stack Console, open the application, go to End devices, and click thermostat-a.
2. Open the Messaging tab and select Simulate uplink.
3. Keep FPort at 1.
4. In Payload, enter 00BC614E5F092950.
5. Click Simulate uplink. A message confirms that the uplink was sent.

The payload holds the values that the decoder reads: sn = 12345678, battery = 95, temperature = 23.45, and saturation = 80.

Open End devices and select the registered device (thermostat-a). Open Messaging → Simulate uplink, keep FPort set to 1, enter the payload 00 BC 61 4E 5F 09 29 50, and click Simulate uplink. A success notification confirms that the uplink message was sent.

• Integration events — go to Integrations ⇾ Integrations, open the integration, and click the Events tab. The uplink appears as an event of type Uplink with status OK. Click ⋅⋅⋅ in the Message column to see the MQTT topic, for example v3/my-thingsboard@ttn/devices/thermostat-a/up, and the full message.
• Converter events — open TTN Uplink Converter in Integrations ⇾ Data converters and click the Events tab. In and Metadata show the message as it came from The Things Stack, before the converter unwrapped it. Out shows the decoder output only, without the network keys.
• Device — go to Devices & assets ⇾ Devices. The integration has created the device Device 70B3D57ED80054FE, named after your DevEUI, with the profile my-thingsboard and the label thermostat-a. Open it and check:
  • Latest telemetry — battery, temperature, and saturation, plus the network keys that the message carries, such as rssi, snr, fCnt, and data.
  • Attributes — sn, eui, devAddr, fPort, and the other network keys in Client attributes.

ThingsBoard publishes each downlink right away to the downlink topic of the device, with QoS 1. Nothing is queued in ThingsBoard. The Things Stack adds the downlink to the device queue (/down/push) and sends it in a receive window after the next uplink of the device.

The downlink converter turns a Rule Engine message into a The Things Stack downlink message and returns the end device ID for the topic. In this guide, a change of a shared attribute sends the changed attributes to the device as JSON. For the full encoder reference, see Downlink data converter.

1. Open the integration in Integrations ⇾ Integrations and click Toggle edit mode (pencil icon).
2. In the Downlink data converter field, click Create new.
3. Enter a name, for example TTN Downlink Converter.
4. Main encoding configuration opens in TBEL with a generic encoder that builds an MQTT topic from the device name, not the message that The Things Stack needs. Replace it with the encoder below. For JavaScript, use the TBEL / JS toggle and the JavaScript tab.
5. To record downlink events, click the debug button next to the name, select All messages, and click Apply.
6. Click Add.
7. Click Apply changes.

Encoder used in this guide. It encodes the message as JSON, puts it in Base64 into frm_payload, and sends it on the port of the last uplink. The rule chain adds the end device ID to the metadata as devId, and the fPort client attribute as cs_fPort.

/** Encoder **/

// End device ID in The Things Stack, for example thermostat-a.
// The rule chain adds it to the metadata from the device label.
var devId = metadata.devId;
if (devId == null || devId == "") {
    raiseError("Missing required metadata field: devId");
}

// LoRaWAN port: the fPort client attribute, stored from the last uplink.
if (metadata.cs_fPort == null) {
    raiseError("Missing required metadata field: cs_fPort");
}
var fPort = parseInt("" + metadata.cs_fPort);
if (fPort < 1 || fPort > 223) {
    raiseError("Invalid LoRaWAN port. Expected a value from 1 to 223.");
}

// The message as JSON, for example {"powerState":"on"}, in Base64.
var frmPayload = bytesToBase64(stringToBytes(JSON.stringify(msg)));

var data = {
    downlinks: [
        {
            f_port: fPort,
            frm_payload: frmPayload,
            confirmed: false,
            priority: "NORMAL"
        }
    ]
};

return {
    contentType: "JSON",
    data: JSON.stringify(data),
    metadata: {
        // Replaces ${devId} in the downlink topic pattern.
        devId: devId
    }
};

/** Encoder **/

// UTF-8 string to Base64.
function utf8ToBase64(value) {
    var binary = encodeURIComponent(value).replace(/%([0-9A-F]{2})/g, function (match, hex) {
        return String.fromCharCode(parseInt(hex, 16));
    });
    return btoa(binary);
}

// End device ID in The Things Stack, for example thermostat-a.
// The rule chain adds it to the metadata from the device label.
var devId = metadata.devId;
if (devId === undefined || devId === null || devId === '') {
    throw new Error('Missing required metadata field: devId');
}

// LoRaWAN port: the fPort client attribute, stored from the last uplink.
if (metadata.cs_fPort === undefined || metadata.cs_fPort === null) {
    throw new Error('Missing required metadata field: cs_fPort');
}
var fPort = parseInt('' + metadata.cs_fPort, 10);
if (isNaN(fPort) || fPort < 1 || fPort > 223) {
    throw new Error('Invalid LoRaWAN port. Expected a value from 1 to 223.');
}

// The message as JSON, for example {"powerState":"on"}, in Base64.
var frmPayload = utf8ToBase64(JSON.stringify(msg));

var data = {
    downlinks: [
        {
            f_port: fPort,
            frm_payload: frmPayload,
            confirmed: false,
            priority: 'NORMAL'
        }
    ]
};

return {
    contentType: 'JSON',
    data: JSON.stringify(data),
    metadata: {
        // Replaces ${devId} in the downlink topic pattern.
        devId: String(devId)
    }
};

To check the encoder, click Test encoder function. Replace the Message with {"powerState": "on"}, add devId = thermostat-a and cs_fPort = 1 to Metadata, and click Test. The Output panel shows:

{
  "contentType": "JSON",
  "data": "{\"downlinks\":[{\"f_port\":1,\"frm_payload\":\"eyJwb3dlclN0YXRlIjoib24ifQ==\",\"confirmed\":false,\"priority\":\"NORMAL\"}]}",
  "metadata": {
    "devId": "thermostat-a"
  }
}

The integration reads these fields from the encoder result:

To set a fixed port, replace fPort with a number, for example f_port: 2. To send only one key, replace JSON.stringify(msg) with JSON.stringify({ powerState: msg.powerState }). For a device that expects bytes, build them instead of JSON, and encode them with bytesToBase64.

The encoder needs the end device ID and the port. Add them to the metadata, then pass the message to the integration.

1. Go to Data processing ⇾ Rule chains and open the Root Rule Chain.
2. From the Enrichment section, drag an originator attributes node onto the canvas:
   • Name — for example Add fPort.
   • Client attributes — fPort. The node adds it to the metadata as cs_fPort.
   • Add originator attributes to — keep Metadata.
   • Click Add.
3. From the Enrichment section, drag an originator fields node onto the canvas:
   • Name — for example Add Device ID.
   • Under Originator fields mapping, set Source field to Label and Target key to devId.
   • Add mapped originator fields to — keep Metadata.
   • Click Add.
4. From the Action section, drag an integration downlink node onto the canvas:
   • Name — for example Downlink to TTN.
   • Integration — select The Things Stack Community integration.
   • Click Add.
5. Connect the message type switch node to Add fPort with the Attributes Updated relation.
6. Connect Add fPort to Add Device ID with the Success relation.
7. Connect Add Device ID to Downlink to TTN with the Success relation.
8. Click Apply changes.

Use only Attributes Updated. The integration stores client attributes with every uplink, so a Post attributes relation would send a downlink after every uplink.

1. Go to Devices & assets ⇾ Devices and open the device created in Test Uplink.
2. On the Attributes tab, select Shared attributes and click +.
3. Enter Key powerState, keep the String type, enter Value on, and click Add.

• Converter events — open TTN Downlink Converter in Integrations ⇾ Data converters and click the Events tab. In shows the message {"powerState": "on"} with devId and cs_fPort in its metadata. Out shows the downlinks data and devId.
• Integration events — open the integration’s Events tab. Two events appear: Downlink: ATTRIBUTES_UPDATED for the message from the Rule Engine, and Downlink with status OK for the publish, with the topic, for example v3/my-thingsboard@ttn/devices/thermostat-a/down/push, and the payload in its message.
• The Things Stack — open the end device in the console and click Live data. The downlink appears in the list. Select it to see the payload and the port.

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 — Typed and Generic converters, the Converters library, and the output format.
• Downlink data converter — encoder reference.
• The Things Stack Industries integration — connect to a private The Things Industries deployment.
• integration downlink node — route Rule Engine messages to an integration.
• originator attributes node — add attributes of the message originator to the metadata.
• originator fields node — add fields of the message originator, such as the label, to the metadata.
• message type switch node — route messages by type, for example attribute updates.
• Remote Integration — run the integration outside the ThingsBoard cluster.
• TBEL — built-in functions and syntax for converter scripts.
• The Things Stack MQTT server — topics, credentials, and the downlink message format.
• The Things Stack payload formatters — decode payloads in The Things Stack before they reach ThingsBoard.