Status

Contract: openroad.vehicle.trip.state
Current version: 3
Initial transport: ZeroMQ PUB/SUB
Payload encoding: JSON

This document defines the public accumulated Trip telemetry contract. The Trip service derives this state from vehicle and navigation observations and publishes SI-normalized snapshots independently of whether the Trip screen is visible.

Envelope and framing

ZeroMQ uses a UTF-8 topic frame followed by a JSON payload containing version, timestamp, source, and data. The timestamp is UTC Unix epoch time using the shared seconds and nanoseconds timestamp object.

Version 3 data fields

| Field | Unit / type | Nullable | Meaning | | — | — | — | — | | status | idle|active|paused|complete | no | Trip lifecycle | | started_at, ended_at | timestamp | yes | Trip boundaries | | elapsed_s, moving_s, stopped_s | s | no | Accumulated durations | | distance_m | m | no | Accumulated distance | | average_speed_m_s, maximum_speed_m_s | m/s | yes | Trip speed statistics | | fuel_used_m3 | m³ | yes | Total measured/estimated fuel volume | | instantaneous_fuel_consumption_m3_per_m | m³/m | yes | Current distance-normalized fuel consumption | | average_fuel_consumption_m3_per_m | m³/m | yes | Trip-average distance-normalized fuel consumption | | estimated_range_m | m | yes | Estimated remaining range | | boost_time_s | s | no | Time observed above the configured boost threshold | | boost_distance_m | m | no | Distance accumulated while boosted | | boost_fuel_used_m3 | m³ | no | Fuel consumed while boosted | | peak_boost_pa | Pa | yes | Maximum observed positive boost | | high_load_fuel_used_m3 | m³ | no | Fuel consumed while engine load met the configured high-load threshold | | start_latitude_deg, start_longitude_deg | degrees | yes | First usable trip position | | current_latitude_deg, current_longitude_deg | degrees | yes | Latest usable trip position | | end_latitude_deg, end_longitude_deg | degrees | yes | Final usable trip position |

All numeric values must be finite. Durations, distances, fuel quantities, speeds, range, and positive boost metrics are nonnegative. Latitude is constrained to -90..90 degrees and longitude to -180..180 degrees.

Version history and compatibility

Version 1: base trip timing, distance, speed, fuel, range, and position state.
Version 2: adds boost time, boost distance, fuel consumed while boosted, and peak boost.
Version 3: adds fuel consumed while under high engine load.

The decoder accepts Versions 1 through 3 and supplies neutral defaults for metrics introduced after the received version. Producers emit Version 3.

Semantics

Boost and high-load fuel values are observational associations. They describe fuel consumed while those conditions were present; they do not claim that boost or load caused a specific incremental amount of fuel consumption.

Trip accumulation is independent of presentation. Hiding the Trip screen does not reset or pause the tracker. The automotive BACKGROUND telemetry profile remains Trip-biased so request-limited OBD sources continue supplying useful Trip inputs.

Producer and consumer requirements

Producers must publish complete objects for their declared schema version, use SI units, preserve nullability, and identify the source with a non-empty string. Consumers must tolerate nullable measurements and explicitly handle unsupported future versions.