# FleetLume Trip Monitoring v9

## Purpose

Trip Monitoring watches active dispatch routes and border-crossing schedules using FleetLume browser GPS or mapped Motive, Samsara, Geotab, and generic telematics data. When a truck deviates from its route, is projected to arrive late, misses a crossing time, remains at a crossing too long, or the driver reports a hurdle, FleetLume creates one shared operational exception and notifies the assigned driver plus owners, administrators, and dispatchers.

## Automatic route-deviation detection

FleetLume compares the truck’s latest coordinates with the latitude and longitude stored on the route waypoints.

- A deviation starts only after the truck remains outside the configured route corridor for the confirmation period.
- The default deviation corridor is 5 miles.
- The default confirmation period is 10 minutes.
- A larger deviation is escalated from High to Critical.
- Duplicate alerts are not created while the same exception remains active.
- If an active alert becomes more severe, FleetLume reopens it and sends an escalation notification.
- When the truck returns inside the recovery corridor, the alert closes automatically and the driver and dispatch team receive a recovery notification.

A route needs at least two geocoded waypoints before automatic deviation checks can calculate a corridor.

## Border-crossing monitoring

Each crossing can define:

- Planned arrival date and time
- Arrival grace period
- Expected stop duration
- Border latitude and longitude
- Geofence radius

FleetLume checks for:

1. **Projected late arrival** — latest truck position and speed indicate the crossing window may be missed.
2. **Missed crossing check-in** — the planned time plus arrival grace has passed and the driver has not moved the crossing into an arrived status.
3. **Border stop overrun** — elapsed time after arrival or queue start exceeds the expected stop time plus the company stop grace.

Arrival and missed alerts close when the driver is marked arrived. Stop-overrun alerts close when the crossing is cleared, crossed, cancelled, rejected/returned, or manually resolved.

## Driver hurdle reporting

On an assigned load, drivers have a **Report a Hurdle** panel with GPS capture and these categories:

- Heavy traffic
- Severe weather
- Road closure or detour
- Truck breakdown
- Roadside inspection
- Accident or safety event
- Border delay
- Parking or rest-area issue
- Shipper delay
- Receiver delay
- Other

The driver enters an estimated delay and a short description. FleetLume immediately creates an exception, marks the route as an exception where applicable, confirms the report to the driver, and notifies owners, administrators, and dispatchers. The driver can later mark their own hurdle cleared.

## Dispatcher and administrator workflow

Open **Dispatch → Trip Alerts** to:

- See active and critical exception totals
- Review route deviations, border delays, and driver hurdles
- Open the related load or crossing
- View distance outside the route or delay minutes
- Acknowledge an alert
- Add a resolution note and resolve it
- Review the resolved-alert audit trail
- Run a monitoring check manually

The live truck map also includes active trip-alert counts in its operational-risk indicators.

## Notifications

Alerts are written to FleetLume’s notification center for the assigned driver and all active owner, administrator, and dispatcher users.

While FleetLume is open, the browser checks for new notifications every 20 seconds and displays a live alert prompt. Users can enable browser/device notifications from the Notifications page. Device alerts depend on browser permission and are not a replacement for a dedicated SMS or mobile push provider.

## Settings

Owners and administrators can configure these values under **Company Settings**:

- Automatic Trip Monitoring
- Route deviation corridor
- Route recovery corridor
- Route deviation confirmation time
- Default border arrival grace
- Default border expected stop time
- Border stop overrun grace
- Border ETA calculation speed

Individual border crossings can override arrival grace and expected stop time.

## Automation schedule

Use the existing unified runner every minute:

```cron
* * * * * /usr/bin/php /absolute/path/to/fleetlume/operations_autopilot.php >> /absolute/path/to/fleetlume/storage/operations-autopilot.log 2>&1
```

The runner synchronizes due telematics connections first, then performs the trip-monitoring checks using the newest location data.

## Production checklist

1. Back up the database and application.
2. Upload the v9 package.
3. Run `/install.php?unlock=1` with the current database credentials.
4. Confirm the unified cron runner is active.
5. Add coordinates to route waypoints and border crossings.
6. Test with a staging truck and driver account.
7. Confirm driver, dispatcher, admin, and owner users receive the expected notifications.
8. Tune thresholds to match the carrier’s operating area and dispatch policy.