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