Handbook

Appearance

Liveness: Alive, Located, Parked, Or Dark ​

What this chapter covers ​

"Is this truck online?" is the wrong question, because it hides two different facts: whether the tracker is still talking, and whether we still have a fresh position. This chapter explains the two-clock model that keeps those facts apart, and the states it produces — driving, stopped, idle, "Stationné — dernière position connue", "Sans GPS", and offline. It ends on the single decision that trips people up most: a parked truck that has gone quiet on GPS is normal, and telling that apart from real GPS failure is the whole job of this layer.

The picture — two clocks ​

  • The message clock is the last time any message arrived from the tracker — a fix, a status frame, or a bare heartbeat. It answers "is the device alive?" It drives the device-offline alert.
  • The location clock is the last time an accepted, live GPS fix arrived. It answers "do we know where the truck is?" It drives signal-gap detection.

A status frame advances the message clock but not the location clock. That single asymmetry is why a report-by-motion truck can be provably alive and provably un-moved at the same time — and it is what makes the distinction between parked and "Sans GPS" possible. A buffered dead-zone flush is the opposite case: it advances neither clock, so a stale batch catching up can neither fake live contact nor close a real gap.

The behavior — the states ​

Korido resolves one activity state per truck from its open structural records and its two clocks, in strict priority order.

Current behavior

A parked report-by-motion truck is allowed to hold an old map position while its heartbeat and telemetry stay fresh. The state turns amber only when the location clock is stale in a way the engine cannot explain as ordinary parked sleep.

  • Driving. An open trip. The truck is moving on an accepted-fix trail.
  • Stopped. An open stop — the truck has halted somewhere the engine is tracking. At an accountable place (a port, border, checkpoint, warehouse, or depot) this reads as "at checkpoint."
  • "Stationné — dernière position connue". The report-by-motion resting state. The heartbeat is fresh, the ignition is off, and the last known position is held. A report-by-motion tracker sends no fixes while parked, so a missing fix here is normal — the truck is simply parked where we last saw it. Rendered in the calm default tone: no badge, no alarm.
  • "Sans GPS". The heartbeat is fresh, the ignition is on, and there is still no fresh fix. A running truck that cannot get a GPS position means genuine GPS failure or jamming. Rendered amber — this one is a problem.
  • Idle. Heartbeat present but none of the confident-parked conditions met — a fallback resting state, marked inactive once silence passes the configured threshold.
  • Offline. A signal gap is open and the confident-parked test fails. Location observability is genuinely lost.

The confident-parked test ​

A truck is confidently parked only when all three hold:

  1. the heartbeat is fresh — a message within the last 2 hours
  2. the ignition reads off (taken from the freshest telemetry, which status frames keep current even with no fix)
  3. there is a known last position to show

The 2-hour bound is twice the roughly-hourly cadence of a parked tracker: one missed heartbeat is expected, but after two the truck has been quiet too long for "confidently parked" and it falls back to plain idle or offline.

Where "Sans GPS" versus parked is decided ​

The two look identical at first glance — both are alive, both lack a fresh fix. The ignition is the tiebreaker. Ignition off plus fresh heartbeat is a parked truck resting: "Stationné — dernière position connue". Ignition on plus fresh heartbeat plus no fresh fix is a working truck that has lost GPS: "Sans GPS". Reserving the amber Sans GPS state for the ignition-on case is what stops every overnight-parked truck from lighting up as a fault.

When GPS dies but the truck is parked ​

A signal gap can open on a confidently parked truck — the engine notices the location clock has gone stale. If that gap is specifically a GPS-denied-while-alive gap and the truck is confidently parked, an open stop still wins as the more specific truth; otherwise the truck shows as "Stationné — dernière position connue" in the amber degraded tone, carrying a quiet "position may be stale" signal rather than a false alarm.

This exception resolves entirely inside the gap branch and never falls through to the driving branch. That matters: a truck whose GPS dies mid-trip could otherwise keep an open trip and render a confident "driving" forever. Resolving the GPS-denied gap up front prevents that.

The device-offline alert ​

Separately from the display states, the message clock drives a hardware device-offline alert. Because a sleepy Teltonika and a chatty JimiIoT stay silent for wildly different windows, each device carries one explicit silence expectation, resolved from a single chain:

  1. a per-device override set from the admin portal — a plain minutes value, between one minute and 24 hours — if present, otherwise
  2. the device model's known sleep cadence (roughly hourly for Teltonika FMB; for the JimiIoT VL-series, the interval set by the device's own configuration), otherwise
  3. the tenant's default

The per-device override sits at the top of that chain: when Korido staff set an expected-silence value for a unit, it overrides the model cadence and the tenant default outright. It is the direct lever for a tracker whose real rhythm differs from its model's typical cadence.

The truck counts as offline only once it has been silent past that expectation plus a 10-minute grace beat — one missed heartbeat is within cadence; the second is worth alerting on. The customer tracking portal and the owner alert read the same boundary, so a customer never sees a live dot on a truck the owner already knows is dark.

Edge cases ​

  • The central case — a parked report-by-motion truck. Fresh heartbeat, ignition off, no new fix for hours. This is "Stationné — dernière position connue" in the calm tone, never "Sans GPS." The absence of fixes is the tracker working as designed.
  • Genuine GPS failure or jamming. Fresh heartbeat, ignition on, no fresh fix. This is "Sans GPS" in amber — a real fault worth surfacing.
  • GPS dies mid-trip. The GPS-denied gap resolves inside the gap branch and never falls through to "driving," so a GPS-dark truck cannot show a confident driving state indefinitely.
  • Heartbeat older than 2 hours. Confident-parked is lost; the truck falls back to plain idle or, if a gap has opened, offline.
  • Sleepy device versus chatty device. A flat offline threshold would spam false alerts on the hourly Teltonika and hide real outages on the minute-cadence JimiIoT. The per-device silence expectation resolves both correctly.
  • A buffered flush after a dead zone. It advances neither clock — its timestamps rebuild the truck's past without ever counting as live contact — so it cannot fake a live position or close a real signal gap.

Known limitations ​

The two-clock model draws sharp lines, and the sharpness comes from a couple of fixed choices worth naming.

  • The calm parked window is a fixed two hours, separate from the offline alert. A truck counts as confidently parked only while its last heartbeat is within two hours — a flat bound, not the per-device silence expectation that governs the offline alert. A tracker deliberately configured to sleep longer than two hours between parked heartbeats therefore slips out of the calm "Stationné — dernière position connue" state into plain idle before its offline expectation has elapsed. The two boundaries answer different questions and move independently.
  • The parked-versus-"Sans GPS" split needs a trusted ignition-off reading. The whole distinction rests on the ignition line: ignition off means resting, ignition on with no fix means a fault. A tracker that offers no ignition signal can produce neither verdict — it never enters the confident-parked state and never raises "Sans GPS." The clean split is available only on units wired to read ignition.

How it connects ​