Skip to main content

Geofence Processing

This guide explains how the geofence processing system works in the tracker application.

Overview​

The geofence processing system is responsible for updating the status of trackers based on their location history. When a tracker has been within a geofence (a defined geographical area) for a certain period of time, its status is updated accordingly.

Components​

The geofence processing system consists of the following components:

  1. Location Reports: Raw location data from trackers, stored in the location_reports table.
  2. Location History: Aggregated location data, stored in the location_history materialized view.
  3. Geofences: Defined geographical areas, stored in the storage_locations and delivery_locations tables.
  4. match_geofences() Function: A PostgreSQL function that processes the location history and updates tracker statuses.
  5. process_geofences.py Script: A Python script that calls the match_geofences() function periodically.

How It Works​

  1. Data Collection: Location reports are collected from trackers and stored in the location_reports table.
  2. Data Aggregation: The location reports are aggregated into the location_history materialized view using TimescaleDB continuous aggregates.
  3. Geofence Processing: The match_geofences() function is called periodically to process the location history and update tracker statuses.
  4. Status Updates: When a tracker has been within a geofence for a certain period of time (default: 12 hours), its status is updated accordingly:
    • If the tracker is within a storage location geofence, its status is updated to IN_STORAGE.
    • If the tracker is within a delivery location geofence, its status is updated to DELIVERED.
  5. Notifications: When a tracker's status changes, notifications are sent to users who have access to the tracker.

Configuration​

The geofence processing system can be configured in the following ways:

  1. Geofence Radius: The radius of the geofence is set to 200 meters by default. This can be changed in the match_geofences() function.
  2. Time Threshold: The time threshold for a status change is set to 12 hours by default. This can be changed in the match_geofences() function.
  3. Processing Frequency: The geofence processing script is run every hour by default. This can be changed in the cron job configuration.

Implementation Details​

Location History Materialized View​

The location_history materialized view is created from the location_history_hourly and location_history_daily continuous aggregates. It includes the following columns:

  • id: A unique identifier for the location history record.
  • timestamp: The timestamp of the location report.
  • location: The location of the tracker as a PostGIS geometry.
  • nearest_city: The nearest city to the location, if available.
  • tracker_id: The ID of the tracker.
  • confidence: The confidence level of the location report (0-100).

match_geofences() Function​

The match_geofences() function processes the location history and updates tracker statuses. It performs the following steps:

  1. Get all trackers with location history in the last 24 hours.
  2. For each tracker, get its production run ID and current status.
  3. Process each hour of data for the tracker.
  4. For each hour, find the location with the longest time in a storage location geofence.
  5. If a storage location is found and the time in the geofence is >= the threshold, update the tracker's status to IN_STORAGE.
  6. If no storage location is found, find the location with the longest time in a delivery location geofence.
  7. If a delivery location is found and the time in the geofence is >= the threshold, update the tracker's status to DELIVERED.
  8. When a tracker's status changes, add a status history entry and send notifications to users.

process_geofences.py Script​

The process_geofences.py script calls the match_geofences() function periodically. It performs the following steps:

  1. Connect to the database.
  2. Call the match_geofences() function.
  3. Log the result of the operation.

Deployment​

The geofence processing system can be deployed in the following ways:

  1. Systemd Service: The systemd/geofence-processing.service file can be used to create a systemd service that runs the geofence processing script periodically. See Systemd Services for more details.
  2. Cron Job: The cron_geofence_processing.txt file contains a cron job configuration that runs the geofence processing script every hour.

Troubleshooting​

If the geofence processing system is not working as expected, check the following:

  1. Location Reports: Make sure that location reports are being collected and stored in the location_reports table.
  2. Location History: Make sure that the location_history materialized view is being updated with the latest location data.
  3. Geofences: Make sure that the geofences are defined correctly in the storage_locations and delivery_locations tables.
  4. match_geofences() Function: Make sure that the match_geofences() function is working correctly by running it manually.
  5. process_geofences.py Script: Make sure that the process_geofences.py script is being run periodically by checking the logs.