What is a Destination?

Unlock the power of your IoT data with KPN Destinations. Whether you want to visualize, enrich, analyze or build complete AI products with your IoT data, our destinations offer flexible connections to any proprietary or cloud platforms of your choice.

With integrated custom apps, pre-built visualisation templates, or popular cloud environments, you're free to choose the platform that best fits your needs. Plus, you can skip the hassle of reformatting data; if desired - we've handled that for you. Start to build, scale, and optimize platforms seamlessly for IoT success, with no platform restrictions.

No KPN Things account? No worry. Get started here.

To create a destination you'll need;

• Name - A descriptive name for your Destination.

• Description (optional) - Some more information about your Destination.

• Destination type - The type of Destination you are adding. KPN Things supports several.

Created Destinations have additional information:

• UUID - The technical identifier of your Destination.

• Destination status - The operational status of your Destination.

Destination types

Multiple different Destination types are supported by KPN Things. Each Destination type has its own configuration attributes and specific working, explained on the corresponding More info page.

Missing Destinations?

Destination types capabilities

We currently support five types of destinations:

Mgmt - Whether KPN Things can manage objects in the connected Destination. Up - Whether KPN Things can send uplink data to the connected Destination. Down - Whether KPN things can send downlink data to the connected Destination.

Destination status

All Destinations page

The All Destinations page can be reached by clicking on All Destinations in the side menu of the Portal.

On this page you will find:

1. The number of Destinations you have.

2. A table with information about all your Destinations:

   1. Their name.

   2. Their Destination type.

   3. In which Projects they are used.

   4. To how many Flows they are linked.

   5. Their Destination status.

3. A button to add a new Destination.

Clicking on a row in the Destinations table will link you to the Destination detail page for that Destination.

Add new Destination

When adding a new Destination, you first have to select the type of Destination you want to add. Each Destination type has its own input form presenting you with all configuration options you have for the Destination.

Check out all available Destination types and click on More info to get more details about that Destination type. All configuration options are explained, as well as the detailed working of each Destination type.

After entering the correct values, click the Add button to add your Destination.

Destination details page

This page offers you with all detailed information about your Destination.

The elements on this page are:

1. The name of your Destination.

2. General information about your Destination.

3. Status information about your Destination:

   1. The Destination status.

   2. The Flows your Destination is linked to.

4. Button to deactivate your Destination. If your Destination is deactivated, this will be an activation button.

5. Destination Specification tab showing you detailed information about your Destination configuration.

6. Flows tab showing you detailed information about the Flows your Destination is linked to.

7. A button to delete your Destination. This will completely remove your Destination from KPN Things!

Destination Specification tab

The Destination Specification tab shows you detailed information about your Destination (#1 in the screenshot below). Displayed information differs for different Destination types. The tab also offers you an Edit link to edit the configuration of your Destination (#2 in the screenshot below).

Flows tab

The Flows tab offers you a list of all the Flows your Destination is linked to and the Project this Flow is in. You can click on a Flow to open it, or you can click on Unlink from this Flow to remove the Destination from that Flow. The option to link your Destination to another Flow from here will be added in the near future.

Technical specifications

Do you want to whitelist our IP address in your application? This is our outgoing IP address:

194.122.128.33

Connect an MQTT broker

The following parameters are available to connect an MQTT broker:

*) required value †) secret value, can only be written

Variables

• {clientUuid} Your Client UUID

• {mqttClientId} MQTT Client ID

• {deviceUuid} Device UUID

• {senmlBaseName} SenML base name

• {destinationUuid} Destination UUID

• {messageRequestId} Message request ID

What does the connection do?

• Open an encrypted client connection to your MQTT broker.

• Publish all forwarded IoT data in SenML JSON format on topics following the specified topic template.

Trusted TLS/SSL certificates

We do not support self-signed certificates. Your TLS/SSL certificate should be signed by a root certificate authority (CA) that is trusted by the default Java trust store. You can use the SSL Server Test from Qualys to check if your certificate is trusted by the Java trust store:

Your server should preferably use TLSv1.2 or higher, but at least TLSv1.1. Older protocols are not supported because they are not considered safe.

Learn about MQTT

Are you new to MQTT, but still interested in using it? HiveMQ has published some very nice articles about MQTT essentials:

Test with a demo broker

You can find a publicly available Mosquitto MQTT server/broker on https://test.mosquitto.org. This allows you to try to connect KPN Things to an MQTT broker. Do not use this public MQTT broker for production!

Configure a Cumulocity destination

Name

Give your Cumulocity destination name and optionally a description.

• Destination name (required) - the administrative name of your Destination.

  • Technical name: name

  • Example value: Tenant X

• Description - an administrative description of your Destination.

  • Technical name: description

  • Example value: Tenant with Materieelbeheer application

Connection details

Create a Cumulocity environment at https://signup.softwareag.cloud.

• URL (required) - base URL of your Cumulocity environment.

  • Technical name: tenant

  • Example value: https://example.eu-latest.cumulocity.com

Create KPN Things user in Cumulocity

Create an additional user in de Administration of your Cumulocity environment. To do so use the Application Switcher to switch to the Administration application and click on Users. Create a new user with the role admin.

• Username (required, secret) - Username of the functional user that KPN Things should use to access your tenant.

  • Technical name: username

  • Example value: kpnthings

• Password (required, secret) - Password of the functional user that KPN Things should use to acces your tenant.

  • Technical name: password

• Generate a dedicated Things user & renew password automatically - Credentials of Cumulocity accounts expire after some time. Enabling this option will renew the password in time to prevent expiry.

  • Technical name: credentialManagementEnabled

  • Boolean value

Advanced configuration

• Bidirectional behavior - Choose whether the destination should process uplink data (data from Device to Application), downlink data (data from Application to Device) or both.

• Technical name: bidirectionalBehaviour

• Default value: ONLY_UPLINK

• Available values:

  • ONLY_UPLINK - Only forward uplink data to Cumulocity.

  • ONLY_DOWNLINK - Only synchronize Cumulocity operations with Things downlinks.

  • BIDIRECTIONAL - Process both uplink and downlink data.

  • BIDIRECTIONAL_WITH_RETRY - Process both uplink and downlink data, and make sure downlinks are retried by KPN Things.

• Which messages should be sent to this Destination?

  • Technical name: sendMeasurements(Boolean value)

  • Technical name: sendLocationUpdateEvents(Boolean value)

• Extra label for new devices - List of additional custom fragments to add to the device object when it is created in Cumulocity.

  • Technical name: customFragments

  • Example value: c8y_CustomApplication

What does the connection do?

This section describes the functionality of the connection to Cumulocity.

Find or create device record

When IoT dat is about to be forwarded to Cumulocity, it will first try to find the device Managed Object using the base name from the SenML message. For this it looks for an external identifier of type DEVEUI and the base name as value. For instance:

GET /identity/externalIds/DEVEUI/urn:dev:DEVEUI:0123456789012345:

If such an external identifier does not exist, a new device Managed Object and the required external identifiers is created. This is called provisioning in runtime.

Create device record

KPN Things will create a device Managed Object if it did not exist. The device Managed Object will be created with the following information, using the device record that is known in the Data Management platform.

Additionally, the configured custom fragments (and fragments used for application association) are added to the object. In the example below, a device is created that had customFragment exampleFragment configured and application ASSET_TRACKING was configured as well.

{
  "name": "<device.name>",
  "c8y_IsDevice": {},
  "c8y_Metadata": {
    "barcode": "<device.barcode>" /* If barcode is known */
    "activatedNetworks": [ /* For each network the device is registered */
      {
        "networkStatus": "ACTIVE",
        "networkType": "<device.network.networkType>",
        "uuid": "<device.network.uuid>",
        "devEUI": "<device.network.networkId>"
      }
    ]
  },
  "c8y_Hardware": {
    "serialNumber": "<device.networkId>", /* SenML base name of primary network */
    "model": "<device.deviceSpecification.model>"
  },
  "exampleFragment": {}, /* Configured custom fragment */
  "c8y_IsForAssetTracking": {} /* Asset Tracking fragment */
}

Create external identifiers

Using the main network id an external identifier is created for the newly created device Managed Object.

Additionally, if a barcode is known present in the device object, another external identifier of type BARCODE is created as well.

Uplink: Send measurement

After the device Managed Object is found or created, a measurement is added to this device of the type kpn_SenMLMeasurement. A full example can be found below.

{
  "time": "<from SenML bt>",
  "type": "kpn_SenMLMeasurement",
  "kpn_SenMLMeasurement": {
    "<senml[0].n>": { (For all number and boolean measurements)
      "unit": "<senml[0].u>",
      "value": <senml[0].v>
    },
    "<senml[1].n>": {
      "unit": "<senml[1].u>",
      "value": <senml[1].v>
    },
	...
  },
  "kpn_SenMLMeasurement_data": { (for all string measurements)
    "<senml[2].n>": "<senml[2].v>"
  }
}

More information on SenML can be found on this page.

Uplink: Update location and send location update event

If the measurement contains both latitude and longitude, the device Managed Object's c8y_Position value is updated with the newly calculated location.

Also, it will create a c8y_LocationUpdate event on the device, according to the Cumulocity sensor library.

Example location update event

{
  "time": "2019-07-02T11:20:34.000Z",
  "source": {
    "id": "<device id>"
  },
  "text": "LocUpdate",
  "type": "c8y_LocationUpdate",
  "c8y_Position": {
    "lat": 51.9072126,
    "lng": 4.4893038,
    "alt": 0.0,
    "radius": 140.2
  }
}

Downlink: Synchronize Cumulocity operations with Things downlinks

The Cumulocity destination will poll your Cumulocity environment for operations. When the destination finds a new operation, recognizable because its status is PENDING, a Downlink is created for the corresponding Device.

To create the Downlink, the Cumulocity external ID is used to map to the correct Device in KPN Things. Additionally, the Cumulocity operation value deviceStatus is fetched, and put in a string value for the SenML downlink command mode.

When the operation has been picked up by KPN Things, we change the status to EXECUTING. When the downlink has finished, we will update the Cumulocity operation status to SUCCESSFUL or FAILED depending on whether the downlink was successful or not.

Connecting an HTTPS destination enables you to forward IoT data from KPN Things to your server through an HTTPS connection.

Connect an HTTPS destination

The following parameters are available to connect an HTTPS destination:

*) required value †) secret value, can only be written

The request

• {xx} is a destination parameter

• <xx> is a variable filled by the system for each request

{method} {url(path)} HTTP/1.1
Host: {url(domain)}
Things-Plug-UUID: <plugUUID>
Things-Message-Token: <token>
Content-type: application/json
{additional-headers}

<senML>

• plugUUID is the unique identifier of the destination connection that allows you to lookup the shared secret in your own database that should be used to check the Things-Message-Token

• token must be used to verify the authenticity of the request data. It is a SHA-256 hash calculated over the SenML body in the request and a shared secret unique for this destination. Since only KPN Things and you know this secret, the authenticity of the message is verified.

• senML is the device data

Things-Message-Token

The HTTPS request contains a Things-Message-Tokenheader which allows you to verify the origin of the request. The token is a hash, calculated as following:

token = sha256({senMLBody}{sharedSecret})

Where {senMLBody} is the body of the request, and sharedSecret is the password set when adding the destination. The shared secret should at least be 30 characters long.

You must generate and fill in your own shared secret when adding the destination. Since the token is stored securely in our system, it is not possible to retrieve the shared secret from the destination configuration after creation. It is only possible to renew the secret.

Request body

The body of the HTTPS request will contain the SenML object in JSON formatting. It will contain the device identifier and the measurement data. Learn more on the SenML object here:

TLS/SSL Requirements

KPN Things does not facilitate unsafe connections. For the definition of a safe connection we follow the KPN Security Policy. There are three aspects you need to take into account when configuring TLS/SSL on the endpoint where you want to deliver your IoT Data.

Trusted certificate

We do not support self-signed certificates. Your HTTPS certificate should be signed by a root certificate authority (CA) that is trusted by the default Java trust store. You can use the SSL Server Test from Qualys to check if your certificate is trusted by the Java trust store:

Up to date TLS version

Your server should use TLSv1.2 or higher. Older protocols are not supported because they are not considered safe.

Safe cipher suite

Your server should support at least one of the cipher suites stated below. The cipher suites in this table are considered safe.

Example HTTPS request

POST /thingsdata HTTP/1.1
Host: www.example.com
Things-Plug-UUID: fbc063cb-4dd4-41b3-917a-e2d1ea907f75
Things-Message-Token: a7939780a487b036d5f41edf29ee3e087b14c121302e321326865255de8ea9c9
Content-type: application/json
Content-length: 106
Test-header: Hello world

[{"bn":"urn:dev:DEVEUI:0000000000000000:","bt":1.58565075E9},{"n":"temperature","v":21.22,"u":"Celsius"}]

Setup test endpoint

If you do not have an HTTPS endpoint in your back pocket, you could use services like webhook.site to setup your first endpoint to receive your IoT data.

When you open the webhook.site website you will get a unique URL that you can use as endpoint for your HTTPS destination:

KPN Things: Configure a ThingsBoard destination

Name

Give your ThingsBoard Destination a name and optionally a description.

• Destination name (required) - the administrative name of your Destination.

  Technical name: name

  Example value: Tenant X

• Description - an administrative description of your Destination.

  Technical name: description

  Example value: Tenant with Materieelbeheer application

Connection details

First you need to create a ThingsBoard Cloud account (Professional Edition) on https://thingsboard.io. Then follow the instructions below to create an integration in your ThingsBoard account. Keep your KPN Things Destination configuration screen open, as you will need to copy information from and to it later.

ThingsBoard: Create an integration

Log in to your ThingsBoard account and go to Integrations center > Integrations. There, add a new integration (by clicking the "+"-sign) and follow the steps below.

1. Basic settings

In the first step, enter the following information.

• Integration type (required) Select HTTP as the integration type.

• Name (required) Enter a descriptive name, anything you like, such as KPN Things integration.

Click Next.

2. Uplink data converter

Select Create new uplink data converter and enter a descriptive name, such as KPN Things converter.

Next, replace the example code with the following code:

Click Next.

3. Downlink data converter

Skip this step. Yes, by clicking the Skip button ;-).

4. Connection

In this step, you need to copy/paste information back and forth. So pay attention, please.

• HTTP endpoint URL Copy the HTTP endpoint URL from ThingsBoard into the KPN Things Destination configuration.

• Enable security (Headers filter) In ThingsBoard, switch the toggle Enable security (Headers filter) to on.

• Add a set of headers Click Add to reveal a set of input fields.

• Configure the Header and Value pair Go back to the KPN Things Destination configuration screen, and click the Generate button next to the Security header fields. This will generate a value for the X-Things-Secret header. Copy/paste both the Header and generated Value to the corresponding fields in ThingsBoard. Then, press Add the save new integration in ThingsBoard.

Lastly, go back to the KPN Things Destination configuration screen and press the Add ThingsBoard destination button to save the new destination in KPN Things.

Now you are finished and good to go!

The Test Endpoint is designed to inspect the messages sent from your Flow.

Configure your Test Endpoint

1. Choose Test Endpoint as your destination.

1. Type in your name for your new Test Endpoint and write your description to describe your current Test Endpoint. - url: used to send device-data to. Automatically filled in. - Shared Secret: Used for encryption & Validation. Automatically filled in.

1. Link your device to a flow. You'll also have to link your device(s) to your desired flow, before creating your Test Endpoint.

1. Thats it! Now you should be able to find and view your Test Endpoint within your "Destinations" page. Feel free to make as many as you'd like.

1. View the messages that were sent to the Test Endpoint.

Be aware of the following constraints.

• All messages expire after 5 days.

• A maximum of 100 most recent messages will be shown.

• Messages: Here you can view the messages that were sent to your Test Endpoint.

• Details: Contains the message ID and the timestamp when the message was received.

• Headers: The default HTTP headers that are sent to the Test Endpoint. These headers are the same default headers that a HTTPS Destination would receive. Note that for a Test Endpoint these headers can not be customised, for a HTTPS Destination you are able to add custom headers.

• Content: Contains the payload that was sent to the Test Endpoint. It matches the output of your decoders that was enabled in the flow. For the majority of cases, this payload will be SenML JSON data. See:

Below instructions help you connecting your Azure IoT Hub to KPN Things.

Don't have an Azure IoT Hub yet? Head on over to the Microsoft documentation on Azure IoT Hub. You can try one for free using the Azure free account!

For now, a Basic tier will be sufficient for a working connection with KPN Things. Later, we will introduce downlink and device twin functionality to the connection and for that the Standard tier is required.

Connect an Azure IoT Hub

The following parameters are available to connect your Azure IoT Hub:

*) required value †) secret value, not returned by our API's

Where to find the required configuration values in the Azure Portal?

Hostname

You can find the hostname on the overview page of your IoT Hub, as highlighted in the screenshot below:

SAS key name and SAS key

For the key name and key you need to create a Shared access policy for your IoT Hub. Make sure you enable all permissions for the Policy you create for KPN Things, since all permissions are required:

• Registry write

• Service connect

• Device connect

After creation of your policy, you can find the SAS key name and SAS key in the

What does the connection do?

• KPN Things will register new devices in the IoT hub when IoT data is forwarded for devices that are not yet in the IoT Hub.

• KPN Things will forward all IoT data as telemetry in the IoT Hub from devices linked to the destination.

In the future we plan to support downlink communication using Cloud-to-Device communication in the IoT Hub, and we plan to support device twin synchronization between KPN Things and the IoT Hub.

KPN Things: Configure a Google Cloud Run functions destination

Name

Give your Google Cloud Run functions Destination a name and optionally a description.

• Destination name (required) - the administrative name of your Destination.

  Technical name: name

  Example value: Tenant Z

• Description - an administrative description of your Destination.

  Technical name: description

  Example value: Send my data to Google Cloud for further data processing

Connection details

First you need to create a Google Cloud account on, or use an existing Google Cloud account. Then follow the instructions below to create an integration in your Google Cloud account. Keep your KPN Things Destination configuration screen open, as you will need to copy information from and to it later.

Google Cloud: Create an integration

Log in to your Google Cloud account and go to Console. Then select the project of your choice and from there select the Cloud Run Product.

From the Cloud Run menu select the option Write a Function

The following form is presented.

1. Basic information

In the first step, enter the following information.

• Service name Enter a name that describes the purpose of your function.

• Runtime Choose the language to use to write your function. For this example Python 3.10 is chosen.

• Authentication

  Choose the authentication type. For this example, Allow unauthenticated invocations.

All other setting can be left to default.

Click Create .

2. Code

Select the Source tab to define your code. The screenshot below contains example code.

Click Save and Redeploy

KPN Things: Continue with Configure a Google Cloud Run functions destination

In this step, you need to copy/paste information from Google Cloud to Things. So pay attention, please.

Go back to the KPN Things Destination configuration screen and fill the remain fields.

• HTTP endpoint URL Copy the Function URL from Google Cloud into the KPN Things Destination configuration.

• Shared secret With the shared secret you have the possibility to verify that Things has sent the data and not someone else, because with the shared secret a unique Things Message Token is calculated for each message. Within the Google Cloud Run function you can repeat the calculation and check whether the calculated Things-Message-Token is the same as the received Things-Message-Token. Below you can find an example of a calculation and a check in Python.

Finally, go back to the KPN Things Destination configuration screen and press the Add Google Cloud Run functions destination button to save the new destination in KPN Things.

Now you are finished and good to go!

KPN Things: Configure a Datacake destination

Name

Give your Datacake destination a name and optionally a description.

• Destination name (required) - the administrative name of your Destination.

  Technical name: name

  Example value: My Datacake destination

• Description - an administrative description of your Destination.

  Technical name: description

  Example value: View my device data in Datacake

Connection details

Connectivity type (required) - As part of the set up you will need to choose which connectivity type to use while creating your Devices in Datacake. You can use either LoRaWAN or API with KPN Things depending on the choice of the Connectivity type in Datacake.

Now, follow the instructions below to create an integration in your Datacake account. Keep your KPN Things Destination configuration screen open, as you will need to copy information to it later.

Datacake: Create an integration

Log in to your Datacake account and go to Devices. There, add a new device (by clicking the "Add Device"-button in top right corner) and follow the steps below.

Choose LoRaWAN for LoRa devices that send raw payloads. For M2M devices or LoRa devices that do not send raw payloads choose API. The option LoRaWAN also offers the possibilty to send downlinks and to secure the connection between KPN Things and Datacake. For securing the connection between KPN and Datacake you can use a Shared Secret.

Click Next.

2. Select product

Select a New Product from Template, an Existing Product or create a new Product depending on the device type.

Click Next.

In case of LoRaWan

Select KPN as Network Server and then click Next.

In case API

There is no Network Server Selection.

3. Add devices

Add one or more devices together with their details. This step is the same for both options (LoRaWAN/API).

Click Next

4. Choose the Plan

Click "Add [Number of devices] devices". This step is the same for both options (LoRaWAN/API).

After that the device(s) should appear in the Device list under Devices.

5. Select the device

Select the device from the Device list and go to the Configuration tab.

In case of LoRaWAN

In the LoRaWAN section, click the Change button under Network Server and right next to KPN. From there copy the Uplink URL

In case of API

In the HTTP endpoint URL section copy the URL.

KPN Things: Continue with Configure a Datacake destination

In this step, you need to copy/paste information from Datacake to the Datacake Destination in KPN Things. So pay attention, please.

In case of LoRaWAN

• Uplink URL Paste the URL copied from Datacake mentioned under 5.

In case of API

• HTTP endpoint URL Take the HTTP endpoint URL from the HTTP Payload Decoder section on the device Configuration tab.

Then, press Add Datacake Endpoint to save the new destination in KPN Things. Do not forget to add the newly created Datacake destination to a flow.

Now you are finished and good to go!

KPN Things: Configure an AWS Lambda destination

Naming

Give your AWS Destination a nice name and optionally a description.

Connection details

First you need to create an AWS account (AWS Free Tier) on, or use an existing AWS account. Then follow the instructions below to create an integration in your AWS account. Keep your KPN Things Destination configuration screen open, as you will need to copy information from and to it later.

AWS: Create an integration

Log in to your AWS account and go to Services > Lambda. There, click the Create function button and follow the steps below.

1. Basic information

In the first step, enter the following information.

• Function name Enter a name that describes the purpose of your function.

• Runtime Choose the language to use to write your function.

• Architecture

  Choose the instruction set architecture you want for your function code.

Permissions and Advanced Settings can be left to default.

Click Create Function.

2. Code

Select the Code tab to define your code.

3. Configuration

In the Configuration tab choose the option Function URL.

Then Click Create function URL and choose your Auth type, in this case NONE.

Click Save. This result in Function URL.

KPN Things: Continue with Configure a AWS destination

In this step, you need to copy/paste information from AWS to Things. So pay attention, please.

Go back to the KPN Things Destination configuration screen and fill the remain fields.

• HTTP endpoint URL Copy the Function URL from AWS into the KPN Things Destination configuration.

Finally, go back to the KPN Things Destination configuration screen and press the Add AWS destination button to save the new Destination in KPN Things.

Now, you are finished and good to go!

Below instructions help you connecting your Azure Event Hubs to KPN Things.

Don't have an Azure Event Hubs yet? Head on over to the Microsoft documentation on Azure Event Hubs:

Connect an Azure Event Hubs

The following parameters are available to connect an Azure Event Hubs

*) required value †) secret value, write only, not returned by our systems

Where to find the required configuration values in the Azure Portal?

Host name and Namespace

Open the Overview page of your Event Hubs Namespace in your Azure Portal. You will find the host name of your namespace (#1 in the screenshot) and the Event Hubs Namespace (#2 in the screenshot) as highlighted in the screenshot below.

Can't see the Host name? In the Dutch user interface, it is not visible. Switch to English language to see the host name in the Overview page.

Now, use this value to make the following input values for the Azure Event Hubs destination configuration:

• Host name: should be of the form https://X.servicebus.windows.net, so put https:// before your host name and you're done.

• Event Hubs Namespace: should be the name of your namespace.

Event Hubs Instance / Event space name

Continue by clicking on Event Hubs under Entities in the left menu of your Namespace. Select the Event Hub Instance you would like to connect to. This opens the Overview page of your Event Hubs Instance. Here you will find the name of your Event Hubs Instance, also known as Event Space Name, as highlighted in the screenshot below:

• SAS Policy name: #1 in the screenshot above highlights the SAS key name of a selected Policy.

• SAS Primary key: #2 in the screenshot above highlights the SAS key of a selected Policy.

What does the connection do?

Example for data debugging #1: Capture

Example for data debugging #2: Process data explorer (Query)

You can use SQL-like queries to explore your Event Hub data in the Process data feature. In the screenshot below it is shown how raw LoRa payload can be found in the data explorer.