Logistics Tracking Controller

Overview

The Logistics Tracking Controller manages trip-level operational metrics for vehicle logistics tracking. It calculates and updates key performance data such as:

Trip start and end timestamps
Actual travel distance
Vehicle odometer readings
Fuel consumption
Trip mileage

This controller integrates with vehicle telemetry systems to retrieve accurate operational metrics and update the Logistics Tracking document.

Main API Method

update_trip_metrics()

@frappe.whitelist()
def update_trip_metrics(tracking_id)

Purpose

Updates all trip metrics for a Logistics Tracking record.

Workflow

Fetch Logistics Tracking Document
        ↓
Update Actual Trip Timestamps
        ↓
Calculate Trip Window
        ↓
Fetch Distance Metrics
        ↓
Update Odometer Values
        ↓
Calculate Fuel Consumption
        ↓
Calculate Trip Mileage
        ↓
Save Document

Trip Window Calculation

Function

_get_trip_window(doc)

Purpose

Determines the telemetry data time window used for trip metric calculations.

Logic

Start time = actual_start_time - 1 minute
End time = actual_end_time + 1 minute

This ensures telemetry records immediately before and after the trip are included.

Actual Timestamp Update

Function

_update_actual_timestamps(doc)

Updates trip timestamps using logistics tracking log entries.

Status Mapping

Vehicle Status	Updated Field
Trip Started	actual_start_time
At Delivery	actual_end_time
Parking	actual_time_in_safe_zone

Distance Metrics

Function

_update_distance_metrics(doc, from_date, to_date)

Purpose

Fetches the actual trip distance between pickup and destination using the telemetry provider API.

Data Source

get_distance_value()

Updated Field

actual_distance_from_pickup_to_destination

Odometer Metrics

Function

_update_odometer_values(doc, vehicle_id)

Updates odometer values for the trip.

Two Data Sources

Telematics API (preferred)
Tracking logs fallback

Odometer from Telematics

_update_odometer_from_intangles(doc)

Retrieves odometer values using the telematics connector API.

Fields Updated

trip_start_odometer
trip_end_odometer
trip_odometer_in_safe_zone

Odometer from Tracking Logs

_update_odometer_from_logs(doc)

Fallback method when telematics API is not available.

Distance Calculation

actual_distance = trip_end_odometer - trip_start_odometer

Safe Zone Distance

distance_safe_zone = trip_odometer_in_safe_zone - trip_end_odometer

Fuel Metrics

Function

_update_fuel_and_mileage(doc, vehicle_id)

Calculates trip fuel consumption and vehicle mileage.

Two Methods

Telematics fuel data
Fuel sensor logs

Fuel Calculation from Telematics

update_fuel_metrics_for_intangles()

Data Source

get_fuel_value()

Fields Updated

trip_fuel_consumption
trip_mileage

Mileage Formula

Mileage = Distance / Fuel Consumed

Fuel Calculation from Sensors

_calculate_fuel(curr, prev, estimated_per_km)

Calculates fuel usage based on fuel tank sensor values.

Fuel Tanks Supported

Primary Tank
Secondary Tank

Logic

If fuel level decreases → consumption detected
If fuel increases → refill detected

Refill Handling

If refill is detected, fuel consumption is estimated using distance traveled.

Estimated Fuel Consumption

Function

_get_estimated_fuel_per_km()

Determines estimated fuel consumption when direct values are unavailable.

Priority Order

Latest tracking log values
Previous trip metrics
Average historical vehicle data

Historical Average Calculation

get_avg_estimated_value_from_other_doc()

Calculates fuel consumption using data from previous trips of the same vehicle.

Trip Mileage Finalization

Function

_finalize_trip_mileage()

Finalizes overall trip mileage after fuel consumption is calculated.

Formula

Trip Mileage = Total Distance / Total Fuel Consumption

Fields Updated

trip_mileage
trip_fuel_consumption

System Architecture Flow

Tracking Logs
       ↓
Trip Timestamp Detection
       ↓
Telemetry Distance API
       ↓
Odometer Data Collection
       ↓
Fuel Consumption Calculation
       ↓
Trip Mileage Calculation
       ↓
Logistics Tracking Document Update

Key Benefits

Automated trip metric calculation
Integration with vehicle telematics
Accurate distance and fuel monitoring
Fallback mechanisms for missing telemetry data
Improved logistics performance analytics

Conclusion

The Logistics Tracking Controller provides a centralized mechanism for calculating operational metrics for vehicle trips. By combining telemetry data, tracking logs, and historical data, the system ensures reliable trip analytics and performance monitoring.