地理围栏字段计算

• 为什么使用Geofencing字段计算？
• Configuration
  • 实体坐标
  • 地理围栏区域组
    • 名称
    • 实体类型
    • 从实体到区域的路径
    • 周长属性键
    • 报告策略
    • 创建与匹配区域的关系
    • 区域组刷新间隔
  • 输出
• 示例
  • 示例1：宠物追踪器（自地理围栏）
  • 示例2：仓库设备（直接关联）
  • 示例3：复杂的车队管理（多个区域类型）
• 反馈

Geofencing（地理围栏）字段计算通过将传入的GPS坐标与已配置的地理围栏区域比对，实时监控实体移动。 可通过配置表达空间逻辑，自动检测实体（车辆、集装箱、追踪器等）是否位于特定区域（如禁入区、停车场或作业边界）内。

在以下场景使用Geofencing字段计算：

• 跟踪操作区域中的存在状态（例如，”卡车是否在仓库周边？”）。
• 检测进出变化并记录边界穿越事件（进入 / 离开）。
• 同时监控多个独立区域（例如，安全区 + 限制区）。
• 当逻辑区域由多个相邻多边形表示时，不会造成错误的变化。
• 生成警报准备好的输出（状态 + 事件键），可直接用于警报、仪表板、自动化或分析。
• 支持通过关系动态分配区域（可添加或移除，无需重新配置每个设备）。

为什么使用Geofencing字段计算？

Geofencing字段计算引入了区域组，消除了冲突状态并改进了可扩展性：

每个区域组的独立状态
每个区域组维持自己的”内部/外部”状态。这使得可以同时跟踪多个区域类别（例如，位于安全区内且在限制区外），不会覆盖或造成错误的变化。

逻辑区域组合（防止产生错误的变化）
当区域动态发现时，多个物理多边形可以作为一个逻辑组来定义。当实体在同一组中的相邻区域之间移动时，该字段计算会保持组内的连续”内部”状态，并不会生成错误的进入/离开事件。

警报和仪表板的标准化输出
对于每个区域组，该字段计算生成一致的输出键（<zoneGroupName>Status及 <zoneGroupName>Event），可直接用于 alarm rules、仪表板、自动化或分析。

Configuration

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

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

实体坐标

映射表示实体GPS位置的传入遥测key。

• Latitude time series key — 如 latitude 或 lat
• Longitude time series key — 如 longitude 或 lng

要求

• 值须为数字。
• 若任一坐标缺失或无效，则跳过计算。

地理围栏区域组

Zone Group 是将一个或多个物理区域（多边形/圆）捆绑为一次评估的逻辑容器。

字段计算检查组内所有zones并确定实体状态：

• INSIDE — 实体位于组内至少一个 zone内
• OUTSIDE — 实体不在组内任何 zone内

点击 Add zone group 配置新组。

在区域组配置对话框中，配置以下设置：

区域组设置

名称

区域组名称被用作为生成的地理围栏键的前缀：

• <name>Status
• <name>Event

最佳实践：使用camelCase（例如，restrictedArea）以保持键一致性：

• restrictedAreaStatus
• restrictedAreaEvent

实体类型

选择区域几何定义（多边形/圆形）的存储位置：

• 当前实体 - 字段计算被应用的当前实体。
  如果该字段计算在设备配置或资产配置级别创建，计算对于与该配置相关联的实体颇行。
• 另一个设备或资产 — 不同的实体。
• 客户 — 相关联的客户。
• 当前租户 — 当前租户。
• 当前所有者 — 当前实体的所有者。

⚠️ 静态配置的注意事项： 选定一个特定设备/资产/客户会硬编码执行，降低可利用性。更倾向于配置级别配置。

提示

选择正确的来源，请考虑以下常见模式：

1) 自地理围栏（每个实体有其自己的区域）

问题： 每个追踪器是否在自身上存储一个唯一的区域（例如，个人主页区域）？
答案： 是的。
行动： 选择当前实体。
工作原理： 字段计算直接从其中应用字段的实体中读取周长属性。这对于设备特定区域（例如_Family_或自定义_Safe Areas_）是理想的。

2) 动态区域列表（通过关系添加/删除区域）

问题： 区域组是否包含多个区域，或区域是否会随着时间动态变化？
答案： 是的。
行动： 选择相关实体并配置从实体到区域的路径。
工作原理： 字段计算通过从源实体遍历配置的关系路径来发现区域。路径可以包括多个步骤和方向（UP/DOWN），允许您通过层次关系到达区域资产。

示例路径：
- 从_Vehicle_向上UP到_Fleet_，使用关系类型_FleetToVehicle_
- 然后从_Fleet_向下DOWN到_Zone_，使用关系类型_FleetToRestrictedZone_

最佳实践：
这种方法可扩展性最好。您可以将所有几何图形存储在单个Zone资产配置中，并使用关系类型（例如_FleetToParking_、FleetToRestricted）来构建多个逻辑区域组，而无需复制配置。

3) 组织级区域（从租户/所有者继承）

问题： 区域是否在组织级别为整个层次结构定义（例如，按租户或按客户/所有者）？
答案： 是的。
行动： 选择当前租户或当前所有者。
工作原理： 字段计算从拥有该实体的租户或客户检索周长属性。设备有效地继承在业务级别定义的区域。

最佳实践：
这对于高级别策略是理想的。例如，在多客户解决方案中，每个客户可以定义其自己的全球_服务区域_多边形，该客户下的所有设备都会自动应用它，而无需进行每设备的配置。

从实体到区域的路径

本节定义系统所遵循的精确”路线图”以找到区域实体。 路径从源实体（运行此字段计算的设备或资产）开始，并遵循您指定的关系。

级别
指示关系步骤深度的序列号。

⚠️ 注意： 最小级别为1。允许的最大深度由您的租户配置配置中的”每个’相关实体’参数的最大关系级别”确定。

方向

• 向上： 查找父实体（例如，从设备向上到车队）。
• 向下： 查找子实体（例如，从车队向下到区域）。

关系类型
为每个步骤遵循的特定连接名称（例如”FleetToVehicle”、”FleetToRestrictedZone”、”FleetToNoParkingZone”）。

💡 配置灵活性： 您不受限于特定拓扑。 您可以配置单级路径（例如，如果区域直接与源实体相关，只需一个向上步骤） 或复杂的多级路径（混合向上和向下），具体取决于您的实体层次结构。

示例配置
要为属于车队的车辆（源实体）查找区域：

• 级别1： 方向：”向上”，关系类型：VehicleToFleet（查找车队）。
• 级别2： 方向：”向下”，关系类型：”FleetToRestrictedZone”（查找与该车队使用”FleetToRestrictedZone”关系类型相关的所有区域实体）。

周长属性键

指定区域实体上存储几何图形的服务器端属性键。支持多边形和圆形。

报告策略

控制区域组生成的遥测内容：

仅过渡事件

仅存在状态

存在状态和过渡事件

此设置控制字段计算为区域组生成哪些遥测。选择最适合您的监控需求的选项：

仅过渡事件

• 仅在状态更改时生成过渡事件（ENTERED / LEFT）。
• 事件驱动的工作流和最小存储。当您只关心边界穿越时使用（例如，计算车辆进入现场的次数）。

仅存在状态

• 仅生成当前状态（INSIDE / OUTSIDE）。
• 简单的状态监控。当您只需要当前位置状态（例如，”卡车在车库里吗？”）而不保持事件历史时使用。

存在状态和过渡事件

• 生成状态（INSIDE / OUTSIDE）和过渡事件（ENTERED / LEFT）。
• 完全监控和自动化。此选项支持仪表板（当前状态）以及基于进入/离开事件的实时警报/通知。

创建与匹配区域的关系

启用后，字段计算会自动创建/删除源实体与该实体当前所在区域之间的关系。

生命周期：
关系根据移动动态管理：

• 进入时： 当实体进入区域时立即创建关系。
• 离开时： 当实体离开区域时立即删除关系。

配置

关系方向：

• 从区域到实体 — 区域被视为父级，源实体被视为子级。
• 从实体到区域 — 源实体被视为父级，区域被视为子级。

关系类型
定义要创建的关系类型名称（例如，currentlyInside）。

用例
列出当前在特定区域内的实体。

区域组刷新间隔

控制ThingsBoard刷新已发现区域的缓存列表的频率：

• 禁用： 区域关系只获取一次，永远不刷新。仅当实体关系是永久的且不会在运行时更改时使用（例如，静态基础设施）。
• 启用： 根据配置的间隔（秒）定期刷新区域关系。

调整指南

• 低间隔（例如60秒）： 如果关系经常更改。系统更快地检测重新分配，并以最小延迟应用最新区域。
• 高间隔（例如3600秒）： 如果关系很少更改。这会通过更长地缓存关系来减少数据库负载，並改进整体性能。

  ⚠️ 最小允许值由租户配置设置”‘相关实体’参数的最小允许更新间隔”控制。

输出

对于每个区域组，ThingsBoard生成内部变量：

• <zoneGroupName>Status -> INSIDE / OUTSIDE
• <zoneGroupName>Event -> ENTERED / LEFT

例如，对于名为restrictedArea的组：

• restrictedAreaStatus
• restrictedAreaEvent

在输出部分，将这些变量映射到目标输出键，并将其存储为遥测（推荐）或属性。

最佳实践： 将输出数据存储为遥测，因为这为仪表板、分析和警报提供了最大的灵活性。

示例

为了帮助您快速上手，以下是应用于现实场景的三个常见配置模式。

示例1：宠物追踪器（自地理围栏）

场景
您正在构建宠物追踪解决方案。每个狗项圈追踪器发送GPS坐标（latitude、longitude）并将其自己的”主页区域”几何图形（一个圆）存储在服务器端属性safeZone中。

每条狗都有唯一的区域（例如，Buddy和Rex住在不同的地点），因此地理围栏几何图形必须存储在设备本身上。

目标
检测狗何时进入/离开其安全区并生成：

• 存在状态（INSIDE / OUTSIDE）
• 过渡事件（ENTERED / LEFT）

字段计算配置
下载”宠物追踪器”字段计算配置（JSON）。

配置步骤

1. 导入演示设备
导入两个设备 — 每个设备代表内置在狗项圈中的追踪器。这些设备将发布GPS坐标作为遥测和一个服务器端safeZone属性，其中包含圆形形式的主页区域坐标。

1. 下载包含设备配置的CSV文件。
2. 转到设备并导入 CSV文件。

CSV包括：

• Name： Buddy、Rex
• Type： pet-tracking
• Time series： latitude、longitude
• Server attribute： safeZone

关于CSV的重要注意事项：

• CSV分隔符必须是;。
• latitude和longitude是定义狗当前坐标的时间序列键。
• safeZone是定义区域周长为圆形的服务器端属性。

2. 将字段计算应用于设备配置
导入设备时，”pet-tracking”配置文件会自动创建并分配给它们。 将字段计算应用于此配置文件，以便它对使用它的所有设备运行。

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

此字段计算评估每条狗是否在其自己的safeZone内，并相应地生成状态/事件。

（可选）启用调试模式并通过事件按钮检查执行。

3. 导入演示仪表板
导入仪表板JSON以监视设备：

• 下载仪表板配置文件。
• 转到仪表板页面并导入 JSON文件以及仪表板配置。

仪表板包括：

• 显示狗位置的地图小部件。
• 属性卡小部件，显示：
  • 狗相对于其安全区的当前存在状态（INSIDE / OUTSIDE）
  • 最近的安全区过渡事件（ENTERED / LEFT）

结果

当您移动狗的标记到主页区域之外或返回主页区域时：

• 状态更新（INSIDE / OUTSIDE）
• 事件更新（ENTERED / LEFT）

示例2：仓库设备（直接关联）

场景
您管理一个大型配送中心。您有两台叉车。每个叉车跟踪器发布GPS遥测（latitude、longitude）。
仓库资产将地理围栏周长发布为属性。

目标
检测叉车何时离开其所在建筑的周长，并生成：

• 当前存在状态（INSIDE / OUTSIDE）
• 过渡事件（ENTERED / LEFT）

字段计算配置
下载”仓库设备”字段计算配置（JSON）。。

配置步骤

1. 导入演示设备
导入两个设备 — 每个设备代表安装在叉车中的跟踪器。设备发布GPS坐标作为遥测。

1. 下载包含设备配置的CSV文件。
2. 转到设备页面并导入 CSV文件。

CSV包括：

• Name： Forklift A、Forklift B
• Type： forklift
• Time series： latitude、longitude

关于CSV的重要注意事项：

• CSV分隔符必须是;。
• latitude和longitude键的列类型必须设置为”时间序列“。

2. 导入演示资产

• 下载CSV文件：warehouse-equipment-example-asset-data.csv
• 转到资产页面并导入 CSV文件到您的ThingsBoard实例：

CSV包括：

• Name： Warehouse A
• Type： warehouse
• Server attribute： perimeter

关于CSV的重要注意事项：

• CSV分隔符必须是;。
• perimeter键的列类型必须设置为”服务器属性“。

3. 创建关系

在仓库建筑A资产和叉车A和叉车B设备之间创建关系：

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

此关系由字段计算用来解决每个叉车的分配建筑区域。

4. 将字段计算应用于设备配置
导入设备时，”forklift”配置文件会自动创建并分配给它们。 将字段计算应用于此配置文件，以便它对使用它的所有设备运行。

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

此字段计算通过关系解决仓库区域并生成状态/事件。

5. 导入仪表板
导入仪表板以实时监控叉车。

• 下载仪表板配置文件。
• 转到仪表板页面并导入 JSON文件以及仪表板配置。

仪表板包括：

• 地图小部件显示每个叉车的当前位置
• 属性卡小部件显示：
  • 当前存在状态（INSIDE / OUTSIDE）
  • 最后一个过渡事件（ENTERED / LEFT）

结果

当您将叉车标记移到仓库建筑A的周长之外或返回其周长时，叉车小部件会自动更新：

• 存在状态已更新，
• 边界穿越时生成过渡事件。

这确认了基于直接设备到资产关联的地理围栏工作正确。

示例3：复杂的车队管理（多个区域类型）

场景
一家物流公司运营一支卡车车队。每辆卡车必须同时针对多个区域类别进行监控，例如指定的服务区和限制的”禁区”。

目标
同时跟踪每辆卡车的两个独立条件：

• 服务区域 — 卡车当前是否在其分配的服务区INSIDE/OUTSIDE。
• 限制区域 — 检测卡车是否进入/离开任何禁区。

此示例在单个地理围栏字段计算内使用两个区域组。两组均通过车队关系动态发现区域，但使用不同的关系类型来分离逻辑：

• serviceArea组：UP到车队(Contains) → DOWN到区域(FleetToAllowedZone)
• restrictedArea组：UP到车队(Contains) → DOWN到区域(FleetToRestrictedZone)

注意（仅可视化）： 区域资产可能包括zoneType服务器属性（例如，允许/限制），仅用于地图着色。字段计算逻辑依赖于关系类型，而不是zoneType。

字段计算配置
下载”车队地理围栏”字段计算配置（JSON）。

配置步骤

1. 导入演示设备
导入两个设备 — 每个代表安装在卡车中的追踪器。设备发布GPS坐标作为遥测。

1. 下载包含设备配置的CSV文件。
2. 转到设备页面并导入 CSV文件。

CSV包括：

• Name： Truck 101、Truck 102
• Type： truck
• Time series： latitude、longitude

关于CSV的重要注意事项：

• CSV分隔符必须是;。
• latitude和longitude键的列类型必须设置为”时间序列“。

2. 导入演示资产
导入代表车队和区域的资产。

• 下载CSV文件：complex-fleet-management-example-assets-data.csv
• 转到”资产”页面并导入 CSV文件到您的ThingsBoard实例：

CSV包括：

• Name： No-Go Zone A、Service Zone A、North East Fleet
• Type： zone、fleet
• Server attribute： perimeter、zoneType

关于CSV的重要注意事项：

• CSV分隔符必须是;。
• perimeter和zoneType键的列类型必须设置为”服务器属性“。

3. 创建关系
创建字段计算用于发现车队及其区域的关系。

1. 将卡车链接到车队：
   • North East Fleet ↔ Truck 101和Truck 102
     • 关系方向： From
     • 关系类型： Contains
2. 将车队链接到服务区：
   • North East Fleet ↔ Service Zone A
     • 关系方向： From
     • 关系类型： FleetToAllowedZone
3. 将车队链接到限制区：
   • North East Fleet ↔ No-Go Zone A
     • 关系方向： From
     • 关系类型： FleetToRestrictedZone

4. 将字段计算应用于设备配置
导入设备时，”truck”设备配置会自动创建并分配给它们。 将字段计算应用于此配置文件，以便它对使用它的所有卡车运行。

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

5. 导入仪表板
导入仪表板以实时监控。

• 下载仪表板配置文件。
• 转到”仪表板”页面并导入 JSON文件以及仪表板配置。

仪表板包括：

• 显示卡车位置和区域覆盖的地图小部件
• 显示以下内容的属性卡小部件：
  • 当前serviceAreaStatus
  • 当前restrictedAreaStatus
  • 最后一个restrictedAreaEvent（ENTERED / LEFT）

结果

当您将卡车标记移动到区域边界前后时：

• serviceAreaStatus更新为INSIDE / OUTSIDE
• restrictedAreaEvent在过渡时生成（ENTERED / LEFT）
• 两个条件同时为同一卡车独立跟踪，不会发生状态冲突。

反馈

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