gps geofencing events

从传入消息中提取经纬度，并监控实体是否进入、离开或停留在配置的地理围栏（多边形或圆形）内/外。节点跟踪状态转换和时长阈值以产生不同事件类型。

当实体进入围栏时，消息经 Entered 路由；离开时经 Left 路由。根据配置的在场监控策略和最短停留时长，消息也可经 Inside 或 Outside 路由。

配置

坐标字段名

指定消息中用于监控的GPS坐标字段。

Latitude field name — 包含待检查点纬度的key名。
Longitude field name — 包含待检查点经度的key名。

两字段先在消息数据中查找，若未找到则回退到元数据。

地理围栏配置

地理围栏可为多边形或圆形。多边形适用于不规则边界（如物业线、配送区），圆形适用于以兴趣点为中心、基于半径的简单监控。

有两种配置方式：

静态配置 — 在节点设置中直接定义地理围栏。适用于边界不变或所有设备共享同一监控区域。该配置对经本节点处理的所有消息生效。

动态配置 — 从每条消息的元数据加载地理围栏定义。适用于不同实体需要不同边界或区域频繁变更的场景。

配置字段

Perimeter type — 指定围栏形状：Polygon 或 Circle。
Fetch perimeter information from metadata — 决定配置方式：
- Disabled (static)：地理围栏在节点配置中定义一次，所有消息共用同一边界。
- Enabled (dynamic)：每条消息可在元数据中定义自己的地理围栏，节点从指定元数据key读取边界。
Perimeter key name — 仅动态配置启用时使用。指定包含地理围栏定义的元数据key。值格式取决于围栏类型（见下方格式示例）。

For static Polygon configuration:

Polygon definition — a JSON array of coordinates defining the boundary (see format examples below).

For static Circle configuration:

Center latitude — the latitude of the circle’s center point.
Center longitude — the longitude of the circle’s center point.
Range — the radius distance from the center.
Range units — the unit of measurement: Meter, Kilometer, Foot, Mile, or Nautical mile.

Geofence definition formats

The following formats apply whether using static configuration or storing definitions in metadata.

Polygon formats

Polygon definitions are JSON arrays of coordinates, where each coordinate is [latitude, longitude].

Single polygon

A minimum of three points is required to form a closed shape (the node automatically connects the last point back to the first):

[[48.195, 24.645], [48.200, 24.655], [48.205, 24.645]]

Rectangle shorthand

Provide two opposite corners and the node will compute the remaining corners:

[[48.195, 24.645], [48.205, 24.655]]

Multiple zones

Monitor several separate areas by nesting polygon arrays:

[
  [[48.195, 24.645], [48.200, 24.655], [48.205, 24.645]],
  [[48.210, 24.650], [48.215, 24.660], [48.220, 24.650]]
]

Exclusion zones (holes)

Create exclusions by placing a smaller polygon completely inside a larger one. The inner polygon becomes a “hole” that is excluded from the monitored area:

[
  [[48.190, 24.640], [48.210, 24.640], [48.210, 24.660], [48.190, 24.660]],
  [[48.197, 24.647], [48.203, 24.647], [48.203, 24.653], [48.197, 24.653]]
]

Circle format

Circle definitions are JSON objects with these fields:

{
  "latitude": 48.1986,
  "longitude": 24.6532,
  "radius": 100.0,
  "radiusUnit": "METER"
}

latitude — center point latitude
longitude — center point longitude
radius — distance from center (must be positive)
radiusUnit — optional, defaults to "METER" if not specified. Valid values: "METER", "KILOMETER", "FOOT", "MILE", "NAUTICAL_MILE"

Presence monitoring strategy

Controls how the node reports the entity’s presence status after the initial entry or exit event.

On each message strategy

After an entity enters or leaves the geofence, every subsequent message is routed via Inside or Outside as long as the entity remains in that state. No minimum duration requirements apply with this strategy.

On first message strategy

After an entity enters or leaves and remains in the new state for the minimum duration, only the first message that satisfies the duration threshold is routed via Inside or Outside. All subsequent messages are routed via Success until the state changes again.

Duration thresholds

Duration thresholds define how long an entity must remain inside or outside the geofence before the node routes messages via Inside or Outside connections. These thresholds prevent false positives from brief GPS fluctuations or temporary boundary crossings.

Minimum inside duration — the time period an entity must continuously remain inside the geofence before messages are routed via the Inside connection. Specified as a duration value and time unit (Milliseconds, Seconds, Minutes, Hours, Days).
Minimum outside duration — the time period an entity must continuously remain outside the geofence before messages are routed via the Outside connection. Specified as a duration value and time unit (Milliseconds, Seconds, Minutes, Hours, Days).

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "TbGpsGeofencingActionNodeConfiguration",
  "type": "object",
  "required": [
    "latitudeKeyName",
    "longitudeKeyName",
    "perimeterType",
    "fetchPerimeterInfoFromMessageMetadata",
    "minInsideDuration",
    "minOutsideDuration",
    "minInsideDurationTimeUnit",
    "minOutsideDurationTimeUnit",
    "reportPresenceStatusOnEachMessage"
  ],
  "properties": {
    "latitudeKeyName": {
      "type": "string",
      "description": "Name of the key that holds the latitude of the point to check."
    },
    "longitudeKeyName": {
      "type": "string",
      "description": "Name of the key that holds the longitude of the point to check."
    },
    "perimeterType": {
      "type": "string",
      "description": "Specifies whether the geofence is a Polygon or a Circle.",
      "enum": [
        "CIRCLE",
        "POLYGON"
      ]
    },
    "fetchPerimeterInfoFromMessageMetadata": {
      "type": "boolean",
      "description": "Whether to load the geofence definition from message metadata or use static configuration."
    },
    "perimeterKeyName": {
      "type": "string",
      "description": "Name of the metadata key that contains the perimeter definition."
    },
    "polygonsDefinition": {
      "type": "string",
      "description": "String representing a JSON array of coordinates for polygon perimeter."
    },
    "centerLatitude": {
      "type": "number",
      "description": "Latitude of the center of the circle perimeter."
    },
    "centerLongitude": {
      "type": "number",
      "description": "Longitude of the center of the circle perimeter."
    },
    "range": {
      "type": "number",
      "description": "Radius of the circle perimeter."
    },
    "rangeUnit": {
      "type": "string",
      "description": "Unit of measurement for the circle radius.",
      "enum": [
        "METER",
        "KILOMETER",
        "FOOT",
        "MILE",
        "NAUTICAL_MILE"
      ]
    },
    "minInsideDuration": {
      "type": "integer",
      "description": "Minimum time an entity must remain inside before Inside event is triggered."
    },
    "minOutsideDuration": {
      "type": "integer",
      "description": "Minimum time an entity must remain outside before Outside event is triggered."
    },
    "minInsideDurationTimeUnit": {
      "type": "string",
      "description": "Time unit for minimum inside duration.",
      "enum": [
        "MILLISECONDS",
        "SECONDS",
        "MINUTES",
        "HOURS",
        "DAYS"
      ]
    },
    "minOutsideDurationTimeUnit": {
      "type": "string",
      "description": "Time unit for minimum outside duration.",
      "enum": [
        "MILLISECONDS",
        "SECONDS",
        "MINUTES",
        "HOURS",
        "DAYS"
      ]
    },
    "reportPresenceStatusOnEachMessage": {
      "type": "boolean",
      "description": "If true, report Inside/Outside on each message. If false, report only once after duration threshold is met."
    }
  },
  "additionalProperties": false
}

Message processing algorithm

Extract coordinates to check
The node retrieves latitude and longitude using the configured keys:
- First looks in the message data.
- If not found there, falls back to the message metadata.
  Both values must be present and parseable as decimal numbers. Otherwise, the message is routed via Failure.
Resolve the geofence (perimeter)
The geofence is determined in one of two ways:
- If Fetch perimeter information from metadata is disabled, the perimeter is built from static configuration fields.
- If enabled, the perimeter is loaded from the metadata key specified in Perimeter key name. If the metadata key is missing or contains an invalid value, the message is routed via Failure.
Check if point is inside the geofence
- For circle perimeters, the node calculates the geodesic distance between the point and the center. If the distance is less than the configured range, the point is considered inside.
- For polygon perimeters, the node checks if the point is located within the defined shape. If multiple polygons are provided, any containing polygon counts. Polygons fully enclosed by others are treated as holes.
Load entity state
The node loads the current geofencing state for the message originator from server-scope attributes. The state includes:
- inside — whether the entity was previously inside the geofence.
- stateSwitchTime — timestamp of the last state transition.
- stayed — whether the minimum duration threshold has been met.
  If no state exists, the node initializes a new state with inside=false, stateSwitchTime=0, and stayed=false.
Detect state transitions
The node compares the current geofence check result with the stored state. When a state change is detected (first message or entity crossing the boundary), the message is immediately routed via Entered or Left accordingly. The state is updated and persisted to server attributes with the new status and timestamp.
Handle messages with no state transition
When the entity remains in the same state (inside or outside), routing depends on the configured strategy:
- “On each message” strategy: Every message is routed via Inside or Outside based on the entity’s current location.
- “On first message” strategy: The node checks whether the configured minimum duration has elapsed. The first message after meeting the duration threshold is routed via Inside or Outside. All subsequent messages are routed via Success until the entity crosses the boundary again.

Output connections

Entered:
- The entity has just entered the geofence (transitioned from outside to inside).
- Triggered immediately on state transition, regardless of duration settings.
Left:
- The entity has just left the geofence (transitioned from inside to outside).
- Triggered immediately on state transition, regardless of duration settings.
Inside:
- The entity is currently inside the geofence and one of the following conditions is met:
  - “On each message” strategy: Every message while inside the geofence.
  - “On first message” strategy: The first message after the entity has stayed inside for at least minInsideDuration.
Outside:
- The entity is currently outside the geofence and one of the following conditions is met:
  - “On each message” strategy: Every message while outside the geofence.
  - “On first message” strategy: The first message after the entity has stayed outside for at least minOutsideDuration.
Success:
- Used when “On first message” strategy is enabled and:
  - The entity has not changed state (still inside or outside).
  - The duration threshold was already met in a previous message, so subsequent messages don’t need to be routed via Inside or Outside again.
Failure:
- Incoming data is not a JSON object.
- Latitude/longitude are missing in both data and metadata or not numeric.
- Fetch perimeter information from metadata is enabled but the perimeter definition is missing/invalid.
- Other unexpected error.

Examples

Example 1 — “On each message” strategy

State of the system

Entity is inside the geofence (entered 3 minutes ago).

Incoming message

Data:

{
  "latitude": 48.199,
  "longitude": 24.653
}

Node configuration

{
  "latitudeKeyName": "latitude",
  "longitudeKeyName": "longitude",
  "fetchPerimeterInfoFromMessageMetadata": false,
  "perimeterType": "CIRCLE",
  "centerLatitude": 48.1986,
  "centerLongitude": 24.6532,
  "range": 150.0,
  "rangeUnit": "METER",
  "minInsideDuration": 5,
  "minInsideDurationTimeUnit": "MINUTES",
  "minOutsideDuration": 5,
  "minOutsideDurationTimeUnit": "MINUTES",
  "reportPresenceStatusOnEachMessage": true
}

Result

Routed via Inside

Explanation

With “On each message” strategy enabled, every message while the entity is inside the geofence is routed via Inside, regardless of how long it has been there or whether the duration threshold was previously met.

Example 2 — “On first message” strategy