ThingPark Enterprise Integration

ThingPark Enterprise Integration receives LoRaWAN uplinks from Actility ThingPark Enterprise (TPE), the private LoRaWAN network server of Actility. TPE sends each uplink as an HTTP request to the integration endpoint. An uplink data converter transforms it into device data, including telemetry and attributes. For downlink, ThingsBoard sends commands to the device through the TPE DX API.

Use ThingPark Enterprise Integration when:

• Your LoRaWAN devices are registered in your own ThingPark Enterprise instance.
• You need to send commands from ThingsBoard to those devices, for example when a shared attribute changes.

If your devices are on the Actility ThingPark Wireless network instead, use ThingPark Integration.

1. Receive data. The device sends an uplink through a LoRaWAN gateway to ThingPark Enterprise. TPE sends it to the integration endpoint as an HTTP request with a DevEUI_uplink JSON body. The query string carries the AS_ID, LrnDevEui, LrnFPort, Time, and Token parameters.
2. Check the request. The AS_ID parameter must match the AS ID of the integration, and the body must hold DevEUI_uplink with DevEUI and FPort. Otherwise, the integration rejects the request with 403 Forbidden.
3. Decode the payload. The uplink converter unwraps the TPE message, decodes the device payload, and returns telemetry and attributes. If Allow create devices or assets is on, ThingsBoard creates the device on its first uplink.
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 through the TPE DX API, with an OAuth access token.

• Access to ThingsBoard Cloud with integrations enabled for your tenant. The ThingsBoard endpoint must be reachable from your ThingPark Enterprise instance, because TPE calls it.
• Permission to create integrations and data converters, and to edit rule chains for downlink.
• A ThingPark Enterprise instance with at least one LoRaWAN device registered and joined to the network, and an account that can create applications.
• For downlink: credentials that the TPE DX API accepts, and the address of the DX API of your instance.

TPE sends uplinks only to an HTTP application that the device is assigned to. The application needs the integration endpoint URL, so you create it after creating the integration. Prepare the credentials first.

The AS ID and AS Key identify ThingsBoard as the application server of the TPE application. You enter the same pair in TPE and in ThingsBoard:

Take the values from an existing TPE application, or generate new ones with any hex string generator.

TPE adds the AS ID to every uplink as the AS_ID query parameter, and the integration compares it with its own AS ID. ThingsBoard sends the AS ID and AS Key back to TPE in every downlink request.

Skip this step if you only need uplinks. To send downlinks, the integration calls the TPE DX API. It needs:

• DX API address — the base address of the DX API of your TPE instance. The integration appends the API paths to it, for example /admin/latest/api/oauth/token.
• Client ID and Client Secret — the credentials that the DX API accepts for an OAuth client_credentials token request, usually the login and password of a TPE user with API access.

Create the uplink converter and the integration, then create the TPE application that sends uplinks to the integration endpoint.

ThingPark Enterprise Integration uses the Typed uplink converter. ThingsBoard selects it automatically for this integration type, and you cannot change it later. The converter first unwraps the TPE message: it takes the device payload from payload_hex and puts the network fields, such as eui, fPort, rssi, and snr, into the metadata. The decoder then decodes only the device payload. For details, see Typed uplink converter.

To use a ready-made decoder for your device model instead, see Use a Library Converter.

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

2. Converter type — keep Uplink.

3. Integration type — select ThingParkEnterprise.

4. Keep Create new selected.

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

6. Main decoding configuration:

   • Entity type — keep Device.
   • Device name — keep Device $eui. ThingsBoard replaces $eui with the DevEUI of the uplink, for example Device 0018B20000000123. Any key from Decoder Inputs works as a $key placeholder.
   • The decoder editor opens in TBEL with a default decoder for a sample 8-byte payload: a 4-byte serial number, then battery, temperature, and saturation. Replace it with your device’s decoding logic, or keep it to follow this guide. The decoder below is a shorter version of the default one. For JavaScript, use the TBEL / JS toggle and the JavaScript tab.
   • TBEL (Recommended)
   • JavaScript

   // payload — the device payload bytes from payload_hex.
   // metadata — integration metadata plus the keys unwrapped from the TPE message.
   return {
       attributes: {
           // Serial number: bytes 0–3.
           sn: parseBytesToInt(payload, 0, 4)
       },
       telemetry: {
           // Time of the uplink, parsed from the Time field of the message.
           ts: metadata.ts,
           values: {
               battery: parseBytesToInt(payload, 4, 1),
               temperature: parseBytesToInt(payload, 5, 2) / 100.0,
               saturation: parseBytesToInt(payload, 7, 1)
           }
       }
   };

   To adapt:

   • Payload layout — change the byte offsets, lengths, and scaling to match the payload specification of your device.
   • Device identity — to override the values of Main decoding configuration and Advanced decoding parameters, add name, type (DEVICE or ASSET), profile, label, customer, or group to the result, for example name: 'Sensor ' + metadata.eui.
   • Network fields — read any key from Decoder Inputs, for example metadata.rssi, or list it in Advanced decoding parameters to store it without code.

7. Advanced decoding parameters — ThingsBoard pre-fills them for ThingPark Enterprise:

   • Device profile name, Device label, Customer name, and Device group name — empty. Without a profile name, the device gets the default profile. These fields accept $key placeholders too.
   • Telemetry — fCnt, data, rssi, snr, channel, and decoded. Attributes — eui, fPort, adr, spreadingFactor, bandwidth, devAddr, frequency, and class. ThingsBoard adds these metadata keys to the decoder output, if the uplink has them. A key that the decoder already returns keeps the decoder value. The lists add keys: they do not filter the decoder output.
   • Update only keys list — the same keys as Attributes. 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

TPE sends an uplink like this one:

{
  "DevEUI_uplink": {
    "Time": "2026-10-22T10:30:00.000+00:00",
    "DevEUI": "0018B20000000123",
    "FPort": 1,
    "FCntUp": 42,
    "ADRbit": 1,
    "MType": 4,
    "FCntDn": 5,
    "payload_hex": "0000162e5a0a2b41",
    "mic_hex": "a1b2c3d4",
    "Lrcid": "00000065",
    "LrrRSSI": -85.0,
    "LrrSNR": 7.25,
    "SpFact": 7,
    "SubBand": "G0",
    "Channel": "LC1",
    "Lrrid": "FF0000C8",
    "Late": 0,
    "LrrLAT": 48.8566,
    "LrrLON": 2.3522,
    "CustomerID": "100000507",
    "DevAddr": "04A1B2C3",
    "Frequency": 868.1
  }
}

The converter unwraps these fields into metadata keys:

The converter also unwraps less common fields when TPE sends them, for example LostUplinksAS as lostUplinksAs, LrrESP as esp, DevLrrCnt as devLrrCnt, TxPower as txPower, and CustomerData as customerData.

The sample payload_hex holds the serial number 0x0000162E (5678), battery 0x5A (90), temperature 0x0A2B (2603, or 26.03 after scaling), and saturation 0x41 (65).

Test the Decoder

Click Test payload decoder below the editor. The Payload and Metadata of the dialog hold the already unwrapped input: the device payload and the metadata keys. To test with a full TPE message:

1. Click Updated RAW payload.
2. Replace the Payload with the uplink from Decoder Inputs and click Apply. ThingsBoard unwraps it: Payload content type becomes Binary (Base64) with the payload AAAWLloKK0E=, and Metadata lists the unwrapped keys, such as eui and rssi.
3. Click Test.

The Decoder output tab shows the result of the decoder:

{
  "attributes": {
    "sn": 5678
  },
  "telemetry": {
    "ts": 1792665000000,
    "values": {
      "battery": 90,
      "temperature": 26.03,
      "saturation": 65
    }
  }
}

The Converter output tab shows the data that ThingsBoard stores: the device name Device 0018B20000000123 and the default profile, telemetry with fCnt, data, rssi, snr, and channel added to the decoded values, and attributes with eui, fPort, adr, spreadingFactor, bandwidth, devAddr, and frequency added to sn. 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 specific device models, from the public thingsboard/data-converters repository. For ThingPark Enterprise, it has decoders for Decentlab devices.

1. In Add data converter, select Uplink and the ThingParkEnterprise integration type, and switch from Create new to Library.
2. Vendor — select the vendor, for example Decentlab.
3. Model — select the device model, for example DL-5TM.
4. Name — ThingsBoard fills it as ThingParkEnterprise Uplink Converter for <Vendor> <Model>, for example ThingParkEnterprise Uplink Converter for Decentlab DL-5TM. Change it if needed.
5. Review the decoder and the Update only keys list, and click Add.

Library converters can differ from the converter in this guide. Some are written as generic decoders: they parse the full TPE message themselves, for example with decodeToJson(payload).DevEUI_uplink.payload_hex, and choose their own telemetry keys. Test a library converter with a full TPE message from your device before you use it.

1. Go to Integrations ⇾ Integrations and click + Add integration.
2. Basic settings:
   • Integration type — select ThingParkEnterprise.
   • Name — keep the default ThingParkEnterprise 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 ThingPark Enterprise Uplink Converter.
   • Alternatively, click Create new to configure a converter here, or Library to load a ready-made one.
   • 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 TPE application.
   • Enable security is always on for this integration type. Enter the AS ID and AS Key from Choose the AS ID and AS Key.
   • Leave the other parameters at their defaults. See Connection Settings for details.
6. Click Add.

The integration answers 200 OK when the request passes the check, 403 Forbidden when it does not, 400 Bad Request on a converter script error, and 500 Internal Server Error on other processing errors.

The HTTP application tells TPE where to send the uplinks of its devices.

1. Sign in to your ThingPark Enterprise portal.
2. Go to Applications and click Create.
3. Select the HTTP application type.
4. Configure the destination:
   • URL — paste the HTTP endpoint URL of the integration.
   • Content-type — select application/json.
   • AS ID and AS Key — enter the same values as in the integration.
5. Click Save.

1. In ThingPark Enterprise, go to Devices and open the device.
2. In Associated Application, select the HTTP application you created.
3. Click Save.

A device can belong to one application at a time. If the device is already assigned to another application, reassign it.

Send an uplink, then confirm that ThingsBoard decoded it and created the device.

Wait for the next uplink of an assigned device. TPE forwards it to the integration endpoint.

To test without a device, send the uplink from Decoder Inputs with curl. Replace $HTTP_ENDPOINT_URL with the HTTP endpoint URL and $AS_ID with the AS ID of the integration, and run:

curl -v -X POST "$HTTP_ENDPOINT_URL?LrnDevEui=0018B20000000123&LrnFPort=1&AS_ID=$AS_ID&Time=2026-10-22T10:30:00.500%2B00:00&Token=test" \
  -H "Content-Type: application/json" \
  -d '{"DevEUI_uplink":{"Time":"2026-10-22T10:30:00.000+00:00","DevEUI":"0018B20000000123","FPort":1,"FCntUp":42,"ADRbit":1,"MType":4,"FCntDn":5,"payload_hex":"0000162e5a0a2b41","mic_hex":"a1b2c3d4","Lrcid":"00000065","LrrRSSI":-85.0,"LrrSNR":7.25,"SpFact":7,"SubBand":"G0","Channel":"LC1","Lrrid":"FF0000C8","Late":0,"LrrLAT":48.8566,"LrrLON":2.3522,"CustomerID":"100000507","DevAddr":"04A1B2C3","Frequency":868.1}}'

The endpoint returns 200 (HTTP/2 200 on ThingsBoard Cloud). The integration does not verify the Token parameter, so any value works. ThingsBoard stores the telemetry with the time in Time. Change it to the current time to see the data as the latest values.

• TPE — for an uplink from a real device, open the Wireless Logger in ThingPark Enterprise. The uplink shows that TPE sent it to the application.
• Integration events — go to Integrations ⇾ Integrations, open the integration, and click the Events tab. The request appears as an event of type Uplink with status OK. Click ⋅⋅⋅ in the Message column to see the body. A request that fails the check appears with status FORBIDDEN.
• Converter events — open ThingPark Enterprise Uplink Converter in Integrations ⇾ Data converters and click the Events tab. In shows the full TPE message, before unwrapping. Out shows the decoder result. Metadata shows the integration metadata: integrationName, AS_ID, LrnDevEui, and LrnFPort.
• Device — go to Devices & assets ⇾ Devices. The integration has created the device Device 0018B20000000123 with the default profile. Open it and check battery, temperature, saturation, fCnt, data, rssi, snr, and channel on the Latest telemetry tab, and sn, eui, fPort, adr, spreadingFactor, bandwidth, devAddr, and frequency on the Attributes tab, in Client attributes.

ThingsBoard sends each downlink right away through the TPE DX API. Nothing is queued in ThingsBoard: if a call fails, ThingsBoard records an error and drops the command.

For each downlink, the integration:

1. Gets an access token with POST {Downlink URL}/admin/latest/api/oauth/token?grant_type=client_credentials&client_id={Client Id}&client_secret={Client Secret}, and reuses it until it expires.

2. Finds the device with GET {Downlink URL}/core/latest/api/devices: it takes the ref of the device whose EUI equals the DevEUI from the encoder.

3. Sends the payload with POST {Downlink URL}/core/latest/api/devices/{ref}/downlinkMessages, with the token as a Bearer token and this body:

   {
     "payloadHex": "<payload from the encoder>",
     "targetPorts": "<1 to 15>",
     "securityParams": {
       "asId": "<AS ID>",
       "creationTime": "<current time>",
       "asKey": "<AS Key>"
     }
   }

The integration sets targetPorts itself: it counts from 1 to 15 and starts again, one step per downlink. The encoder cannot set the LoRaWAN port.

The downlink converter turns a Rule Engine message into the payload. 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. The Downlink converter type and ThingParkEnterprise integration type are preselected.
3. Enter a name, for example ThingPark Enterprise Downlink Converter.
4. Main encoding configuration opens in TBEL with a generic encoder. It does not build the DevEUI and payload fields that this integration 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. Debug is off by default.
6. Click Add.
7. Under Enable security, turn on Enable security for automatic token updates and enter the Client Id and Client Secret from Get DX API Credentials.
8. Under Advanced settings, set Downlink URL to the DX API address of your TPE instance.
9. Click Apply changes.

Encoder used in this guide. It sends the value of the downlinkHex shared attribute as the payload, and ignores messages without it. The rule chain adds the device EUI to the metadata as cs_eui.

/** Encoder **/

// Device EUI. The rule chain adds the client attribute "eui" to the metadata as cs_eui.
var eui = metadata.cs_eui;

// Payload as a hex string, for example "0102". Nothing to send without it.
var payloadHex = msg.downlinkHex;
if (eui == null || payloadHex == null) {
    return [];
}

return {
    contentType: "JSON",
    // The integration reads DevEUI and payload from data.
    data: JSON.stringify({
        DevEUI: eui,
        payload: payloadHex
    }),
    // The integration checks that metadata has DevEUI.
    metadata: {
        DevEUI: eui
    }
};

/** Encoder **/

// Device EUI. The rule chain adds the client attribute "eui" to the metadata as cs_eui.
var eui = metadata.cs_eui;

// Payload as a hex string, for example "0102". Nothing to send without it.
var payloadHex = msg.downlinkHex;
if (eui == null || payloadHex == null) {
    return [];
}

return {
    contentType: "JSON",
    // The integration reads DevEUI and payload from data.
    data: JSON.stringify({
        DevEUI: eui,
        payload: payloadHex
    }),
    // The integration checks that metadata has DevEUI.
    metadata: {
        DevEUI: eui
    }
};

To check the encoder, click Test encoder function. Replace the Message with {"downlinkHex": "0102"}, add cs_eui = 0018B20000000123 to Metadata, and click Test. The Output panel shows:

{
  "contentType": "JSON",
  "data": "{\"DevEUI\":\"0018B20000000123\",\"payload\":\"0102\"}",
  "metadata": {
    "DevEUI": "0018B20000000123"
  }
}

Without downlinkHex in the message, the output is [], and nothing is sent.

The integration reads these fields from the encoder result:

The encoder needs the device EUI. The uplink converter stores it as the eui client attribute. Add it 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 Add EUI.
   • Client attributes — eui. The node adds it to the metadata as cs_eui.
   • Add originator attributes to — keep Metadata.
   • Click Add.
3. From the Action section, drag an integration downlink node onto the canvas:
   • Name — for example Downlink to ThingPark Enterprise.
   • Integration — select ThingParkEnterprise integration.
   • Click Add.
4. Connect the message type switch node to Add EUI with the Attributes Updated relation.
5. Connect Add EUI to Downlink to ThingPark Enterprise with the Success relation.
6. Click Apply changes.

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 downlinkHex, keep the String type, enter Value 0102, and click Add.

• Converter events — open ThingPark Enterprise Downlink Converter in Integrations ⇾ Data converters and click the Events tab. In shows the message {"downlinkHex": "0102"} with cs_eui in its metadata. Out shows the data with DevEUI and payload.
• Integration events — open the integration’s Events tab. Downlink: ATTRIBUTES_UPDATED appears for the message from the Rule Engine, and an event of type Downlink with status OK for each successful DX API call. A failed call appears with status ERROR and the error text.
• TPE — open the Wireless Logger in ThingPark Enterprise. The downlink to the device shows that TPE received it. TPE sends it in the next receive window of the device.

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.
• ThingPark Integration — connect devices on the Actility ThingPark Wireless network.
• Uplink data converter — Typed and Library converters, decoder inputs, and output format.
• 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 — the source of the Converters library.