Handbook

Appearance

Trips: a driving window's life ​

What this chapter covers ​

A trip is a single driving window — the truck left, drove, and came to rest. It is the atom the vehicle diary is built from, and it is where the engine works hardest, because the hardest question in the whole system is deceptively simple: did this truck actually start moving, or is a parked tracker just twitching? This chapter walks a trip from the evidence that opens it, through what keeps it alive, to every way it closes — and the edge cases that make each of those hard.

The picture ​

A trip opens only on trusted motion evidence, extends while the truck keeps moving (including a slow crawl state for queues and checkpoints), and closes on one of several causes.

The behavior ​

The building block: a movement signal ​

Before a trip can open, the engine needs evidence the truck is really moving, not just reporting noise. A parked truck's GPS can report a phantom 5–7 km/h from Doppler drift while its coordinates jitter within a few metres. Trusting the speedometer alone would open a trip every time that happens.

So a movement signal requires two independent things to agree:

  1. The tracker's reported speed is above 5 km/h, and
  2. the implied speed — the actual ground distance between this fix and the last one, divided by the time between them — is above 2 km/h.

Reported speed says the wheels are turning; implied speed says the truck is somewhere new. A jittering parked truck satisfies the first and fails the second: its speedometer reads 6 km/h but it hasn't gone anywhere, so no movement signal is produced. Only a fix the quality pipeline already rated trusted is eligible; a degraded fix never generates a movement signal. This is the multiple-signal rule, and it is the source of the engine's resistance to phantom trips.

What opens a trip ​

A standing truck (activity stationary or the fresh unknown state) is evaluated for departure on every fix. A trip opens by one of three paths:

  • The ordinary departure. Two movement signals accumulate and the truck has left a 200-metre stationary-noise radius around where it was standing. The radius is the guard that in-place jitter can never clear: a genuine departure crosses it within a fix or two at corridor reporting cadence, while Doppler noise stays inside it forever. A truck reporting motion but never leaving the radius opens no trip at all.
  • Ignition corroboration. On a wired-ignition truck, once a departure is already pending, an ignition-on fix moving faster than a low threshold counts toward the two signals even if that single fix is imperfect — the engine running plus some speed is corroborating evidence the truck is underway.
  • The crawl departure. Some journeys begin at walking pace — edging out of a packed yard or a border queue. Two trusted slow-progress fixes that together carry the truck at least 300 metres within the crawl window open a trip directly into a crawl state, without ever producing a fast movement signal.

Backdating: the recorded start is when motion began ​

There is a subtlety worth calling out because it shows up everywhere downstream. The engine cannot confirm a departure until the truck clears the 200-metre radius — which happens a fix or two after it actually pulled away. If the trip's start time were the confirmation fix, every trip would begin 200 metres and a minute late.

Instead, the engine remembers the first movement signal as the departure moment and backdates the trip's start to it. Only confirmation waits for the radius; the recorded start reflects when the truck truly began moving. Distance, duration, and the diary all read the honest start.

What extends a trip, and the crawl state ​

While a trip is open, each trusted fix accumulates distance, moving time, and top speed. The interesting part is slow movement. A truck in a border queue or a congested urban approach moves a little, stops a little, moves again — for hours. Treating each pause as the end of a trip and each nudge as a new one would shred one crossing into dozens of fragments.

The crawl state absorbs this. When a moving truck drops to inching speed (at or below 5 km/h, or reporting null speed), the engine opens a crawl window and tracks the frontier — the furthest it has progressed from the crawl's start. Each real step forward of at least 30 metres advances the frontier. A crawl becomes proven once the truck has covered at least 100 metres across at least two frontier advances, and while a proven crawl is recent (its last progress within the 10-minute pause grace), it suppresses stop detection — a truck genuinely creeping forward is not "stopped" just because it paused for a light. A strong movement signal closes the crawl and resumes ordinary driving.

How a trip closes ​

A trip has one open lifetime and exactly one close cause:

  • Arrival at a stop. The truck goes still and stays still long enough for a stop to confirm (3 minutes — see Stops). The stop opens and the trip closes, timed to the moment the truck came to rest.
  • Ignition off while stationary. On a wired-ignition truck, an ignition-off reading is treated as speed zero regardless of what GPS drift reports. That makes the truck a stationary candidate, and once it holds, the stop confirms and the trip closes. A CAN speed above 5 km/h vetoes this — an ignition-off reading contradicted by the vehicle bus is read as a flicker.
  • Gap resolution. If the truck goes dark mid-trip and the engine later decides it was parked or relocated during the silence, the trip closes at the moment the gap began. If instead it decides the truck drove through the gap, the trip continues unbroken. The gaps chapter owns that decision.
  • The staleness safety net. A trip that somehow stays open longer than 24 hours — a truck that vanished without a clean resolution — is closed by a background sweep so the diary never carries an eternally-open driving window.

Merged artifacts: one crossing, not eighteen fragments ​

The 200-metre radius stops most border-queue noise from ever opening a trip. But occasionally a queue does creep across the radius before halting again, opening a real — but degenerate — micro-trip that dies at the next halt. Repeated for six hours, a single customs crossing could fragment into a run of tiny trips and stops.

The engine catches this at close time. When a just-opened trip is degenerate — under 300 metres and under two minutes of driving — and it halts within 45 minutes and 200 metres of the stop it just left, the two fragments are recognised as one continuing stop. The stray trip row is closed but stamped a merged artifact: it stays in the record for audit, but the diary and the per-segment statistics exclude it, and no "trip completed" milestone fires. From the operator's side, the six-hour crossing reads as one long stop, which is what it was. Because the engine processes one truck's batch serially, this merge happens in the same transaction as the fragment it folds — there is no race.

Edge cases ​

  • Same-second fixes. Two fixes can share a device timestamp to the microsecond — a fix-bearing frame and a status frame, or a duplicate upload. On an exact tie the fix-bearing frame is ordered first so it wins the database's once-only insert. Any later frame at or before the last processed timestamp is flagged late and skipped from structural state, so a duplicate can never open a second trip or re-close an open one.
  • Buffered-data floods arriving late. A truck leaving a dead zone can dump hours of stored fixes at once. Those buffered fixes still run the full departure and crawl logic, so the engine can reconstruct a trip that happened during the outage — but they are held back from the liveness clocks, so a late flush never makes the truck look like it is moving right now. History is rebuilt; the present is not faked.
  • A gap opening mid-trip. When silence opens a gap while a trip is running, the engine freezes the fact that the truck was driving, closes any active crawl, and waits. On return it uses that frozen activity plus the distance and timing across the gap to decide whether the trip continues or closes — a short reconnect with real displacement on a truck that was moving reads as drove-through and keeps the trip alive.
  • Jitter near a geofence. A truck parked just inside a waypoint's edge can jitter across the boundary. Because a trip needs real displacement past the 200-metre radius — not just a boundary crossing — the jitter never opens a phantom trip, and the low-speed-near-anchor fixes are rated degraded, keeping them out of the movement-signal count entirely.
  • A departure that never completes. A pending departure that collects a signal or two and then goes quiet — the truck rocked but never left — expires after 15 minutes with no crawl progress, and the candidate resets. A truck standing in one place for 30 minutes resets its stationary reference outright, so stale half-departures never accumulate into a false start.

Known limitations ​

Resistance to phantom trips is the engine's proudest property here, and it is bought with a deliberate trade.

  • A real move shorter than the departure radius is not recorded as a trip. The 200-metre stationary-noise radius is what makes in-place jitter incapable of opening a trip — and the same rule means a genuine short reposition that never clears the radius before halting again produces no trip. The engine chooses to under-count tiny moves rather than invent trips from noise; on a long-haul corridor that trade is nearly always right, but it is a trade.
  • Reconstructing a trip taken in the dark depends on the tracker having buffered. When a truck drives through a dead zone, the engine can rebuild the trip only from the fixes the device stored and replayed on reconnect. A tracker that buffered nothing leaves a silence the gap logic classifies by inference, not a trip rebuilt from real positions.
  • Crawl and stop share a fuzzy border. The crawl state absorbs stop-start creep through a queue so a crossing does not shred into fragments, and the merge rule folds the fragments that slip through back into one stop. Both are heuristics tuned to the corridor's queues; an unusual creep pattern can still sit right on the line between "still crawling" and "stopped."

How it connects ​