传播字段计算

• 配置
  • 向关联实体的传播路径
  • 要传播的数据
  • 输出
• 示例
  • 示例1：将设备电池电量传播到父级资产
  • 示例2：露点计算并传播到父级资产
  • 示例3：将HVAC模式传播到多个子设备
• 故障排查
  • 更新后传播路径设置未生效
• 反馈

Propagation（传播）自动将当前实体的数据传送到一个或多个通过实体关系解析出的关联实体。 可原样复制值，也可发送前先计算新值，适合在实体层级间同步遥测与属性。

在以下场景使用“Propagation”：

• 将设备遥测镜像到父级资产（如电池电量、信号强度、最近状态）
• 将配置属性从资产推送到子设备（如HVAC模式、设定点、运行配置）
• 共享前转换数据（如在设备上计算露点并存储到温室资产）
• 向多个实体传播（如更新某建筑或分组管理的所有设备）

配置

打开 创建字段计算 对话框并指定：

• 字段计算 title；
• 将应用字段计算的 entity或entity profile；
• 选择 “Propagation” 作为字段计算 type。

向关联实体的传播路径

关系方向
定义从当前实体到数据传播目标实体的路径：

• Up to parent — 数据传播到父实体。
• Down to child — 数据传播到子实体。

Propagation仅支持直接（单层）关系，不支持递归或多层遍历。

关系类型
定义目标实体与关联实体间的关系类型（如 Contains、Manages 或任意类型）。

若多个实体符合所选关系方向与关系类型，数据将传播到其中每一个。

要传播的数据

定义将传播到关联实体的数据。
传播数据以arguments形式配置，详见 Arguments 章节。

支持两种模式：

1. 仅Arguments
直接复制数据：将属性或最新遥测从_当前实体_复制到关联实体，可在存储前重命名传播的键。

2. 计算结果
在传播到关联实体前，基于多实体数据（当前实体 / 设备 / 资产 / 客户 / 当前租户 / 当前所有者）的属性、最新遥测或时间序列滚动进行计算或转换。

操作顺序如下：

• 配置从所选实体提供输入数据的arguments。
• 提供 TBEL 脚本，根据定义的arguments计算新值。
• 将计算结果传播到关联实体。

存储计算结果的变量名须在函数体内直接定义。

Script

使用基于 Arguments 中配置变量的 TBEL 函数定义计算逻辑。

Script字段计算必须实现：

1
function calculate(ctx, arg1, arg2, ...): object | object[]

函数可返回单个JSON对象（多个输出key）或JSON对象数组（多条time series记录）。

输出变量名在返回对象内直接定义。

示例：露点计算

1
2
3
4
5
6
7
8
// Constants for Magnus formula
var a = 17.625;
var b = 243.04;

var alpha = ((a * temperature) / (b + temperature)) + Math.log(humidity / 100.0);
var dewPoint = toFixed((b * alpha) / (a - alpha), 1);

return {"dewPoint": dewPoint};

函数使用 temperature 与 humidity 参数计算露点值。 结果将存储在变量 dewPoint 中，保留一位小数。

直接访问参数
Arguments也作为函数参数（arg1、arg2…）传入，可直接使用（如temperature、humidity）以简化脚本。

可按清晰度与个人习惯选择直接参数或 ctx.args.<arg>。

上下文对象 (ctx)

ctx 对象提供元数据及对argument值的访问：

• ctx.latestTs — 来自基于遥测的参数的最近时间戳（毫秒）。用于存储与传入数据相同时间戳的结果。
• ctx.args — 包含所有配置参数的对象，可通过点（.）表示法访问：
  • 单值参数 （属性或最新遥测）
    • ctx.args.<arg>.ts — 参数的时间戳。
    • ctx.args.<arg>.value — 参数的值。
  • 滚动时间序列参数
    • ctx.args.<arg>.timeWindow — 包含开始和结束时间戳的对象 { startTs, endTs }。
    • ctx.args.<arg>.values — 表示时间戳遥测的 { ts, value } 记录数组。
    • ctx.args.<arg>.<method>() — 内置方法，如 mean()、sum()、min()、max()、first()、last()、merge() 等。

输出

数据传播到各关联实体，并以 time series 或 attributes 形式存储。

输出类型与处理策略详见 Output 章节。

示例

以下为三个常见配置模式的实用示例。

示例1：将设备电池电量传播到父级资产

场景
Tracker A设备以遥测形式向ThingsBoard发送电池电量（batteryLevel）。

目标
自动将设备电池电量传播到关联的Truck 1资产，并以服务端属性存储，使用新key：deviceBatteryLevel。

字段计算配置
下载“电池电量传播”字段计算配置 (JSON)。

配置步骤

1. 导入示例设备

导入发布电池遥测的设备。

1. 下载CSV文件：battery-level-device-data.csv
2. 转到设备并导入 CSV文件。

CSV包含：

• Name： Tracker A
• Type： tracker
• Time series： batteryLevel

CSV注意事项： batteryLevel 的列类型须设为“Time series”。

2. 导入示例资产

导入代表被追踪卡车的资产。

1. 下载CSV文件：battery-level-asset-data.csv
2. 转到资产并导入 CSV文件。

CSV包含：

• Name： Truck 1
• Type： truck

3. 在资产与设备间创建关系

创建关系以便字段计算能解析到目标资产。

在Truck 1资产与Tracker A设备间创建关系：

• 关系方向：From
• 关系类型：Contains

Propagation字段计算通过此关系定位父实体。

4. 将Propagation字段计算应用于设备配置

在tracker设备配置（设备导入时自动创建）中配置Propagation字段计算，使其对Tracker A生效。

1. 下载字段计算配置文件。
2. 转到”字段计算”选项卡并导入配置。

此配置将batteryLevel的最新遥测值传播到父资产（Truck 1）。

结果

deviceBatteryLevel属性已传播并作为服务端属性存储在Truck 1资产上。

示例2：露点计算并传播到父级资产

场景
Smart Device向ThingsBoard发送temperature与humidity遥测，并通过 Contains 关系关联到Greenhouse A资产。

目标
计算露点，将结果传播到关联资产（Greenhouse A），并以遥测形式存储。

字段计算配置
下载”露点传播”字段计算配置（JSON）。

配置步骤

1. 导入演示设备

导入发布温度和湿度遥测的设备。

1. 下载CSV文件：dew-point-calculation-device-data.csv
2. 转到设备并导入 CSV文件。

CSV包含：

• Name： Smart Device
• Type： smart-device
• Time series： humidity、temperature

关于CSV的重要说明： humidity和temperature键的列类型必须设置为”时间序列“。

2. 导入演示资产

导入代表温室的资产。

1. 下载CSV文件：dew-point-calculation-and-propagation-asset-data.csv
2. 转到资产并导入 CSV文件。

CSV包含：

• Name： Greenhouse A
• Type： greenhouse

3. 在资产与设备间创建关系

创建Greenhouse A资产与Smart Device之间的关系：

• 关系方向：From
• 关系类型：Contains

此关系允许字段计算在传播输出时找到父资产。

4. 将字段计算应用于设备配置

在”smart-device”设备配置（设备导入期间自动创建）上配置字段计算，使其对Smart Device运行。

1. 下载字段计算配置文件。
2. 转到”字段计算”选项卡并导入配置。

此场景从指定的输入数据计算露点值。该值传播并存储在父资产（Greenhouse A）上作为遥测，其键为dewPoint。

结果

计算值传播到Greenhouse A资产并存储为遥测，其键为dewPoint。

示例3：将HVAC模式传播到多个子设备

场景
Building A资产通过 Manages 关系管理多个子HVAC设备。资产级 hvacMode 服务端属性为所有设备定义运行模式（如 cooling、heating、off）。

目标
将 hvacMode 属性从Building A自动传播到所有关联HVAC设备。

字段计算配置
下载“HVAC模式传播”字段计算配置 (JSON)。

配置步骤

1. 导入演示设备

1. 下载CSV文件：propagate-hvac-mode-device-data.csv
2. 转到“设备”并导入该CSV文件。

CSV包含：

• 名称： Room Sensor 1
• 类型： sensor

2. 导入演示资产

导入代表建筑的资产。

1. 下载CSV文件：propagate-hvac-mode-asset-data.csv
2. 转到“资产”并导入该CSV文件。

CSV包含：

• 名称： Building A
• 类型： building
• 服务端属性： hvacMode

关于CSV的重要说明： hvacMode 键的列类型必须设置为“服务端属性”。

3. 创建资产与设备之间的关系

创建“Building A”资产与“房间设备”之间的关系。

• 关系方向： 从
• 关系类型： 管理

字段计算通过该关系找到父实体。

4. 将字段计算应用于资产配置

在“building”资产配置上配置一个“传播”字段计算（在资产导入时自动创建），以便为Building A运行。

1. 下载字段计算配置文件。
2. 转到“字段计算”标签页并导入配置。

此配置将 hvacMode 属性值传播到子设备。

结果

每个HVAC设备都接收到 hvacMode 属性，值为 cooling。

故障排查

更新后传播路径设置未生效

现象： 编辑现有字段计算并修改 关系方向 或 关系类型（例如从 Contains 改为 Manages）时，字段忽略这些变更，仍按原路径传播数据。

原因： 字段计算逻辑会缓存首次创建时定义的向关联实体的传播路径。对关系方向或关系类型的专项修改不会被正确识别，导致路径未能重新初始化。

解决： 强制字段计算应用新的传播路径时，需修改 Data to propagate 区域配置。对arguments的任何改动都会触发必要的重新初始化。

可选以下两种方式之一：

1. 重新创建字段（最干净） 若必须保持现有arguments不变（如不能修改默认值），则需删除原字段计算并新建一个，使用正确的传播路径设置。

2. 修改默认值（推荐变通） 若希望在不断建字段的前提下修复，可编辑已有argument并修改其 Default value（例如由空改为有值，或更新值）。

   若源数据缺失，将使用新默认值。若源数据始终存在，这是最稳妥方式，可在不影响数据的前提下强制更新。

反馈

欢迎为ThingsBoard在 github 加星。 如有疑问，请 联系我们。