lingniu-vehicle-ingest/docs/vehicle-telemetry-internal-fields.md

Vehicle Telemetry Internal Fields

This document defines the internal telemetry field model for Lingniu hydrogen vehicle operations. Protocol fields such as GB/T 32960, JT808, MQTT, and vendor extensions must be mapped into these fields before storage, statistics, or business reporting.

Design Rules

• Business statistics use internal fields, not protocol field names.
• Every internal field has one stable unit and one business meaning.
• Protocol-specific raw values remain traceable through source_protocol, protocol_version, metadata, and raw archive references.
• Core operational fields are stored as typed columns or typed payload fields.
• Unstable vendor-specific fields can stay in extension metadata until promoted.
• Hydrogen leak safety is a first-class critical safety event, not a generic alarm count.

Identity And Time

Internal field	Type	Unit	Meaning	GB/T 32960 source
vin	string	-	Vehicle VIN and partition key	header VIN
event_time	instant	-	Device collection time	command body timestamp
ingest_time	instant	-	Platform receive time	ingest server clock
source_protocol	enum	-	Source adapter	GB32960
protocol_version	string	-	Source protocol version	V2016 / V2025

Real-Time Vehicle State

Internal field	Type	Unit	Meaning	GB/T 32960 source
vehicle_state	enum	-	Started, shutdown, other, invalid	vehicle block vehicleState
charging_state	enum	-	Charging state	vehicle block chargingState
running_mode	enum	-	Electric, hybrid, fuel, other	vehicle block runningMode
speed_kmh	double	km/h	Current speed	vehicle block speedKmh
total_mileage_km	double	km	Odometer mileage	vehicle block totalMileageKm
gear_level	integer	-	Gear value	vehicle block gearRaw low 4 bits
accelerator_pedal	double	%	Accelerator pedal opening	V2016 vehicle block
brake_pedal	double	%	Brake pedal opening	V2016 vehicle block

Location

Internal field	Type	Unit	Meaning	GB/T 32960 source
longitude	double	deg	Longitude	position block
latitude	double	deg	Latitude	position block
altitude_m	double	m	Altitude when available	extension or other protocol
direction_deg	double	deg	Direction when available	extension or other protocol
location_status_raw	long	-	Raw location status bits	position block statusFlag

Battery And Electricity

Internal field	Type	Unit	Meaning	GB/T 32960 source
battery_soc	double	%	Battery SOC	vehicle block socPercent
battery_voltage_v	double	V	Battery total voltage	vehicle block totalVoltageV
battery_current_a	double	A	Battery total current	vehicle block totalCurrentA
battery_power_kw	double	kW	Derived instantaneous battery power	voltage * current / 1000 in statistics
battery_temperature_max_c	integer	C	Max battery temperature	temperature or extreme blocks
battery_temperature_min_c	integer	C	Min battery temperature	temperature or extreme blocks
daily_electricity_kwh	double	kWh	Daily electricity usage	statistics time integral

Daily electricity must be computed in the statistics layer from typed telemetry points. Do not accumulate protocol raw values directly.

Hydrogen And Fuel Cell

Internal field	Type	Unit	Meaning	GB/T 32960 source
fc_voltage_v	double	V	Fuel cell voltage	fuel cell block
fc_current_a	double	A	Fuel cell current	fuel cell block
fc_temp_c	double	C	Fuel cell or hydrogen system temperature	fuel cell block
hydrogen_remaining_kg	double	kg	Remaining hydrogen mass	vendor extension or capacity conversion
hydrogen_remaining_percent	double	%	Remaining hydrogen percent	V2025 fuel cell block
hydrogen_high_pressure_mpa	double	MPa	Hydrogen high pressure	fuel cell block
hydrogen_low_pressure_mpa	double	MPa	Hydrogen low pressure when available	extension or other protocol
daily_hydrogen_kg	double	kg	Daily hydrogen consumed	statistics layer
hydrogen_mileage_efficiency	double	km/kg	Mileage per kg hydrogen	statistics layer

Daily hydrogen usage should be calculated from adjacent hydrogen remaining values. A rising value indicates refueling and must not be counted as negative consumption.

Hydrogen Tank Safety

Internal field	Type	Unit	Meaning	GB/T 32960 source
safety_category	enum	-	GENERAL, TANK_PRESSURE, TANK_TEMPERATURE, HYDROGEN_LEAK	alarm bit classification
hydrogen_leak_detected	boolean	-	Whether hydrogen leak is detected	general alarm bit HYDROGEN_LEAK
hydrogen_leak_level	enum	-	NONE, WARNING, CRITICAL, UNKNOWN	internal rule
hydrogen_leak_action_required	boolean	-	Whether immediate handling is required	internal rule
tank_pressure_status	enum	-	Normal, warning, critical	hydrogen pressure bit or threshold rule
tank_temperature_status	enum	-	Normal, warning, critical	hydrogen temp bit or threshold rule

Safety rule:

If HYDROGEN_LEAK is present:
  alarm.level = CRITICAL
  safety_category = HYDROGEN_LEAK
  hydrogen_leak_detected = true
  hydrogen_leak_level = CRITICAL
  hydrogen_leak_action_required = true

Hydrogen leak overrides otherwise normal vehicle, speed, battery, or hydrogen state. It must be counted independently from generic alarms.

Daily Operation Statistics

Daily statistics are generated by stat_date + vin.

Internal field	Type	Unit	Meaning
stat_date	date	-	Statistics date
vin	string	-	Vehicle VIN
first_event_time	instant	-	First valid telemetry time
last_event_time	instant	-	Last valid telemetry time
online_minutes	double	min	Online duration
running_minutes	double	min	Running duration
daily_mileage_km	double	km	Daily mileage
daily_electricity_kwh	double	kWh	Daily electricity usage
daily_hydrogen_kg	double	kg	Daily hydrogen usage
hydrogen_added_kg	double	kg	Refueled hydrogen
km_per_kg_hydrogen	double	km/kg	Hydrogen efficiency
kwh_per_100km	double	kWh/100km	Electricity efficiency
alarm_count	integer	-	Generic alarm count
tank_safety_alarm_count	integer	-	Tank safety alarm count
hydrogen_leak_alarm_count	integer	-	Hydrogen leak alarm count
hydrogen_leak_duration_seconds	long	s	Hydrogen leak duration
data_quality_level	enum	-	Good, partial, bad

Implementation Status

• RealtimePayload already uses internal operational field names for state, location, battery, fuel cell, and hydrogen fields.
• AlarmPayload carries internal hydrogen safety fields.
• Gb32960EventMapper maps GB/T 32960 alarm bits into internal safety fields.
• TelemetrySnapshot publishes full-field internal telemetry values through the Kafka protobuf envelope.
• event-history-service, vehicle-state-service, and vehicle-stat-service consume the same full-field telemetry snapshot contract.
• event-history-service CSV export can flatten selected internal fields with fields=field_a,field_b; media archive references are exposed through rawArchiveUri by falling back to MediaMeta.archiveRef.