Vehicle Telemetry & Tracking

Vehicle telemetry is the real-time data stream from your fleet's IoT devices. This guide covers how telemetry works, what data is available, and how to use it for fleet management.

What is Vehicle Telemetry?

Telemetry refers to the automated collection and transmission of data from your vehicles to the Levy Fleets platform. Each vehicle's IoT device continuously reports:

• Location - GPS coordinates
• Battery levels - Both vehicle and IoT battery
• Lock state - Whether the vehicle is locked or unlocked
• Motion status - Moving or stationary
• Speed - Current velocity
• Odometer - Total distance traveled
• Error codes - Any device or vehicle faults
• Signal strength - Cellular connectivity quality

How Telemetry Works

Data Flow

Vehicle IoT Device → Cellular Network → Levy Servers → Dashboard
        ↓                                      ↓
    Sends data                          Stores & processes
    every 10-60s                        Updates in real-time

Update Frequency

Telemetry update intervals vary by device type and state:

Viewing Telemetry Data

Vehicle List View

The vehicle list shows key telemetry at a glance:

Vehicle Detail Page

The detail page provides comprehensive telemetry:

Status & Telemetry Card:

• Vehicle battery percentage with color coding
• IoT battery percentage (separate from vehicle battery)
• Charging indicator
• Lock/unlock status
• Current GPS coordinates with timestamp
• Signal strength indicator
• Error codes (if any)

Location Map:

• Current position marker
• Historical location trail
• Zone overlays

Real-Time Updates

Telemetry updates automatically via WebSocket subscriptions:

1. When you open a vehicle detail page, a subscription is created
2. New telemetry pushes to your browser instantly
3. Status badges, battery levels, and location update without refresh
4. Leaving the page closes the subscription

GPS Tracking

Location Data

Each GPS update includes:

Location Accuracy

GPS accuracy varies by conditions:

Historical Tracking

View where a vehicle has been:

1. Open the vehicle detail page
2. View the location map
3. Historical breadcrumb trail shows recent positions
4. Hover over points to see timestamps

Battery Monitoring

Two Battery Types

Most vehicles report two battery levels:

Battery Level Indicators

Color coding helps quickly assess battery health:

Charging Detection

The is_charging field indicates when a vehicle is plugged in:

• Shows charging icon on vehicle list
• Useful for tracking charging station usage
• Helps verify chargers are working

Lock State Monitoring

Lock Status

Vehicles report their current lock state:

Lock/Unlock Events

Every lock state change is logged:

• Who initiated the change (customer, staff, system)
• Timestamp of the change
• Command success/failure
• Useful for auditing and troubleshooting

Signal & Connectivity

Cellular Signal

Telemetry includes signal quality indicators:

Last Signal Time

The "Last Signal" timestamp shows when the device last communicated:

Error Codes

Understanding Error Codes

IoT devices report error codes when issues occur:

Viewing Errors

Errors appear in:

• Vehicle detail page (Status section)
• Recent telemetry feed
• Alert notifications (if configured)

Common Error Codes

Telemetry Feed

Raw Telemetry View

On the vehicle detail page, expand "Show Commands" to see raw telemetry:

• Last 30 messages displayed
• Click entries to expand full payload
• Copy raw data for debugging
• Message types indicated (status, heartbeat, ack)

Message Types

Using Telemetry for Fleet Management

Finding Low Battery Vehicles

1. Go to Vehicles page
2. Click More Filters
3. Set Battery Level (Max %) to 20
4. View all vehicles needing charging

Locating Offline Vehicles

1. Click the Offline status card
2. Review last known locations
3. Check last signal timestamps
4. Prioritize investigation by duration offline

Monitoring Active Rides

During a ride, telemetry shows:

• Real-time location updates
• Speed monitoring
• Battery drain rate
• Distance traveled

Detecting Anomalies

Watch for unusual patterns:

• Sudden location jumps (GPS glitch or transport)
• Rapid battery drain (potential issue)
• Extended periods without movement (may be abandoned)
• Lock state not matching expected (command failure)

Telemetry Storage

Data Retention

Telemetry data is stored for:

Accessing Historical Data

• Vehicle detail page shows recent history
• Export via API for longer analysis
• Ride detail pages include ride-specific telemetry

API Access

Get Vehicle Telemetry

GET /api/vehicles/{id}

Returns current telemetry state:

{
  "id": "vehicle-uuid",
  "vehicle_number": "VH-001",
  "battery_level": 85,
  "iot_battery_pct": 92,
  "is_charging": false,
  "lock_status": "locked",
  "latitude": 40.7128,
  "longitude": -74.0060,
  "last_location_update": "2025-01-15T12:30:00Z",
  "vehicle_odometer": "1234.5",
  "gps_signal": 4,
  "error_code": null
}

Subscribe to Real-Time Updates

Use Supabase real-time subscriptions:

const subscription = supabase
  .channel('vehicle-telemetry')
  .on('postgres_changes',
    { event: 'UPDATE', schema: 'public', table: 'vehicles', filter: `id=eq.${vehicleId}` },
    (payload) => {
      console.log('Telemetry update:', payload.new)
    }
  )
  .subscribe()

Troubleshooting

No Telemetry Updates

1. Check vehicle battery level (may be dead)
2. Verify IoT device is properly linked
3. Check cellular coverage in vehicle location
4. Review last known position for clues
5. May need physical inspection

Inaccurate GPS

1. Check GPS accuracy field in telemetry
2. Vehicle may be indoors or in poor coverage
3. Allow time for GPS fix after device wake
4. Check for antenna issues on device

Battery Reading Incorrect

1. Compare vehicle vs IoT battery readings
2. Check if charging indicator matches reality
3. Battery calibration may be needed
4. Check for battery connection issues

Delayed Updates

1. Verify cellular signal strength
2. Check if device is in sleep mode
3. Review IoT device configuration
4. May indicate network congestion

---