# Device Twin

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.

<figure><img src="https://1453626848-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fl6RrePMSAjRvOgcHjMBZ%2Fuploads%2FpvbzREI6mKbImS39PGWt%2Fimage.png?alt=media&#x26;token=3a67c47b-2039-4c9f-8a46-24ff740a4632" alt=""><figcaption></figcaption></figure>

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.&#x20;
* **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.

{% hint style="info" %}
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.
{% endhint %}

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

{% hint style="warning" %}
So, the **Desired state is only available for KPN Devices**.
{% endhint %}

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](https://docs.kpnthings.com/kpn-things/building-blocks/devices#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:

1. The [reported state](#reported-state)
2. The [desired state](#desired-state)
3. The [observed state](#observed-state)
4. The [metadata](#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.

<figure><img src="https://1453626848-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fl6RrePMSAjRvOgcHjMBZ%2Fuploads%2FbKR6FsbFI7Sbd8Uw2nkb%2Fimage.png?alt=media&#x26;token=6035ffed-ac04-427a-b8b8-8e5f02192e1c" alt=""><figcaption></figcaption></figure>

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.

<figure><img src="https://1453626848-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fl6RrePMSAjRvOgcHjMBZ%2Fuploads%2FsdeTaZsl6d9vbbQD7bUZ%2Fimage.png?alt=media&#x26;token=870ed7e8-5cb8-41c9-aecf-b63fbf14a653" alt=""><figcaption></figcaption></figure>

Some trivial units will be hidden in the Portal, like `enum`, `/`, and `string`.

### Desired state

{% hint style="info" %}
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.
{% endhint %}

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.

<figure><img src="https://1453626848-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fl6RrePMSAjRvOgcHjMBZ%2Fuploads%2F2mCYpu6T2X48RYTQ7MBW%2Fimage.png?alt=media&#x26;token=5fd8ecbe-4e07-4300-96d0-6dad1087966f" alt=""><figcaption></figcaption></figure>

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](https://docs.kpnthings.com/kpn-things/getting-started/tutorials/send-instruction-to-lora-device-page) of your Device.

<figure><img src="https://1453626848-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fl6RrePMSAjRvOgcHjMBZ%2Fuploads%2F1SQ4DLEDa4xifNPISQHe%2Fimage.png?alt=media&#x26;token=1e856a2b-cfb8-4faa-a4a6-67adfd53200b" alt=""><figcaption></figcaption></figure>

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

<figure><img src="https://1453626848-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fl6RrePMSAjRvOgcHjMBZ%2Fuploads%2FZP8OiVgZIizCzgpqtmuz%2Fimage.png?alt=media&#x26;token=386c5254-41db-4266-8836-f111ef540a37" alt=""><figcaption></figcaption></figure>

## 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