IoT Hub
IoT Hub Documentation
Telemetry delta calculation
Getting Started Documentation Guides API FAQ

On this page

Telemetry delta calculation

Use case

Let’s assume we have a device that uses a temperature sensor to collect and read temperature readings in the IoT Hub. In addition, let’s assume that we need to generate the alarm when the delta between the last five-minutes temperature readings and the latest temperature reading does exceed 5 degrees. Please note that this is just a simple theoretical use case to demonstrate the capabilities of the platform. You can use this tutorial as a basis for much more complex scenarios.

Prerequisites

We assume you have completed the following guides and reviewed the articles listed below:

Adding the device

Add Device entity in IoT Hub. Its name is Thermometer and its type is temperature sensor.

image


Message flow

In this section, we explain the purpose of each node in this tutorial. There will be two rule chains involved:

  • Root rule chain - rule chain that actually saves telemetry from devices into the database, and redirect the messages to Temperature delta validation chain

  • Temperature delta validation - rule chain that actually calculates the delta between the last five-minutes temperature and latest temperature readings.
    As a result, if delta value exceeds 5 degrees, the alarm will be created/updated, otherwise, the alarm will be cleared.

The following screenshots show how the above Rule Chains should look like:

  • Temperature delta validation:

image

  • Root Rule Chain:

image


Download the attached json file for the Temperature delta validation rule chain.

Create Node G as shown on the image above in the root rule chain to forward telemetry to the imported rule chain.

The following section shows you how to create this rule chain from scratch.

Create new Rule Chain (Temperature delta validation)

Go to Rule Chains -> Add new Rule Chain

Configuration:

  • Name : Temperature delta validation

image

New Rule Chain is created. Press Edit button and configure Chain.

Adding the required nodes

In this rule chain, you will create 6 nodes as it will be explained in the following sections:

Node A: Originator telemetry
  • Add the Originator telemetry node and connect it to the Input node with a relation type Success. This rule node adds selected telemetry of message originator into message metadata for the selected time range.

The rule node has three fetch modes:

  • FIRST: retrieves telemetry from the database that is closest to the beginning of the time range

  • LAST: retrieves telemetry from the database that is closest to the end of the time range

  • ALL: retrieves all telemetry from the database, which is in the specified time range.

We will use fetch mode: LAST with the time range from 24 hours ago till 5 minutes.

  • Enter the Name field as Latest five-minute old record.

image

Fetch Mode ALL

Originator telemetry node also supports ability to fetch all telemetry from the particular time range. We will not use this ability in our tutorial, but it may be useful in the cases if you need to calculate variance for a particular key or to predict further change of telemetry depending on telemetry changes in the selected time range.

In this case, you need to select the fetch mode ALL. It will force rule node to fetch all telemetry from the specified time range and add it to the message metadata as an array. This array will contain JSON objects with the timestamp and value.

  • Metadata of the outbound message would be JSON document with the following structure:
1
2
3

  {
    "temperature": "[{\"ts\":1540892498884,\"value\":22.4},{\"ts\":1540892528847,\"value\":20.45},{\"ts\":1540892558845,\"value\":22.3}]"
  }
  • In order to convert the array to the valid JSON document you can use the following function:
1

  var temperatureArray = JSON.parse(metadata.temperature);
  • The temperature array will look like introduced below:
1
2
3
4
5
6
7
8
9
10
11
12

  {
      "temperatureArray": [{
          "ts": 1540892498884,
          "value": 22.4
      }, {
          "ts": 1540892528847,
          "value": 20.45
      }, {
          "ts": 1540892558845,
          "value": 22.3
      }]
  }
Node B: Script Transformation
  • Add the Script Transformation node and connect it to the Change Orignator node with a relation type Success.

This node will calculate the delta between the temperature reading from message payload and the five-minute old temperature reading from the message metadata using the following script:

1
2
3
4
5

   var newMsg = {};
   
   newMsg.deltaTemperature = parseFloat(Math.abs(msg.temperature - JSON.parse(metadata.temperature)).toFixed(2));
     
   return {msg: newMsg, metadata: metadata, msgType: msgType};
  • Enter the Name field as Calculate delta.

image

Node C: Save Timeseries

  • Add the Save TimeSeries node and connect it to the Script Transformation node with a relationship type Success.
    This node will save the TimeSeries data from the incoming Message payload into the database and link it to the Device that is identified as the Message Originator.

  • Enter the Name field as Save Time Series.

image

Node D: Filter Script
  • Add the Filter Script node and connect it to the Save TimeSeries node with a relation type Success.
    This node will validate that calculated delta value between the latest temperature reading and five-minutes ago temperature reading did not exceed 5 degrees using the following script:
1

   return msg.deltaTemperature > 5;
  • Enter the Name field as Validate delta.

image

Node E: Create alarm

  • Add the Create alarm node and connect it to the Filter Script node with a relation type True.
    This node loads the latest Alarm with configured Alarm Type for Message Originator, namely Thermometer
    if the published delta temperature is not at expected range (filter script node returns True).

  • Enter the Name field as Create alarm and the Alarm type as General Alarm.

image

Node F: Clear Alarm

  • Add the Clear Alarm node and connect it to the Filter Script node with a relation type False.
    This node loads the latest Alarm with configured Alarm Type for Message Originator Thermometer
    and Clears alarm if it exists in case if the published temperature delta is in expected range (script node returns False).

  • Enter the Name field as Clear Alarm and the Alarm type as General Alarm.

image

Modify Root Rule Chain

The initial root Rule Chain has been modified by adding the following node:

Node G: Rule Chain

  • Add the Rule Chain node and connect it to the Save Timeseries node with a relation type Success.
    This node forwards incoming Message to specified Rule Chain Temperature delta validation.

  • Select the Rule Chain field: Temperature delta validation.

image


The following screenshot shows how the final Root Rule Chain should look like:

image

  • Download the attached json file for the rule chain indicated above and import it.
  • Don’t forget to mark the new rule chain as root.



How to verify the Rule Chain and Post telemetry

For posting device telemetry we will use the Rest APIs, Telemetry upload APIs. For this we will need to copy device access token from the device Thermometer.

image

1

**you need to replace $ACCESS_TOKEN with actual device token**

To validate that rule chains works as expected, we need to post telemetry twice for the same device, with an interval, not less than 5 minutes and not more than 24 hours.
Also, let’s pushed debug mode button in Create Alarm node to verify that alarm will be created after the second post telemetry request.

image

sent temperature = 20.

1

curl -v -X POST -d '{"temperature":20}' http://localhost:8080/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"

image

After 5 minutes delay let’s sent e.g temperature = 26

1

curl -v -X POST -d '{"temperature":26}' http://localhost:8080/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"

image

Alarm should be created:

image


Also, you can:

  • configure Alarm Details function in the Create and Clear Alarm nodes.

  • configure the Dashboard by adding an alarm widget to visualize the alarms.

  • define an additional logic for alarm processing, for example, sending an email.

Please refer to the links from the second to the fourth under the See Also section to see how to do this.


See Also

Next steps

  • Getting started guides - These guides provide quick overview of main IoT Hub features. Designed to be completed in 15-30 minutes.