Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Data Processing is the core of the KPN Things platform. Both in uplink and downlink communication it links the devices to the destinations and vise versa. It makes information from raw data, and translates universal instructions into device specific commands.
Data Processing can be configured on the Data Processing in Flow page.
Data Processing configuration is configured in a Flow. It expresses how data from and to your Devices should be processed by KPN Things. This processing is useful, because your Destination does not always understand what your Device is saying, and vice versa. This data should be transformed or interpreted between your Device and Destination.
We distinguish two type of actors that process data:
Decoders process data coming from your device (uplink data).
Encoders process data going to your device (downlink data).
Uplink data is processed by Decoders, Downlink data is processed by Encoders.
Uplink data configuration has to do with the data sent from your Device and possible metadata coming along when data is sent by your Device. An example of the latter is LoRa Geolocation data; location data that the LoRa network can determine when receiving the message from your Device.
We distinguish three types of data that can be enabled to forward to your Destination. Each type has its own symbol that is used in the name of the Decoder.
Symbol
Output data type
›
Decoded data, so incoming encoded data transformed into understandable measurements in SenML format.
+
Additional data (decoders) enabling metadata corresponding to the message send by your Device.
=
Raw data, just forwarding data like it is received by KPN Things.
Downlink data configuration has to do with the data sent to your Device. Often you want to send a clear instruction to your Device, which is transformed under water into a technical data message to your Device. This is where Encoders come into play. Next to that, also raw data can be sent to your Device.
We distinguish two different ways of sending data to your Device, identified by a symbol in the name of the Encoder.
Within a Flow you configure the way your IoT data should flow through KPN Things. You link one or more Devices to one or more Destinations through the Flow, and you determine the Data Processing in between. So, if data is received from a Device that is linked to a Flow, its data will be processed as configured and then forwarded to the Destinations that are linked to the same Flow.
A Flow has the following attributes:
UUID - the technical identifier of your Flow.
Name - the name you give to your Flow.
Description (optional) - further explanation of your Flow.
This page gives you an overview of the configuration of a Flow.
It shows you:
The name and description of your Flow.
A link to the Flow detail page, where you can edit the name and description of your Flow.
The number of Devices in your Flow and a smart link to the Devices in your Flow.
A summary of the Data Processing in your Flow and a link to the Data Processing in Flow page.
Removed. The configuration of Device Twin values has been removed in favor of showing all possibles values by default.
The number of Destinations in your Flow and a smart link to the Destinations in your Flow.
A delete button to remove your Flow. All Devices and Destinations that were linked to the Flow will not be deleted, they can still be found on the All Devices page and All Destinations page respectively after you deleted your Flow.
If there is an issue with the configuration of your Flow, a warning icon is shown in the description of the concerning part of the configuration. Click on the warning label to find out more about the issue.
The smart link allows you to quickly get to the Devices and Destinations in your Flow from the overview page. Depending on the number of Devices or Destinations you have in your Flow, the card will link you to a different view:
The Flow detail page shows the details of your Flow (#1 in the screenshot) and it allows you to edit the name and description of your Flow by clicking Edit (#2 in the screenshot).
This page shows you the Devices that are linked to the current Flow.
Elements on this page are:
The number of Devices in the current Flow.
The list of devices, showing their name, device type and last message time.
When you click on a table row, you are sent to the Device detail page of the selected Device.
You can sort the Device list by clicking on the column header you want to sort by.
A button to add another Device to this Flow.
Checkboxes that allow you to start bulk actions.
After selecting one or more Devices you enter the bulk editing mode. This allows you to select several Devices (#1 in the screenshot below) or all Devices at once (#2 in the screenshot below). After you completed your selection, click on the desired action in the bulk action bar in the bottom of your screen. In this case, you can Unlink all selected Devices from the current Flow.
When you have reached the maximum number of unique devices in your Project, you will not be able to add another device to your Flow. The Add Device button will then be grey and disabled.
Also, it can occur that you have reached the total maximal amount of Devices in your account. Then you can only link an existing Device to your Flow, you cannot add a new Device. In that case the Add a new Device button will be grey and disabled.
When adding another Device to a Flow, you have two choices:
Add a new Device - register a complete new device to KPN Things and directly add it to the Flow.
Link an existing Device - link a device that is already registered to KPN Things. You can add one Device to multiple Flows.
This page is identical to the Add new Device page coming from the All Devices page, with the additional step of Decoder activation.
At this step you can select the decoders you want to enable for this device type in the current Flow by checking the corresponding decoder (like #1 in the screenshot above). If you have previously activated decoders on this Flow for this Device type, they will be already checked (like #2 in the screenshot above). Learn more about Decoders.
This page will show you an overview of all Devices already linked to your Flow and other available Devices. There are two methods to link existing Devices to a Flow:
By clicking Link on the row of a Device, you link that single Device to the Flow.
By selecting a checkbox in a row of a Device, you start with linking multiple Devices to the Flow.
After selecting one Device you can select more using the checkboxes (#1 in the screenshot below), or even select all Devices you have using the checkbox in the top row (#2 in the screenshot below). When you finalized your selection you can commit the linkage with the button Link selected (#3 in the screenshot below).
The Data Processing in Flow page shows you the configuration of the data processing for Devices in that Flow.
When you visit the page, it first shows you the Device types that are present in the Flow. For each Device type it shows the number of devices linked to the Flow (#1 in the screenshot below), and the number of Decoders and Encoders enabled for that Device type (#2 in the screenshot below.
After you clicked on one of the Device types, all available Decoders (#1 in the screenshot below) and Encoders (#2 in the screenshot below) are shown for that Device type. The toggles to the right of the list (#3 in the screenshot below) indicate whether a Decoder or Encoder is enabled for that Flow. Learn more about Data Processing configuration
If there is a possible issue with your data processing configuration, a warning icon is shown for the concerning Device type (#1 in the screenshot below) and a warning message is shown explaining the issue (#2 in the screenshot below). We offer three possible solutions for the issue:
Show you where to fix the issue (#3 in the screenshot below)
Fix it for you (#4 in the screenshot below)
Let you ignore the warning (#5 in the screenshot below)
This page shows you the Destinations linked to the current Flow.
On this page you can see:
The number of Destinations in the current Flow.
A list of the Destinations in this Flow with their name, status and type. By clicking on a Destination, you will go to the Destination detail page of the selected Destination.
A button to add another Destination to your Flow. If you have reached the maximum number of Destination links in your Project, this button will be disabled.
When you have reached the maximum number of Destination links in your Project, you will not be able to add another Destination to your Flow. The Add Destination button will then be grey and disabled.
Also, it can occur that you have reached the total maximal amount of Devices in your account. Then you can only link an existing Destination to your Flow, you cannot add a new Device. In that case the Create a new Destination option will not be available in the drop down.
When adding a Destination to a Flow, you have two options, as illustrated in the screenshot above:
Create a new Destination
Select an existing Destination to link to your Flow
This page is identical to the Add new Destination page coming from the All Destinations page.
After selecting the desired Destination in the drop down menu, click Add Destination to link the selected Destination to your Flow.
These changes only apply to Freemium projects.
KPN Things currently rounds the SenML bt and t fields in its SenML output to whole seconds. We are going to remove or change this rounding to allow for more accurate time values. Although time values always use seconds as their unit, it means that these values may contain fractional seconds.
For example, "t" may contain the value 0.001 or -33.333333 whereas before they would be rounded as 0 or -33 respectively. Depending on the device, a "t" value may change from "t": 1.659571200E9 to "t": 1.6595711995E9. So this changes in this example from Thursday, August 4, 2022 0:00:00 to Wednesday, August 3, 2022 23:59:59.500.
Check your device specification and your implementation to see if this has an impact on you. You may be affected if your software assumes the time values are always integers.
The base values sent by KPN Things are currently presented as a separate SenML record. As each record represents a measurement, this record containing only the base values implies a measurement of "v": 0 for "n": "". This is incorrect, as such a measurement was never made. In the future, KPN Things will no longer generate a separate SenML record with only the base name and base time fields, but instead will follow the SenML specification and store the base values as needed in existing records. Note: base values can appear in any SenML record, not just the first. To properly resolve the records in a SenML pack care must be taken to follow the specification to decompress the pack correctly.
To read more on this topic see Section 4 of the SenML standard
base values can appear in any SenML record, not just the first. To properly resolve the records in a SenML pack, care must be taken to follow the specification to decompress the pack correctly.
Currently the system sends SenML like this:
In the first measurement, the "v" and "u" fields of the first measures are missing (which is allowed in SenML). But this indicates a sensor with the name urn:dev:DEVEUI:0123456789ABCDEF: that has no units or values, which is not a representation of reality.
In the new situation this will no longer occur. The base values will be part of the first measurement, and will look like this:
Check the software on your end to see if it can handle this.
The primary aim of this document is to provide a comprehensive guide on how to correctly interpret Sensor Measurement List (SenML) data within the KPN Things platform. This guidance is essential for ensuring accurate data processing and utilization on the receiving end of the platform.
To get the most out of SenML data, it is important to interpret it correctly. Not doing so may result in missing or incorrect data in your downstream applications. As SenML data structures can be complex and varied, understanding the nuances is vital for reliable data handling.
SenML data is structured in JSON format to ensure uniformity and readability. Following are examples of correctly structured SenML records. All the records in this paragraph represent the same SenML data, this will help you understand what the SenML that arrives at your Destination might look like.
In the above example, we can see unresolved SenML. The SenML contains a base name (bn) and a base time (bt). A SenML Record is referred to as "resolved" if it does not contain any base values, i.e., labels starting with the character b, (except for Base Version fields), and has no relative times. The message above, when "resolved", looks like this:
As mentioned earlier, all the SenML in this paragraph represents the same data. So when it is resolved, it matches the SenML records in the previous example.
The records should be in chronological order in the resolved SenML, however in this example the time values are equal so switching the order still represents the same SenML:
Numeric values should be valid JSON numbers, which means that they can have a decimal point and an exponent. Therefore the above example is equal to the following example:
Time values are relative to the base time. So if measurement records have time values, they are relative to the value of the previous base time record. If you look at the example below, the base time should be added to the time fields of the measurements to resolve the time of the measurement.
The SenML data is the same as all the previous SenML messages.
It is possible to have multiple base value records. The base value applies to all successive measurements until another of that base value is found. In the example below, a single base name is used for all the records. On the contrary, the base time is altered in the second record. Since in both record the base time and the time elements add up to the same value, this data still equals the previous SenML examples.
Working with SenML requires an understanding of the SenML data structures. Simple parsing strategies, such as string splitting, might work with one SenML representation, but could fail when dealing with a different one. When SenML is sent out to your destination, we give no guarantees on the representation.
It is advised that incoming data should be parsed and normalised to an appropriate internal representation of the resolved SenML records, before any further processing is attempted.
To assist in correctly interpreting SenML, several libraries are available for different programming languages:
These libraries are designed to handle the complexities of the SenML data and provide more reliable parsing and data extraction.
When in doubt you can always use the RFC: rfc8428 as a reference. Or take a look at the senml-spec GitHub page.
At KPN Things, we strive to adhere as closely as we can to the SenML standard. This dedication sometimes necessitates modifications on our end to align more precisely with these standards. We recommend our customers to also embrace this approach, ensuring customer applications remain robust and future-proof by closely following the SenML standard.
Understanding and correctly interpreting SenML data is crucial for accurate and reliable data processing when interacting with the KPN Things platform. We urge our users to follow best practices and consult the official SenML specification. Adhering to these guidelines not only guarantees data integrity but also maximizes the benefits derived from using the KPN Things platform.
Introduction on the SenML data representation
For Freemium projects, the way KPN Things processes device data to SenML changed (per December 13th 2022). Read all the details about the Changes in KPN SenML.
SenML is the default data format for device data in KPN Things. Currently KPN Things only supports SenML in JSON. We plan to support SenML in CBOR in the future.
A SenML message is officially called a SenML pack. One SenML pack consists of one or more SenML records. One SenML record expresses a single measurement. That way a SenML pack expresses a set of measurements
The first record in a SenML pack always contains base information. Base information expresses from which device the measurements are from (base name) and the moment the measurements were taken (base time).
There are different type of SenML records:
Number record - for communicating a number measurement
Boolean record - for communicating an on/off measurement
String record - for communicating a string measurement
Data record - for communicating raw data measurement
Below you find a non-exhaustive example of a SenML pack:
Line nr.
Explanation
2
First line with base attributes, stating measurement source and timestamp.
3
Number record
4
Number record with relative time
5
Boolean record
6
String record
7
Data record
This section explains the attributes you can use to express your measurements in SenML
When the base name and/or base time values are present in the pack, they are available in the first measurement of the pack and applicable for all the measurements in the pack.
The base name of a SenML pack states which device the measurements are from. It should contain a unique resource name. The parts of the base name, which are colon separated, are as following:
urn stands for unique resource name.
dev means we are identifying a device.
DEVEUI is the type of device identifier used to identify the device.
01234567890ABCDEF is the DevEUI, the device identifier.
In the example above we identify a LoRa device by its DEVEUI. If we would have an M2M device, we would identify it by its IMEI and the base name would be as following: urn:dev:IMEI:0123456789012345:.
A base name always ends with a colon :!
The timestamp of the measurement in UNIX timestamp format. If KPN Things receives a measurement without base time, the time of receiving the measurement is taken as base time. SenML being sent by KPN Things will always contain a base time.
Name of the individual measurement.
The (..) name MUST consist only of characters out of the set "A" to "Z", "a" to "z", and "0" to "9", as well as "-", ":", ".", "/", and "_"; furthermore, it MUST start with a character out of the set "A" to "Z", "a" to "z", or "0" to "9". - The SenML spec, RFC8428 section 4.5.1
When designing your SenML measurement format for M2M and Internet devices, you should take into account our Common measurements list. By using as much name and unit pairs from that list, you achieve higher compatibility with current and future data processing features.
Unit of the measurement. Write your u-values in camel case, so start with a lower case character.
The timestamp of an individual record relative to the base time in seconds.
Value of the number measurement.
Boolean value for a boolean measurement. Should be true or false.
String value for a string measurement.
Data value for a data measurement. Should be a base64 encoded string.
There are more attributes in the SenML specification, but these values are not used by KPN Things. You can read about them in the Sensor Measurements Lists specification:
For easier integration with KPN Things we have created client libraries in C and Python for you to use in your devices.
To make SenML more suitable for communication over LoRa, we have introduced ThingsML. ThingsML is a valid extension of SenML that introduces measurement indices. We have listed several common measurements, allowing you to only send the measurement index number instead of sending the complete name and unit of the measurement. Learn more about ThingsML.
A generic payload protocol by KPN, also suitable for LoRa
ThingsML is an extension of the SenML specification, in a way SenML is designed to be extended (as described in Section 4.4 of the SenML specification).
ThingsML provides a more compact way of sending measurements based on SenML by indexing commonly used measurements and allowing to only send the measurement index instead of the full name and unit. It is inspired by the way developers try to cope with the small number of bytes available when using LoRaWAN for data transmission. They often employ context-based encoding schemes, meaning you need to know a lot of specifics to be able to decode a message. ThingsML tries to find the middle ground between bloaty generic protocols and niche specific protocols.
The ThingsML specification only covers the JSON and CBOR data types.
JSON is a suitable data type for Internet and M2M communication.
CBOR is a suitable data type for LoRa communication.
Currently only the following use cases are supported in KPN Things:
ThingsML for LoRa for uplink messages from own LoRa devices.
Support for M2M and downlink message will follow. For M2M communication we currently use SenML, and for LoRa downlink messages only raw payload communication is available.
ThingsML is part of our Device SDK (written in C). With the Device SDK you can easily setup communication between your Device and KPN Things. Learn more about the Things Device SDK.
With the ThingsML playground you can compare SenML with ThingsML, as well as JSON with CBOR. Visit the ThingsML playground.
This section explains the way ThingsML works.
In SenML the type of measurement present in a record is expressed by its name and its unit. You will find almost all temperature measurements described with name temperature and unit Cel. In ThingsML every of these very common types of measurements is indexed in the measurement index list. This means every combination of SenML name and unit gets a unique number.
The measurement index value starts with -24, because this value is finetuned on the CBOR specification to allow for optimal usage of this protocol for LoRaWAN applications. In CBOR a number from -24 to 23 can be encoded without additional bytes. For more information read the Major types section in the CBOR specifications https://tools.ietf.org/html/rfc7049#section-2.1.
So now, if you want to put a measurement in SenML, you only need to add the measurement index to the record instead of the full name and unit, saving you a lot of bytes. This measurement index is stored in a new field called the measurement index field and it has the label name i_.
If you want to send a measurement using ThingsML, but you want to send a measurement that is not in the measurement index list, you still can. Just add the name and unit to the record as you are used to, and a ThingsML decoder will accept it nonetheless. ThingsML is fully compatible with SenML, since it is a valid extension of the latter.
To experiment with ThingsML, please visit the online ThingsML Playground:
This section explains the fields that ThingsML introduces or uses.
Since the measurement index field is a custom field that is mandatory to understand to correctly process the pack, it must have a label name that ends with the "_" character [SenML, Section 12.2].
For every update of the measurement index list we will up the version number. The version number of the list you implemented can be added to the ThingsML pack in the bver field. This guarantees that your ThingsML pack will not be interpreted incorrectly.
We aim to only extend and not modify the measurement index list for backwards compatibility.
Also, we aim to keep the ThingsML Decoder in KPN Things up-to-date with the most recent version of the measurement index list. So, when using ThingsML in combination with KPN Things, you would not need to use the bver field.
This section explains more about ThingsML in JSON data format.
The difference between SenML and ThingsML in JSON is illustrated with the example below.
SenML
277 bytes
ThingsML
203 bytes (-30%)
This section explains more about ThingsML in CBOR data format.
CBOR stands for Concise Binary Object Representation and is a standard data format: https://tools.ietf.org/html/rfc7049. It is the more compact counterpart of JSON. That means each JSON object has its equal in CBOR and the other way around. In the SenML specification additional translation steps from JSON to CBOR are proposed to further decrease the size of SenML packs in CBOR. More information about SenML in CBOR can be found here: https://tools.ietf.org/html/rfc8428#section-6.
ThingsML has an integer CBOR representation for the label of the measurement index field. Officially, only default SenML labels should have an integer as CBOR representation. But this would save us 2 extra bytes per measurement in the SenML record, giving is more compactness. Since the measurement index is a regular field, the CBOR representation should be a positive integer.
Name
Label
CBOR Label
Measurement index
i_
23
The example below shows a measurement list in both SenML and ThingsML in CBOR hexadecimal representation and CBOR diagnostic notation. The hexadecimal representation could be copy-pasted into the CBOR tool at http://cbor.me.
SenML
142 bytes
ThingsML
66 bytes (-55%)
85a300686c6174697475646502fb4049f9ed288ce70401636c6174a3
00696c6f6e67697475646502fb40155165d3996fa801636c6f6ea300
6b74656d706572617475726502fb403dc00000000000016343656ca3
006e62617474657279566f6c7461676502fb400cb851eb851eb80161
56a3006b74656d706572617475726502fb40313851eb851eb8016343
656c
85a202fb4049f9ed288ce7041735a202fb40155165d3996fa81734a2
02fb403dc000000000001737a202fb400cb851eb851eb81706a202fb
40313851eb851eb81737
This example encodes all decimal numbers as double point float representations. Further payload size optimization can be achieved by using single point or half point float representations.
SenML
187 bytes
ThingsML
128 bytes (-30%)
87a221782075726e3a6465763a4445564555493a3031323334353637
38393031323334353a221a5cb35887a300686c6174697475646502fb
4049f9ed288ce70401636c6174a300696c6f6e67697475646502fb40
155165d3996fa801636c6f6ea3006b74656d706572617475726502fb
403dc00000000000016343656ca3006e62617474657279566f6c7461
676502fb400cb851eb851eb8016156a3006765787454656d7002fb40
313851eb851eb8016343656ca20062696f04f4
87a221782075726e3a6465763a4445564555493a3031323334353637
38393031323334353a221a5cb35887a202fb4049f9ed288ce7041735
a202fb40155165d3996fa81734a202fb403dc000000000001737a202
fb400cb851eb851eb81706a3006765787454656d7002fb40313851eb
851eb8016343656ca20062696f04f4
ThingsML for LoRa follows the following additional aspects:
ThingsML for LoRa only supports CBOR data representation, since this is the most compact way of sending ThingsML.
You may omit the base name and base time values from your measurement. The LoRaWAN network layer already provides this information to KPN Things, so your device doesn't have to.
This section gives the measurement index list and the way it is moderated. This list can be found on the common measurements page.
If you have a measurement name and unit you think should be in the ThingsML measurement index list? Please contact the author for a request for change. Proposed records will be added if they are generic and unique in the list. For instance Temperature in Fahrenheit shall not be added to the list, since translation to Celsius can be trivially implemented in the device.
We plan to support use case specific measurement tables, enabling you to define your own measurement index list.
Date
Description
26-11-2019
First version
8-1-2020
Updated text
27-1-2020
Added 3 measurements to the index list
Added change log table
7-4-2020
Specification released publicly
18-11-2020
Made introduction and ThingsML for LoRa more clear.
Specification by Paul Marcelis. Email: pjmarcelis@gmail.com
A generic payload protocol by KPN, also suitable for LoRa.
In KPN Things we use ThingsML as a generic decoding and encoding service for the communication with Devices. SDKs from KPN Things are available to further help you implement ThingsML in your device.
We use SenML within KPN Things and when forwarding the data to a destination.
The Device Twin is a digital representation of your Device. It expresses how your Device is doing, so it gives you a clear overview of the state of your Device!
The image below illustrates how the Device Twin data are set and used. All data can be read through the Portal and the API per Device.
Below the four parts of the Device Twin are :
Reported state - the most recent values of (a part of) the data sent from your Device. So if your Device sends a temperature measurement and you have configured that temperature should be stored in the Device Twin, you will find the last known temperature of that Device in its Twin.
Desired state - the state you want your Device to be in. For instance, if your Device supports changing the sending interval, you set the desired state of your Device to the desired interval, Things will recognize the desired state is different from the reported state and a downlink message is send to the Device to switch to a different interval.
Observed state - information that KPN Things can derive from the behavior of your Device. Here you can find for instance the Device sending interval.
Metadata - static information about your Device you want to store in the Device Twin. For instance in which batch the Device was produced, or the color of the casing of the Device. That way you store all important information for Device management in KPN Things.
The exact content of a Device Twin depends on the data a Device sends, the commands a Device can process, and the metadata you add manually to the Device Twin. Not all attributes may have a desired part, and sometimes an attribute with a desired state may not have a reported state. Closing the loop on desired and reported state is in the end something you should do.
In order to get the Twin up and running for a Device, some parts need to be configured in advance.
Before the Device Twin is able to show some values, the Device must be added to at least one Flow. This triggers processing of the data and allows the system to feed the Device Twin.
All data we receive from the Device is shown in the Device Twin. Previously you were required to configure in the Flow, which values you wanted to see before anything was shown. This setting has been removed from the Flow configuration.
Currently the available controls for the Desired state of a Device is determined in the Device type. Since the Own device types include a large set of different devices, we cannot yet provide a Desired state for own devices.
So, the Desired state is only available for KPN Devices.
In the near future, it will become possible to define your completely own Device type and with that define the Desired state options for your Device.
When you open de Device detail page of a certain Device, the Device Twin tab will provide you with all the information from the Device Twin of that Device.
Before the Device Twin will work:
Your Device should be in at least one Flow.
The Device Twin tab will point you in the right direction if the prerequisites is not yet fulfilled.
After all the configuration is in place, the Device Twin will start filling up with every incoming message from your Device.
In the screenshot below you see an example of a filled Device Twin with labeled:
The reported state
The desired state
The observed state
The metadata
Additionally the Device Twin tab provides you with links to the Device Twin documentation (#5) and a link to the Device Twin configuration page (#6). There is also a refresh button (#7), allowing you to refresh the Device Twin values without having to refresh the complete page.
The state section has been divided into two sections:
Device – showing all state expressing the Device, for instance firmware information, battery information and mode of operation. The name of the measurement is used by KPN Things to determine whether it is a Device state.
Other – all other state.
Below we will discuss every part of the Device Twin in detail.
The reported state of the Device Twin is composed of (a selection of) the most recent values of measurements KPN Things received from your Device. For each measurement where a reported state is known, its value and unit is displayed, as well as the moment when this value was last received. If you hover your mouse over the exact date and time, a popup will show you how long ago the reported state was last set.
Some trivial units will be hidden in the Portal, like enum, /, and string.
In a future release it will be possible to change the desired state even before the first reported state has been stored in the Device Twin of a Device.
The desired state of a Device expresses how you want the Device to behave. It depends on the Type of device which desired state values are available for control. For each state value where desired state control is available the most recent requested desired state is shown.
Next to the desired state value the exact date and time is shown of the moment the most recent desired state change was last requested. If you hover your mouse over the exact date and time, a popup will show you how long ago the reported state was last set. A blue timestamp with a blue circle next to it shows that the desired state change is still underway. If this is the case, the popup will also show you that the state change is still underway.
You can click on a certain desired state to change it (not available for read only accounts). Some values can be edited with a dropdown (#1 in the screenshot below), other values with a free input field (#2 in the screenshot below). After committing the desired state change, the state change will be communicated with your Device. Since the desired state change translates in to a downlink, you can see further information about the status of the downlink on the Send instruction tab of your Device.
The observed state tells you about the behavior of your Device from the perspective of KPN Things.
Currently only the Send interval is determined by calculating the time difference between the two most recently received messages. That means that in the case of a LoRa device, the interval may show a multiple of the expected send interval, since the lost message was not received by KPN Things.
In the metadata of the Device Twin you can (manually) store information about your Device in a key-value manner.
By clicking on Add a metadata property (#1 in the screenshot below) you will be given the input fields to add new metadata and its value. Click Save to store the new metadata property. You can edit the value of existing metadata by simply clicking the value (#2 in the screenshot below) after which an input field is shown and a Save button to store the change. If you want to remove a metadata property you can simply click the corresponding delete icon (#3 in the screenshot below).
In the future it will be possible to view a selection of the Device Twin values on the All Devices page, allowing you to search, sort and filter on these values. This feature is still in development.
Below you find a list of the values you can expect in the Reported state of the KPN Devices.
BatteryVoltage in Volt
CO2Concentration in parts per million
Humidity in % relative humidity
Illuminance in lux
Motion in count
Temperature in Celsius
BatteryVoltage in Volt
CO2Concentration in parts per million
Humidity in % relative humidity
Pressure in Pascal - the measured atmospheric pressure
Temperature in Celsius
VOC in parts per million - measured Volatile Organic Compound concentration
BatteryLevelLow as true/false
BatteryLevelLow_beacon as true/false - the battery level low indication of the detected beacon
Count_LidOpen - number of times the bin lid has been opened
DetectedBeacon - DevEUI of the last detected beacon
Distance in meters - distance to the detected object from the fill sensor
DistanceMeasurementIsValid as true/false
LidOpenedSincePreviousTransmission as true/false
Temperature in Celsius
BatteryLevelLow as true/false
Sabotaged as true/false
Temperature in Celsius
BatteryVoltage in Volt
FirmwareCRC - unique code to express the firmware on the Device
FirmwareVersion
Mode
SettingsCRC - unique code to express the settings on the Device
AcceleratorActive as true/false
AlarmMode as true/false
BatteryVoltage in Volt
MotionTime in minutes
MovementIndication
NfcFieldDetected
Sabotaged as true/false
Temperature in Celsius
No additional data.
AccX in m/s2 - measured acceleration in the X-axis
AccY in m/s2 - measured acceleration in the Y-axis
AccZ in m/s2 - measured acceleration in the Z-axis
CompX in Tesla - measured compass orientation in the X-axis
CompY in Tesla - measured compass orientation in the Y-axis
CompZ in Tesla - measured compass orientation in the Z-axis
DvLat - geographical latitude
DvLon - geographical longitude
GpsFix
Heading in radians
Io31 in 1/0 - arbitrary bit
IoButt in 1/0 - whether the Device's button was pressed
IoMot in 1/0 - whether the Device is in motion
IoRxd in 1/0 - Device's external digital i/o value
Speed in m/s
Temp in Celsius
VBat in Volt - measured battery voltage
MovementIndication
BatteryVoltage in Volt
FirmwareVersion
Altitude in meters
GpsTime in seconds
Heading in radians
Latitude
Longitude
Radius in meters - the accuracy of the geographical latitude and longitude
Status
Temperature in Celsius
Velocity in m/s
TIME_ORIGIN or TimeOrigin
Interval in minutes or hours - sending interval of Device
Latitude
LocAccuracy - deprecated
LocOrigin
LocPrecision - deprecated
LocTime
Longitude
Radius - the accuracy of the geographical latitude and longitude
🔜 Coming soon
This feature is currently in active development. This page has been created to give you a sneak preview of this awesome feature. We expect to release it January 2025.
This page describes the current design of the DIY Decoder functionality. The final version of this feature could differ from what is described below.
With a DIY Decoder, you can provide your own code snippet used to decode messages from your LoRa devices on the KPN Things platform. The code snippet should be written in JavaScript. See for the details.
Initially, DIY decoders are only supported for "Own LoRa" devices. Once you have linked your "Own LoRa" device to a Flow, you can add and edit DIY decoders on the Data Procession page for that Flow.
Initially we do not provide a rich code editor in the Things Portal. We suggest you write the code snippet in the editor of your choice and paste the content in the script field of the DIY decoder edit page in Things Portal.
After activating your DIY decoder in a flow, all messages from your "Own LoRa" devices that are part of that flow, are decoded by your own DIY Decoder and sent to all destinations configured for that flow.
A test routine for your DIY Decoder will be provided later.
Decoding is the first phase in data processing in . In this phase incoming data is normalized into and additional (meta)data is enabled if applicable.
With additional data (decoders), metadata corresponding to the message received is enabled.
Additionally, in KPN Things we have integrated the LoRa On Premises Gateway with our localisation service. When you enable Location by LoRa On Premises Gateway reception, KPN Things will detect when data from your device is received by one of your On Premise Gateways. Then KPN Things will add the administrative location of that gateway to the message. That way, the application can use that data to locate the device at the moment the message was sent.
To get this to work, you need to register your On Premise Gateways in your KPN Things account through the KPN Things API's by giving the gateway ID and the coordinates of the location you have positioned the gateway.
With no-decoders incoming data is not interpreted, it is only put into SenML.
If your device uses the SenML data format to send data to KPN Things, the data will be accepted as is, without further decoding.
Add-on feature This feature is only available for contracted customers. Please contact if your are interested!
When configuring your Destination, you can also configure merger functionality. When you enable the merger for your Destination, you can have data from different decoders merged into one message to your Destination.
The merger could be useful to merge LoRa Geolocation information with the decode payload from your LoRa device, in order to present this LoRa Geolocation data as an ordinary measurement to your application.
If two SenML packs that are merged contain a record with the same SenML name, both SenML records will be put in the final SenML pack. You application should.
In the future, we plan to implement priority, where measurements with the same SenML name can overwrite the other measurement.
With a ttl of 10s you could expect up to 2% of LoRa Geolocation messaged to be outside the ttl. With a ttl of 15s, up to 1% can be outside ttl.
A higher ttl will increase the change all messages are merged. A lower ttl will introduce a shorter delay for message that could not be merged.
Below an example of two merged messages is given.
As you can see the two decoder outputs have been merged into one SenML pack. Because the LoRa Geolocation data is one second newer than the data from the payload, all SenML records from the latter are given an extra t-attribute to express the time difference.
Also, since both decoder outputs contain a radius measurement, there are now two SenML records with this measurement name.
Currently, we are working on improving our decoders. Some older decoders on our platform contain some bugs and output SenML that is not in line with the . Besides improving the output, we are also updating the decoders from a technical perspective. This will provide the basis for the 'DIY-decoder' feature that will be available in the future. This document will give you information on what will change and how it might affect you and how you can use these new decoders.
For all the relevant decoders, a new version is available in the KPN Things Portal. All these new versions have some common changes to improve the SenML output.
String values should not have a unit
Wherever the time origin was set as {"n": "TIME_ORIGIN", "vs": "THINGSENGINE"} it is now set as { "n": "timeOrigin", "vs": "NETWORK" }
Time values (t and bt) are more precise and may contain decimal places.
Valueless 'base records' have been removed and base values are now correctly set on the first real record of the SenML pack.
LoRa Geolocation and Location by LoRa On Premises Gateway data decoding is included by all new LoRa decoders, thus you do not need to use specific extra decoders to receive this data.
With the previous decoder versions, you would typically see SenML as illustrated below:
Whereas the new version would output SenML like:
When you head over to the decoder configuration of your flow, you will see that a new version is available. To use the new version, just press the toggle. Don't forget to disable the previous version, otherwise you might receive your data twice, since it will be decoder with both the old and the new version.
Note that if you use
+ LoRa Geolocation dataor+ Location by LoRa On Premises Gateway receptiondecoders, this functionality is also a part of the new version of your LoRa decoder. To make sure you do not receive duplicate location data you should disable these as well.
If you want to test if you can process the improved payloads without impacting your current flow, you can configure a new flow, using the new version of the decoder.
Please ensure your solution is compatible with the updated decoder version, as the old versions will be retired from the 9th of December 2024.
In there is a measurement index list, allowing you to send only the index for a measurement instead of the full name and unit which is required in .
If you don't use ThingsML, it is still best practice to use the common measurement names and units in your solution. With this you achieve higher compatibility with current and future data processing features in KPN Things.
DIY decoders scripts are responsible for converting the data sent by your device into the format required by KPN Things. The data sent by your device and some other metadata is provided as a stringified JSON structure to your script.
The provided JavaScript snippet that is being executed must have a main function that is called with a single string as input and it should return a single string or null. The string should be a SenML pack as JSON. Returning null signifies that the messages should not be processed further.
The input parameter string contains all the input data in JSON format. See for the structure of the JSON found in the input data.
Below a simple example is given for a script decoding LoRa / Actility messages.
The snippet below describes the structure of the ScriptInput parameter provided to the DIY Decoder function.
See also:
A regular data decoder transforms incoming payload into measurements in SenML, following the data protocol of the specific .
ThingsML is a generic LoRa payload format, allowing you to send multiple measurements encoded in your payload in a compact way. Learn more about the .
Add data to messages where location could be calculated.
To extend the reach of our LoRa network on your location, we offer . A LoRa On Premise Gateway is an extension of our regular LoRa network. They have a smaller reach than our regular outdoor gateways, but you can position it for example in your warehouse to guarantee coverage for your LoRa devices.
Decoder specification uuid's are listed on the page and the page.
For more information on how to interpret and parse SenML data please visit page.
Besides general changes, some decoders may have some specific changes as well, like bug fixes. To see what has changed for a specific decoder, you can head over to the and choose your device type. Here you can find the documentation for its decoders and examples of their output.
SenML record name
Content
locOrigin
vs: "KPNLORA" Indicating that the location information in
the SenML record comes from the LoRa network.
latitude
v The latitude of the location in decimal notation.
u: "lat"
longitude
v The longitude of the location in decimal notation.
u: "lon"
radius
v The theoretical inaccuracy of the calculated location. Can
be used to visualize a circle around the location on a map.
u: "m" In meters.
SenML record name
Content
payload
vs The received payload in hexadecimal notation
(example: 010203).
port
v The application port the data was received on.
Attribute
Value
Description
merge
true/false
Whether to enable merger functionality.
mergeDecoderSpecifications
array of uuid's
Array of decoder specification uuid's of decoder outputs you want to merge.
ttl
nr. seconds
(Default: 10) max. time to wait for all messages to merge.
orphanStrategy
DISCARD/FORWARD
What to do with messages arriving after the ttl.
ThingsML measurement index
ID (unique)
SenML Name
SenML Unit
-24
TEMPERATURE
temperature
Cel
-23
HUMIDITY
humidity
%RH
-22
LATITUDE
latitude
lat
-21
LONGITUDE
longitude
lon
-20
ALTITUDE
altitude
m
-19
POWER
power
W
-18
PRESSURE
pressure
Pa
-17
ANGLE
angle
rad
-16
LENGTH
length
m
-15
BREADTH
breadth
m
-14
HEIGHT
height
m
-13
WEIGHT
weight
kg
-12
THICKNESS
thickness
m
-11
DISTANCE
distance
m
-10
AREA
area
m2
-9
VOLUME
volume
m3
-8
VELOCITY
velocity
m/s
-7
ELECTRIC_CURRENT
electricCurrent
A
-6
ELECTRIC_POTENTIAL
electricPotential
V
-5
ELECTRIC_RESISTANCE
electricResistance
Ohm
-4
ILLUMINANCE
illuminance
lx
-3
ACCELERATION_X
accelerationX
m/s2
-2
ACCELERATION_Y
accelerationY
m/s2
-1
ACCELERATION_Z
accelerationZ
m/s2
0
HEADING
heading
rad
1
CO_CONCENTRATION
COConcentration
ppm
2
CO2_CONCENTRATION
CO2Concentration
ppm
3
SOUND
sound
dB
4
FREQUENCY
frequency
Hz
5
BATTERY_LEVEL
batteryLevel
%EL
6
BATTERY_VOLTAGE
batteryVoltage
V
7
RADIUS
radius
m
8
BATTERY_LEVEL_LOW
batteryLevelLow
boolean
9
COMPASS_X
compassX
T
10
COMPASS_Y
compassY
T
11
COMPASS_Z
compassZ
T
12
READ_SWITCH
readSwitch
/
13
PRESENCE
presence
boolean
14
COUNTER
counter
/
Analysing your devices data
The 'Device - Data' page shows you an overview of the latest measurements that were sent by your devices in a tabular form, providing various sort and filter options to refine the selection of the devices data you want to analyse.
Note that the amount of devices you see in the 'Devices' and the 'Devices - Data' menu items might differ.
A device only shows up in the 'Devices - Data' page when:
your device has recently sent data.
your device is added to a flow, which has a decoder enabled.
you are using one of the common Things Device Types, of which the payload is decoded into SenML JSON output.
Each row in the table represents a device, and each column represents a measurement.
Note that there are 4 default columns: Device Name, Device Type, Customer Name and Last message time.
The remaining columns are deduced from the actual measurements sent out by your devices. For example, the Battery Voltage column will only be visible when one of your devices has sent out a Battery Voltage measurement.
You can sort the table by clicking the column headers and you can add filters by hovering over the right side of the column header and selecting the three dots.
The small menu on the right called 'Columns' can be used to select/unselect columns.
The table is optimised for sorting and filtering performance. To maintain the best performance, you will only see a maximum of 10.000 rows, which you can browse using pagination.
You can easily download the 'Devices - Data' result set by clicking the Download icon just below the Search icon.
This will generate CSV file, containing all devices in the current selection. The CSV file will contain the measurements accompanied with the timestamp of that specific measurement.
Important: the CSV file is not limited to 10.000 rows: all devices that match your filter criteria are included in the CSV file.
The default column 'Last message time' is the latest time that a measurement was received from your device.
Not every device message will include all measurements. As a result the measurement values you see in the table might originate from earlier measurements than the 'Last message time'.
The clock icon next to the value will alert you that this particular measurement was received in a previous message. In the CSV download you will see this earlier timestamp as well.
The Devices Landing Page in the KPN Things platform provides an overview and management interface for all your registered devices.
Search and Filter: At the top, there’s a search bar that allows you to quickly find specific devices by name or other attributes. You can also apply filters to narrow down the devices based on type, status, or other criteria.
Add a New Device: You can manually add a new device by clicking on the "Add new Device" button. This will guide you through the process of registering a new device with details such as its type, unique ID, and configurations.
Bulk Management Options:
Bulk by CSV File: This is a key feature that allows you to upload multiple devices at once using a CSV file. You can use this feature to save time when you need to add or manage large numbers of devices at once.
Firmware Management: This option lets you add new firmware version on your devices. Keeping firmware updated is important for security and functionality improvements.
Next to the device list, you will see options for bulk actions, like activating or deactivating your M2M devices, or editing device settings in batches. These actions can be initiated by selecting multiple devices from the list or by uploading a CSV file that contains the necessary device information.
You can easily download the 'Devices - Data' result set by clicking the Download icon just below the Search icon.
This will generate CSV file, containing all devices in the current selection. The CSV file will contain the measurements accompanied with the timestamp of that specific measurement.
click on the "Bulk by CSV file" button.
This step opens the process for uploading multiple devices at once via a CSV file. This saves time since you don’t need to add each device individually.
You are asked to upload a CSV file with the device data. Ensure that the structure of the file matches the template exactly, which you can download. Use a comma (,) as the CSV separator.
After uploading the CSV file, it will be validated.
This screen gives you feedback on the validation. All devices with valid data are displayed, and devices with errors won’t be processed. The system checks fields such as IMEI, ICCID, and other required fields.
After validation, choose the target project and flow where the new devices should be added. You can also specify the device details, such as the device type.
Here, you define the project and flow in which the new devices will be processed. You can also choose the type of devices being added, for example, M2M devices or another type.
Click on "Add new M2M Devices" to start adding the devices.
The system will now begin adding the devices. You can monitor the process by following the progress in the "Bulk reports," where you can see if all devices were successfully created.
