Vehicle state: what the engine remembers

What this chapter covers

Every other chapter in this part builds on one idea: the engine keeps a small, durable memory for each vehicle and updates it one signal at a time. This chapter describes that memory — the anchors, clocks, and flags the engine carries from batch to batch — the activity states a truck moves through, and why the whole design depends on processing one vehicle's signals strictly in order.

The picture

The engine's core question is simple: is this truck moving, standing still, or have we lost it? Internally it holds three activity states — moving, stationary, and unknown (the state a freshly-seen truck starts in) — plus overlays for an open trip, an open stop, or an open signal gap. The product surfaces project those into the five states a person actually reads on the dashboard.

Two of these five deserve their own chapters — Driving is a trip, and Offline is a signal gap. Stopped and its labelling get their own chapter too. This chapter is about the memory that makes all the transitions possible.

The behavior

One vehicle, one order, one writer

The engine's most important guarantee is that a single vehicle's signals are processed serially, in device-timestamp order, by exactly one writer at a time. When a batch of a truck's positions arrives, the engine locks that truck's state row, replays the batch against it in chronological order, writes the results, and only then releases the lock. No two batches for the same truck run at once.

This is not a performance choice — it is a correctness requirement. The state machines in this part are written the way a person reads a trace: given where the truck was and what it was doing, this next fix means X. That reasoning only holds if fixes arrive in order and nothing else mutates the truck's state underneath. Two batches racing would let one open a trip while the other opens a stop, and the database guards that allow only one open trip, one open stop, and one open gap per vehicle would reject the second writer outright. Serial processing is what keeps the diary coherent.

The consequence for the reader: everything below is a story about one truck's state being advanced one fix at a time. Where a decision needs the truck's history, that history is already in the state memory — the engine never has to go re-read the raw trail mid-batch.

The memory the engine carries

Between batches, each vehicle's state is stored as a compact record. The families that matter for this part:

• Activity — moving, stationary, or unknown, plus the open trip, open stop, and active crawl window if any.
• Anchors — the reference positions the engine measures against. The last usable fix anchors local motion reasoning; the last trusted fix is a stricter anchor used for structural distance and Route Guard; the stationary reference is the spot a standing truck is measured against to detect a real departure. A jitter anchor tracks whether the truck has actually moved across a sliding 60-second window.
• Liveness clocks — several distinct timestamps, never collapsed into one. Last telemetry is the last time any message arrived; last online fix is the last usable GPS fix and is the clock the gap detector watches; the vehicle row also carries the timestamp of the position currently shown on the map. These differ on purpose: a truck can send a heartbeat (advancing last telemetry) without a GPS fix (leaving the online-fix clock frozen), which is exactly the signature of a truck alive but GPS-denied.
• Ignition memory — the last known ignition state and the moment it last went off, held with a debounce (see below).
• Gap and deferral markers — an open gap's details and, when the truck reappears somewhere improbable, a pending-relocation marker.
• Fuel detector state — the reference level and open fuel episode carried forward so drain and fill detection spans batches.

Two of these are derived rather than stored twice: a vehicle is online exactly when it has no open gap, and its last known position is the pending relocation candidate if one is being confirmed, otherwise the last usable fix.

The stored state is the authority for the running state machines. Alongside it, the vehicle row keeps a set of denormalised columns — current position, ignition, battery, last-message time — so the live map and dashboards read a single fast row instead of scanning the position history. Those columns are rewritten at the end of every successful batch.

Ignition memory without GPS

A tracker reports far more than location. Even parked in a basement with no sky view, a wired-to-ignition tracker keeps sending status frames: ignition, battery, power, alarms. The engine updates its ignition memory from every row, fix-bearing or not, so it always knows whether the engine is running even when it cannot see where the truck is.

Ignition memory is guarded two ways so a glitch cannot mislead it:

• Flicker guard. An "ignition off" reading is discarded as a wiring or CAN glitch when the same frame shows real motion — CAN vehicle speed above 5 km/h, or GPS speed above 30 km/h. A truck at highway speed is still running.
• Debounce. The engine records the moment ignition first went off and only trusts the off-state once it has held for at least 60 seconds. Several behaviours — treating a parked wired-ignition truck's silence as normal sleep rather than a fault, for instance — key on this debounced off-state, never on a single raw sample.

Ignition memory being GPS-independent is what lets a parked truck be understood as parked. It is the difference between "Stationné — dernière position connue" (a calm, expected parked state) and "Sans GPS" (a real GPS failure), a distinction the gaps chapter turns into what the operator sees.

Wired versus unknown ignition

Not every tracker is wired to the ignition line. The engine learns a device's capability from its model: the first time a wired-ignition model reports a real ignition reading, the engine promotes that vehicle's ignition mode to wired and unlocks the ignition-aware behaviours — treating ignition-off as authoritative over noisy GPS speed, corroborating movement with ignition, and suppressing false gaps on a truck sleeping overnight. Promotion is one-way: a vehicle never drops back to unknown, so a single model-less batch cannot erase what the engine learned. Trucks whose trackers offer no ignition signal simply never reach those branches and are reasoned about from GPS and CAN alone.

How the five display states are derived

The engine's three internal activity states, combined with the overlays and the liveness clocks, project to the five states a person reads:

Display state	When
Driving	An open trip; activity is moving.
Stopped	An open, confirmed stop (still for at least 3 minutes).
Idle	Engine running, not yet moving — the between-states position.
Parked — "Stationné — dernière position connue"	Heartbeat fresh (within 2 hours), ignition off, and a known last position. A report-by-motion truck sends no fixes while parked, so a missing fix here is normal.
Offline	An open signal gap that is not a confidently-parked truck. Shown as "Sans GPS" when the truck is alive and its engine is on but no fix arrives.

The parked distinction is what stops a correctly-parked overnight truck from lighting up as a fault. It requires a fresh heartbeat (within 2 hours — twice the once-an-hour parked reporting cadence), a trusted ignition-off reading, and a last known position to show.

Edge cases

• A heartbeat with no fix. A status frame (ignition, battery, no coordinates) advances the last-telemetry clock and the ignition memory but not the online-fix clock. The dashboard learns a message arrived — the truck is alive — without pretending the position is fresh. This is what keeps a GPS-denied window visible instead of being masked by an otherwise-healthy tracker.
• A future-dated timestamp. A tracker with a skewed clock can stamp a frame in the future. The liveness clock is clamped to now-plus-tolerance when it advances, so one corrupt timestamp cannot push the clock hours ahead and permanently suppress the truck's offline alert.
• An ignition-off flicker at speed. A lone "ignition off" sample sandwiched between running samples at highway speed is rejected by the flicker guard and never disturbs ignition memory, so it cannot trip a false parked or sleep state.
• A model-less batch. If a batch arrives before the device model is known, the already-learned wired ignition mode is preserved — the engine never forgets a capability it has confirmed.
• A replayed old batch. Buffered signals that arrive late reconstruct history (they can build a past trip or stop) but are held back from the two liveness clocks, so a dead-zone flush never makes a truck look live right now. The trips and gaps chapters cover how that reconstruction works.

Known limitations

The memory model is what makes the engine's reasoning trustworthy, and two of its guarantees are also its boundaries.

• One vehicle is advanced by a single writer, strictly in order. This is a correctness requirement, not a tuning knob: the state machines read like a person reading a trace, and that only holds if a truck's fixes arrive in sequence with nothing else mutating its state. The consequence is that a single vehicle's backlog is worked through sequentially — the engine parallelises across trucks, never within one. A truck that dumps a long buffered flush is reconstructed in order, one fix at a time.
• The ignition-aware behaviours depend on knowing the device model. Treating ignition-off as authoritative, corroborating movement with ignition, and suppressing a sleeping truck's false gap all unlock only once the engine has learned a vehicle's tracker is wired for ignition. A truck whose model is never identified is reasoned about from GPS and CAN alone and never reaches those branches. Promotion is also one-way — a vehicle confirmed as wired never drops back — so a model correction that should narrow a capability is not something the running memory reverses on its own.

How it connects

• Position quality, the liveness clocks, and the parked / "Sans GPS" / offline semantics originate in Part 2 — Telemetry.
• The Driving state is a trip: Trips.
• The Stopped state and its labelling: Stops.
• The Offline state is a signal gap: Signal gaps.
• Fuel detector state, also carried in this memory across batches: Fuel.
• Defined terms (anchor, liveness clock, report-by-motion, crawl) recur across the book: vocabulary.