LORIOT Integration

LORIOT Integration receives device data from the LORIOT LoRaWAN network server through an HTTP Push output of a LORIOT application. An uplink data converter takes the device payload out of each LORIOT message and turns it into device data, including telemetry and attributes. For downlink, ThingsBoard sends commands to the device through the LORIOT REST API. In ThingsBoard, the integration type is called Loriot.

Use LORIOT Integration when:

• Your LoRaWAN devices are registered in a LORIOT application, and you want their data in ThingsBoard without writing a parser for the LORIOT message format.
• You need to send commands from ThingsBoard to those devices, for example when a shared attribute changes.

1. Receive data. The device sends an uplink through a LoRaWAN gateway to LORIOT. The HTTP Push output of the LORIOT application sends the message as an HTTP request with a JSON body to the integration endpoint.
2. Check the request (optional). If you turn on the headers filter, the integration rejects requests without the expected headers with 403 Forbidden.
3. Unwrap and decode. The uplink converter takes the device payload and the network details, such as eui, fPort, and rssi, out of the LORIOT message. Your decoder turns the payload into telemetry and attributes, and the converter adds the network details you selected. If Allow create devices or assets is on, ThingsBoard creates the device on its first message.
4. Send a command (optional). The Rule Engine passes a message to the integration. The downlink converter encodes it, and ThingsBoard sends it right away to the LORIOT REST API as a tx command. LORIOT delivers it to the device in the next receive window.

• Access to ThingsBoard Cloud with integrations enabled for your tenant. The ThingsBoard endpoint must be reachable from the internet, because LORIOT calls it.
• Permission to create integrations and data converters, and to edit rule chains for downlink.
• A LORIOT account. If you do not have one, create it first.
• A LoRaWAN device registered in a LORIOT application. Without hardware, test the uplink with curl and enroll a test device for downlink.

In LORIOT, devices belong to an application, and the application forwards device data to its outputs. Here you create the application, look up its server and ID, and enroll a device. The HTTP Push output comes later: it needs the integration endpoint, so you add it after creating the integration.

1. Go to the LORIOT website. Under Free Community Public Server, click Register Now.
2. Select a region, for example Europe ⇾ Amsterdam, NL.
3. On the login page, click Register a new account.
4. Fill in First Name, Last Name, Country, E-Mail, and Password. Accept the Terms of Service and click Create a free account.
5. Sign in. The LORIOT dashboard opens.

On the LORIOT website, choose Free Community Public Server and click Register Now. Select your region. For Europe, choose a cluster, for example Amsterdam, NL. On the login page, click Register a new account. Fill in the form, accept the Terms of Service, and click Create a free account. The LORIOT dashboard opens. The account is ready.

1. In the LORIOT dashboard, click Applications in the left menu.
2. Click + New LoRaWAN® Application.
3. Enter a Name, for example ThingsBoard. Set Device Capacity to the number of devices you plan to connect, and click Create.

Click Applications in the left menu. Click + New LoRaWAN® Application. Enter the Name, set the Device Capacity, and click Create. The application is created. Note the Application ID, for example BE010A45.

The integration needs both values to create the output automatically and to send downlinks.

• Server — the cluster code in the server selector in the upper-right corner of the LORIOT dashboard, for example EU2 for Amsterdam or EU1 for Frankfurt. Enter it in lowercase in ThingsBoard, for example eu2.
• Application ID — the value in the Application ID column on the Applications page, for example BE010A45.

Register your device in the application. Without hardware, enroll a test device with the EUI that the curl example in Test Uplink uses, so that LORIOT accepts downlinks for it.

1. In your LORIOT application, click Enroll Device in the left menu.
2. Select LoRaWAN® 1.0.x and keep Over the Air Activation.
3. Under Device Details, enter a Device name, for example my-device, and select Class A.
4. Set Device EUI to the EUI of your device, or to BE7A000000000552 for the test device. Autogenerate creates a new EUI: then use it in the curl example too.
5. Under Activation, JoinEUI is filled in automatically. Enter the AppKey of your device, or leave it empty for the test device.
6. Skip Location and click Create Device.

Click Enroll Device (1), select LoRaWAN 1.0.x (2), keep Over the Air Activation, enter the Device name, and select Class A (3). Enter the Device EUI or click Autogenerate (4). JoinEUI is filled in (5). Skip Location and click Create Device (6). The device is enrolled in the application.

Create the uplink converter and the integration, then add an HTTP Push output that points at the integration endpoint.

LORIOT Integration uses the Typed uplink converter. ThingsBoard selects it for the Loriot integration type, and you cannot change it later. Before your decoder runs, the converter unwraps the LORIOT message: the decoder gets the device payload bytes as payload, and the network details as metadata (see Decoder Inputs). The converter then adds the metadata keys you list in Telemetry and Attributes to the result. For the full reference, see Typed uplink converter.

If a ready-made decoder exists for your device model, take it from the library instead of writing one: see Use a Library Converter.

The decoder in this guide is the default LORIOT decoder. It skips messages that are not uplinks (cmd other than rx or gw) and maps:

• Bytes 0–3 ⇾ attribute sn.
• Byte 4 ⇾ telemetry battery.
• Bytes 5–6, divided by 100 ⇾ telemetry temperature.
• Byte 7 ⇾ telemetry saturation.

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

2. Converter type — keep Uplink.

3. Integration type — select Loriot.

4. Keep Create new. Library loads a decoder for a specific device model instead.

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

6. Main decoding configuration:

   • Entity type — keep Device.
   • Device name — keep Device $eui. $eui is replaced with the device EUI, so the device is named, for example, Device BE7A000000000552. Any metadata key works as $key.
   • The decoder editor shows the function header function payloadDecoder(payload, metadata) and opens in TBEL. Replace the body with the decoder below. 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) {
       var result = { attributes: {}, telemetry: {}};
   
       // Serial number (SN) from the first 4 bytes of the payload.
       result.attributes.sn = parseBytesToInt(input, 0, 4);
   
       // Timestamp of the LORIOT message, in milliseconds.
       var timestamp = metadata.ts;
   

   ▼Expand

   To adapt:

   • Byte layout — change the offset and length of each parseBytesToInt() call to match your payload.
   • JSON payload — if LORIOT decodes the payload for you, the message has a decoded object, and payload holds that object as JSON. Read it with decodeToJson(payload) in TBEL, or JSON.parse(String.fromCharCode.apply(String, payload)) in JavaScript.
   • Device name — change the Device name pattern, or set result.name in the decoder.

7. Advanced decoding parameters — the fields are pre-filled for LORIOT. Keep them, or edit the lists:

   • Device profile name, Device label, Customer name, Device group name — empty by default. Like Device name, they accept $key placeholders. Without a profile name, ThingsBoard uses the default profile.
   • Telemetry — battery, fСnt, rssi, snr, data, decoded, encdata. The converter adds these metadata keys to the telemetry. A key that the decoder already returns keeps the decoder value.
   • Attributes — eui, fPort, frequency, dr. The converter adds these metadata keys to the attributes.
   • Update only keys list — eui, fPort, frequency, dr. ThingsBoard stores these keys only when their value changes.

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

9. Click Add.

Decoder Inputs

LORIOT sends each uplink as a JSON message like this one:

{
  "cmd": "rx",
  "seqno": 3040,
  "EUI": "BE7A000000000552",
  "ts": 1792652400000,
  "fcnt": 42,
  "port": 1,
  "freq": 868100000,
  "rssi": -87,
  "snr": 9.5,
  "toa": 61,
  "dr": "SF7 BW125 4/5",
  "ack": false,
  "bat": 255,
  "offline": false,
  "data": "00bc614e5f092950"
}

The converter unwraps it into two inputs:

Test the Decoder

Click Test payload decoder below the editor. The dialog shows the last message that the converter received, or a LORIOT sample message, already split into Payload and Metadata. To test with the message from Decoder Inputs:

1. Click Updated RAW payload.
2. Replace Payload with the message. Keep Metadata: it holds the integration metadata, such as integrationName. Click Apply.
3. Payload now shows ALxhTl8JKVA=, the bytes of 00bc614e5f092950, and Metadata shows the unwrapped keys, including cmd = rx. Click Test.

The output shows the decoded data:

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

If the output is empty or shows an error, fix the decoder and test again.

Use a Library Converter

The Converters library holds ready-made decoders for many LoRaWAN device models. They come from the thingsboard/data-converters repository, from the LORIOT folder of each model.

1. In the Add data converter dialog, select the Loriot integration type, then switch Create new to Library. The Uplink data converter step of the integration wizard offers the same choice.
2. Select the Vendor and the Model of your device.
3. Name is filled in as Loriot Uplink Converter for <Vendor> <Model>. Keep it or enter your own.
4. Review the decoder and the Advanced decoding parameters, and click Add.

A library decoder can work differently from the default one. Some entries use the generic decoder format, function decoder(payload, metadata): they receive the whole LORIOT message as payload and parse it themselves, and Advanced decoding parameters shows only the Update only keys list. The test button is then called Test decoder function, and the test payload is the whole LORIOT message. Check the decoder of your model before you use it.

1. Go to Integrations ⇾ Integrations and click + Add integration.
2. Basic settings:
   • Integration type — select Loriot.
   • Name — keep the default Loriot integration or enter your own.
   • Enable integration and Allow create devices or assets — keep both on, so the device is created on its first message.
   • Click Next.
3. Uplink data converter:
   • Click Select existing and choose Loriot Uplink Converter.
   • Alternatively, click Create new to write a decoder here, or Library to load one for your device model.
   • Click Next.
4. Downlink data converter:
   • Click Skip. Add a downlink converter later if you need to send commands.
5. Connection:
   • Copy the HTTP endpoint URL. You need it for the HTTP Push output.
   • To let ThingsBoard create the output for you, turn on Create Loriot Application output now (see Create the HTTP Push Output). Otherwise, leave the other parameters at their defaults. See Connection Settings for details.
6. Click Add.

The integration answers 204 No Content to an accepted request, 400 Bad Request on a converter script error, 403 Forbidden when the security check fails, and 500 Internal Server Error on other errors.

The output tells the LORIOT application where to send device data. Create it in the LORIOT portal, or let ThingsBoard create it through the LORIOT API.

• Manual
• Automatic

1. In LORIOT, go to Applications and click your application.
2. In the left menu, click Output, then click Add New Output.
3. Select HTTP Push and click Continue.
4. Optionally, enter an Output Name. Paste the HTTP endpoint URL of the integration into Target URL for POSTs, and click Continue.

Go to Applications (1) and click your application (2). Click Output (3), then Add New Output (4). Select HTTP Push (5). Click Continue (6). Enter an Output Name (7), paste the HTTP endpoint URL into Target URL for POSTs (8), and click Continue (9). The HTTP Push output is created. LORIOT now sends uplinks to ThingsBoard.

Anyone who knows the endpoint URL can send data to it. Add a secret header to the output and check it in ThingsBoard: the integration then rejects every request without the right value with 403 Forbidden, before the converter runs.

1. In ThingsBoard, open the integration and click Toggle edit mode (pencil icon).
2. Turn on Enable security.
3. In Headers filter, click Add. Enter a Header, for example Authorization, and a long random Value. A request must carry every header in the list. The header name is not case-sensitive. The value match is exact and case-sensitive.
4. Click Apply changes.
5. In LORIOT, open the application, click Output, and click the ThingsBoard HTTP Push output.
6. Click the pencil icon. Under Custom Headers, enter the same header name as the Key and the same Value, click Add New Custom headers, and click Save changes.

In LORIOT, open Output (5). The list shows the ThingsBoard HTTP Push output. Click the ThingsBoard output to open its settings (6). Under Custom Headers, enter the same header name and value (7). The header appears as a chip. Click Save changes (8).

With Create Loriot Application output, ThingsBoard creates the output with the value of a filter header named exactly Authorization as the output’s authorization value. Other headers in the filter are not copied to the output.

Send an uplink from the device, or simulate one with curl, then confirm that ThingsBoard decoded it and created the device.

With a device: power on a LoRaWAN device registered in your LORIOT application and let it send an uplink.

With curl: send the example LORIOT message from Decoder Inputs straight to the integration. This skips LORIOT, so you can check the converter and the integration before a device is available. Replace $HTTP_ENDPOINT_URL with the HTTP endpoint URL of the integration:

curl -v -X POST "$HTTP_ENDPOINT_URL" \
  -H "Content-Type: application/json" \
  -d '{"cmd":"rx","seqno":3040,"EUI":"BE7A000000000552","ts":1792652400000,"fcnt":42,"port":1,"freq":868100000,"rssi":-87,"snr":9.5,"toa":61,"dr":"SF7 BW125 4/5","ack":false,"bat":255,"offline":false,"data":"00bc614e5f092950"}'

If you turned on Enable security, add the header, for example -H "Authorization: $HEADER_VALUE". The integration answers 204 No Content.

• Integration events — go to Integrations ⇾ Integrations, open the integration, and click the Events tab. The message appears as an event of type Uplink with status OK. Click ⋅⋅⋅ in the Message column to see the LORIOT message.
• Converter events — open Loriot Uplink Converter in Integrations ⇾ Data converters and click the Events tab. In and Metadata show the LORIOT message and the integration metadata as they arrived, before unwrapping. Out shows the decoder result.
• Device — go to Devices & assets ⇾ Devices. The integration has created the device Device BE7A000000000552 with the default profile. Open it and check:
  • Latest telemetry — battery = 95, temperature = 23.45, and saturation = 80 from the decoder, and fСnt = 42, rssi = -87, snr = 9.5, and data = 00bc614e5f092950 from the Telemetry list. battery keeps the decoder value, not the bat value 255 of the message.
  • Attributes (Client attributes) — sn = 12345678 from the decoder, and eui, fPort, frequency, and dr from the Attributes list.

ThingsBoard sends each downlink right away as a LORIOT API call. Nothing is queued in ThingsBoard: if the call fails, ThingsBoard records an error and drops the command. LORIOT queues the downlink and sends it to a Class A device after the device’s next uplink.

For each downlink, the integration:

1. Runs the downlink converter on the Rule Engine message.
2. Checks the encoder result: metadata.EUI must have 16 hex digits, and metadata.port must be from 1 to 223.
3. Sends POST {Downlink URL} with the Application Access Token as a Bearer token and a JSON body like {"cmd":"tx","EUI":"BE7A000000000552","port":1,"appid":"BE010A45","data":"01"}. data is hex, and confirmed is added when the encoder sets it.

For the full encoder reference, see Downlink data converter.

1. In LORIOT, open the application and click Access Tokens in the left menu.
2. Copy an existing token, or click Generate another authentication token and copy the new one.

Add a downlink converter to the integration and turn on Send downlink with the access token.

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 Loriot integration type are preselected.
3. Enter a name, for example Loriot Downlink Converter.
4. Main encoding configuration opens in TBEL with a generic encoder. It builds a JSON object from temperatureUploadFrequency and humidityUploadFrequency and sets an MQTT topic, not the EUI and port that LORIOT 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. Enable downlink: turn on Send downlink. Enter the Server and Application ID if they are empty, check the Downlink URL, and paste the token into Application Access Token.
8. Click Apply changes.

Encoder used in this guide. It turns the shared attribute powerState into a one-byte command: 01 for on, 00 for any other value. It reads the device EUI and port from the eui and fPort client attributes, which the rule chain adds to the metadata as cs_eui and cs_fPort. A message without powerState produces no downlink.

/** Encoder **/

// Send a command only for the powerState shared attribute, for example {"powerState": "on"}.
if (msg.powerState == null) {
    return [];
}

return {
    contentType: "TEXT",
    // One byte as a hex string: 01 turns the device on, 00 turns it off.
    data: (msg.powerState == "on" ? "01" : "00"),
    metadata: {
        // Device EUI and LoRaWAN port, added by the rule chain from the client attributes.
        EUI: metadata.cs_eui,
        port: (metadata.cs_fPort != null ? metadata.cs_fPort : 1),
        // data is already hex: send it as is.
        isHexEncoded: true
    }
};

/** Encoder **/

// Send a command only for the powerState shared attribute, for example {"powerState": "on"}.
if (msg.powerState == null) {
    return [];
}

return {
    contentType: "TEXT",
    // One byte as a hex string: 01 turns the device on, 00 turns it off.
    data: msg.powerState === "on" ? "01" : "00",
    metadata: {
        // Device EUI and LoRaWAN port, added by the rule chain from the client attributes.
        EUI: metadata.cs_eui,
        port: metadata.cs_fPort != null ? metadata.cs_fPort : 1,
        // data is already hex: send it as is.
        isHexEncoded: true
    }
};

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

{
  "contentType": "TEXT",
  "data": "01",
  "metadata": {
    "EUI": "BE7A000000000552",
    "port": "1",
    "isHexEncoded": true
  }
}

With {"temperature": 25}, the output is [], and nothing is sent.

The integration reads these fields from the encoder result:

To send several downlinks from one message, return an array of results.

The encoder needs the device EUI and port. Add them to the metadata with an originator attributes node, 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 Retrieve eui and fPort.
   • Client attributes — add eui and fPort.
   • Add originator attributes to — select Metadata. The node adds client attributes with the cs_ prefix: cs_eui and cs_fPort.
   • Click Add.
3. From the Action section, drag an integration downlink node onto the canvas:
   • Name — for example Downlink to Loriot.
   • Integration — select Loriot integration.
   • Click Add.
4. Connect the message type switch node to Retrieve eui and fPort with the Attributes Updated relation.
5. Connect Retrieve eui and fPort to Downlink to Loriot with the Success relation.
6. Click Apply changes.

1. Go to Devices & assets ⇾ Devices and open Device BE7A000000000552, 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 Loriot Downlink Converter in Integrations ⇾ Data converters and click the Events tab. In shows the message {"powerState":"on"} with cs_eui and cs_fPort in its metadata. Out shows data 01 and the EUI and port.
• Integration events — open the integration’s Events tab. Two events of status OK appear: Downlink: ATTRIBUTES_UPDATED for the message from the Rule Engine, and Downlink for the call to LORIOT, with the encoder metadata and payload in its message. A failed call appears as a Downlink event with an error.
• LORIOT — check either view:
  • Device — open the device, go to LoRaWAN® Parameters, and scroll to Sequence Numbers. FCntQueue = 1 shows a queued downlink that waits for the next uplink of the device.
  • Log — in the application, click Log in the left menu. A green HTTP entry with the device EUI and cmd tx shows that LORIOT accepted the downlink.

Open the device ⇾ LoRaWAN® Parameters ⇾ Sequence Numbers. FCntQueue = 1 shows the queued downlink. In the application Log, a green HTTP entry for the device EUI shows that LORIOT accepted the downlink.

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.
• Typed uplink converter — the converter for LoRaWAN network servers.
• Converters library — ready-made decoders for device models.
• Downlink data converter — encoder reference.
• integration downlink node — route Rule Engine messages to an integration.
• originator attributes node — add attributes of the message originator, such as the device EUI, 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.
• thingsboard/data-converters — source of the converters library.
• LORIOT documentation — applications, outputs, and the network server API.