The Things Stack Industries Integration

The Things Stack Industries integration connects ThingsBoard to a private The Things Industries (TTI) LoRaWAN network server over MQTT. ThingsBoard subscribes to the TTI MQTT API, receives uplink messages from your LoRaWAN devices, decodes the payload via the uplink converter, and stores the result as ThingsBoard telemetry and attributes. Downlink is optional: when configured, ThingsBoard encodes Rule Engine messages via the downlink converter and publishes them back to TTI, which delivers them to the device.

Use this integration when your LoRaWAN infrastructure runs on a private The Things Industries tenant rather than the public The Things Network. For public TTN connectivity, see the The Things Stack Community integration.

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 a The Things Industries account with at least one registered application and device.
• At least one device is registered in your TTI application and is sending uplinks. If you have not registered a device yet, follow the Register an End Device step below.

1. Log in to the The Things Industries console.
2. Go to the Applications section and click Add application.
3. Enter an Application ID — e.g. thingsboard-integration.
4. Click Create application.

Open the Applications section and click Add application. Enter an Application ID (for example, my-thingsboard) and click Create application.

TTI exposes an MQTT broker for each application. ThingsBoard uses the credentials from this integration to subscribe to device uplinks and publish downlinks.

1. In the TTI console, open your application and go to Other integrations → MQTT.
2. Copy the Username and click Generate new API key to obtain the Password.
3. Save both values — you will need them when configuring the ThingsBoard integration.

Open Other integrations → MQTT in your application. Copy the Public TLS address and the Username, then click Generate new API key. After the API key is generated, copy and save it securely. Use the Username as the MQTT username and the generated API key as the MQTT password when configuring the ThingsBoard integration.

1. In the application, open End devices and click Add end device.
2. Configure the End device type:
   • Under Input method, select Enter end device specifics manually.
   • Frequency plan — e.g. Europe 863-870 MHz (SF9 for RX2 - recommended).
   • LoRaWAN version — e.g. LoRaWAN Specification 1.0.0.
3. Click Show advanced activation, LoRaWAN class and cluster settings and set Activation mode to Activation by personalization (ABP).
4. Fill in the Provisioning information:
   • DevEUI — click Generate. This becomes the device identifier in ThingsBoard.
   • Device address — click Generate.
   • AppSKey — click Generate.
   • NwkSKey — click Generate.
   • End device ID — e.g. thermostat-a. This value is used to route downlink messages.
5. Click Add end device.

Open End devices, click Register end device, select Enter end device specifics manually, choose the appropriate frequency plan, LoRaWAN version, and Regional Parameters version. Expand Advanced activation, LoRaWAN class and cluster settings, select Activation by personalization (ABP), and keep the default network settings. In the Provisioning information section, generate or enter the DevEUI, Device address (DevAddr), AppSKey, and NwkSKey values required for ABP activation. Enter an End device ID, review the generated credentials, and click Register end device to create the device.

The uplink converter receives each TTI uplink message, decodes the LoRaWAN payload, and returns a structured object that ThingsBoard uses to create or update a device and store its telemetry and attributes.

If your device is in the built-in catalog, use the Library tab instead of writing a decoder — see Converters library for over 100 ready-made decoders.

For the full decoder function reference — all input parameters and output fields — see Uplink data converter.

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 The Things Stack and select The Things Stack Industries from the list.
5. Name — enter a converter name, for example TTI Uplink Converter.
6. Configure main decoding parameters:
   • Device name — the default value Device $eui names each ThingsBoard device using the DevEUI from the uplink message (e.g. Device ABABABABABABABAA). On the first uplink ThingsBoard creates the device; on subsequent uplinks it updates the existing one.
   • The default decoder is pre-filled. Leave it unchanged for this guide.
     By default the editor opens in TBEL; use the TBEL / JS toggle (upper right) to switch languages.
   • 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 Industries 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.
       var parsed = decodeToJson(input);
       if (parsed.bytes == null) {
         throw new Error("Payload formatter output does not contain a 'bytes' field. " +
             "Update this decoder to match your formatter's output structure.");
       }
       bytes = parsed.bytes;
     } else {
         // payloadFormat is 'BINARY' when no payload formatter is configured — raw bytes from frm_payload are passed directly.
         bytes = input;
     }
   
     // Decode serial number (SN) from the first 4 bytes of the payload.
     // Press '?' icon in the top right corner to learn more about built in helper functions and capabilities.
     result.attributes.sn = parseBytesToInt(bytes, 0, 4);
   
     // Extract the timestamp from metadata (represented in milliseconds).
     var timestamp = metadata.ts; // ts is the timestamp parsed from the incoming message's time, or returns the current time if it cannot be parsed.
   
     // Combine the timestamp with decoded values and add it to the telemetry.
     result.telemetry = {
       ts: timestamp,
       values: {
         // Decode battery level from the 5th byte of the payload.
         battery: parseBytesToInt(bytes, 4, 1),
         // Decode temperature from the 6th and 7th bytes of the payload (divided by 100).
         temperature: parseBytesToInt(bytes, 5, 2) / 100.0,
         // Decode saturation from the 8th byte of the payload.
         saturation: parseBytesToInt(bytes, 7, 1)
       }
     };
   
     // Return the fully constructed output object.
     return result;
     // Same logic, less code:
     // return {
     //     attributes: {
     //         sn: parseBytesToInt(bytes, 0, 4)
     //     },
     //     telemetry: {
     //         ts: convertDateToTimestamp(extractDateFromMetadata()),
     //         values: {
     //             battery: parseBytesToInt(bytes, 4, 1),
     //             temperature: parseBytesToInt(bytes, 5, 2) / 100.0,
     //             saturation: parseBytesToInt(bytes, 7, 1)
     //         }
     //     }
     // };
   }
   
   var result = decodePayload(payload);
   // Uncomment this code block to overwrite values set in the main configuration window. Useful if you extract device/asset/customer/group names from the payload;
   // result.type = 'DEVICE'; // Entity type allows you to choose type of created entity. Can be 'DEVICE' or 'ASSET'.
   // result.name = 'Temperature Sensor'; // Device or asset name (the value must be unique)
   // result.profile = 'IndustrialSensorProfile'; // Device or asset profile name.
   // result.customer = 'MyCustomer'; // If customer is not null - created entity will be assigned to customer with such name.
   // result.group = 'SensorsGroup'; // If group is not null - created entity will be added to the entity group with such name.
   
   // Return the final result object.
   return result;

7. Review advanced decoding parameters — pre-populated for The Things Stack Industries; leave defaults unless your setup differs.

   These parameters control TTI network metadata — signal quality, location, and LoRa settings that ThingsBoard extracts automatically from each uplink message. The decoder script controls device sensor data — the fields written to result.attributes and result.telemetry.values.

   The default telemetry keys extracted from TTI messages include: fCnt, data, decoded, latitude, longitude, altitude, rssi, snr, channel.

   The default attribute keys include: eui, devAddr, fPort, bandwidth, spreadingFactor, codeRate, frequency, brandId, modelId, hardwareVersion, firmwareVersion, attributes, tenantId.

8. Click Add.

What the Converter Receives

ThingsBoard passes two variables to the decoder function:

Key metadata fields available in the decoder:

Example: BINARY Payload Decoded

The decoder reads byte ranges using parseBytesToInt(input, offset, length) and produces:

Example payload (hex):

00BC614E5F092950

Example output:

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

Adapting the Converter

• Different device name — change the Device name pattern in Main decoding configuration (e.g. replace Device $eui with $deviceId or a fixed string).
• Different byte layout — adjust the offset and length in each parseBytesToInt() call to match your payload structure.
• TTI payload formatter configured — if your TTI application has a JavaScript formatter, ThingsBoard receives the formatter’s output as a JSON object (payloadFormat == 'JSON'). Update the parsed.bytes extraction to match your formatter’s output structure, or map decoded fields directly: values: { temperature: parsed.temperature }.
• Additional attributes — add more keys to result.attributes (e.g. result.attributes.firmwareVersion = parsed.fw).

1. Go to Integrations center ⇾ Integrations and click + Add integration.
2. Basic settings:
   • Select The Things Stack Industries as the integration type.
   • Enter a Name for the integration, or keep the default The Things Stack Industries integration.
   • Enable integration and Allow create devices or assets are enabled by default.
   • Click Next.
3. Uplink data converter:
   • Click Select existing and choose the TTI Uplink Converter created in the previous step.
   • Alternatively, click Create new to define the decoder inline, or use Library to load a vendor-provided preset.
   • Click Next.
4. Downlink data converter:
   • Click Skip — the downlink converter is only needed for sending commands to devices and can be added later.
5. Connection settings:
   • Host type — leave Region selected.
   • Region — enter the identifier of the TTI cluster where your application is registered (e.g. eu1). ThingsBoard constructs the broker hostname as {region}.cloud.thethings.industries.
   • Port — 8883.
   • Credentials:
   • Username — the username from the TTI MQTT integration (e.g. my-thingsboard@thingsboard-test).
   • Password — the API key generated in the Obtain MQTT Credentials step.
   • Enable SSL is on by default — leave it enabled.
   Read more about each parameter in Connection Settings.
6. Optionally click Check connection — the wizard shows Connected when successful.
7. Click Add to complete the integration setup.

Click Add integration, select The Things Stack Industries as the integration type, enter a name, and click Next. Select TTI Uplink Converter as the uplink data converter and click Next. If downlink support is not required, click Skip. Otherwise, select a downlink converter and continue. Configure the connection settings using the MQTT credentials from your TTI application. Set Host type to Region, specify the region (for example, eu1), keep port 8883, enter the MQTT username and API key, and leave Enable SSL enabled. Click Check connection to verify connectivity. When the status changes to Connected, click Add to create the integration.

Host Type

Port

Credentials

Enable SSL

Encrypts the MQTT connection using TLS. Enabled by default and required for all connections to TTI clusters (port 8883). Disable only when connecting to a local deployment on port 1883.

Topic Filters

Defines which MQTT topics ThingsBoard subscribes to for uplink messages.

Downlink Topic Pattern

MQTT topic used to publish downlink messages to TTI. Default: v3/{username}/devices/${devId}/down/push, where {username} is the MQTT username (including the @tenantId suffix) and ${devId} is resolved from metadata.devId in the downlink converter output.

Execute Remotely

When enabled, ThingsBoard generates an Integration key and Integration secret that let the integration run as a separate process outside the ThingsBoard cluster — useful when the TTI broker is only reachable from a local network.

Advanced Settings

After the integration is created, send a test uplink and confirm that ThingsBoard received the message, decoded it correctly, and provisioned the device.

Use the TTI console to simulate an uplink from the registered end device.

1. In the TTI console, go to End devices and open thermostat-a — or the end device you registered earlier.
2. Open the Messaging tab and click Simulate uplink.
3. Leave FPort at its default value (1).
4. In the Payload field, enter the test payload:

   00BC614E5F092950

5. Click Simulate uplink. A Success — Uplink sent toast confirms the message was accepted.

This payload matches the byte layout from the uplink converter: sn = 12345678, battery = 95, temperature = 23.45, saturation = 80.

Open the End devices page and select the registered device. Open Messaging → Simulate uplink, keep FPort set to 1, enter the payload 00 BC 61 4E 5F 09 29 50, and click Simulate uplink.

Go to Integrations center ⇾ Integrations, open The Things Stack Industries integration, and click the Events tab. Each successfully processed uplink appears as a row with status OK.

Open the Events tab of the The Things Stack Industries integration to review received uplink messages and verify their processing status. Open an uplink event to inspect the raw message payload received from The Things Stack Industries before it is forwarded to the uplink converter.

To inspect converter processing, go to Integrations center ⇾ Data converters, click TTI Uplink Converter, and open its Events tab:

• In — the raw TTI message passed to the decoder.
• Out — the decoded result: attributes and telemetry values written to ThingsBoard.
• Metadata — the integration name and MQTT topic associated with the message.

Open the Events tab of the TTI Uplink Converter to review converter execution history and inspect individual message processing results. The In view displays the raw uplink message received from The Things Stack before conversion. The Out view displays the converter output, including the device attributes and telemetry values that are stored in ThingsBoard. The Metadata view contains processing details such as the integration name and the MQTT topic used to receive the uplink message.

Go to Entities ⇾ Devices. ThingsBoard automatically provisions a new device named Device <DevEUI> (e.g. Device 70B3D57ED80054FE) on the first uplink from each end device. Open the device and click the Latest Telemetry tab — you should see temperature, battery, and saturation decoded by the converter, plus network metadata fields such as rssi, snr, and latitude extracted from the TTI message.

After the first uplink message is received, ThingsBoard automatically creates a device using the DevEUI as the device name. Open the device and navigate to the Attributes tab to verify that the attributes generated by the uplink converter were imported successfully. Open the Latest telemetry tab to confirm that the telemetry values decoded by the uplink converter were successfully stored in ThingsBoard.

To send a command to a TTI device from ThingsBoard, the Root Rule Chain must forward attribute changes to the TTI integration.

Two rule nodes are needed: an originator fields node that reads the TTI End device ID from the ThingsBoard device Label and injects it into message metadata, and an integration downlink node that sends the message to the integration.

1. Open Rule Chains ⇾ Root Rule Chain and click the edit icon.
2. In the node panel, search for originator fields and drag it onto the canvas.
3. Configure the node:
   • Name — e.g. Retrieve Device ID.
   • Under Originator fields mapping, set Source field to Label and Target key to devId.
   • Set Add mapped originator fields to to Metadata.
   • Click Add.
4. In the node panel, search for integration downlink and drag it onto the canvas.
5. Configure the node:
   • Name — e.g. Downlink to TTI.
   • Integration — select The Things Stack Industries integration.
   • Click Add.
6. Connect the message type switch node to the originator fields node using the Post attributes and Attributes Updated relations.
7. Connect the originator fields node to the integration downlink node using the Success relation.
8. Click Apply changes.

Open the Root Rule Chain in edit mode and search for the originator fields node in the node panel. Set the name to Retrieve Device ID, map Source field: Label to Target key: devId, select Metadata as the destination, and click Add. Place the Retrieve Device ID node on the canvas and connect the Post attributes / Attributes Updated relation to its input. Search for the integration downlink node in the node panel. Set the name to Downlink to TTI, select The Things Stack Industries integration, and click Add. Connect the Success relation from Retrieve Device ID to Downlink to TTI, then click Apply changes to save the rule chain.

The downlink converter receives a Rule Engine message and encodes it into a TTI-compatible downlink payload. The converter output must follow this structure:

{
  "contentType": "JSON",
  "data": "{\"downlinks\":[{\"f_port\":2,\"frm_payload\":\"e3Bvd2VyU3RhdGU9b259\",\"priority\":\"NORMAL\"}]}",
  "metadata": {
    "devId": "thermostat-a"
  }
}

For the full encoder function reference, see Downlink data converter.

Add the downlink converter to the existing integration:

1. Go to Integrations center ⇾ Integrations and open The Things Stack Industries integration.
2. Click the pencil icon to enter edit mode.
3. In the Downlink data converter field, click Create new.
4. Enter a name (e.g. TTI Downlink Converter), paste the encoder script below, and click Add.
5. Click Apply changes to save the integration.

var devId = metadata.devId;

var data = {
  downlinks: [{
    f_port: 2,
    confirmed: false,
    frm_payload: btoa(msg),
    priority: "NORMAL"
  }]
};

var result = {
  contentType: "JSON",
  data: JSON.stringify(data),
  metadata: {
    devId: devId
  }
};

return result;

var devId = metadata.devId;

var data = {
  downlinks: [{
    f_port: 2,
    confirmed: false,
    frm_payload: btoa(msg),
    priority: "NORMAL"
  }]
};

var result = {
  contentType: "JSON",
  data: JSON.stringify(data),
  metadata: {
    devId: devId
  }
};

return result;

The originator fields node injects metadata.devId from the ThingsBoard device’s Label. The full Rule Engine message is serialized to JSON and base64-encoded into frm_payload.

To adapt this converter:

• Different port — change f_port to match the LoRaWAN port your device listens on.
• Confirmed downlink — set confirmed: true to request an acknowledgement from the device. Use with caution — unacknowledged confirmed frames consume retries and may delay subsequent messages.
• Selective payload — to send only a specific field, replace btoa(msg) with btoa(JSON.stringify({ key: msg.key })).
• Different device routing — metadata.devId is populated from the device Label by the Originator fields node. If your ThingsBoard devices use a different field to store the TTI End device ID, update the Originator fields node mapping accordingly.

Open the The Things Stack Industries integration. Initially, the Downlink data converter field is empty. Click the Edit (pencil) button to enter edit mode, then click Create new in the Downlink data converter field. Create a new Downlink data converter, enter the name TTI Downlink Converter, paste the encoder function into the editor, and click Add. After the converter is attached to the integration, click Apply changes to save the updated configuration.

Trigger a downlink by adding a shared attribute to the ThingsBoard device provisioned during the uplink test:

1. Go to Entities ⇾ Devices, open the device provisioned by the integration, and open the Attributes tab.
2. Switch to Shared attributes and click +.
3. Set the key (e.g. powerState) and a value (e.g. on).
4. Click Add.

To verify the downlink was processed, go to Integrations center ⇾ Data converters, open TTI Downlink Converter, and click the Events tab. Click an event row to inspect:

• In — the Rule Engine message received by the converter: msg contains the attribute payload; metadata.devId contains the TTI End device ID injected by the Originator fields node.
• Out — the encoded output sent to TTI: a JSON downlinks array with frm_payload base64-encoded from the message body.

Open the TTI Downlink Converter and navigate to the Events tab. A Downlink event confirms that the converter was executed. Open the In panel to inspect the Rule Engine input. The msg object contains the attribute update payload, while metadata.devId contains the TTI End device ID added by the Originator fields node. Open the Out panel to verify the converter output. The converter generates a JSON payload containing a downlinks array with the base64-encoded frm_payload that will be forwarded to TTI.

Go to the TTI console, open End devices ⇾ thermostat-a (or your device), and click the Live data tab — the downlink event appears in the list.

Open the target device in The Things Stack and navigate to the Live data tab. A Receive downlink data message event confirms that the downlink generated by ThingsBoard was delivered to the device. Open the event details to inspect the generated downlink. Verify the f_port, frm_payload, device identifiers, and correlation information to confirm that the payload created by the ThingsBoard downlink converter was successfully forwarded through TTI.

This section covers the most common problems encountered when setting up and running the The Things Stack Industries integration. Each entry describes the symptom, the most likely cause, and the steps to resolve it.

No Uplinks Received

Uplink Received but Device Not Created

Telemetry Fields Missing or Have Wrong Values

Downlink Not Delivered

Connection Check Fails

How to Read Debug Events

1. Go to Integrations center ⇾ Integrations, open The Things Stack Industries integration, and click the Events tab.
2. Click an event row to inspect:
   • In — the raw MQTT message received from TTI before processing.
   • Out — what the converter returned: device name, attributes, and telemetry values passed to ThingsBoard.
   • Error — error text and stack trace, if processing failed.
3. For converter-level details, go to Integrations center ⇾ Data converters, open TTI Uplink Converter, and click the Events tab — the same In / Out / Error panels are available there.

Enable Debug mode on the integration to capture all raw input/output events. Starting from ThingsBoard 3.9, full debug events are stored only during the first hour — afterward, only error events are retained. Disable debug mode once the issue is identified.

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