KPN Things Integration

KPN Things is an IoT platform provided by KPN, a Dutch telecommunications company. It supports a range of IoT connectivity types — including LoRa, LTE-M, and mobile data — and lets users connect, manage, and route device data to cloud destinations via a concept called Flows. After integrating KPN Things with ThingsBoard, device data flows from the KPN Things platform directly into ThingsBoard for processing, monitoring, and visualization.

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 in ThingsBoard.
• You have a KPN Things portal account with administrative access.
• You have at least one IoT device created and registered in the KPN Things platform.
• Your device is linked to a Flow in KPN Things — devices must be assigned to a flow to send or receive data.
• Optional: For testing downlink functionality, you will need API credentials from KPN Things (see Obtain KPN Things API Credentials section).

The uplink converter receives each HTTP message sent by KPN Things, parses the JSON payload, and returns a structured object that ThingsBoard uses to create or update a device and store its telemetry and attributes.

KPN Things pre-decodes device data to SenML format before forwarding it to ThingsBoard (enabled in the Enable Data Processing step). Because of this, the default converter passes the incoming JSON through without modification — no custom byte decoding is needed. You can extend it to rename fields, filter values, or derive additional attributes.

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 KPN and select KPN Things from the list.
5. Name — enter a converter name, for example KPN Things Uplink Converter.
6. Configure the decoder:
   • 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

   /*
   * By default, we receive a message that is already correctly formatted.
   * But you can change the code for your purposes.
   */
   return decodeToJson(payload);

7. Click Add.

What the Converter Receives

ThingsBoard passes two variables to the decoder function:

The decoded payload returned by decodeToJson(payload) has the following structure:

{
  "deviceName": "urn:dev:DVNUUID:d74df9c0-c343-4879-9e4d-20483ff1b56d:",
  "deviceLabel": "My KPN Device",
  "deviceType": "DeviceSimulator(MobilePhoneapp)",
  "telemetry": [{
    "ts": 1703251120000,
    "values": {
      "battery": "34.0",
      "temperature": 22.5
    }
  }]
}

ThingsBoard reads deviceName to identify or create the device, deviceType to assign the device profile, and the telemetry array to store time-series data. To rename or filter fields before storage, transform these values in the decoder before returning.

Device Identifier

KPN Things identifies each device using a URN (Uniform Resource Name) as the deviceName. The URN follows the format:

urn:dev:DVNUUID:{UUID}:

For example: urn:dev:DVNUUID:d74df9c0-c343-4879-9e4d-20483ff1b56d:

On the first uplink, ThingsBoard creates a new device using this URN as its name. Subsequent messages from the same device update the existing device. The URN is stable for the lifetime of the device registration in KPN Things.

1. Go to Integrations center ⇾ Integrations and click + Add integration.
2. Basic settings:
   • Set Integration type to KPN Things.
   • Enable integration and Allow create devices or assets are on by default.
   • Click Next.
3. Uplink data converter:
   • Click Select existing and choose the KPN Things Uplink Converter created in the previous step.
   • Click Next.
4. Downlink data converter:
   • Click Skip — the downlink converter can be configured later if needed.
5. Connection:
   • Specify your Base URL.
   • Copy the HTTP endpoint URL — you will need it when configuring the KPN Things destination.
   See Connection settings for a full description of each parameter.
6. Click Add.

Go to Integrations center → Integrations and click + Add integration. Set Integration type to KPN Things, enter a name, and click Next Click Select existing and choose the KPN Things Uplink Converter created in the previous step, then click Next Click Skip — the downlink converter can be configured later if needed Enter your Base URL, copy the HTTP endpoint URL to paste into the KPN Things destination, and click Add

Base URL

The base address of the ThingsBoard server, used to construct the HTTP endpoint URL. For ThingsBoard Cloud, this is https://thingsboard.cloud.

Destination shared secret

Optional secret token used to authenticate KPN Things requests arriving at ThingsBoard. Learn how to implement the shared secret.

HTTP endpoint URL

Auto-generated endpoint for this integration. Paste this URL into the KPN Things ThingsBoard destination so that KPN Things forwards device uplink messages to ThingsBoard.

Allow downlink

Enable to allow ThingsBoard to send commands back to devices via KPN Things. When toggled on, a Credentials section appears with two fields:

• API ID — the API key ID used to authenticate ThingsBoard against the KPN Things API
• API Key — the corresponding API secret key

Enable security (Headers filter)

Enable to restrict incoming requests to those carrying a specific HTTP header with a matching value. When toggled on, the section shows No headers filter — click Add to add a Header / Value row. Requests missing any listed header or carrying an incorrect value are rejected. Use this to validate the X-Things-Secret header generated by KPN Things — see Configure KPN Things Webhook Security.

Execute remotely

When enabled, ThingsBoard generates an Integration key and Integration secret (both copyable) that allow the integration to run as a separate process outside the ThingsBoard cluster — useful when the integration must reach services not accessible from the ThingsBoard server.

Advanced settings

• Description — optional free-text description for this integration
• Metadata — key-value pairs injected into every uplink message as integrationMetadata in converter scripts; click Add to define entries

With the ThingsBoard integration created and the HTTP endpoint URL in hand, set up your device and data routes in the KPN Things Portal. This section guides you through device creation, flow configuration, and destination setup.

KPN Things supports multiple device types. For this guide, we use the Device Simulator (Web app) to test without physical hardware — no physical IoT device is required.

1. Go to Things Manager and click My first project to open the project overview.
2. In the Devices row, click Add Device.
3. Select your device type — for this guide, choose Device Simulator (Web app).
4. Enter a device name — for example, My KPN Device — and click Add Device.
5. The device is created — the KPN Internet Network is created toast confirms the setup. Use the browser link or scan the QR code to open the Device Simulator.

Go to Things Manager and click My first project In the Devices row, click Add Device Select Device Simulator (Web app) as the device type Enter a device name — for example, My KPN Device — and click Add Device The device is created — KPN Internet Network is created toast confirms the setup; open the Device Simulator in your browser or scan the QR code

Flows in KPN Things define how devices route their data. Each device must be assigned to a flow to send and receive data.

1. Go to Flows in the left menu and click My first flow.
2. In the Devices row, click Link Device.
3. Click Link next to the device you created.
4. The device is successfully linked to the flow.

Go to Flows in the left menu and click My first flow In the Devices row, click Link Device Click Link next to the device you created The device has been successfully linked to the flow

For ThingsBoard to properly decode device payloads, enable the data processing decoder in KPN Things. This converts device-specific formats into standard SenML (Sensor Markup Language) that ThingsBoard understands.

1. In the Devices in My first flow list, click My KPN Device to open Device Details.
2. Go to the Flows tab to view the flow diagram.
3. In the Decoders section, enable the Decoded ThingsML and raw SenML data toggle. Changes are saved automatically.

In the Devices in My first flow list, click My KPN Device Go to the Flows tab — the Decoded ThingsML and raw SenML data decoder is disabled by default Enable the Decoded ThingsML and raw SenML data toggle — changes are saved automatically

A destination in KPN Things specifies where to route device data. Create a ThingsBoard destination directly from the flow diagram — it will be linked to the flow automatically.

1. On the Flows tab of My KPN Device, click Connect destination in the flow diagram.
2. Click + Add new Destination — the destination list is empty.
3. Find ThingsBoard in the destination type grid and click Choose ThingsBoard.
4. Enter a Destination Name — for example, My ThingsBoard Instance.
5. Fill in Connection Details:
   • Paste the HTTP endpoint URL copied from the ThingsBoard integration.
   • In the Security Header section, the Header is pre-filled as X-Things-Secret — click Generate to create the token value. Save this value — you will need it when configuring the ThingsBoard integration security header.
6. Click Add ThingsBoard Destination — the destination is created and automatically linked to the flow.
7. Return to the Flows tab of My KPN Device to verify the complete pipeline — the flow diagram now shows the device, the enabled decoder, and the active ThingsBoard destination all connected.

On the Flows tab, click Connect destination in the flow diagram No destinations exist yet — click + Add new Destination Find ThingsBoard in the destination type grid and click Choose ThingsBoard Enter a Destination Name and paste the HTTP endpoint URL from the ThingsBoard integration The Header is pre-filled as X-Things-Secret — click Generate to create the token, save it, then click Add ThingsBoard Destination The destination is created and automatically linked to the flow — status shows Active The complete flow — device, decoder, and ThingsBoard destination are all connected and active

To authenticate incoming messages from KPN Things, add the generated security header to your ThingsBoard integration. This prevents unauthorized devices from sending data to your integration.

1. In ThingsBoard, go to Integrations center ⇾ Integrations and open the KPN Things integration.
2. Click the pencil icon to enter edit mode.
3. Scroll to Enable security (Headers filter) and toggle it On.
4. Click Add.
5. In the Header field, enter X-Things-Secret.
6. In the Value field, paste the security token generated in KPN Things (from the destination configuration earlier).
7. Click Apply changes.

Open the KPN Things integration and enter edit mode Enable Enable security (Headers filter), enter X-Things-Secret as the header, paste the generated token as the value, click Add, then click Apply changes

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

Open the KPN Things Device Simulator web app in your internet browser to send a test message to ThingsBoard.

1. In the KPN Things portal, open My KPN Device and go to the Application tab.
2. Under Open the application, click Open the Device Simulator application in a new tab.
3. In the Device Simulator, select the data to send — for example, enable Battery level, Temperature, and Location — and adjust the values if needed.
4. Click Send data now. A Simulated device data updated successfully toast confirms the message was forwarded to ThingsBoard.

Open My KPN Device and click Open the Device Simulator application in a new tab Select the data fields to send and click Send data now Simulated device data updated successfully — the message was sent to KPN Things and forwarded to ThingsBoard

Go to Integrations center ⇾ Integrations, open the KPN Things integration, and click the Events tab. Each successfully processed uplink appears as a row with Type: Uplink and Status: OK.

Go to Integrations center ⇾ Data converters, open KPN Things Uplink Converter, and click the Events tab. Click an event row to inspect:

• In — the decoded JSON payload received from KPN Things: deviceName, deviceLabel, deviceType, and a telemetry array with values such as battery, temperature, latitude, longitude, and orientation.
• Out — the converter output passed to ThingsBoard. For the default pass-through converter the output is identical to the input.
• Metadata — HTTP request headers forwarded by KPN Things, including x-things-secret and things-message-token.

Open the Events tab of the uplink converter to inspect individual message processing results The In view shows the decoded payload received from KPN Things before it is passed to ThingsBoard The Out view shows the converter output — for the default pass-through converter the output is identical to the input The Metadata view shows the HTTP headers forwarded by KPN Things, including the security token and message identifiers

Go to Entities ⇾ Devices. ThingsBoard automatically provisions a new device using the identifier from the uplink payload as the device name on the first message received. Open the device and click the Latest Telemetry tab — you should see the values sent by the simulator, such as battery, temperature, latitude, longitude, and orientation.

Downlink allows ThingsBoard to push commands to KPN Things devices. To enable it, obtain API credentials from the KPN Zakelijk portal, configure the integration for outbound calls, create a downlink converter, and wire up the Rule Chain.

ThingsBoard needs API credentials to authenticate against the KPN Things API when sending downlink messages. Obtain these from the KPN Things portal:

1. Log in to KPN Zakelijk portal.
2. In the left menu, click API keys.
3. Click Add API key.
4. Enter a display name (e.g., ThingsBoard Downlink).
5. Click Add API key.
6. Copy and save securely:
   • ID (e.g., bvr1quripwp951d3boos6la5jou7wtqq)
   • Secret key (e.g., 9ff04a263f6abca124c8ed131615e7…)
7. Switch to the Services and roles tab and click Add service.
8. Select KPN Things, then check Things Creator - Admin and Things Manager - Admin.
9. Click Add, then click Save changes to apply the roles to the API key.

Sign in to the KPN Things admin portal, then click API keys in the left navigation menu. On the API Keys page, click Add API key to create a new API key. Enter a display name, for example ThingsBoard Downlink, optionally provide a description, and click Add API key. Verify that Activate API Key is enabled, then copy the generated ID and Secret key. These values will be used later in the ThingsBoard integration configuration. Open the Services and roles tab and click Add service. Select the KPN Things service, assign the required roles (Things Creator - Admin and Things Manager - Admin), then click Add. Confirm that the required service and roles have been added, then click Save changes to finish configuring the API key.

Update the KPN Things integration with the API credentials:

1. In ThingsBoard, go to Integrations center ⇾ Integrations.
2. Open the KPN Things integration and click the Edit icon.
3. Scroll down to Allow downlink and toggle it On. Additional Credentials fields appear.
4. In the Credentials section:
   • API ID: Paste the ID from Step 1
   • API Key: Paste the Secret key from Step 1
5. Click Apply changes.

Open the KPN Things integration, then click the pencil icon to enter edit mode. Enable and configure the Allow downlink option.

The downlink converter transforms ThingsBoard commands into the SenML format that KPN Things expects.

The converter output must be a JSON object with the following structure:

{
  "contentType": "JSON",
  "data": "[{\"bn\":\"urn:dev:DVNUUID:c837f568-38e3-4425-b39f-d1a63848414b:\",\"n\":\"temperature\",\"v\":25.0}]",
  "metadata": {
    "topic": "devices/urn:dev:DVNUUID:c837f568-38e3-4425-b39f-d1a63848414b:/downlink",
    "FPort": 1
  }
}

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

1. Go to Integrations center ⇾ Integrations and open the KPN Things integration.
2. Click the pencil icon to enter edit mode.
3. In the Downlink data converter field, click Create new.
4. Configure the converter:
   • Name: Enter KPN Things Downlink Converter
   • Script language: leave TBEL selected (recommended).
5. In the converter editor, paste the encoder script below, and click Add.
6. Click Apply changes.

/** Encoder **/

// Create an empty SenML pack for the downlink payload.
var senmlPack = [];

// Get the device URN from metadata.
// The deviceName must contain the full KPN Things device URN.
var deviceUrn = metadata['deviceName'];

// Add the temperature value to the SenML pack if it is present in the message.
if (msg.temperature != null) {
    senmlPack.push({
        "bn": deviceUrn,
        "n": "temperature",
        "v": parseFloat(msg.temperature)
    });
}

// Return the encoded downlink payload and metadata for the integration.
var result = {
    contentType: "JSON",
    data: JSON.stringify(senmlPack),
    metadata: {
        topic: "devices/" + deviceUrn + "/downlink",
        FPort: 1
    }
};

return result;

Open the KPN Things integration, then click the pencil icon to enter edit mode. Enable the Allow downlink option, then click Create new in the Downlink data converter field. The converter type is automatically set to Downlink. Enter a name, for example KPN Things Downlink Converter, paste the encoder function, and click Add. Verify that the Downlink data converter is assigned, enter the API ID and API Key from the KPN Things admin portal, then click Apply changes.

Configure the Root Rule Chain to forward device attribute updates to the KPN Things integration.

Two rule nodes are needed: an originator fields node that reads the device name from ThingsBoard 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.
2. In the node panel, search for originator fields and drag it onto the canvas. Configure the node:
   • Name — e.g. Retrieve Device Name.
   • Under Originator fields mapping, set Source field to Name and Target key to deviceName.
   • Click Add.
3. In the node panel, search for integration downlink and drag it onto the canvas. Configure the node:
   • Name — e.g. Downlink to KPN Things.
   • Integration — select KPN Things integration.
   • Click Add.
4. Connect the message type switch node to the originator fields node using the Attributes Updated relation.
5. Connect the originator fields node to the integration downlink node using the Success relation.
6. Click Apply changes.

In the Root Rule Chain edit view, type originator fields in the node search panel and locate it under the Enrichment category. Set the node name to Retrieve Device Name, map Source field Name to Target key deviceName, and click Add. Type integration downlink in the node search panel and locate it under the Action category. Set the node name to Downlink to KPN Things, select KPN Things integration in the Integration field, and click Add. Connect the message type switch node to Retrieve Device Name via Attributes Updated, then Retrieve Device Name to Downlink to KPN Things via Success. Click Apply changes.

Trigger a downlink by adding a shared attribute to the device provisioned in Send Test Uplink:

1. In ThingsBoard, go to Entities ⇾ Devices.
2. Select a KPN device.
3. Go to the Attributes tab.
4. Click + in the Shared attributes section.
5. Add a test attribute:
   • Key: temperature
   • Type: Integer
   • Value: 25
6. Click Add. The Rule Chain triggers and sends a downlink message to KPN Things.

Check integration events

Go to Integrations center ⇾ Integrations, open the KPN Things integration, and click the Events tab. A Downlink event confirms that ThingsBoard forwarded the message to KPN Things.

The Events tab shows a Downlink event alongside the ATTRIBUTES_UPDATED trigger — both with OK status, confirming the downlink was dispatched. Click the event row to inspect the message detail — the temperature attribute update that triggered the downlink is visible in the payload.

Check downlink converter events

Go to Integrations center ⇾ Data converters, open KPN Things 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 and metadata.deviceName carries the device URN injected by the originator fields node.
• Out — the encoded SenML output sent to KPN Things: a JSON array with the device URN as base name and the temperature value.
• Metadata — integration and user context injected alongside the message.

Open the KPN Things Downlink Converter and click the Events tab — a Downlink event confirms the converter was triggered. The In panel shows the input message: msg.temperature contains the attribute value and metadata.deviceName carries the device URN. The Out panel shows the SenML payload ready to be sent to KPN Things: a JSON array with the device URN as base name and the temperature measurement. The Metadata panel shows the integration context — integration name, user, and the device URN injected by the Originator fields node.

Check delivery on KPN Things

Open the KPN Things portal, navigate to Things Manager ⇾ Devices, and open your device. Click the Send instruction tab and scroll down to the Status Downlink section — the Temperature message with status EXECUTING confirms the downlink reached the device.

Open your device in Things Manager ⇾ Devices and click the Send instruction tab. The Status Downlink section shows the Temperature: 25 message with EXECUTING status — the downlink reached KPN Things and was forwarded to the device.

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

No Uplinks in ThingsBoard

Uplink Received but Device Not Created

Device Created but No Telemetry

Downlink Not Delivered

Security Header Validation Failures

How to Read Debug Events

1. Go to Integrations center ⇾ Integrations, open the KPN Things integration, and click the Events tab.
2. Click an event row to inspect:

• In — the raw HTTP request body received from KPN Things 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.

Enable Debug mode on both the integration and the uplink converter to capture all incoming messages and conversion results. 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
• ThingsBoard Expression Language (TBEL)