Trigger: Distance Between Objects (`distance_trigger`)¶

This trigger starts an automation when the distance between two GPS objects exceeds or falls below a configured threshold. It allows detecting if an object is moving too far from a reference point, or if it is dangerously approaching another object or location.

When to use it?¶

When you need to alert if a vehicle moves too far from its operations base or a checkpoint.
When you want to detect that a guard has separated from the group or their assigned zone.
When you need to trigger an action when two assets approach each other (e.g.: two vehicles that should not be in the same place).
When you want to notify the proximity of a vehicle or person to a fixed location (e.g.: a tracker mounted at a static reference point).
When you need to implement dynamic perimeters based on the actual distance between two GPS objects, rather than a static geographic zone.

If you need to detect entry/exit from a fixed geographic area drawn on the map, use Trigger: GPS Zone (Geofence).
If you need to react to a state change of an object, use Trigger: State Change.

How to configure it¶

Step 0) Open the parameters¶

In the automations canvas, double-click the Distance node.
A modal opens with two tabs: Form and JSON Editor. Stay on Form.

Step 1) Select the object to monitor¶

The Select object field defines which GPS object is moving and whose distance will be measured.

Click the text field to open the object selector.
Search by name or filter by domain using the modal controls.
Select one object from the table (single selection at a time).
The selected object's ID will appear as a tag below the field.
To change the object, close the tag and select a new one.

Examples: - Delivery-Truck-03 (logistics vehicle) - Night-Guard-John (person with personal tracker) - Inspection-Drone-01 (aerial asset)

This field is required.

Step 2) Select the reference object¶

The Select reference object field defines the fixed or moving point from which the distance is measured.

Click the text field to open the same object selector.
Select one object to act as the reference.
It can be any GPS object in the system: a fixed base, another vehicle, or an instrumented location.

Examples: - Central-Operations-Base (fixed tracker at headquarters) - North-Zone-Supervisor (supervisor's vehicle) - Access-Control-Point-A (fixed tracker at access gate)

This field is required.

Step 3) Choose the activation mode¶

The When moving away / When approaching selector defines which type of distance change fires the trigger.

Mode	When it fires	Field configured
When moving away	When the distance exceeds the configured value	`max_distance`
When approaching	When the distance falls below the configured value	`min_distance`

Only one of the two modes can be active at a time.

Step 4) Configure the threshold distance¶

The Distance field defines the value in meters that acts as the trigger threshold.

If the mode is When moving away: enter the maximum allowed distance. If the object exceeds it, the trigger fires.
If the mode is When approaching: enter the minimum proximity distance. If the object comes closer than that value, the trigger fires.

Mode	Recommended value	Usage example
Moving away	`500`	Alert if the vehicle moves more than 500 m from base
Approaching	`50`	Alert if two assets are less than 50 m apart

The value can be decimal (e.g. 250.5). The unit is meters.

Best practices¶

Set a realistic distance: very small thresholds (e.g.: 5 meters) can generate false positives due to GPS imprecision. For moving objects, use at least 30-50 meters.
Use a fixed reference object when possible: if the reference point is also moving, the calculated distance changes with both and can be harder to predict.
Combine with conditions: if the distance trigger fires at any time of day, you can add a Condition: Date/Time node afterwards to filter by schedule.
Avoid configuring the same pair of objects in multiple distance triggers with very close thresholds, as they could fire almost simultaneously and generate duplicate flows.
Consider GPS update frequency: if the tracker updates every 30 seconds, the trigger may take up to that interval to detect the distance change.

Troubleshooting (common issues)¶

The trigger doesn't fire even though the objects are far/close
Verify that both objects (object_id and ref_object) are actively sending GPS position updates.
Confirm that the IDs selected in the form correspond to the correct objects.
Check that the configured distance is consistent with the actual situation (convert your estimate to meters).
The trigger fires constantly
If the distance between objects oscillates around the threshold, the trigger can fire many times. Adjust the threshold so it is outside the normal oscillation range.
Consider adding a wait node or a cooldown in the flow to avoid repetitive triggers.
I can't find the object in the selector
Use the modal's search field to filter by name.
Filter by domain to narrow down the list.
Verify the object exists in the system and has active GPS.
I selected the wrong object
Click the "X" on the tag that appears below the field to deselect it, then reopen the modal to choose the correct one.
The node doesn't save changes
Make sure both fields (object_id and ref_object) are selected and the distance has a value greater than zero.

Advanced configuration (JSON Editor) — expert users only¶

The JSON Editor tab lets you view and directly edit the internal structure of the node. Useful for:

Copying configurations between flows or instances.
Pasting configurations prepared from another source.
Reviewing the exact state of the node.

`input` structure¶

{
  "ruleSet": {
    "object_id": "monitored-object-uuid",
    "ref_object": "reference-object-uuid",
    "max_distance": 500,
    "min_distance": 0
  },
  "config": {}
}

Field table¶

Field	Type	Required	Description
`ruleSet.object_id`	`string`	Yes	ID of the GPS object whose position is monitored
`ruleSet.ref_object`	`string`	Yes	ID of the GPS object acting as the reference point
`ruleSet.max_distance`	`number`	Conditional	Maximum distance in meters (moving away mode). If exceeded, trigger fires. Use `0` when not applicable.
`ruleSet.min_distance`	`number`	Conditional	Minimum distance in meters (approaching mode). If dropped below, trigger fires. Use `0` when not applicable.
`config`	`{}`	No	Always empty (reserved for future use)

Note: max_distance and min_distance are not mutually exclusive at the structure level, but in practice only one has a meaningful value depending on the mode chosen in the form. The other remains 0.

JSON examples by use case¶

Alert when vehicle moves more than 1 km from base¶

{
  "ruleSet": {
    "object_id": "delivery-truck-03-uuid",
    "ref_object": "central-operations-base-uuid",
    "max_distance": 1000,
    "min_distance": 0
  },
  "config": {}
}

Alert when two assets are less than 30 meters apart¶

{
  "ruleSet": {
    "object_id": "guard-shift-a-uuid",
    "ref_object": "guard-shift-b-uuid",
    "max_distance": 0,
    "min_distance": 30
  },
  "config": {}
}

Notify when delivery vehicle approaches within 200 m of the warehouse¶

{
  "ruleSet": {
    "object_id": "delivery-van-01-uuid",
    "ref_object": "north-warehouse-uuid",
    "max_distance": 0,
    "min_distance": 200
  },
  "config": {}
}

Quick guides (recipes)¶

Recipe A — "Alert if a vehicle leaves the headquarters radius"¶

Object: vehicle tracker to monitor (e.g.: Logistics-Truck-02)
Reference: fixed tracker at headquarters (e.g.: Logistics-Central-Base)
Mode: When moving away
Distance: 800 (800 meters)
Action: Telegram notification to control center

Recipe B — "Detect a guard moving too far from their partner"¶

Object: tracker of the moving guard (e.g.: North-Round-Guard)
Reference: tracker of the reference guard (e.g.: South-Base-Guard)
Mode: When moving away
Distance: 300 (300 meters)
Action: Send SMS alert to shift supervisor

Recipe C — "Notify supplier vehicle arrival at main access"¶

Object: supplier vehicle tracker (e.g.: Supplier-Supplies-01)
Reference: fixed tracker at access gate (e.g.: Main-Access-Gate)
Mode: When approaching
Distance: 150 (150 meters)
Action: Send notice to access operator / automatically open barrier

Recipe D — "Proximity alert between two vehicles in maneuvering area"¶

Object: first vehicle tracker (e.g.: Forklift-Zone-A)
Reference: second vehicle tracker (e.g.: Forklift-Zone-B)
Mode: When approaching
Distance: 20 (20 meters)
Action: Activate audible alert / notify plant supervisor

Recipe E — "Drone out of authorized area tracking"¶

Object: drone tracker (e.g.: Inspection-Drone-01)
Reference: tracker at launch base (e.g.: Drone-Base-Sector-3)
Mode: When moving away
Distance: 2000 (2 km)
Action: Notify drone operator / log event in audit log

Internal references (to locate it in the editor)¶

Node key: distance_trigger
Class: trigger
Required fields: object_id (mandatory), ref_object (mandatory)
Conditional fields: max_distance (moving away mode), min_distance (approaching mode)
Distance unit: meters
Supported object types: any object with active GPS position

Trigger: Distance Between Objects (distance_trigger)¶