fleet-telemetry-engine

A lightweight, provider-agnostic telemetry intelligence engine for JavaScript & TypeScript applications.

fleet-telemetry-engine converts raw GPS and telematics data from any hardware device or API provider into standardized fleet intelligence, analytics, driver scores, vehicle health indicators, and real-time anomaly alerts.

Key Features

• Provider Agnostic: Normalizes inconsistent telemetry payloads from any provider (Teltonika, Queclink, Concox, custom APIs) into one standard format.
• Trip Analytics: Calculates accurate trip distance (Haversine & Odometer fallback), trip duration, driving vs. idle time, stopped minutes, average speed, max speed, and stop counts.
• Fuel Intelligence & Theft Anomaly Engine:
  • Calculates fuel consumption (litres / %), fuel efficiency (km/L and L/100km).
  • Detects sudden fuel drop anomalies (fuel theft/leakage) while stationary/ignition OFF.
• Driver Behaviour & Scoring:
  • Detects overspeeding episodes (duration and peak speeds).
  • Identifies harsh braking and harsh acceleration events via acceleration deltas ($m/s^2$).
  • Driver scoring model (0–100 weighted rating breakdown).
• Vehicle Health & Utilization:
  • Breakdown of driving, idle, and inactive hours (utilizationPercent).
  • Health engine tracking temperature overheating, battery voltage drops, RPM redlining, and service due intervals.
• Cost Analytics: Fuel cost and operating cost per kilometer calculations.
• Real-Time Streaming Engine: TelemetryEngine class built on EventEmitter for processing single-point streams and triggering live alerts (fuel_anomaly, overspeed, harsh_braking, vehicle_health_warning).
• Zero Database Dependency: Pure, stateless, high-performance data processing library.

Installation

npm install fleet-telemetry-engine

Quick Start

1. Batch Analysis

import { analyzeFleetTelemetry } from 'fleet-telemetry-engine';

const rawTelemetry = [
  {
    timestamp: '2026-09-02T10:00:00Z',
    location: { latitude: 15.4589, longitude: 75.0078 },
    motion: { speedKph: 55 },
    fuel: { levelPercent: 72 },
    engine: { ignition: true, rpm: 1800, temperatureC: 85 }
  },
  {
    timestamp: '2026-09-02T10:30:00Z',
    location: { latitude: 15.7589, longitude: 75.2078 },
    motion: { speedKph: 88 },
    fuel: { levelPercent: 68 },
    engine: { ignition: true, rpm: 2200, temperatureC: 88 }
  }
];

const report = analyzeFleetTelemetry({
  vehicleId: 'KA-01-AB-1234',
  telemetry: rawTelemetry,
  options: {
    fuelTankCapacityLitres: 100,
    fuelPricePerLitre: 1.25,
    speedLimitKph: 80
  }
});

console.log(report.trip);
// { distanceKm: 42.5, durationMinutes: 30, drivingMinutes: 30, idleMinutes: 0, averageSpeedKph: 71.5, ... }

console.log(report.fuel);
// { startLevelPercent: 72, endLevelPercent: 68, consumedLitres: 4, kmPerLitre: 10.63, litresPer100Km: 9.41 }

console.log(report.driver);
// { score: 92, rating: 'EXCELLENT', overspeedEventsCount: 1, ... }

2. Normalizing Provider Data

If your telematics device sends non-standard payloads:

import { CustomProviderAdapter, PRESET_MAPPINGS, analyzeFleetTelemetry } from 'fleet-telemetry-engine';

// Raw payload from vendor
const vendorData = [
  { lat: 15.4589, lng: 75.0078, time: '2026-09-02T10:00:00Z', speed: 60, fuel: 72 },
  { lat: 15.5000, lng: 75.0500, time: '2026-09-02T10:15:00Z', speed: 65, fuel: 70 }
];

const adapter = new CustomProviderAdapter(PRESET_MAPPINGS.FLAT_GPS);
const telemetry = adapter.normalize(vendorData);

const result = analyzeFleetTelemetry({ vehicleId: 'TRUCK-101', telemetry });

3. Real-Time Streaming Engine

For live MQTT / WebSocket telemetry streams:

import { TelemetryEngine } from 'fleet-telemetry-engine';

const engine = new TelemetryEngine({
  speedLimitKph: 80,
  fuelDropThresholdPercent: 5.0
});

// Listen to real-time events
engine.on('overspeed', (event) => {
  console.warn(`[OVERSPEED ALERT] ${event.message}`);
});

engine.on('fuel_anomaly', (event) => {
  console.error(`[FUEL THEFT ALERT] ${event.message}`);
});

engine.on('vehicle_health_warning', (event) => {
  console.warn(`[HEALTH WARNING] ${event.message}`);
});

// Incoming stream packet
engine.process({
  vehicleId: 'KA-01-AB-1234',
  timestamp: new Date(),
  location: { latitude: 15.4589, longitude: 75.0078 },
  motion: { speedKph: 95 }
});

License

MIT