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
  • Introduction to the Device Twin
  • Configure the Device Twin
  • Add the Device to a Flow
  • Select measurements for Reported state
  • Desired state options 🔜
  • Consult Device Twin of a single Device
  • Reported state
  • Desired state
  • Observed state
  • Metadata
  • Consult Device Twin values on the All Devices page 🔜
  • Values to be expected for KPN Devices
  • KPN Conditionsensor CO2 II
  • KPN Conditionsensor CO2 III
  • KPN FillTag I
  • KPN LocationTag I
  • KPN LocationTag II
  • KPN LocationTag II v2
  • KPN LocationTag III
  • KPN LocationTag V
  • KPN LocationTag VI
  • For all LoRa devices
  • For LoRa devices with Geolocation decoder enabled

Was this helpful?

Export as PDF
  1. BUILDING BLOCKS
  2. Data Processing

Device Twin

PreviousChanges in KPN SenMLNextDecoders and encoders

Last updated 3 months ago

Was this helpful?

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!

Introduction to the Device Twin

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.

Configure the Device Twin

In order to get the Twin up and running for a Device, some parts need to be configured in advance.

Add the Device to a Flow

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.

Select measurements for Reported state

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.

Desired state options 🔜

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.

Consult Device Twin of a single 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:

  1. 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:

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.

Reported state

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.

Desired state

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.

Observed state

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.

Metadata

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

Consult Device Twin values on the All Devices page 🔜

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.

Values to be expected for KPN Devices

Below you find a list of the values you can expect in the Reported state of the KPN Devices.

KPN Conditionsensor CO2 II

  • BatteryVoltage in Volt

  • CO2Concentration in parts per million

  • Humidity in % relative humidity

  • Illuminance in lux

  • Motion in count

  • Temperature in Celsius

KPN Conditionsensor CO2 III

  • 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

KPN FillTag I

  • 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

KPN LocationTag I

  • BatteryLevelLow as true/false

  • Sabotaged as true/false

  • Temperature in Celsius

KPN LocationTag II

  • 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

KPN LocationTag II v2

  • AcceleratorActive as true/false

  • AlarmMode as true/false

  • BatteryVoltage in Volt

  • MotionTime in minutes

  • MovementIndication

  • NfcFieldDetected

  • Sabotaged as true/false

  • Temperature in Celsius

KPN LocationTag III

No additional data.

KPN LocationTag V

  • 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

KPN LocationTag VI

  • 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

For all LoRa devices

  • TIME_ORIGIN or TimeOrigin

  • Interval in minutes or hours - sending interval of Device

For LoRa devices with Geolocation decoder enabled

  • Latitude

  • LocAccuracy - deprecated

  • LocOrigin

  • LocPrecision - deprecated

  • LocTime

  • Longitude

  • Radius - the accuracy of the geographical latitude and longitude

The

The

The

The

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 of your Device.

Send instruction tab
reported state
desired state
observed state
metadata