LogoLogo
  • KPN THINGS USER GUIDE
    • Introduction
    • Getting started
      • Registration and setup
      • Device simulator app
      • Connect devices
        • SIM cards
        • Supported devices and KPN Devices
        • SODAQ R412M
        • Smartrak
        • Marvin development board
        • LoPy5
        • Arduino MKR WAN 1300/1310
        • Arduin MKR NB 1500
    • All videos
    • Tutorials
      • Configure a flow
      • Connect a HTTPs destination
      • Create a simple IoT web applicationPage
      • Send instruction to LoRa DevicePage
      • Send your data to Azure SQL
      • Technical overview
        • Management data model
        • Uplink communication
        • Downlink communication
        • Location data
      • Accounts and projects
        • Customer accounts and users
        • Projects
        • Customer management
        • Cost overview and contract
    • Frequently asked
      • Multi Factor Authentication
  • GENERAL FUNCTIONS
    • Quick reference videos
    • APIs
  • THE PORTAL EXPLAINED
    • Things Manager
      • Devices
        • Bulk operations
      • Data
        • Device data graph
      • Connectivity
        • LoRa connectivity configuration
      • Bulk reports
    • Things Creator
    • Support
      • News
      • Release notes
      • Real-time status
      • Service reports
      • Documents
      • Support tickets
      • Invoices
      • Contact info
    • Shop
  • BUILDING BLOCKS
    • Devices
      • Sensors
        • KPN Conditionsensor CO2 II
        • KPN Conditionsensor CO2 III
        • KPN Conditionsensor CO2 III motionPage 1
        • KPN FillTag I
        • KPN FillTag II
        • 1M2M ED1608
        • Elsys ERS
        • Device Simulator (Mobile Phone app)
        • Generic Device (Internet connected)
        • Generic LoRa device (preset connectivity)
        • Generic LoRa device (programmable)
        • Generic M2M device
        • Generic M2M device (with Internet connection)
      • Trackers
        • KPN Global Tracker Autonomous
        • KPN Global Tracker Wired
        • KPN LocationTag I
        • KPN LocationTag II
        • KPN LocationTag II v2
        • KPN LocationTag II v2 Expert Mode
        • KPN LocationTag II v3
        • KPN LocationTag III (with GPS)
        • KPN LocationTag III (without GPS)
        • KPN LocationTag III v2
        • KPN LocationTag III v2 Buffer
        • KPN LocationTag III v3
        • KPN LocationTag III v4
        • KPN LocationTag V
        • KPN LocationTag VI
        • KPN LocationTag WS
        • Streamline LoRa
        • Streamline M2M
        • Viloc
      • Routers
      • Gateways
        • KPN FSK Basestation
      • Device SDK
    • Connectivity
      • Connecting LoRa devices
        • LoRa connectivity configuration
      • Connecting M2M devices
      • Connecting Internet devices
      • Connecting MQTT Devices
    • Data Processing
      • ThingsML and SenML
        • ThingsML
        • SenML
          • Understanding and Interpreting SenML Data
          • Changes in KPN SenML
      • Device Twin
      • Decoders and encoders
        • Common measurements list
        • Decoder migrations
        • DIY Decoder
          • DIY decoder scripts
      • Merger
      • Device data
      • Devices
    • Destinations
      • HTTPS destination
      • MQTT broker
      • Cumulocity IoT Platform
      • Azure Event Hubs
      • Azure IoT Hub
      • Test Endpoint
      • ThingsBoard
      • Datacake
      • AWS Lambda
      • Google Cloud Run functions
  • IOT LINE UP
    • Freemium
      • Test SIM cards
    • Explorer
    • Modular
    • Tailored
    • Terms and Conditions
Powered by GitBook

© 2024 KPN - All rights reserved.

On this page
  • Configure a Cumulocity destination
  • Name
  • Connection details
  • Create KPN Things user in Cumulocity
  • Advanced configuration
  • What does the connection do?
  • Find or create device record
  • Uplink: Send measurement
  • Uplink: Update location and send location update event
  • Downlink: Synchronize Cumulocity operations with Things downlinks

Was this helpful?

Export as PDF
  1. BUILDING BLOCKS
  2. Destinations

Cumulocity IoT Platform

Forward your IoT data to a Cumulocity environment

PreviousMQTT brokerNextAzure Event Hubs

Last updated 3 months ago

Was this helpful?

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 .

  • 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

  • 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)

    • Technical name: customFragments

    • Example value: c8y_CustomApplication

A secret value is treated as a secret in our database and is therefor not returned in the API object response.

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.

createdDeviceRecord
{
  "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

The following configurations are required to enable sending measurements:

  1. Bidirectional behavior set to Only uplink or Bidirectional.

  2. One of the following:

    1. sendMeasurements should be enabled to enable this feature, or

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>"
  }
}

Uplink: Update location and send location update event

The following configurations are required to send location update events:

  1. Bidirectional behavior set to Only uplink or Bidirectional.

  2. One of the following:

    1. sendLocationUpdateEvents should be enabled to enable this feature, or

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 following configurations are required to send location update events:

  1. Bidirectional behavior set to Only downlink or Bidirectional.

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.

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

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

An should be selected that enables sending measurements.

More information on SenML can be found on .

An should be selected that enables sending measurements.

An should be selected that enables operations handling.

https://signup.softwareag.cloud
application
this page
application
application
uplink
data
downlink data
created in Cumulocity