Archive for category: Technical Knowledgebase

The Problem

Tracking a vehicle’s total distance traveled or total engine hours sounds simple — until you deal with the real world:

• Devices get swapped. A vehicle’s GPS tracker fails and is replaced. The new device starts counting from zero.
• Data gaps happen. A device loses power, goes offline, or misses reporting windows. When it comes back, there’s a jump in values.
• Counters reset unexpectedly. Firmware updates, device reboots, or hardware issues can cause a device’s internal counters to drop back to zero.
• Multiple data sources disagree. The GPS-calculated odometer says 102,450 km. The vehicle’s ECU says 104,203 km. Which one is “right”?
• Engine data is received from different source addresses. The data from the engine’s onboard computer / CAN network is received from multiple sources. Read this article for more information.

If you’re building fleet reports on top of raw device data, you have to handle all of these edge cases. Every device swap means manual corrections. Every data gap means broken reports. No worries, there’s a data-processing engine that handles this for you.

---

 

How Pegasus Structures Counter Data

Pegasus organizes absolute counter data (data that’s constantly supposed to increment) into three layers, each building on the one before it:

┌─────────────────────────────────────────────────┐
│  Layer 3: Vehicle Counters  (vehicle_dev_dist)  │  ← User-editable absolute value
│  "The odometer reads 104,203 km"                │    Set it to "match the dashboard"
├─────────────────────────────────────────────────┤
│  Layer 2: Pegasus Counters  (dev_dist)          │  ← Normalized & protected
│  "Consistent, gap-free, swap-safe values"       │    Pegasus manages automatically
├─────────────────────────────────────────────────┤
│  Layer 1: Raw Counters      (vo, ce, cl)        │  ← Straight from the device
│  "Whatever the hardware reported"               │    No adjustments, no "protection", raw telemetry data
└─────────────────────────────────────────────────┘

 

Layer 1 — Raw Counters

These are the unmodified values reported by the device or vehicle’s onboard computer (ECU). They use fixed units (meters, seconds, liters) and are not adjusted to your user’s unit preferences when you query it.

 

When to use: Only when you need the original hardware-reported value for diagnostics or debugging.

 

Layer 2 — Pegasus Counters

Pegasus takes the raw values and applies automatic protections:

These counters adjust to your unit preferences (km vs. miles, liters vs. gallons, etc.) and are the recommended default for reports and calculations.

When to use: For any report, dashboard, or integration that needs reliable cumulative values.

 

Layer 3 — Vehicle Counters

Vehicle counters inherit all of the protections from Layer 2, but add one critical feature: you can set their value.

This is how you align Pegasus with the real world. If a vehicle’s dashboard reads 104,203 km but the GPS-based counter shows 97,600 km, you set vehicle_dev_dist to 104203942 meters, and from that point on, the counter increases in unison with the Pegasus counter — but from your specified starting point.

When to use: When you need an absolute odometer or hourmeter that matches the physical vehicle (for compliance, resale records, maintenance scheduling, etc.). Note that the “GPS Odometer” will always tend to drift from the real dashboard values because it relies on the gps coordinates and satellite visibility, etc. Pegasus doesn’t fix that but at least the value you set manually will be closer to the real world value. It’s recommended to adjust these values once every few months so they maintain coherence.

---

 

Counter Reference by Type

 

Distance (Odometer)

 

Engine-On Time (Hourmeter)

 

Idle Time

 

Fuel Consumed

 

Idle Fuel Consumed

Unit preferences: Raw counters always return in their fixed unit. Pegasus and Vehicle counters adjust to your workspace’s configured unit preferences.

---

 

Which Layer Should I Use?

---

 

What’s Next

This article covers how Pegasus structures and protects counter data. To learn how to query this data — including interval-based reports (daily, weekly, monthly breakdowns), derived metrics (average speed, fuel efficiency), and shared user counters — see the complete documentation:

Counters — Full Documentation