Skip to content

Minor changes to Calculated Fields doc #2484

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ashvayka merged 1 commit into from
Jan 14, 2026
Merged

Minor changes to Calculated Fields doc #2484

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions _data/pages_info.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4318,6 +4318,9 @@
"/docs/reference/mqtt-sparkplug-api/":
url: "/docs/reference/mqtt-sparkplug-api/"
redirect_from: []
"/docs/reference/mqtt-v5-errors-code/":
url: "/docs/reference/mqtt-v5-errors-code/"
redirect_from: []
"/docs/reference/msa/":
url: "/docs/reference/msa/"
redirect_from: []
Expand Down
149 changes: 64 additions & 85 deletions _includes/docs/user-guide/calculated-fields/geofencing-calculated-field.md
View file
Open in desktop

Large diffs are not rendered by default.

96 changes: 42 additions & 54 deletions _includes/docs/user-guide/calculated-fields/propagation-calculated-field.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,9 +119,10 @@ The Tracker A device sends its battery charge level (<span class="code-light">ba
<b><font size="4">Goal</font></b>
Automatically propagate the device battery level to the related Truck 1 asset and store it as a server-side attribute under a new key: <span class="code-light">deviceBatteryLevel</span>.

<hr>
<b><font size="4">Calculated field configuration</font></b>
[Download the "Battery level propagation" calculated field configuration (JSON)](/docs/user-guide/resources/calculated-fields/propagation/battery_level_propagation_cf.json){:target="_blank" download="battery_level_propagation_cf.json"}.

<b><font size="4">Configuration steps</font></b>
<br><b><font size="4">Configuration steps</font></b>

<b><font size="3">1. Import demo device</font></b>

Expand All @@ -134,6 +135,8 @@ Import a device that publishes battery telemetry.
- **Type:** tracker
- **Time series:** <span class="code-light">batteryLevel</span>

> **Important note about the CSV:** the column type for the <span class="code-light">batteryLevel</span> key must be set to "**Time series**".

{% assign examplePropagateDeviceBattery1 = '
===
image: /images/user-guide/calculated-fields/propagation/propagation-cf-example-1-1-ce.png
Expand All @@ -143,9 +146,7 @@ Import a device that publishes battery telemetry.

{% include images-gallery.liquid imageCollection=examplePropagateDeviceBattery1 %}

<hr>

<b><font size="3">2. Import demo asset</font></b>
<br><b><font size="3">2. Import demo asset</font></b>

Import an asset that represents the tracked truck.
1. Download the CSV file: [battery-level-asset-data.csv](/docs/user-guide/resources/calculated-fields/propagation/battery-level-asset-data.csv){:target="_blank" download="battery-level-asset-data.csv"}
Expand All @@ -164,9 +165,7 @@ Import an asset that represents the tracked truck.

{% include images-gallery.liquid imageCollection=examplePropagateDeviceBattery2 %}

<hr>

<b><font size="3">3. Create a relation between the asset and the device</font></b>
<br><b><font size="3">3. Create a relation between the asset and the device</font></b>

Create a relation so the calculated field can resolve the target asset.

Expand All @@ -176,18 +175,16 @@ Create a relationship between the **Track 1** asset and the **Tracker A** device

This relation is used by the propagation calculated field to locate the parent entity.

{% assign examplePropagateDeviceBattery4 = '
{% assign examplePropagateDeviceBattery3 = '
===
image: /images/user-guide/calculated-fields/propagation/propagation-cf-example-1-3-ce.png
title: The **Tracker** device linked to the **Track 1** asset via the **Contains** relation.
'
%}

{% include images-gallery.liquid imageCollection=examplePropagateDeviceBattery4 %}

<hr>
{% include images-gallery.liquid imageCollection=examplePropagateDeviceBattery3 %}

<b><font size="3">4. Apply the Propagation calculated field to the device profile</font></b>
<br><b><font size="3">4. Apply the Propagation calculated field to the device profile</font></b>

Configure a **Propagation** calculated field in the **tracker** device profile (automatically created during device import) so that it works for Tracker A.
1. [Download the calculated field configuration file](/docs/user-guide/resources/calculated-fields/propagation/battery_level_propagation_cf.json){:target="_blank" download="battery_level_propagation_cf.json"}.
Expand All @@ -213,20 +210,18 @@ This configuration propagates the latest telemetry value of <span class="code-li

{% include images-gallery.liquid imageCollection=examplePropagateDeviceBattery4 %}

<hr>

<b><font size="4">Result</font></b>
<br><b><font size="4">Result</font></b>

The <span class="code-light">deviceBatteryLevel</span> attribute is propagated and stored on the **Truck 1** asset as a **server-side attribute**.

{% assign examplePropagation12 = '
{% assign examplePropagateDeviceBattery5 = '
===
image: /images/user-guide/calculated-fields/propagation/propagation-cf-example-1-8-ce.png
title: The **deviceBatteryLevel** attribute is propagated and stored on the **Truck 1** asset as a **server-side attribute**.
'
%}

{% include images-gallery.liquid imageCollection=examplePropagation12 %}
{% include images-gallery.liquid imageCollection=examplePropagateDeviceBattery5 %}

<hr>

Expand All @@ -238,9 +233,10 @@ A Smart Device sends <span class="code-light">temperature</span> and <span class
<b><font size="4">Goal</font></b>
Calculate the **dew point**, propagate the result to the related asset (**Greenhouse A**), and store it as a **telemetry**.

<hr>
<b><font size="4">Calculated field configuration</font></b>
[Download the "Dew point propagation" calculated field configuration (JSON)](/docs/user-guide/resources/calculated-fields/propagation/dew_point_propagation_cf.json){:target="_blank" download="dew_point_propagation_cf.json"}.

<b><font size="4">Configuration steps</font></b>
<br><b><font size="4">Configuration steps</font></b>

<b><font size="3">1. Import demo device</font></b>

Expand All @@ -253,18 +249,18 @@ Import a device that publishes temperature and humidity telemetry.
- **Type:** smart-device
- **Time series:** <span class="code-light">humidity</span>, <span class="code-light">temperature</span>

{% assign examplePropagation21 = '
> **Important note about the CSV:** the column type for the <span class="code-light">humidity</span> and <span class="code-light">temperature</span> keys must be set to "**Time series**".

{% assign exampleDewPointPropagation1 = '
===
image: /images/user-guide/calculated-fields/propagation/propagation-cf-example-2-1-ce.png
title: Import a device that publishes **temperature** and **humidity** telemetry.
'
%}

{% include images-gallery.liquid imageCollection=examplePropagation21 %}

<hr>
{% include images-gallery.liquid imageCollection=exampleDewPointPropagation1 %}

<b><font size="3">2. Import demo asset</font></b>
<br><b><font size="3">2. Import demo asset</font></b>

Import the asset that represents the greenhouse.
1. Download the CSV file: [dew-point-calculation-and-propagation-asset-data.csv](/docs/user-guide/resources/calculated-fields/propagation/dew-point-calculation-and-propagation-asset-data.csv){:target="_blank" download="dew-point-calculation-and-propagation-asset-data.csv"}
Expand All @@ -274,45 +270,41 @@ Import the asset that represents the greenhouse.
- **Name:** Greenhouse A
- **Type:** greenhouse

{% assign examplePropagation22 = '
{% assign exampleDewPointPropagation2 = '
===
image: /images/user-guide/calculated-fields/propagation/propagation-cf-example-2-2-ce.png
title: Import the demonstration asset Greenhouse A.
'
%}

{% include images-gallery.liquid imageCollection=examplePropagation22 %}
{% include images-gallery.liquid imageCollection=exampleDewPointPropagation2 %}

<hr>

<b><font size="3">3. Create a relation between the asset and the device</font></b>
<br><b><font size="3">3. Create a relation between the asset and the device</font></b>

Create a relationship between the **Greenhouse A** asset and the **Smart Device**:
- Relation direction: **From**
- Relation type: **Contains**

This relation allows the calculated field to locate the parent asset when propagating output.

{% assign examplePropagation23 = '
{% assign exampleDewPointPropagation3 = '
===
image: /images/user-guide/calculated-fields/propagation/propagation-cf-example-2-3-ce.png
title: Create a relationship between the **Greenhouse A** asset and the **Smart Device**.
'
%}

{% include images-gallery.liquid imageCollection=examplePropagation23 %}

<hr>
{% include images-gallery.liquid imageCollection=exampleDewPointPropagation3 %}

<b><font size="3">4. Apply the calculated field to the device profile</font></b>
<br><b><font size="3">4. Apply the calculated field to the device profile</font></b>

Configure the calculated field on the "smart-device" device profile (created automatically during device import), so it runs for Smart Device.
1. [Download the calculated field configuration file](/docs/user-guide/resources/calculated-fields/propagation/dew_point_propagation_cf.json){:target="_blank" download="dew_point_propagation_cf.json"}.
3. Go to the "Calculated fields" tab and [import](/docs/user-guide/calculated-fields/#export--import-calculated-field){:target="_blank"} the configuration.

This scenario calculates the dew point value from the specified input data. The value is propagated and stored as telemetry on the parent asset (**Greenhouse A**) under the <span class="code-light">dewPoint</span> key.

{% assign examplePropagation24 = '
{% assign exampleDewPointPropagation4 = '
===
image: /images/user-guide/calculated-fields/propagation/propagation-cf-example-2-4-ce.png
title: Go to the **Calculated fields** tab and import the calculated field configuration.
Expand All @@ -331,22 +323,20 @@ This scenario calculates the dew point value from the specified input data. The
'
%}

{% include images-gallery.liquid imageCollection=examplePropagation24 %}
{% include images-gallery.liquid imageCollection=exampleDewPointPropagation4 %}

<hr>

<b><font size="4">Result</font></b>
<br><b><font size="4">Result</font></b>

The calculated value is propagated to the **Greenhouse A** asset and stored as a **telemetry** under the key <span class="code-light">dewPoint</span>.

{% assign examplePropagation25 = '
{% assign exampleDewPointPropagation5 = '
===
image: /images/user-guide/calculated-fields/propagation/propagation-cf-example-2-9-ce.png
title: The calculated value is propagated to the **Greenhouse A** asset and stored as a **telemetry** under the key **dewPoint**.
'
%}

{% include images-gallery.liquid imageCollection=examplePropagation25 %}
{% include images-gallery.liquid imageCollection=exampleDewPointPropagation5 %}

<hr>

Expand All @@ -358,9 +348,10 @@ The Building A asset manages multiple child HVAC devices linked via the _Manages
<b><font size="4">Goal</font></b>
Automatically propagate the <span class="code-light">hvacMode</span> attribute from Building A to all related HVAC devices.

<hr>
<b><font size="4">Calculated field configuration</font></b>
[Download the "Propagate HVAC mode" calculated field configuration (JSON)](/docs/user-guide/resources/calculated-fields/propagation/cooling_propagation_cf.json){:target="_blank" download="cooling_propagation_cf.json"}.

<b><font size="4">Configuration steps</font></b>
<br><b><font size="4">Configuration steps</font></b>

<b><font size="3">1. Import demo devices</font></b>
1. Download the CSV file: [propagate-hvac-mode-device-data.csv](/docs/user-guide/resources/calculated-fields/propagation/propagate-hvac-mode-device-data.csv){:target="_blank" download="propagate-hvac-mode-device-data.csv"}
Expand All @@ -378,9 +369,8 @@ Automatically propagate the <span class="code-light">hvacMode</span> attribute f
%}

{% include images-gallery.liquid imageCollection=examplePropagation31 %}
<hr>

<b><font size="3">2. Import demo asset</font></b>
<br><b><font size="3">2. Import demo asset</font></b>

Import an asset that represents the building.
1. Download the CSV file: [propagate-hvac-mode-asset-data.csv](/docs/user-guide/resources/calculated-fields/propagation/propagate-hvac-mode-asset-data.csv){:target="_blank" download="propagate-hvac-mode-asset-data.csv"}
Expand All @@ -391,6 +381,8 @@ Import an asset that represents the building.
- **Type:** building
- **Server attributes:** <span class="code-light">hvacMode</span>

> **Important note about the CSV:** the column type for the <span class="code-light">hvacMode</span> keys must be set to "**Server attributes**".

{% assign examplePropagation32 = '
===
image: /images/user-guide/calculated-fields/propagation/propagation-cf-example-3-2-ce.png
Expand Down Expand Up @@ -419,9 +411,7 @@ This relation is used by the propagation calculated field to locate the parent e

{% include images-gallery.liquid imageCollection=examplePropagation33 %}

<hr>

<b><font size="3">4. Apply the calculated field to the asset profile</font></b>
<br><b><font size="3">4. Apply the calculated field to the asset profile</font></b>

Configure a **Propagation** calculated field on the "building" asset profile (created automatically during asset import), so it runs for Building A.
1. [Download the calculated field configuration file](/docs/user-guide/resources/calculated-fields/propagation/cooling_propagation_cf.json){:target="_blank" download="cooling_propagation_cf.json"}.
Expand All @@ -444,13 +434,11 @@ This configuration propagates the attribute value of <span class="code-light">hv

{% include images-gallery.liquid imageCollection=examplePropagation34 %}

<hr>

<b><font size="4">Result</font></b>
<br><b><font size="4">Result</font></b>

Each HVAC device received the <span class="code-light">hvacMode</span> attribute with the value **cooling**.

{% assign examplePropagation33 = '
{% assign examplePropagation35 = '
===
image: /images/user-guide/calculated-fields/propagation/propagation-cf-example-3-7-ce.png
title: Each HVAC device received the **hvacMode** attribute with the value **cooling**.
Expand All @@ -461,7 +449,7 @@ Each HVAC device received the <span class="code-light">hvacMode</span> attribute
'
%}

{% include images-gallery.liquid imageCollection=examplePropagation33 %}
{% include images-gallery.liquid imageCollection=examplePropagation35 %}

<hr>

Expand Down
25 changes: 7 additions & 18 deletions ...s/user-guide/calculated-fields/related-entities-aggregation-calculated-field.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -148,23 +148,17 @@ Collect temperature telemetry from all sensors related to Building A and compute

Store both values as **telemetry** on the **Building A** asset.

<hr>

What you will configure

You will apply an "Aggregation" calculated field to the Building A asset that:
- reads the latest temperature value from related devices (child sensors)
- computes average and maximum
- writes the results back to Building A as telemetry keys <span class="code-light">avgTemperature</span> and <span class="code-light">maxTemperature</span>.

<hr>

<b><font size="4">Calculated field configuration</font></b>
[Download the "Related entities aggregation" calculated field configuration (JSON)](/docs/user-guide/resources/calculated-fields/related-entities-aggregation/temperature_aggregation_cf.json){:target="_blank" download="temperature_aggregation_cf.json"}.

<hr>

<b><font size="4">Configuration steps</font></b>
<br><b><font size="4">Configuration steps</font></b>

<b><font size="3">1. Import demo devices</font></b>

Expand All @@ -177,6 +171,8 @@ Import multiple smart devices that publish <span class="code-light">temperature<
- **Type:** sensor
- **Time series:** <span class="code-light">temperature</span>

> **Important note about the CSV:** the column type for the <span class="code-light">temperature</span> key must be set to "**Time series**".

{% assign exampleRelatedEntities1 = '
===
image: /images/user-guide/calculated-fields/related-entities/related-entities-cf-example-1-1-ce.png
Expand All @@ -191,9 +187,8 @@ Import multiple smart devices that publish <span class="code-light">temperature<
%}

{% include images-gallery.liquid imageCollection=exampleRelatedEntities1 %}
<hr>

<b><font size="3">2. Import demo asset</font></b>
<br><b><font size="3">2. Import demo asset</font></b>

Import the asset that represents the building.
1. Download the CSV file: [building-asset-data.csv](/docs/user-guide/resources/calculated-fields/related-entities-aggregation/building-asset-data.csv){:target="_blank" download="building-asset-data.csv"}
Expand All @@ -212,9 +207,7 @@ Import the asset that represents the building.

{% include images-gallery.liquid imageCollection=exampleRelatedEntities2 %}

<hr>

<b><font size="3">3. Create relations between the asset and devices</font></b>
<br><b><font size="3">3. Create relations between the asset and devices</font></b>

Create relationships between Building A and all smart sensors:
- **Relation direction:** From (Device &#8702; Building A)
Expand All @@ -232,9 +225,7 @@ These relations define the set of related entities whose telemetry will be aggre

{% include images-gallery.liquid imageCollection=examplePropagation33 %}

<hr>

<b><font size="3">4. Apply the calculated field to the asset</font></b>
<br><b><font size="3">4. Apply the calculated field to the asset</font></b>

Apply the **Related Entities Aggregation** calculated field to the **Building A** asset.
1. [Download the calculated field configuration file](/docs/user-guide/resources/calculated-fields/related-entities-aggregation/temperature_aggregation_cf.json){:target="_blank" download="temperature_aggregation_cf.json"}.
Expand Down Expand Up @@ -271,9 +262,7 @@ The field will:

> (Optional) Enable [Debug mode](/docs/user-guide/calculated-fields/?calculatedfieldsargumenttype=attribute#debug){:target="_blank"} and review execution events using the **Events** icon.

<hr>

<b><font size="4">Result</font></b>
<br><b><font size="4">Result</font></b>

The Building A asset stores aggregated telemetry such as:
- <span class="code-light">avgTemperature</span> — average temperature across all sensors
Expand Down
Loading