GPS Geofence Trigger

The Geofence trigger fires an automation rule the moment a tracked device enters or exits a circular boundary you draw on a map. It works with any device that sends GPS location data to VWire — the mobile app, an ESP32 with a GPS module, a vehicle tracker, or anything else.

WHEN  device location crosses the geofence boundary
IF    [optional conditions]
THEN  send notification / set pin / call webhook / ...

Common uses:

Arrival/departure alerts — know when a vehicle arrives at a depot, or when a child leaves a safe area
Asset theft detection — trigger an alarm if equipment is moved outside a worksite
Automated control — unlock a gate, activate a sensor, or log an entry event when a device enters a zone
Field worker tracking — know when a technician reaches a job site

How It Works

Every time a device sends a location pin update (CSV: lat,lng,...), the server:

Computes the distance between the new position and the geofence centre using the Haversine formula
Compares the distance to your configured radius
Checks the previous state (inside or outside) stored in memory
If the state changed — that is, the device crossed the boundary — and the crossing matches your event type (enter, exit, or both), the rule fires

The rule only fires on state transitions, not on every update. If the device is already inside the zone and sends 100 more GPS pings while staying inside, the rule fires zero additional times — until it exits and optionally re-enters.

Device update 1: outside  → no previous state → record as "outside"
Device update 2: outside  → still outside     → no fire
Device update 3: inside   → crossed IN        → 🔥 FIRE (if event = ENTER or BOTH)
Device update 4: inside   → still inside      → no fire
Device update 5: outside  → crossed OUT       → 🔥 FIRE (if event = EXIT or BOTH)

Devices That Support Geofencing

Any device that publishes a location value to a VWire pin in the standard CSV format works automatically:

lat,lng[,speed,altitude,heading,accuracy]

The extra fields (speed, altitude, etc.) are optional. Only lat and lng are required.

Device type	How it sends location data
VWire mobile app (Android)	Native background location service posts to your chosen pin automatically while tracking is active
ESP32 / Arduino + GPS module	Your firmware reads the GPS and publishes `lat,lng` via MQTT on any virtual pin
External GPS tracker	Use the External REST API to `PUT` a location string to a pin
Python script / server	Use the Python library to write a location string to a pin

Setting Up a Geofence Rule

Step 1 — Open the Automation Wizard

In the dashboard, click Automations (⚡) in the left sidebar, then click New Rule.

Step 2 — Basics

Fill in a rule name and select the project that contains your target device. For example: Workshop Exit Alert.

Step 3 — Trigger: Geofence

On the Trigger step, select GPS Geofence — location enters/exits boundary.

Four settings appear:

Device (sends GPS data)

Select the device whose location pin you want to watch. Only devices associated with the selected project are shown.

Location Pin

Select the pin that receives the lat,lng GPS value. For the mobile app this is typically V0 (the default location pin). For hardware GPS devices it is whatever pin your firmware publishes to.

Finding the right pin

Open your device detail page and look at the Live Pins panel. The GPS pin will show a value like 24.87432,67.01524,0.3,12.1,270.0,4.5 — that is the pin to select.

Fire when device

Option	When the rule fires
Enters the zone	Device moves from outside the circle to inside
Exits the zone	Device moves from inside the circle to outside
Either enters or exits	Both entry and exit crossings fire the rule

Radius

Use the slider or the number input to set the geofence radius in metres (50 m to 50 km). The circle on the map updates in real time as you drag.

Small radius (50–200 m): Precise entry point (gate, parking bay, building entrance)
Medium radius (200 m–2 km): Neighbourhood or campus
Large radius (2–50 km): City-level zone or region

Placing the Zone Centre

Click anywhere on the map to place the geofence centre. A blue circle shows the zone at your chosen radius. You can click again to reposition it.

The current centre coordinates are shown below the map in lat, lng format for your reference.

note

You must click the map to set a centre before you can proceed. The Next button stays disabled until a centre is placed and a device + pin are selected.

Step 4 — Conditions (optional)

Add conditions to add extra filtering on top of the boundary crossing. For example:

Only fire during business hours → combine with an Active Time Window in Step 5 (Options)
Only fire if a sensor value is above a threshold → add a condition on a different pin

Most geofence rules work well with no conditions at all.

Step 5 — Actions

Choose what happens when the boundary is crossed. Any action type works:

Action	Typical geofence use
Send Notification	"Vehicle has entered the depot"
Send Alarm	Persistent alarm when asset leaves authorised zone
Set Pin	Activate a relay, light, or lock on the device
Call Webhook	Log the event in an external system
Send Email	Notify a manager when a device arrives

Using Geofence Variables in Messages

When a geofence rule fires, two special variables are available for use inside notification, alarm, and email messages:

Variable	Value
`{{geofence_event}}`	`entered` or `exited`
`{{distance_m}}`	Distance from the zone centre in metres at time of crossing

Example notification message:

Vehicle has {{geofence_event}} the depot zone ({{distance_m}} m from centre).

This renders as:

Vehicle has entered the depot zone (48 m from centre).

You can also use standard pin template variables. The trigger device's location pin value is available as {{VW-XXXXX:V0}} (replace with your Device ID and pin).

Step 6 — Options

Cooldown

Set a cooldown period to prevent repeated firing if a device oscillates near the boundary.

Recommended cooldown for geofences

Set cooldown to at least 60–120 seconds for real-world GPS scenarios. GPS accuracy can cause a device to drift in and out of the boundary, which would otherwise fire the rule multiple times in quick succession.

Active Time Window and Days

Restrict geofence firing to business hours, weekdays only, etc. This is useful for overnight or weekend absence alerts.

If your project has a Map Widget configured for the same device and pin, active geofence rules are automatically drawn as overlay circles directly on the map:

Circle colour	Meaning
🟢 Green	Enter-only zone
🔴 Red	Exit-only zone
🔵 Blue	Both enter and exit

Click the circle on the map to see a popup with the rule name, event type, and radius.

This overlay is read-only — to edit the zone, open the rule in the Automations page.

Background Tracking on Mobile

The VWire mobile app on Android sends location data from a native foreground service that runs independently of the WebView. This means:

Location updates are sent even when the app is minimised or in the background
Location updates are sent even when the screen is locked (in regular Android battery modes)
The service announces itself via a persistent notification (required by Android for foreground services)

Battery optimisation

Android aggressive battery modes (e.g. "Extreme battery saver", some manufacturer-specific restrictions) can kill background services. If tracking stops unexpectedly, check the app's battery settings and set it to Unrestricted / Not optimised.

iOS

The native background foreground service is available on Android only. On iOS, the app uses browser geolocation while the app is in the foreground. The geofence evaluation still happens server-side — you just need to keep the app open for continuous tracking on iOS.

Hardware GPS Devices

For ESP32 or Arduino boards connected to a GPS module (e.g. NEO-6M, NEO-8M):

Arduino / ESP8266 / ESP32
Python (Raspberry Pi / Linux)
External API (any language)

#include <VwireIOT.h>
#include <TinyGPSPlus.h>
#include <SoftwareSerial.h>

SoftwareSerial gpsSerial(4, 3); // RX, TX
TinyGPSPlus gps;
VwireIOT Blynk;

void setup() {
  Blynk.begin("your-auth-token", "your-wifi-ssid", "your-wifi-password");
  gpsSerial.begin(9600);
}

void loop() {
  // Feed GPS data
  while (gpsSerial.available()) {
    gps.encode(gpsSerial.read());
  }

  // Send location every 5 seconds when fix is valid
  if (gps.location.isValid() && gps.location.isUpdated()) {
    String location = String(gps.location.lat(), 6) + "," +
                      String(gps.location.lng(), 6) + "," +
                      String(gps.speed.mps(), 1) + "," +
                      String(gps.altitude.meters(), 1);

    Blynk.virtualWrite(V0, location);
  }

  Blynk.run();
  delay(5000);
}

import vwire
import serial
import pynmea2
import time

vw = vwire.VwireClient(auth_token="your-auth-token")

gps_port = serial.Serial('/dev/ttyAMA0', 9600, timeout=1)

while True:
    line = gps_port.readline().decode('ascii', errors='replace')
    try:
        msg = pynmea2.parse(line)
        if hasattr(msg, 'latitude') and msg.latitude:
            location = f"{msg.latitude:.6f},{msg.longitude:.6f}"
            vw.write_pin("V0", location)
    except pynmea2.ParseError:
        pass
    time.sleep(5)

PUT /external/api/v1/devices/{deviceId}/pins/V0
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "value": "24.874320,67.012540,0.0,5.2"
}

See the External REST API for authentication and full endpoint reference.

Example: Vehicle Depot Alert

Scenario: A fleet manager wants a notification when a company vehicle arrives at the main depot and another when it leaves.

Config item	Value
Trigger	GPS Geofence
Device	`Fleet Tracker Unit 3`
Location Pin	`V0`
Fire when	Either enters or exits
Radius	`150 m`
Centre	Click on the depot location on the map
Action	Send Notification
Message	`Truck Unit 3 has {{geofence_event}} the depot ({{distance_m}} m from gate).`
Cooldown	`120 seconds`

This produces notifications like:

Truck Unit 3 has entered the depot (67 m from gate).
Truck Unit 3 has exited the depot (112 m from gate).

Example: Child Safety Zone

Scenario: Parents want an alarm if their child's phone leaves the school grounds during school hours.

Config item	Value
Trigger	GPS Geofence
Device	`Child's Phone` (mobile app tracking)
Location Pin	`V0`
Fire when	Exits the zone
Radius	`300 m`
Centre	Click on the school on the map
Action	Send Alarm — Priority `3 — Critical`
Message	`⚠️ Child has left the school zone!`
Cooldown	`300 seconds`
Active days	Mon–Fri only
Active time	`08:00 – 16:00`

Troubleshooting

The rule doesn't fire when the device crosses the boundary

Check location data is arriving. Open the device detail page → Live Pins panel. The selected pin should be updating with lat,lng values as the device moves. If no updates are visible, the device isn't sending location data.
Check the pin matches. The pin selected in the geofence rule must exactly match the pin receiving location data on the device.
Check the rule is enabled and ACTIVE. On the Automations page, the rule card must show a green "ACTIVE" status. An amber "PAUSED" or red "ERROR" status means the rule won't fire.
Check the cooldown. If the rule fired recently, it will be suppressed until the cooldown expires. The Last triggered time is shown on the rule card.
Check the radius. The map widget shows the geofence circle. Confirm the device marker is visually crossing the boundary when you expect it to.
Check the active time window. If you set an active time window, ensure the current time (in the rule's timezone) falls within it.

GPS accuracy is causing the rule to fire repeatedly

If the device GPS occasionally drifts just outside the boundary and back in, the rule fires on each crossing. Fix this by:

Increasing the radius slightly — 10–20% larger than the area you want to monitor reduces edge-case drift crossings
Increasing the cooldown — a 60–120 second cooldown suppresses rapid re-crossings
Both together work best for indoor/urban environments where GPS accuracy is lower

The zone circle is only shown if:

The Map Widget is configured for the same device and pin as the geofence rule
The geofence rule is enabled and in ACTIVE status

If the Map Widget shows the device location but no circle, open the Automations page and confirm the rule's device + pin match the widget's device + pin exactly.

Summary

Feature	Detail
Shape	Circle (single centre point + radius)
Radius range	50 m – 50 km
Event types	Enter, Exit, or Both
Location format	`lat,lng` or `lat,lng,speed,altitude,heading,accuracy`
Firing behaviour	Transition-based — fires once per crossing, not on every update
State storage	Server-side Redis — survives replica restarts
Cooldown	Shared with all other rule trigger types (30 s minimum)
Works in background	Yes (Android native service); foreground only on iOS/web
Works for hardware devices	Yes — any device publishing lat,lng CSV to a pin
Map Widget overlay	Yes — colour-coded circles (green/red/blue)
Available plans	All plans (Free, Pro, Pro Plus, Enterprise)

GPS Geofence Trigger

How It Works

Devices That Support Geofencing

Setting Up a Geofence Rule

Step 1 — Open the Automation Wizard

Step 2 — Basics

Step 3 — Trigger: Geofence

Device (sends GPS data)

Location Pin

Fire when device

Radius

Placing the Zone Centre

Step 4 — Conditions (optional)

Step 5 — Actions

Using Geofence Variables in Messages

Step 6 — Options

Cooldown

Active Time Window and Days

Visualising the Zone on the Map Widget

Background Tracking on Mobile

Hardware GPS Devices

Example: Vehicle Depot Alert

Example: Child Safety Zone

Troubleshooting

The rule doesn't fire when the device crosses the boundary

GPS accuracy is causing the rule to fire repeatedly

The zone overlay doesn't appear on the Map Widget

Summary

How It Works​

Devices That Support Geofencing​

Setting Up a Geofence Rule​

Step 1 — Open the Automation Wizard​

Step 2 — Basics​

Step 3 — Trigger: Geofence​

Device (sends GPS data)​

Location Pin​

Fire when device​

Radius​

Placing the Zone Centre​

Step 4 — Conditions (optional)​

Step 5 — Actions​

Using Geofence Variables in Messages​

Step 6 — Options​

Cooldown​

Active Time Window and Days​

Visualising the Zone on the Map Widget​

Background Tracking on Mobile​

Hardware GPS Devices​

Example: Vehicle Depot Alert​

Example: Child Safety Zone​

Troubleshooting​

The rule doesn't fire when the device crosses the boundary​

GPS accuracy is causing the rule to fire repeatedly​

The zone overlay doesn't appear on the Map Widget​

Summary​

How It Works

Devices That Support Geofencing

Setting Up a Geofence Rule

Step 1 — Open the Automation Wizard

Step 2 — Basics

Step 3 — Trigger: Geofence

Device (sends GPS data)

Location Pin

Fire when device

Radius

Placing the Zone Centre

Step 4 — Conditions (optional)

Step 5 — Actions

Using Geofence Variables in Messages

Step 6 — Options

Cooldown

Active Time Window and Days

Visualising the Zone on the Map Widget

Background Tracking on Mobile

Hardware GPS Devices

Example: Vehicle Depot Alert

Example: Child Safety Zone

Troubleshooting

The rule doesn't fire when the device crosses the boundary

GPS accuracy is causing the rule to fire repeatedly

The zone overlay doesn't appear on the Map Widget

Summary