脚本字段计算

• 配置
  • 参数
  • 脚本
  • 输出
• 示例
  • 示例1：华氏温度转换
  • 示例2：空气密度计算
  • 示例3：冰箱温度分析
• 反馈

Script字段计算使用 TBEL（ThingsBoard Expression Language）对遥测与属性执行高级实时计算。与Simple字段不同，Script字段支持条件逻辑、对滚动时序值的迭代、历史窗口处理，以及单次执行返回多个结果。

在需要超越单一数学表达式的逻辑时使用“Script”字段计算，例如：

• 多步计算（如露点、空气密度、效率指标）
• 条件规则（如根据多个输入生成状态标志）
• 多输出结果（如同时计算多个派生值）
• 类事件遥测生成（如生成带时间戳的异常记录）
• 基于历史窗口的滚动分析（如滚动平均、趋势检测、平滑）

配置

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

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

参数

Arguments定义传入脚本的数据源和key。Script字段计算的arguments可为 Latest telemetry、Attribute 或 time series rolling。
数据源可为 Current entity、另一 Device/Asset、Customer、Current tenant 或 Current owner。

参数类型与配置详见字段计算文档中的 Arguments 章节。

脚本

使用基于 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 或 attribute 形式存储。

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

示例

为了帮你高效地开始，下面是应用于真实世界场景的三个常见配置模式。

示例1：华氏温度转换

为了帮你高效地开始，下面是应用于真实世界场景的三个常见配置模式。

场景
设备以华氏温度为单位发布室内温度遥测数据，键为 temperatureF。

目标
将 temperatureF 转换为摄氏温度，舍入到两位小数，并使用与传入数据相同的时间戳将结果存储为遥测数据，键为 temperatureC。

字段计算配置
下载“华氏温度转换”字段计算配置 (JSON).

配置步骤

1. 导入演示设备

导入发布温度遥测数据的设备。

1. 下载CSV文件：fahrenheit-to-celsius-calculation-device-data.csv
2. 转到“设备”并导入 CSV文件。

CSV包含：

• 名称： Smart Device
• 类型： smart-device
• 时间序列： temperatureF

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

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

1. 下载字段计算配置文件 (JSON).
2. 转到“字段计算”标签页并导入配置。
   将字段计算应用于设备导入时自动创建的“smart-device”配置文件。此字段将应用于所有使用此配置文件的设备。

此配置读取 temperatureF, 将其转换为摄氏温度，并将结果存储为 temperatureC。

Script used in this example:

function calculate(ctx, altitude, temperature) {

1
2
3
4
5
6
7
var temperatureC = (temperatureF - 32) / 1.8;
return {
    "ts": ctx.latestTs,
    "values": {
        "temperatureC": toFixed(temperatureC, 2)
    }
}

}

结果

在智能设备的“最新遥测”标签页上，计算的温度值（摄氏温度）会显示在新的键下：temperatureC。

示例2：空气密度计算

场景
Building A 资产关联了两个设备：

• Smart Device — 以华氏温度为单位捧布室内温度遥测数据，键为 temperature
• Altimeter — 以服务端属性提供高度，键为 altitude

目标
基于以下数据计算空气密度：

• 最后15分钟内的平均温度（滚动窗口）
• 高度属性

将结果作为新的遥测值喁储在Building A的 airDensity 键下。

字段计算配置
点击下载“空气密度计算”字段配置 (JSON).

配置步骤

1. 导入演示设备

导入两个设备：一个发布温度遥测数据，一个提供高度作为属性。

1. 下载CSV文件：air-density-calculation-device-data.csv
2. 转到“设备”并导入 CSV文件。

CSV包含：

设备1

• 名称： Smart Device
• 类型： smart-device
• 时间序列： temperature

设备2

• 名称： Altimeter
• 类型： height-sensor
• 服务端属性： altitude

关于CSV的重要说明：

• temperature 键的列类型必须设置为“时间序列”。
• altitude 键的列类型必须设置为“服务端属性”。

%}

2. 导入演示资产

导入代表建筑的资产。

1. 下载CSV文件：air-density-calculation-asset-data.csv
2. 转到“资产”并导入 CSV文件。

CSV包含：

• 名称： Building A
• 类型： building

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

将字段计算应用于“building”资产配置，以便为Building A运行。

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

此配置：

• 从Smart Device读取滚动温度
• 从Altimeter读取高度作为属性
• 计算空气密度
• 将输出存储为资产遥测

Script used in this example:

function calculate(ctx, altitude, temperature) {

1
2
3
4
5
6
7
8
9
10
11
12
13
var avgTemperature = temperature.mean(); // Get average temperature
var temperatureK = (avgTemperature - 32) * (5 / 9) + 273.15; // Convert Fahrenheit to Kelvin

// Estimate air pressure based on altitude
var pressure = 101325 * Math.pow((1 - 2.25577e-5 * altitude), 5.25588);

// Air density formula
var airDensity = pressure / (287.05 * temperatureK);

return {
    "airDensity": toFixed(airDensity, 2)
};

}

结果

在Building A资产的“最新遥测”标签页上，计算值显示在 airDensity 键下。

示例3：冰箱温度分析

场景
A freezer device publishes two telemetry keys:

• temperature — freezer temperature (°C)
• defrost — defrost mode status (0 = OFF, 1 = ON)

目标
Generate an event-like telemetry record under the issue key whenever:

• defrost = 0 (defrost is OFF), and
• temperature > -5°C

When the condition is met, store an “issue record” with a timestamp.

字段计算配置
下载“冰箱温度分析”字段计算配置 (JSON).

配置步骤

1. 导入演示设备

导入发布温度和遭霗模式数据作为遥测的设备。

1. 下载CSV文件：freezer-temperature-analysis-device-data.csv
2. 转到“设备”并导入 CSV文件。

CSV包含：

• 名称： Smart Device
• 类型： smart-device
• 时间序列： temperature、defrost

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

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

将字段计算应用于“smart-device”配置文件，以便为冰箱设备运行。

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

此配置：

• 按时间戳整合温度和遭霗状态数据。
• 仅选择温度高于 -5°C且遭霗模式关闭OFF（值为0）的时刻。
• 结果，会得到一个这种时刻的列表，显示温度值、时间戳和一个defrostState：false标记（或者如果没有满足的时刻，则是一个空列表）。

Script used in this example:

function calculate(ctx, altitude, temperature) {

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
var merged = temperature.merge(defrost);
var result = [];

foreach(item: merged) {
  if (item.v1 > -5.0 && item.v2 == 0) {
    result.add({
      ts: item.ts,
      values: {
        issue: {
          temperature: item.v1,
          defrostState: false
        }
      }
    });
  }
}

return result;

}

结果

在智能设备的“最新遥测”标签页上，当冰箱需要维修时issue键将出现，例如：

1
2
3
4
5
6
7
{
  "issue": {
    "temperature": 0.8,
    "defrostState": false
  }
}

这表明冰箱正处于潜在的危险状态，可能需要注意。

反馈

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