ThingPark Enterprise Integration

The Actility ThingPark Enterprise integration connects ThingsBoard to a private, on-premise ThingPark Enterprise LoRaWAN network server. Use it to bring telemetry from LoRaWAN devices already registered in ThingPark Enterprise into ThingsBoard for monitoring and rule-based automation — including sending commands back to those devices.

A LoRaWAN device sends an uplink to ThingPark Enterprise, which pushes it as an HMAC-signed HTTP notification to the integration’s endpoint via the DX Dataflow API. The uplink converter decodes the notification into telemetry and attributes, and the ThingsBoard Core Service stores the data, creating the device automatically on first contact. For downlink, the Rule Engine hands a message to the integration; the downlink converter encodes it, and ThingsBoard delivers it to the device through the configured Downlink URL.

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 running ThingPark Enterprise instance with at least one registered LoRaWAN device.
• You have an AS ID and AS Key (Application Server credentials) — see Obtaining AS ID and AS Key below.

The AS ID and AS Key authenticate ThingsBoard as an Application Server to ThingPark Enterprise. You choose these values yourself and enter the same pair in both systems.

You can obtain them in two ways:

• From an existing ThingPark Enterprise application — in the TPE admin portal, open your application and find the Security (or Local Protocol Settings) section. The AS ID and AS Key are shown there; click the eye icon to reveal them if masked.
• Generate new values — use any hex string generator to produce 16 characters for the AS ID and 32 for the AS Key. Enter them in ThingsBoard first, then configure the identical values in ThingPark Enterprise.

The uplink converter receives a ThingPark Enterprise message (JSON containing DevEUI_uplink) and maps it to ThingsBoard device telemetry and attributes. For the full decoder function reference, see Uplink data converter.

Sample payload:

{
  "DevEUI_uplink": {
    "Time": "2024-01-15T10:30:00.000+00:00",
    "DevEUI": "0018B20000000123",
    "FPort": 1,
    "FCntUp": 42,
    "ADRbit": 1,
    "MType": 4,
    "FCntDn": 5,
    "payload_hex": "0364011a",
    "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
  }
}

DevEUI identifies the device. payload_hex contains the raw application payload. LrrRSSI and LrrSNR are radio quality metrics from the receiving gateway.

1. Go to Integrations center ⇾ Data converters.
2. Click + Add data converter ⇾ Create new converter.
3. Converter type — leave Uplink (selected by default).
4. Integration type — in the search field, enter ThingPark and select ThingParkEnterprise from the list.
5. Name — enter a converter name, for example ThingPark Enterprise Uplink Converter.
6. In Main decoding configuration:
   • The default device name pattern Device $eui uses the DevEUI from the ThingPark message as the unique device name in ThingsBoard. Change it if you prefer a different naming scheme.
   • The default decoder is pre-filled. Leave it unchanged for this guide, or paste the decoder function below.
7. Review Advanced decoding parameters — pre-populated for ThingPark, auto-extracting telemetry keys channel, data, fCnt, rssi, and snr, plus attribute keys bandwidth, eui, fPort, and spreadingFactor. Adjust if needed.
8. Click Add.

The decoder function used in this guide:

/**
* 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 is the timestamp parsed from the incoming message's time, or returns the current time if it cannot be parsed.

  // 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: convertDateToTimestamp(metadata.time),
  //         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;

/**
* Decodes the incoming payload and returns a structured object containing telemetry data and attributes.
*
* @param {number[]} 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 is the timestamp parsed from the incoming message's time, or returns the current time if it cannot be parsed.

  // 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: convertDateToTimestamp(metadata.time),
  //         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;

/**
* Parse a slice of bytes from an array into an integer (big-endian).
*
* @param {number[]} input - The array of bytes.
* @param {number} offset - The starting index.
* @param {number} length - The number of bytes to convert.
* @returns {number} - The resulting integer.
*/
function parseBytesToInt(input, offset, length) {
  var result = 0;
  for (var i = offset; i < offset + length; i++) {
    result = (result << 8) | (input[i] & 0xFF);
  }
  return result;
}

What the Converter Receives

Adapting the Decoder to Your Device

• Match your payload structure — update the byte offsets, lengths, and field names in decodePayload to match your device’s binary specification.
• Add or remove fields — add more parseBytesToInt calls (or parseBytesToFloat, string extraction, etc.) for additional sensors; remove entries your device does not transmit.
• Timestamp — metadata.ts is already parsed from the message’s Time field (in milliseconds); use it directly instead of converting a date string yourself.
• Attributes — move static device properties (model, firmware version, installation site) to attributes and keep frequently changing values in telemetry.
• Override device identity from the payload — set result.name, result.profile, result.group, or result.customer to derive device identity from payload content rather than the Main decoding configuration template.

1. Go to Integrations center ⇾ Integrations and click + Add integration.
2. Basic settings:
   • Set Integration type to ThingParkEnterprise.
   • Enter a Name, or keep the default ThingParkEnterprise integration.
   • Leave Enable integration and Allow create devices or assets enabled so that devices are created automatically when data is received for the first time.
   • Click Next.
3. Uplink data converter:
   • Click Select existing and choose the ThingPark Enterprise Uplink Converter created above, or click Create new to define the decoder inline.
   • Click Next.
4. Downlink data converter:
   • Click Skip — a downlink converter is only needed when ThingsBoard must send commands back to devices. See Configure and Test Downlink to add one later.
5. Connection:
   • Base URL — pre-filled with your ThingsBoard instance URL (for example, https://thingsboard.cloud).
   • Copy the generated HTTP endpoint URL in the following format: https://{base-url}/api/v1/integrations/tpe/{integration-id}. You will configure ThingPark Enterprise to send uplink data to this address using HTTP POST requests.

   • Enable security — enable this option to validate the HMAC-SHA256 signature of incoming messages. When enabled, configure:

     • AS ID — a 16-character hexadecimal string. It must match the value configured in ThingPark Enterprise.
     • AS Key — a 32-character hexadecimal string. It must match the value configured in ThingPark Enterprise.
     • Maximum time difference (seconds) — the allowed clock difference when validating message timestamps. The default value is 60.
   • Enable security for automatic token updates — allows ThingPark Enterprise to refresh the authentication token automatically.
   • Optionally, expand Advanced settings to configure the downlink URL and metadata.
6. Click Add to save the integration.

Basic settings — set Integration type to ThingParkEnterprise, enter a name, and click Next. Uplink data converter — select Create new, paste your decoder function, and click Next. Downlink data converter — click Skip if downlink is not required yet. Connection — copy the HTTP endpoint URL, enable security, and enter your AS ID and AS Key.

Base URL

Your ThingsBoard instance base URL (e.g. https://thingsboard.cloud). Pre-filled automatically; used to construct the HTTP endpoint URL.

HTTP Endpoint URL

The unique endpoint generated by ThingsBoard for this integration, in the form:

https://{base-url}/api/v1/integrations/tpe/{integration-id}

Configure your ThingPark Enterprise application to POST device uplinks to this URL. The URL is stable as long as the integration exists.

Enable Security

When enabled, ThingsBoard validates the HMAC-SHA256 signature that ThingPark Enterprise attaches to each notification. Requires:

Enable Security for Automatic Token Updates

When enabled, ThingPark Enterprise can refresh the AS authentication token automatically without manual intervention.

Replace Response Status from ‘No-Content’ to ‘OK’

Some ThingPark Enterprise versions expect an HTTP 200 OK response instead of 204 No Content. Enable this toggle if your ThingPark Enterprise server logs HTTP errors after a successful uplink delivery.

Downlink URL

The ThingPark Enterprise endpoint for sending downlink commands to devices (e.g. https://api.thingpark.com/thingpark/lrc/rest/downlink). Required only if you configure a downlink converter and rule chain. Adjust the base host to match your ThingPark Enterprise installation.

Execute Remotely

When enabled, ThingsBoard generates an Integration key and Integration secret for running the integration outside the ThingsBoard cluster — useful when ThingsBoard is not publicly reachable. See Remote Integration.

After saving the ThingsBoard integration, configure ThingPark Enterprise to push device uplinks to it.

1. Log in to your ThingPark Enterprise administration portal.
2. Go to Applications in the left panel and click Create.
3. Select the application type HTTP.
4. Configure the Destination:
   • URL — paste the HTTP endpoint URL copied from the ThingsBoard integration connection step.
   • Content-type — select application/json.
   • AS ID — enter the same AS ID you set in ThingsBoard (16-character hex string).
   • AS Key — enter the same AS Key you set in ThingsBoard (32-character hex string).
5. Click Save to create the application.

1. In ThingPark Enterprise, go to Devices.
2. Open the device you want to connect to ThingsBoard.
3. In the Associated Application field (sometimes labelled Connectivity Plan), select the HTTP application you just created.
4. Click Save.

Once assigned, ThingsBoard identifies the device by its DevEUI and creates a device named TPE-<DevEUI> on the first uplink, provided Allow create devices or assets is enabled on the integration.

Testing requires an uplink from a real device registered in ThingPark Enterprise. Unlike a plain HTTP webhook, a simulated request cannot easily stand in for one here: when Enable security is on, ThingsBoard rejects any request whose HMAC-SHA256 signature doesn’t match your AS ID/AS Key pair, so a hand-crafted test request would need a correctly computed signature.

After your device sends an uplink, open the Wireless Logger in ThingPark Enterprise. Look for a log entry with status “Sent to Application” (indicated by a green upward arrow). This confirms that ThingPark Enterprise successfully delivered the uplink to ThingsBoard.

Go to Integrations center ⇾ Integrations, open ThingParkEnterprise integration, and click the Events tab. An Uplink event with Status: OK confirms the message was processed. Click … in the Message column to inspect the raw payload.

Go to Integrations center ⇾ Data converters, open the uplink converter, and click the Events tab. Inspect the In (raw payload), Out (decoded result), and Metadata columns to verify the decoder output.

Go to Entities ⇾ Devices. A device named TPE-<DevEUI> is automatically provisioned on the first message. Open it and check:

• Latest telemetry — fPort, fCntUp, rssi, snr, and spreadingFactor reflect values from the uplink.
• Attributes — devEui, subBand, channel, and integrationName are set from the notification.

Expected result: the device appears in Entities ⇾ Devices shortly after the uplink is delivered, with telemetry and attributes matching the values decoded by the converter.

The downlink converter (encoder) transforms a Rule Engine message into the payload ThingsBoard sends back to the device. ThingsBoard posts the encoded payload to the Downlink URL — pre-filled under Advanced settings in the integration’s Connection step to https://api.thingpark.com/thingpark/lrc/rest/downlink; adjust it only if your ThingPark installation uses a different host. For the full encoder function reference, see Downlink data converter.

The encoder output must include two fields in metadata required for delivery:

1. Go to Integrations center ⇾ Integrations and open the ThingParkEnterprise integration.
2. Click the pencil icon to enter edit mode.
3. In the Downlink data converter field, click Create new.
4. In the Add data converter dialog:
   • Enter a name for the converter, for example, ThingParkEnterprise Downlink Converter.
   • Use the default encoder script or replace it with your own implementation.
   • Click Add.
5. Click Apply changes to save the integration.

The encoder function used in this tutorial:

// Encode downlink data from incoming Rule Engine message.
// msg - JSON message payload (e.g. { "state": "on" })
// msgType - message type, e.g. 'ATTRIBUTES_UPDATED'
// metadata - enriched by the Originator attributes node with device client attributes.
//            ThingsBoard prefixes client-scope attributes with "cs_":
//            metadata.cs_eui — Device EUI stored on first uplink (e.g. "20635F00C5000660")
//            metadata.cs_fPort — LoRaWAN frame port stored on first uplink (e.g. "1")

var eui = metadata.cs_eui;
if (eui == null) {
  raiseError("DevEUI is missing (expected metadata.cs_eui).");
}

// Read port from the device client attribute "fPort" (set per-device).
// Falls back to 1 if the attribute is not set.
var port = (metadata.cs_fPort != null && metadata.cs_fPort != '') ? parseInt(metadata.cs_fPort) : 1;

var result = {
  // Downlink data content type: JSON, TEXT, or BINARY (base64 format).
  contentType: "JSON",

  // Downlink data — serialise the full message payload as a JSON string.
  data: JSON.stringify(msg),

  // metadata must include DevEUI and fPort for ThingPark delivery.
  metadata: {
    "DevEUI": eui,
    "fPort": port
  }
};

return result;

// Encode downlink data from incoming Rule Engine message.
// msg - JSON message payload (e.g. { "state": "on" })
// msgType - message type, e.g. 'ATTRIBUTES_UPDATED'
// metadata - enriched by the Originator attributes node with device client attributes.
//            ThingsBoard prefixes client-scope attributes with "cs_":
//            metadata.cs_eui — Device EUI stored on first uplink (e.g. "20635F00C5000660")
//            metadata.cs_fPort — LoRaWAN frame port stored on first uplink (e.g. "1")

var eui = metadata.cs_eui;

// Read port from the device client attribute "fPort" (set per-device).
// Falls back to 1 if the attribute is not set.
var port = parseInt(metadata.cs_fPort) || 1;

var result = {
  // Downlink data content type: JSON, TEXT, or BINARY (base64 format).
  contentType: "JSON",

  // Downlink data — serialise the full message payload as a JSON string.
  data: JSON.stringify(msg),

  // metadata must include DevEUI and fPort for ThingPark delivery.
  metadata: {
    "DevEUI": eui,
    "fPort": port
  }
};

return result;

To trigger a downlink when an attribute changes (for example, a shared attribute update), add two nodes to the Root Rule Chain: an Originator attributes node (Enrichment category) that reads the device eui and fPort client attributes into message metadata, and an Integration Downlink node (Action category) that forwards the encoded message to the ThingPark integration.

1. Open Rule Chains ⇾ Root Rule Chain.
2. In the node panel, search for originator attributes. The node appears under the Enrichment category. Drag it onto the canvas.
3. Configure the node:
   • Name — Fetch eui and fPort.
   • Under Client attributes, add the following keys: eui and fPort.
   • Set Add originator attributes to to Metadata.
   • Click Add.
4. In the node panel, search for integration downlink. The node appears under the Action category. Drag it onto the canvas.
5. Configure the node:
   • Name — Downlink to ThingPark Enterprise.
   • Integration — select your ThingPark Enterprise integration.
   • Click Add.
6. Connect the Message Type Switch node to the Fetch eui and fPort node using the Post attributes and Attributes Updated relations.
7. Connect the Fetch eui and fPort node to the Downlink to ThingPark Enterprise node using the Success relation.
8. Click Apply changes.

Adding or updating a shared attribute triggers the Rule Chain, which runs the downlink converter and posts the encoded command to ThingPark.

1. Go to Entities ⇾ Devices, select your device (e.g. Device 20635F00C5000660), and open the Attributes tab.
2. Switch to Shared attributes and click +.
3. Enter a key (e.g. powerState) and a value (e.g. on), then click Add.

Go to Integrations center ⇾ Data converters, open ThingPark Enterprise Downlink Converter, and click the Events tab — a Downlink event should appear in the list:

• In — the ATTRIBUTES_UPDATED message containing powerState.
• Out — the encoded JSON payload, with DevEUI and fPort set in metadata.

Open the ThingPark Enterprise Wireless Logger and confirm a downlink entry for the device — this indicates ThingsBoard successfully posted the payload to the Downlink URL for delivery to the device over LoRaWAN.

• Integrations Overview — how ThingsBoard connects to external platforms and how uplink/downlink flow works
• ThingPark Integration — connect to the hosted ThingPark network server instead of a private, on-premise ThingPark Enterprise deployment
• Uplink Data Converter — full decoder function reference: input parameters, output fields, and scripting patterns
• Downlink Data Converter — full encoder function reference: input parameters, output fields, and scripting patterns
• Remote Integration — run the integration outside the ThingsBoard server to reach ThingPark Enterprise from a private network
• TBEL scripting reference — built-in functions and operators for writing converter scripts
• Rule Engine — how the Root Rule Chain routes shared attribute updates to the downlink converter