LORIOT Integration

The LORIOT integration connects ThingsBoard to a LORIOT LoRaWAN Network Server over HTTP. LORIOT pushes uplink messages from your LoRaWAN devices to a ThingsBoard HTTP endpoint; the uplink converter decodes each message and stores the result as device telemetry and attributes on the platform. In the reverse direction, ThingsBoard encodes Rule Engine messages via the downlink converter and delivers them to devices through the LORIOT REST API.

Before creating the integration, ensure:

• You have access to ThingsBoard Cloud with integration functionality enabled for your tenant.
• You have permissions to create integrations and data converters.
• You have a LORIOT account with at least one registered application. If you do not have an account yet, follow the Register a LORIOT Account step below.

1. Go to the LORIOT website and choose a service package (e.g. Community Public Network Server).
2. Pick your preferred region and country, then complete the registration and log in.

Select a service package on the LORIOT website Choose your preferred region Complete the registration form LORIOT dashboard after successful login

You will need the server name and Application ID when configuring the integration connection settings and downlink output.

• Server — the subdomain in your LORIOT dashboard URL, for example eu1 from eu1.loriot.io.
• Application ID — listed on the Applications page next to your application name.

The server name is the subdomain in your LORIOT dashboard URL — for example, eu1 from eu1.loriot.io. The Application ID is listed on the Applications page next to your application name.

The uplink converter receives each LORIOT 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 Loriot and select Loriot from the list.
5. Name — enter a converter name, for example Loriot Uplink Converter.
6. Configure main decoding parameters:
   • Device name — the default value Device $eui names each ThingsBoard device using the EUI from the LORIOT uplink message (e.g. Device BE7A000000000552). On the first uplink ThingsBoard creates the device; on subsequent uplinks it updates the existing one. Change this pattern if you prefer a different naming scheme.
   • 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: {}};
   
     // 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(input, 0, 4);
   
     // Extract the timestamp from metadata (represented in milliseconds).
     var timestamp = metadata.ts; // ts from the incoming message.
   
     // Initialize an object to store decoded key/value telemetry data.
     var values = {};
   
     // Decode battery level from the 5th byte of the payload.
     values.battery = parseBytesToInt(input, 4, 1);
   
     // Decode temperature from the 6th and 7th bytes of the payload (divided by 100).
     values.temperature = parseBytesToInt(input, 5, 2) / 100.0;
   
     // Decode saturation from the 8th byte of the payload.
     values.saturation = parseBytesToInt(input, 7, 1);
   
     // Combine the timestamp with values and add it to the telemetry.
     result.telemetry = {
       ts: timestamp,
       values: values
     };
   
     // Return the fully constructed output object.
     return result;
     // Same logic, less code:
     // return {
     //     attributes: {
     //         sn: parseBytesToInt(input, 0, 4)
     //     },
     //     telemetry: {
     //         ts: metadata.ts,
     //         values: {
     //             battery: parseBytesToInt(input, 4, 1),
     //             temperature: parseBytesToInt(input, 5, 2) / 100.0,
     //             saturation: parseBytesToInt(input, 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 LORIOT; leave defaults unless your setup differs.

   The default telemetry keys extracted from LORIOT messages include: data, fCnt, rssi, snr.

   The default attribute keys include: eui, fPort, dr, freq.

8. Click Add.

Set Integration type to Loriot, enter the converter name, and configure the decoder. Paste the decoder script into the editor (TBEL recommended) and 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 assumes a fixed binary payload structure. It reads byte ranges using parseBytesToInt(input, offset, length) and produces:

Example payload (hex):

00BC614E5F092950

Example output:

{
  "attributes": { "sn": 12345678 },
  "telemetry": {
    "ts": 1690000000000,
    "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 a fixed string or a field extracted from the payload).
• Different byte layout — adjust the offset and length in each parseBytesToInt() call to match your payload structure.
• Different field names — rename battery, temperature, or saturation; add or remove fields as needed.
• Additional attributes — add more keys to result.attributes (e.g. result.attributes.firmwareVersion = parseBytesToInt(input, 8, 2)).

1. Go to Integrations center ⇾ Integrations and click + Add integration.
2. Basic settings:
   • Select Loriot as the integration type.
   • Enter a Name for the integration, or keep the default Loriot integration.
   • Enable integration and Allow create devices or assets are enabled by default — leave them enabled.
   • Click Next.
3. Uplink data converter:
   • Click Select existing and choose the Loriot 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:
   • Copy the HTTP endpoint URL — you will need it when configuring LORIOT.
   See Connection settings for a full description of each parameter.
6. Click Add to create the integration.

After the integration is created, copy the HTTP endpoint URL from the integration details panel — you will need it in the next step to configure LORIOT to push uplinks to ThingsBoard.

Go to Integrations center → Integrations, click + Add integration, select Loriot as the integration type, provide a name, and click Next. On the Uplink data converter step, click Select existing, choose Loriot Uplink Converter, and click Next. The Downlink data converter step is optional. Click Skip to continue. A downlink converter can be configured later if downlink support is required. Copy the generated HTTP endpoint URL from the Connection step. This URL will be used when configuring the webhook in LORIOT. Click Add to create the integration.

Base URL

The base address of the ThingsBoard server, used to construct the HTTP endpoint URL below. For ThingsBoard Cloud this is pre-filled automatically.

HTTP Endpoint URL

Auto-generated webhook endpoint for this integration. LORIOT sends uplink messages to this URL as HTTP POST requests. Copy it before closing the wizard — you will need it in the next step.

Create Loriot Application Output / Send Downlink

These two toggles share a common settings group. Enabling either one reveals the following shared fields:

Create Loriot Application output — when enabled, ThingsBoard automatically registers itself as an HTTP Push output in your LORIOT application via the LORIOT API, so no manual webhook configuration is needed. Enabling this additionally reveals:

Send downlink — when enabled, ThingsBoard can send commands to LORIOT devices via the LORIOT API. Enabling this additionally reveals:

Enable Security (Headers Filter)

When enabled, ThingsBoard validates an HTTP header on every incoming uplink request and rejects requests that do not carry the expected header/value pair. Click Add to define one or more Header / Value pairs.

Execute Remotely

When enabled, ThingsBoard generates an Integration key and Integration secret. Use these credentials to run the integration as a separate remote process — useful when the integration must reach services not accessible from the ThingsBoard server.

Advanced Settings

To receive uplinks, ThingsBoard must be registered as an HTTP output in your LORIOT application. Choose one of the two methods below — both result in the same data flow.

• Option A: HTTP Push (recommended)
• Option B: Automatic setup

Manually create an HTTP Push output in the LORIOT UI. No LORIOT credentials are stored in ThingsBoard.

1. In the LORIOT UI, go to Applications and open your application.
2. In the left sidebar, click Output.
3. Click + Add new output.
4. Select HTTP Push as the output type.
5. Paste the HTTP endpoint URL copied from the integration Connection step into the Target URL for POSTs field.
6. Click Add Output.

Go to Applications (1) and click your application to open it (2) Click Output in the left sidebar (3) Click + Add new output (4) Select HTTP Push (5), paste the ThingsBoard HTTP endpoint URL in Target URL for POSTs (6), and click Add Output (7) HTTP Push output created — LORIOT will now forward uplinks to ThingsBoard

To reject requests that don’t include specific HTTP headers, enable Enable security (Headers filter) in the integration settings.

1. Open the Loriot integration, click the edit (pencil) icon, and enable Enable security (Headers filter).
2. Click Add and enter a Header name and Value (e.g. authorization / secret).
3. Click Apply changes.
4. In the LORIOT HTTP Push output configuration, enter the same values in Custom header name and Custom header value, then click Accept.

Integration details — Enable security (Headers filter) is off by default; click the edit icon to modify Enable security (Headers filter), add the header name (e.g. authorization) and value; the Create Loriot Application output credentials are also visible in this view — click Apply changes when done In the LORIOT HTTP Push output, enter the same header name and value in Custom header name and Custom header value, then click Accept

When a device sends an uplink message via LORIOT, ThingsBoard automatically creates the device and stores its telemetry. If you do not have a physical device sending data, you can emulate a device message by sending an HTTP request directly to the ThingsBoard endpoint using curl — bypassing LORIOT entirely. This is useful to verify that the integration and uplink converter are configured correctly before connecting real hardware. To send a test uplink, you need the HTTP endpoint URL from the integration details.

Go to Integrations center ⇾ Integrations, open the Loriot integration, and copy the HTTP endpoint URL.

Replace $HTTP_ENDPOINT_URL with the copied URL and run:

Without security:

curl -v -X POST \
  -H "Content-Type: application/json" \
  -d '{"EUI":"BE7A000000000552","data":"00BC614E5F092950","port":1,"cmd":"rx","dr":"SF12 BW125 4/5","snr":1.2,"ack":"false","freq":868500000,"fcnt":1,"rssi":-130,"ts":1613745998000}' \
  "$HTTP_ENDPOINT_URL"

With security:

curl -v -X POST \
  -H "Content-Type: application/json" \
  -H "$HEADER:$VALUE" \
  -d '{"EUI":"BE7A000000000552","data":"00BC614E5F092950","port":1,"cmd":"rx","dr":"SF12 BW125 4/5","snr":1.2,"ack":"false","freq":868500000,"fcnt":1,"rssi":-130,"ts":1613745998000}' \
  "$HTTP_ENDPOINT_URL"

Once an uplink is received, a new device named Device BE7A000000000552 (matching the EUI field from the payload) appears in Entities ⇾ Devices:

Go to Entities → Devices (1) — the device is auto-created on the first uplink (2); open it and check the Attributes tab (3) — dr, eui, fPort, and frequency are stored as client attributes Latest telemetry tab — raw LORIOT fields: data, fCnt, rssi, snr

Go to Integrations center ⇾ Data converters, click the Loriot uplink converter, and open the Events tab — In shows the raw incoming payload bytes, Out shows the decoded result, Metadata shows all LORIOT message fields passed alongside the payload:

Go to Data converters (1), open the Loriot uplink converter (2), and navigate to the Events tab (3) — one Uplink event listed In — raw payload bytes passed to the decoder Out — decoded result with attributes and telemetry Metadata — HTTP request headers and all LORIOT message fields (EUI, cmd, data, fPort, rssi, snr, ts, etc.)

The downlink converter encodes ThingsBoard Rule Engine messages into LORIOT-compatible payloads. For the full encoder function reference, see Downlink data converter.

The encoder result must include two metadata fields required by the LORIOT API:

• EUI — the device EUI (see below)
• port — the LoRaWAN port (1–223)

To find the device EUI, go to the Devices section of your LORIOT application and open the device.

Go to the Devices section of your LORIOT application and click the device to open its details The device EUI is shown in the device details — copy it for use in the encoder metadata

1. Go to Integrations center ⇾ Data converters.
2. Click + Add data converter ⇾ Create new converter.
3. Enter a name: Loriot Downlink Converter, and set Type to Downlink.
4. Paste the encoder function below and click Add.

// Encode downlink data from incoming Rule Engine message
// msg        - JSON message payload
// msgType    - message type, e.g. 'ATTRIBUTES_UPDATED'
// metadata   - key-value pairs with additional message data
var result = {
    // downlink data content type: JSON, TEXT or BINARY (base64 format)
    contentType: "TEXT",
    // downlink data
    data: msg.firmware,
    // metadata must include EUI and port
    metadata: {
        "EUI": metadata.deviceName,
        "port": 1
    }
};
return result;

// Encode downlink data from incoming Rule Engine message
// msg        - JSON message payload
// msgType    - message type, e.g. 'ATTRIBUTES_UPDATED'
// metadata   - key-value pairs with additional message data
var result = {
    // downlink data content type: JSON, TEXT or BINARY (base64 format)
    contentType: "TEXT",
    // downlink data
    data: msg.firmware,
    // metadata must include EUI and port
    metadata: {
        "EUI": metadata.deviceName,
        "port": 1
    }
};
return result;

Go to Data converters (1), click + Add data converter → Create new converter (2): enter the name, set Type to Downlink, select TBEL (3), paste the encoder function, and click Add (4) To use JavaScript instead of TBEL: select the Java Script tab (3), paste the encoder function, and click Add (4)

After creating the converter, open the Loriot integration, click the edit icon, select Loriot Downlink Converter in the Downlink data converter field, and click Apply changes.

To send messages from ThingsBoard to LORIOT devices, enable Send downlink in the integration settings and provide the LORIOT API credentials.

1. Open the Loriot integration and click the edit icon.
2. Enable Send downlink and fill in the required fields:
   • Server — the LORIOT server subdomain (e.g. us1); see Finding server and application ID.
   • Application ID — the Application ID from your LORIOT project.
   • Downlink URL — auto-populated from Server/Application ID (e.g. https://us1.loriot.io/1/rest); override if your setup uses a custom endpoint.
   • Application Access Token — generate this in the Access Tokens section of your LORIOT application and paste it here.
3. Click Apply changes.

To trigger a downlink when a shared attribute changes, add an Integration Downlink node to the Root Rule Chain:

1. Open Rule Chains ⇾ Root Rule Chain and click the edit icon.
2. Add an Integration Downlink action node and connect it to the Message Type Switch node via the Attributes Updated relation.
3. Save the rule chain.

1. Go to Entities ⇾ Devices and open the device (e.g. Device BE7A000000000552).
2. Open the Attributes tab, switch to Shared attributes, and click +.
3. Enter key firmware and a value (e.g. 01052020.v1.1), then click Add.
4. Click the edit icon next to the attribute, change the value (e.g. to 01052020.v1.2), and click Update.

Open the device Shared attributes and add the firmware key with an initial value Edit the firmware value (e.g. 01052020.v1.2) and click Update — this triggers the downlink

Go to Integrations center ⇾ Data converters, click the Loriot Downlink Converter, and open the Events tab — In shows the incoming attribute update, Out shows the encoded payload sent to LORIOT:

In — the incoming ATTRIBUTES_UPDATED message with the new firmware value and device metadata Out — encoded downlink payload: contentType TEXT, data contains the firmware value, metadata includes EUI and port

To confirm the message reached LORIOT, open the device in the LORIOT UI, go to LoRaWAN Parameters, and check the Downlink Queue at the bottom of the page.

• Integration Overview
• Uplink Converters
• Downlink Converters
• Rule Engine
• ThingsBoard Expression Language (TBEL)