Trackers And What They Report

What this chapter covers

Every fact Korido knows about a truck begins as a radio message from a hardware tracker bolted into the cab. This chapter introduces the tracker families the platform supports, the two kinds of message they send — position fixes and status frames — and the individual signals those messages carry, including the BLE fuel probes that read a tank's level. It sets up the single most important idea in this part of the book: a silent GPS does not mean a silent truck.

The picture

The tracker is the source of truth for where a truck is. Phone GPS from the driver app is shown to the driver but never sent back to the platform, so nothing downstream ever has to reconcile two competing ideas of a truck's position.

The device families

Korido normalizes several tracker families into one shared shape, so the rest of the platform never has to know which brand of hardware a given truck carries. Three families matter today.

Family	Protocol	Typical units	Parked reporting	Sends device events while parked
JimiIoT VL-series	JimiIoT	VL863, VL802, VL103	report-by-motion — periodic status frames at an interval set by device configuration	yes
Teltonika FMB	Teltonika FMB	FMB920, FMB003 (CAN)	roughly hourly at rest	no

The JimiIoT VL-series shares one protocol and one configuration across every model, so Korido treats VL863, VL802, and VL103 as a single family. The families differ in the details — a Teltonika reports its battery as a voltage where a JimiIoT reports it as a percentage; a JimiIoT frame carries a high-precision capture timestamp that a Teltonika frame may omit — but Korido collapses those variants at the door. Downstream code reads one canonical set of signals and never branches on hardware brand.

The two rhythms matter enormously. A Teltonika that legitimately sleeps for an hour and a JimiIoT whose parked reporting follows its own configured cadence cannot share one flat "you are offline now" rule. Set the threshold short and every sleeping Teltonika trips a false alarm; set it long and a genuinely dead JimiIoT stays invisible for that whole hour.

Korido therefore carries one explicit silence expectation per device — never a learned guess — which Liveness explains in full.

Fixes versus status frames — report-by-motion

A tracker sends two structurally different kinds of message.

• A GPS fix frame carries coordinates: latitude, longitude, speed, heading, plus all the telemetry below. It is what draws the truck on the map.
• A status frame carries the same telemetry but no coordinates. It is the tracker saying "here is my state" without a fresh satellite fix.

These trackers are report-by-motion: while a truck drives, it streams fixes; while it sits parked, it stops computing new fixes and falls back to periodic status frames and voltage heartbeats. This is by design, not a fault. A parked truck that has sent no GPS fix for six hours but is still sending hourly status frames is a perfectly healthy, perfectly located truck — it simply has not moved.

Holding onto this distinction is what lets Korido tell a parked truck apart from a truck whose GPS has genuinely failed. Both stop producing fixes; only one keeps producing status frames while the engine is off. That difference drives the "Stationné — dernière position connue" versus "Sans GPS" decision in Liveness.

The signals a message carries

Whether it carries coordinates or not, a frame is dense with operational signal. Korido persists all of it, so a message shape never quietly drops a field.

Signal	What it tells the fleet
Ignition	engine on or off, from a wired connection on VL863 and Teltonika FMB models
Battery level	the tracker's own backup battery — warns before the device dies
External voltage	the truck's electrical supply feeding the tracker; a clean drop from present to cut while the device keeps transmitting is read as a main-power disconnection — an interference-relevant signal
GSM signal level	cellular reception strength where the truck currently is
Alarm line	the hardware SOS / panic input
Engine immobilizer	the remote engine-block state — whether the truck's starter is cut, and every time it flips
Defense / vibration	factory defense state and tamper/shock detection
CAN data (where wired)	vehicle speed, engine RPM, coolant temperature, engine load, fuel counters, diagnostic trouble codes, and VIN read straight off the truck's own bus
BLE fuel	tank level from a Bluetooth probe (below)

CAN signals appear only when the tracker is physically wired into the truck's data bus — an FMB003 on a CAN harness reports engine RPM and ECU fuel consumption; a tracker with no bus connection simply reports null for those fields, which means "not equipped," never "lost in transit."

BLE fuel sensors

Fuel is measured by a BLE fuel probe sitting inside the tank. The probe is a capacitive sensor: the height of liquid around it changes the capacitance it reads, so its raw output is a measure of fuel height, not volume. The probe broadcasts that reading over Bluetooth; the tracker overhears it and relays it to Korido inside its normal telemetry stream.

Two probe families are in the corridor fleet, told apart by the name the probe broadcasts:

• JimiIoT KF201S — the probe reports its own calibrated full-scale value on every message, and Korido divides the raw reading by that value to get the height fraction.
• Escort (broadcast names beginning TD_) — the probe's full-scale field is a meaningless placeholder, so Korido substitutes the sensor's known fixed twelve-bit range (0 to 4095) instead. Without that substitution every Escort tank would read as permanently full.

From there both families are handled identically. The height fraction is not the same as the fuel fraction, because a truck tank has a rounded-rectangular cross-section — the middle of the tank holds far more litres per centimetre than the top or bottom. Korido therefore passes the height fraction through a height-to-volume calibration curve to get a true volume percentage, which is the single number the platform reasons about and shows. Once a truck's tank capacity is recorded, that percentage becomes litres for display.

The probe also reports its own temperature and battery, and an error-state code. Korido corrects the two values the sensor mislabels on the wire (temperature and battery are reported at the wrong scale and rescaled on the way in), and treats the error code — not the GPS fix — as the authority on whether a reading is trustworthy.

Heartbeats as proof of life

The humblest message a tracker sends is a bare voltage or info heartbeat: no position, sometimes almost no telemetry, just the device announcing that it is powered and connected. That is exactly its value. Every message — fix, status frame, or heartbeat — advances the moment Korido last heard from the physical device. That timestamp, the message clock, is the foundation of the whole liveness model: it answers "is the tracker alive?" independently of "do we have a fresh position?" Liveness builds the two-clock model on top of this idea.

Edge cases

• A parked truck goes quiet on GPS but keeps heartbeating. This is the normal resting state of a report-by-motion tracker, not a malfunction. The last known position stays valid and the message clock stays fresh.
• The Escort probe reports a nonsense full-scale. Its full-scale field is a fixed placeholder; Korido ignores it and uses the sensor's known twelve-bit range, otherwise every Escort-equipped truck would read as 100% fuel forever.
• A fuel reading arrives with no GPS fix. BLE fuel frames — especially from Escort probes, and from any truck sitting in a satellite dead zone — routinely carry a real tank level and no coordinates. The reading is still valid; its validity is decided by the sensor's error code, never by whether a satellite fix happened to accompany it.
• A sensor error code is non-zero. The tank-level number is suppressed (the gauges and the fuel logic skip it), but the raw reading, temperature, battery, and error code are all still stored as evidence.
• CAN fields are null. The tracker is not wired to that truck's data bus; the fields mean "not equipped," never "dropped."

Known limitations

The signal set a tracker can offer is bounded by how it is wired and how it is built, and a few facts follow from that:

• Power-cut detection needs a wired voltage line. The main-power disconnection signal reads the truck's external supply voltage falling from present to cut. A unit that does not report external voltage — because it is not wired to the truck's supply, or its model does not measure it — cannot produce that signal, so a power cut on such a unit is not detectable from voltage alone. Absence of the reading is treated as no information, never as a cut.
• CAN telemetry exists only on a bus-wired truck. Engine RPM, ECU fuel counters, coolant, and VIN appear only where the tracker is physically joined to the vehicle data bus. On a truck with no bus connection these fields are null — "not equipped," not "lost."
• A parked report-by-motion truck shows its last known position, not a live one. By design, these trackers stop computing fixes while parked, so no fresh position exists to display. Korido holds the last known fix and marks the truck confidently parked; it does not — and cannot — show live movement for a truck that is reporting none. This is the feature working as intended, and the liveness model is built precisely to tell it apart from real GPS failure.

How it connects

• Next: The ingestion pipeline — how these messages authenticate, validate, and become durable rows.
• Then: Position quality — how a fix earns trust.
• Then: Liveness — how fixes and heartbeats produce the driving / parked / Sans GPS / offline states.