Logistics Tracking Engine

Overview

The Logistics Tracking Engine manages real-time vehicle trip monitoring, telemetry processing, route validation, and logistics event detection.

It processes telemetry data from vehicle tracking providers and automatically determines key trip events such as:

Trip Start
Vehicle Stoppage
Route Deviation
Arrival at Delivery Location
Delivery Completion
Parking Detection

This system enables automated logistics monitoring and operational visibility for fleet management.

Purpose

The Logistics Tracking module is designed to:

Monitor vehicle trips using GPS telemetry.
Detect logistics events automatically.
Compare vehicle movement with the planned route.
Track delivery status and trip progress.
Generate alerts when operational events occur.

Core Component

LogisticsTracking DocType Controller

class LogisticsTracking(Document)

This class manages the lifecycle of the Logistics Tracking document and controls the complete trip monitoring process.

Main Responsibilities

Trip validation
Tracking link generation
Route path generation
Telemetry processing
Event detection
Trip summary updates

Document Lifecycle Events

Validate Event

def validate(self)

Executed before the document is saved.

Operations Performed

Validates pickup and delivery locations
Generates tracking link if missing
Sets default values for missing fields
Sorts tracking logs
Updates tracking summary
Calculates delivery delay

Update Event

def on_update(self)

Executed whenever the document is updated.

This function checks if route coordinates have changed and regenerates the route path if required.

Tracking Link Generation

Function

generate_tracking_link_if_missing()

Purpose

Automatically generates a public tracking URL for sharing vehicle tracking information externally.

Example Tracking URL

https://domain.com/track/<tracking_id>

Workflow

Generate a unique tracking ID.
Create a public tracking link.
Set link expiry based on system configuration.

Route Path Generation

Function

handle_route_path_updates()

Fetches route path data from a routing service and stores it in the Logistics Tracking document.

Process

Detect coordinate changes.
Fetch route from routing API.
Store route geometry.
Simplify route points.

Route Simplification

simplify_route_points()

Uses the Douglas-Peucker algorithm to reduce unnecessary route points and improve performance.

Benefits

Optimizes route comparison
Improves deviation detection performance
Reduces storage size

Telemetry Processing

Telemetry data is received from vehicle tracking providers and processed in background jobs.

Background Job

update_logistics_tracking_bg()

Workflow

Fetch Logistics Tracking Document
        ↓
Fetch Route Path
        ↓
Get Telemetry Data
        ↓
Process Telemetry Events
        ↓
Update Tracking Logs
        ↓
Trigger Alerts

Telemetry Event Processing

Main Function

process_telemetry_bulk()

Processes incoming telemetry data and detects operational logistics events.

Detected Event Types

1. Trip Started

Triggered when the vehicle enters the pickup geofence.

Trip status changes from Not Started to Started.
A tracking log entry is created.

2. Stoppage Detection

Detected when the vehicle speed falls below the defined threshold.

Condition

Speed ≤ SPEED_THRESHOLD

If stoppage continues longer than the configured threshold, a stoppage event is recorded.

3. Route Deviation Detection

Triggered when the vehicle moves outside the defined route corridor.

Condition

Distance from planned route ≥ DEVIATION_THRESHOLD

Deviation details such as start location, end location, and duration are stored.

4. Delivery Arrival

Detected when the vehicle enters the delivery location geofence.

Vehicle status is updated to At Delivery.

5. Delivery Completion

Triggered when the vehicle leaves the delivery geofence after the required dwell time.

Vehicle status becomes Delivered.

6. Parking Detection

Detected after delivery when the vehicle reaches the parking location.

Two states exist:

In Parking – vehicle enters parking area
Parking – vehicle stays parked for configured duration

Geofence Detection

Function

is_near_location()

Determines whether the vehicle is within the defined geofence radius of a location.

Logic

Calculate distance between vehicle and location coordinates.
If distance ≤ geofence radius, location is considered reached.

Distance Calculation

Distances between coordinates are calculated using geodesic distance.

Library Used

geopy.distance.geodesic

This ensures accurate geographic distance measurement.

Trip Status Flow

Not Started
     ↓
Started
     ↓
At Delivery
     ↓
Delivered
     ↓
Completed

Delivery Delay Calculation

Function

update_delivery_delay()

Compares expected trip duration with actual trip duration.

Condition

Actual Duration > Expected Duration

If true, the trip is marked as Delayed.

Alert Triggering

After telemetry processing, alerts may be triggered for important logistics events.

Examples

Route deviation
Long vehicle stoppage
Delivery delay

Threshold Configuration

System thresholds are fetched from logistics configuration settings.

Threshold	Purpose
LINK_EXPIRY_THRESHOLD	Tracking link expiry duration
SPEED_THRESHOLD	Vehicle stoppage detection
STOP_THRESHOLD_SEC	Minimum stoppage duration
DEVIATION_THRESHOLD_M	Route deviation detection
PICKUP_THRESHOLD_M	Pickup geofence radius
DESTINATION_THRESHOLD_M	Delivery geofence radius

System Architecture Flow

Vehicle Telemetry
       ↓
Telemetry Provider API
       ↓
Logistics Tracking Background Job
       ↓
Telemetry Processing Engine
       ↓
Tracking Log Creation
       ↓
Trip Status Updates
       ↓
Alert System

Benefits

Automated vehicle trip monitoring
Real-time logistics visibility
Accurate route deviation detection
Delivery tracking automation
Integrated alerting system
Operational analytics support

Conclusion

The Logistics Tracking Engine forms the core of the logistics monitoring system, enabling real-time fleet tracking, event detection, and operational alerts.

By processing telemetry data and comparing it with planned routes, the system ensures accurate trip monitoring and improved logistics management.