Skip to Content
Front pageLabsLabs, projects & CCNA notes

Mileage engine

What the MileWage phone app records, which GPS fixes the track engine discards, and how the Kotlin and TypeScript implementations produce identical totals.


The track engine converts raw GPS fixes into a distance, a list of trips and a list of stops. It runs twice for every shift: once on the phone in Kotlin and once on the server in TypeScript.

Recording

StateBehaviour
Shift running, phone movingOne GNSS fix every 5 seconds, no distance filter. Android 12 and later may batch delivery up to 15 seconds.
Shift running, still for 150 secondsOne fix every 60 seconds, plus the significant-motion sensor.
Movement detectedReturns to the 5-second cadence. Triggers: a fix outside the stillness radius, a fix at 9 km/h, or the motion sensor.
No shift runningNothing is recorded. The service is stopped.

Only fixes from the gps provider are stored. Network positions from Wi-Fi and cell towers help detect movement but are never stored or counted.

Filtering

The engine applies the same rules on the phone and on the server.

RuleThresholdEffect
Accuracy filterWorse than 50 mThe fix is dropped.
Minimum movemax(20 m, worse accuracy of the two fixes), capped at 50 mSmaller movements from the last accepted fix are held back.
Speed boundAbove 42 m/s (about 150 km/h)The jump is cut.
SilenceLong gap between fixesThe gap is flagged on the shift. No distance is invented.

A held-back fix is not lost. The gate measures each step from the last accepted fix, so the next accepted fix counts the whole distance from that anchor.

The filters decide what is counted. They do not delete recorded points.

Minimum move options

Engine version 3 used a fixed 20 m minimum move. A parked phone with 35 m accuracy drifts further than that and adds distance. Version 4 scales the threshold with the reported accuracy.

The options were measured on synthetic tracks: a phone parked for 10 minutes at 30 to 50 m accuracy, and a slow city ride at 25 to 50 m accuracy.

Minimum movePhantom distance while parkedLoss on the slow ride
20 m (version 3)About 290 m per 10 minutes0.8%
max(20 m, worse of anchor and fix) (version 4)About 116 m2.5%
max(20 m, sqrt(a² + f²))About 51 m3.9%
max(20 m, anchor + fix)About 8 m6.0%

The reasoning is recorded in Accuracy-gated minimum move.

Stops, active miles and deadhead miles

The engine finds stops from the recorded track after the shift. The driver taps nothing during the shift.

  • A shift starts as deadhead.
  • A stop of about three minutes or more flips the state. The first is treated as a pickup, the next as a dropoff.
  • The split is labelled "estimated" on shift pages, in the mileage log and in exports.

The estimate assumes one order at a time, so stacked orders can understate active miles. The total distance does not depend on stop detection, and the mileage deduction uses the total.

Two implementations, one result

PropertyDetail
ArithmeticResults are whole numbers (decimetres), so rounding cannot differ between devices.
TrigonometryThe Kotlin port includes its own port of V8's sin, cos and atan2.
VersioningEach result carries the engine's algorithm version.
Conformance setpackages/track-engine/conformance/fixtures.json, generated by npm run conformance:fixtures.
Cross-checknpm run crosscheck:engine compares the Kotlin and TypeScript outputs.
On-device checkSettings > Diagnostics > Mileage maths check runs the conformance set on the phone.

The cross-check for 0.3.0 covered 2,000 and 5,000 random shifts, 900,195 maths calls and 250,000 distance pairs with 0 differences. It ran on x86-64 only.

Recalculation

The server reruns the engine when a shift ends, when fixes arrive late, and when a trip or stop is edited on the web. Trip edits, stop labels and manual trips are preserved.

A finalized shift is never recalculated.

Back to top