Stand with Ukraine flag
Pricing Try it now
Cloud
Community Edition Professional Edition Cloud Edge PE Edge IoT Gateway License Server Trendz Analytics Mobile Application PE Mobile Application MQTT Broker PE MQTT Broker
Europe
North America N. Virginia Europe Frankfurt
Telemetry delta calculation
Getting Started Documentation Guides API FAQ
On this page

Telemetry delta calculation

This guide explains how to calculate the difference (delta) between telemetry values in ThingsBoard and use this calculated value to automatically trigger and clear alarms.

The guide is introductory and focuses on demonstrating the core capabilities of the platform rather than building configurations from scratch.
For this reason, predefined configurations for calculated fields and alarm rules are provided and imported during the setup.

After importing these configurations into your ThingsBoard instance, you can explore their structure, logic, and behavior, and later adapt them for your own use cases.

Use case

Assume you have a device equipped with a temperature sensor that periodically sends telemetry data to ThingsBoard.

You need:

  • Monitor temperature changes over a fixed time window (for example, 15 minutes).
  • Trigger an alarm when the temperature change exceeds a defined threshold (5 °C).
  • Automatically clear the alarm when the value returns to normal.

This workflow represents a common real-time monitoring and anomaly detection scenario and can be easily extended to more advanced use cases.

Prerequisites

Before proceeding, it is recommended to review the following ThingsBoard documentation:

  • Calculated fields - learn how to compute new telemetry values based on incoming data.
  • Alarm rules - learn how to define alarm trigger conditions to promptly respond to abnormal conditions.

These concepts are essential for understanding the configuration described below.

1. Add demo device

Start by adding a demo device that publishes temperature telemetry.

The device serves as the source of telemetry data used by the calculated field and alarm rules.

Actions

  1. Navigate to Entities ⇾ Devices.
  2. Click the + (Add) button in the top-right corner, select Add new device and create:
     • Device name: Thermometer
     • Device profile: thermostat

The device is registered in ThingsBoard and ready to publish telemetry data.

2. Import a calculated field for telemetry delta

The provided configuration calculates the temperature delta over the last 15 minutes and stores the result as a new telemetry key: deltaTemperature.

Actions

  1. Download the calculated field configuration file:
    telemetry_delta_calculation_cf.json.
  2. Navigate to the Calculated fields page.
  3. Click the + (Add) button in the top-right corner and select Import calculated field.
  4. Upload the calculated field configuration file.
  5. Select the thermostat device profile as the target entity so the calculated field is applied automatically to all relevant devices.
  6. Click Add to complete the import.

Calculation logic

The calculated field script:

  • Collects temperature values from the last 5 minutes
  • Uses the first and last values in the time window
  • Calculates their difference
  • Stores the absolute value as telemetry

Script used in this example

function calculate(ctx, altitude, temperature) {

1
2
3
4
5
6
7
8
9

var delta = 0;

if (temperature.values.size() >= 2) {
  delta = temperature.last - temperature.first;
}

return {
  "deltaTemperature": Math.abs(toInt(delta))
}

}

Key points

  • If fewer than two values are available, the delta is set to 0
  • The script is resilient to sparse telemetry
  • The result is stored as time series telemetry and updated automatically

3. Configure alarm rules based on telemetry delta

Configure the alarm rule that react to changes in the deltaTemperature key value.

Alarm logic:
 • Trigger the alarm when deltaTemperature ≥ 5
 • Clear the alarm when deltaTemperature < 5

Actions

  1. Download the alarm rule configuration file:
    temperature_deviation_alarm_rule.json.
  2. Navigate to Alarms ⇾ Alarm rules.
  3. Upload the alarm rule configuration file.
  4. Configure the alarm rule for a thermostat device profile to ensure it is applied consistently to all devices that use this profile.
  5. Click Add.

Once imported, the alarm lifecycle is managed automatically by ThingsBoard.

4. Verify the configuration

To confirm that everything works as expected, publish two temperature values within a 15-minute interval.

Verification steps

  1. Publish an initial temperature value (for example, 25).
    The easiest way is to use the check connectivity feature. Alternatively, execute the command below*:
    * Make sure to replace $ACCESS_TOKEN with the Thermostat device access token.

    1

    curl -v -X POST https://eu.thingsboard.cloud/api/v1/$ACCESS_TOKEN/telemetry --header Content-Type:application/json --data "{temperature:25}"
  2. Open the device Latest telemetry tab to monitor incoming data in real time.
    At this stage, you should see the following telemetry keys:
    • temperature = 25
    • deltaTemperature> = 0</span (only one value is available)

  3. Publish a second temperature value within 15 minutes (for example, 32).

    1

    curl -v -X POST https://eu.thingsboard.cloud/api/v1/$ACCESS_TOKEN/telemetry --header Content-Type:application/json --data "{temperature:32}"
  4. After the second update:
    • deltaTemperature = 7
    • The alarm is triggered because the threshold is exceeded
  5. Open the Alarms tab to verify the alarm status.

As soon as the deltaTemperature key value becomes less than 5, the alarm will be automatically cleared.

Next steps