feat: a reading says whether the car measured it or a model guessed it

The dashboard formatted nullable floats straight out of the snapshot, which
worked only because every figure on it happened to be a vehicle reading. That
stops being true with the next feature: adaptive range, the climate share and
the speed comparison are models, and they have to arrive on screen visibly
different from the state of charge.

DashboardReadings maps the snapshot into EVHardware's Provenanced carrier —
vehicle signals measured, trip totals derived from them, nothing zero when it is
missing — and ProvenanceText draws the difference in text rather than colour: a
band for an estimate, an em dash for a gap, and the reason for that gap in the
reading's content description and in the diagnostics report, where there is room
for a sentence. An unrecognised firmware now says it was never taught to read
the signal instead of implying the car went quiet.

Verified on the API 28 1920x720 emulator, which exposes no car service: every
field renders its em dash with its unit intact and the trip controls stay
disabled, with no crash in logcat.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: malys

CHANGELOG.md

@@ -6,6 +6,17 @@ All notable changes follow [Keep a Changelog](https://keepachangelog.com/en/1.1.
 
 ### Added
 
+- **Every figure on the dashboard now says what kind of claim it is.** The energy work ahead is
+  mostly inference — the MG4 publishes no per-consumer counters, so the climate share, the speed
+  comparison and the arrival state of charge will all be models — and a model drawn in the same
+  typeface as a vehicle reading is a vehicle reading as far as the driver is concerned. Readings
+  are mapped into EVHardware's `Provenanced` carrier, which cannot hold an estimate without its
+  uncertainty band and cannot hold a number for a value it calls unavailable. An estimate wears a
+  `≈` and its band; a missing figure stays an em dash whose reason — unsupported generation,
+  signal not published, not enough samples — is spoken by the reading's description and spelled
+  out in the diagnostics report. The distinction is carried by text, not colour, so it survives
+  daylight and reaches a screen reader.
+
 - **The diagnostics dialog lists what each energy property actually answers.** A field showing
   an em dash says a signal is unusable but not why, and unsupported, declared-but-never-published
   and unreachable all look identical from the driver's seat. The report names the status, the raw

EVHardware

@@ -0,0 +1,69 @@
+package com.evsuite.chargepilot
+
+import com.evsuite.hardware.FirmwareInfo
+import com.evsuite.hardware.telemetry.EnergySnapshot
+import com.evsuite.hardware.telemetry.EnergyTripSummary
+import com.evsuite.hardware.telemetry.Provenanced
+import com.evsuite.hardware.telemetry.UnavailableReason
+
+/**
+ * One frame of the dashboard, with every figure carrying what kind of claim it is.
+ *
+ * The activity used to format nullable floats straight out of the snapshot, which worked
+ * only because everything on screen happened to be a vehicle reading. It will not stay that
+ * way: adaptive range, the climate share and the speed comparison are models, and they have
+ * to arrive on screen visibly different from the state of charge. Mapping the snapshot into
+ * [Provenanced] values here is what makes that difference impossible to forget later.
+ */
+data class DashboardReadings(
+    val soc: Provenanced<Float>,
+    val range: Provenanced<Float>,
+    val speed: Provenanced<Float>,
+    val power: Provenanced<Float>,
+    val outsideTemp: Provenanced<Float>,
+    val batteryTemp: Provenanced<Float>,
+    val tripDuration: Provenanced<Long>,
+    val tripDistance: Provenanced<Double>,
+    val tripEnergy: Provenanced<Double>,
+    val tripRegen: Provenanced<Double>,
+    val tripConsumption: Provenanced<Double>,
+) {
+    companion object {
+        /** Nothing read yet: every field unavailable, none of them zero. */
+        fun empty(): DashboardReadings {
+            fun <T : Any> gap() = Provenanced.unavailable<T>(UnavailableReason.SIGNAL_ABSENT)
+            return DashboardReadings(
+                soc = gap(), range = gap(), speed = gap(), power = gap(),
+                outsideTemp = gap(), batteryTemp = gap(),
+                tripDuration = gap(), tripDistance = gap(), tripEnergy = gap(),
+                tripRegen = gap(), tripConsumption = gap(),
+            )
+        }
+
+        fun of(snapshot: EnergySnapshot, trip: EnergyTripSummary?): DashboardReadings {
+            // An unrecognised generation is not a car that stopped publishing: it is a car
+            // this build was never taught to read. The screen says which.
+            val absent = if (snapshot.firmware == FirmwareInfo.Gen.UNKNOWN) {
+                UnavailableReason.UNSUPPORTED_FIRMWARE
+            } else {
+                UnavailableReason.SIGNAL_ABSENT
+            }
+            return DashboardReadings(
+                soc = Provenanced.measured(snapshot.socPercent, absent),
+                range = Provenanced.measured(snapshot.rangeKm, absent),
+                speed = Provenanced.measured(snapshot.speedKmh, absent),
+                power = Provenanced.measured(snapshot.batteryPowerKw, absent),
+                outsideTemp = Provenanced.measured(snapshot.outsideTempCelsius, absent),
+                batteryTemp = Provenanced.measured(snapshot.batteryTempCelsius, absent),
+                // The trip figures are arithmetic over those readings, so they are derived,
+                // and they are missing for a different reason: no trip is being recorded, or
+                // no usable interval has accumulated yet.
+                tripDuration = Provenanced.derived(trip?.durationMs),
+                tripDistance = Provenanced.derived(trip?.distanceKm),
+                tripEnergy = Provenanced.derived(trip?.consumedKwh),
+                tripRegen = Provenanced.derived(trip?.regeneratedKwh),
+                tripConsumption = Provenanced.derived(trip?.averageConsumptionKwhPer100Km),
+            )
+        }
+    }
+}

app/src/main/java/com/evsuite/chargepilot/DashboardReadings.kt

@@ -1,6 +1,7 @@
 package com.evsuite.chargepilot
 
 import android.os.Bundle
+import android.widget.TextView
 import androidx.appcompat.app.AlertDialog
 import androidx.appcompat.app.AppCompatActivity
 import com.evsuite.chargepilot.databinding.ActivityMainBinding
@@ -12,7 +13,7 @@ import com.evsuite.hardware.telemetry.EnergySnapshot
 import com.evsuite.hardware.telemetry.EnergyTelemetryReader
 import com.evsuite.hardware.telemetry.EnergyTripHistoryStore
 import com.evsuite.hardware.telemetry.EnergyTripSession
-import com.evsuite.hardware.telemetry.EnergyTripSummary
+import com.evsuite.hardware.telemetry.Provenanced
 import java.io.File
 import java.util.Locale
 import java.util.concurrent.Executors
@@ -24,18 +25,22 @@ class MainActivity : AppCompatActivity() {
     private lateinit var binding: ActivityMainBinding
     private lateinit var reader: EnergyTelemetryReader
     private lateinit var tripStore: EnergyTripHistoryStore
+    private lateinit var provenance: ProvenanceText
     private val sampler = Executors.newSingleThreadScheduledExecutor { runnable ->
         Thread(runnable, "chargepilot-sampler")
     }
     private var samplingTask: ScheduledFuture<*>? = null
     /** Written by the sampler thread, read by the main thread on a control tap. */
     @Volatile private var latest: EnergySnapshot? = null
+    /** The last frame drawn, so the diagnostics report can explain what the screen shows. */
+    @Volatile private var latestReadings: DashboardReadings = DashboardReadings.empty()
 
     override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)
         binding = ActivityMainBinding.inflate(layoutInflater)
         setContentView(binding.root)
 
+        provenance = ProvenanceText(this)
         reader = EnergyTelemetryReader(applicationContext)
         tripStore = EnergyTripHistoryStore(File(filesDir, "trips.json"))
         binding.tripAction.setOnClickListener { toggleTrip() }
@@ -82,12 +87,9 @@ class MainActivity : AppCompatActivity() {
     }
 
     private fun render(value: EnergySnapshot) {
-        binding.socValue.text = percent(value.socPercent)
-        binding.rangeValue.text = distance(value.rangeKm?.toDouble())
-        binding.speedValue.text = speed(value.speedKmh)
-        binding.powerValue.text = power(value.batteryPowerKw)
-        binding.outsideTempValue.text = temperature(value.outsideTempCelsius)
-        binding.batteryTempValue.text = temperature(value.batteryTempCelsius)
+        val readings = DashboardReadings.of(value, EnergyTripSession.current(value.timestampMs))
+        latestReadings = readings
+        renderReadings(readings)
         binding.climateValue.text = climate(value)
 
         val hasVehicleData = value.hasVehicleData
@@ -96,9 +98,6 @@ class MainActivity : AppCompatActivity() {
         )
         binding.dataStatus.setTextColor(getColor(if (hasVehicleData) R.color.ev_ok else R.color.ev_warn))
 
-        val trip = EnergyTripSession.current(value.timestampMs)
-        renderTrip(trip)
-
         // Recording controls are for a parked driver. Live values remain passive and readable
         // while moving; the app never presents an overlay or asks for attention.
         val parked = value.speedKmh?.let { it <= 0.1f } == true
@@ -114,24 +113,49 @@ class MainActivity : AppCompatActivity() {
         }
     }
 
-    private fun renderTrip(summary: EnergyTripSummary?) {
-        binding.tripDurationValue.text = summary?.durationMs?.let(::duration) ?: DASH
-        binding.tripDistanceValue.text = summary?.distanceKm?.let(::distance) ?: DASH
-        binding.tripEnergyValue.text = energy(summary?.consumedKwh)
-        binding.tripRegenValue.text = energy(summary?.regeneratedKwh)
-        binding.tripConsumptionValue.text = consumption(summary?.averageConsumptionKwhPer100Km)
+    private fun renderReadings(readings: DashboardReadings) {
+        bind(binding.socValue, R.string.label_soc, readings.soc, PATTERN_SOC, SOC_UNAVAILABLE)
+        bind(binding.rangeValue, R.string.label_range, readings.range, PATTERN_DISTANCE)
+        bind(binding.speedValue, R.string.label_speed, readings.speed, PATTERN_SPEED)
+        bind(binding.powerValue, R.string.label_power, readings.power, PATTERN_POWER, POWER_UNAVAILABLE)
+        bind(binding.outsideTempValue, R.string.label_outside_temp, readings.outsideTemp, PATTERN_TEMP)
+        bind(binding.batteryTempValue, R.string.label_battery_temp, readings.batteryTemp, PATTERN_TEMP)
+        bind(binding.tripDistanceValue, R.string.label_distance, readings.tripDistance, PATTERN_DISTANCE)
+        bind(binding.tripEnergyValue, R.string.label_energy_used, readings.tripEnergy, PATTERN_ENERGY)
+        bind(binding.tripRegenValue, R.string.label_regenerated, readings.tripRegen, PATTERN_ENERGY)
+        bind(
+            binding.tripConsumptionValue, R.string.label_consumption,
+            readings.tripConsumption, PATTERN_CONSUMPTION,
+        )
+        val recorded = provenance.renderWith(readings.tripDuration, transform = ::duration)
+        binding.tripDurationValue.text = recorded
+        binding.tripDurationValue.contentDescription =
+            provenance.describe(getString(R.string.label_duration), readings.tripDuration, recorded)
+    }
+
+    /**
+     * A reading and its description move together: the visible text says what the value is,
+     * the description says what kind of claim it is and, when it is missing, why. Colour is
+     * deliberately not carrying either — it would say nothing to a screen reader and nothing
+     * in daylight.
+     */
+    private fun bind(
+        view: TextView,
+        label: Int,
+        value: Provenanced<out Any>,
+        pattern: String,
+        unavailable: String = DASH,
+    ) {
+        val rendered = provenance.render(value, pattern, unavailable)
+        view.text = rendered
+        view.contentDescription = provenance.describe(getString(label), value, rendered)
     }
 
     private fun renderUnavailable() {
-        binding.socValue.text = getString(R.string.value_soc_unavailable)
-        binding.rangeValue.text = DASH
-        binding.speedValue.text = DASH
-        binding.powerValue.text = getString(R.string.value_power_unavailable)
-        binding.outsideTempValue.text = DASH
-        binding.batteryTempValue.text = DASH
+        latestReadings = DashboardReadings.empty()
+        renderReadings(latestReadings)
         binding.climateValue.text = DASH
         binding.dataStatus.text = getString(R.string.status_waiting_for_vehicle)
-        renderTrip(null)
         binding.tripAction.isEnabled = false
         binding.tripHint.text = getString(R.string.trip_control_speed_unavailable)
     }
@@ -174,20 +198,31 @@ class MainActivity : AppCompatActivity() {
             appendLine(getString(R.string.diagnostics_properties_hint))
             EVHardware.probeTelemetryProperties().forEach { appendLine(it.toString()) }
             appendLine()
+            // The dashboard has room for an em dash and not for a sentence. The report is
+            // where the sentence goes: per field, what kind of value it is and why it is
+            // missing when it is.
+            appendLine(getString(R.string.diagnostics_provenance))
+            describeReadings(latestReadings).forEach { appendLine(it) }
+            appendLine()
             appendLine(getString(R.string.diagnostics_recent_log))
             append(recentLog.ifBlank { getString(R.string.diagnostics_no_log) })
         }
     }
 
-    private fun percent(value: Float?) = value?.let { format("%.1f %%", it) }
-        ?: getString(R.string.value_soc_unavailable)
-    private fun speed(value: Float?) = value?.let { format("%.0f km/h", it) } ?: DASH
-    private fun power(value: Float?) = value?.let { format("%+.1f kW", it) }
-        ?: getString(R.string.value_power_unavailable)
-    private fun temperature(value: Float?) = value?.let { format("%.0f °C", it) } ?: DASH
-    private fun distance(value: Double?) = value?.let { format("%.1f km", it) } ?: DASH
-    private fun energy(value: Double?) = value?.let { format("%.2f kWh", it) } ?: DASH
-    private fun consumption(value: Double?) = value?.let { format("%.1f kWh/100 km", it) } ?: DASH
+    private fun describeReadings(readings: DashboardReadings): List<String> = listOf(
+        Triple(R.string.label_soc, readings.soc, PATTERN_SOC),
+        Triple(R.string.label_range, readings.range, PATTERN_DISTANCE),
+        Triple(R.string.label_speed, readings.speed, PATTERN_SPEED),
+        Triple(R.string.label_power, readings.power, PATTERN_POWER),
+        Triple(R.string.label_outside_temp, readings.outsideTemp, PATTERN_TEMP),
+        Triple(R.string.label_battery_temp, readings.batteryTemp, PATTERN_TEMP),
+        Triple(R.string.label_distance, readings.tripDistance, PATTERN_DISTANCE),
+        Triple(R.string.label_energy_used, readings.tripEnergy, PATTERN_ENERGY),
+        Triple(R.string.label_regenerated, readings.tripRegen, PATTERN_ENERGY),
+        Triple(R.string.label_consumption, readings.tripConsumption, PATTERN_CONSUMPTION),
+    ).map { (label, value, pattern) ->
+        provenance.describe(getString(label), value, provenance.render(value, pattern))
+    }
 
     private fun climate(value: EnergySnapshot): String = when (value.climate.powerOn) {
         true -> buildString {
@@ -209,5 +244,16 @@ class MainActivity : AppCompatActivity() {
     private companion object {
         const val TAG = "EVChargePilot"
         const val DASH = "—"
+        // The unit-bearing fields keep their unit while unavailable so the layout does not
+        // shift the moment the vehicle starts answering.
+        const val SOC_UNAVAILABLE = "— %"
+        const val POWER_UNAVAILABLE = "— kW"
+        const val PATTERN_SOC = "%.1f %%"
+        const val PATTERN_SPEED = "%.0f km/h"
+        const val PATTERN_POWER = "%+.1f kW"
+        const val PATTERN_TEMP = "%.0f °C"
+        const val PATTERN_DISTANCE = "%.1f km"
+        const val PATTERN_ENERGY = "%.2f kWh"
+        const val PATTERN_CONSUMPTION = "%.1f kWh/100 km"
     }
 }

app/src/main/java/com/evsuite/chargepilot/MainActivity.kt

@@ -0,0 +1,78 @@
+package com.evsuite.chargepilot
+
+import android.content.Context
+import com.evsuite.hardware.telemetry.Provenance
+import com.evsuite.hardware.telemetry.Provenanced
+import com.evsuite.hardware.telemetry.UnavailableReason
+import java.util.Locale
+
+/**
+ * Draws a [Provenanced] value so its kind is visible without a legend.
+ *
+ * The distinction is carried by the text itself, not by colour: an estimate wears a `≈` and
+ * its band, an unavailable figure is an em dash whose reason is spelled out in the reading's
+ * description and in the diagnostics report. That keeps the daylight contrast floor intact
+ * and keeps the meaning available to a screen reader, which a coloured dot would not.
+ */
+class ProvenanceText(private val context: Context) {
+
+    /**
+     * @param pattern a `String.format` pattern carrying the unit, e.g. `"%.1f %%"`.
+     * @param unavailable what stands in for a missing value; the unit-bearing fields keep
+     *   their unit so the layout does not shift when the vehicle starts answering.
+     */
+    fun render(
+        value: Provenanced<out Any>,
+        pattern: String,
+        unavailable: String = DASH,
+    ): String = when (value.provenance) {
+        Provenance.UNAVAILABLE -> unavailable
+        Provenance.MEASURED, Provenance.DERIVED -> format(pattern, value.value!!)
+        Provenance.ESTIMATED -> context.getString(
+            R.string.value_estimated,
+            format(pattern, value.value!!),
+            format(BAND_PATTERN, value.uncertainty!!),
+        )
+    }
+
+    /** Same rules, for a value whose text is not a `String.format` pattern (a duration). */
+    fun <T : Any> renderWith(
+        value: Provenanced<T>,
+        unavailable: String = DASH,
+        transform: (T) -> String,
+    ): String = value.value?.let(transform) ?: unavailable
+
+    /** What the reading is, and — when it is missing — why. Used for accessibility and diagnostics. */
+    fun describe(label: String, value: Provenanced<out Any>, rendered: String): String {
+        val kind = context.getString(
+            when (value.provenance) {
+                Provenance.MEASURED -> R.string.provenance_measured
+                Provenance.DERIVED -> R.string.provenance_derived
+                Provenance.ESTIMATED -> R.string.provenance_estimated
+                Provenance.UNAVAILABLE -> R.string.provenance_unavailable
+            }
+        )
+        val reason = value.reason?.let { context.getString(reasonRes(it)) }
+        return if (reason == null) {
+            context.getString(R.string.provenance_description, label, rendered, kind)
+        } else {
+            context.getString(R.string.provenance_description_missing, label, kind, reason)
+        }
+    }
+
+    private fun reasonRes(reason: UnavailableReason): Int = when (reason) {
+        UnavailableReason.UNSUPPORTED_FIRMWARE -> R.string.reason_unsupported_firmware
+        UnavailableReason.UNVALIDATED_FIRMWARE -> R.string.reason_unvalidated_firmware
+        UnavailableReason.SIGNAL_ABSENT -> R.string.reason_signal_absent
+        UnavailableReason.INSUFFICIENT_SAMPLES -> R.string.reason_insufficient_samples
+        UnavailableReason.MODEL_NOT_TRAINED -> R.string.reason_model_not_trained
+    }
+
+    private fun format(pattern: String, value: Any): String =
+        String.format(Locale.getDefault(), pattern, value)
+
+    private companion object {
+        const val DASH = "—"
+        const val BAND_PATTERN = "%.1f"
+    }
+}

app/src/main/java/com/evsuite/chargepilot/ProvenanceText.kt

@@ -38,5 +38,18 @@
     <string name="diagnostics_no_log">Aucune entrée pour le moment.</string>
     <string name="diagnostics_properties">Propriétés énergie du véhicule</string>
     <string name="diagnostics_properties_hint">Ce que le véhicule répond pour chaque propriété en lecture seule. Une propriété déclarée par le firmware mais jamais publiée est signalée indisponible et affichée par un tiret cadratin sur le tableau de bord, jamais par zéro.</string>
+    <string name="provenance_measured">mesuré par le véhicule</string>
+    <string name="provenance_derived">calculé à partir des mesures véhicule</string>
+    <string name="provenance_estimated">estimé par un modèle</string>
+    <string name="provenance_unavailable">indisponible</string>
+    <string name="provenance_description">%1$s : %2$s, %3$s</string>
+    <string name="provenance_description_missing">%1$s : %2$s, %3$s</string>
+    <string name="reason_unsupported_firmware">cette génération de firmware n\'expose pas le signal</string>
+    <string name="reason_unvalidated_firmware">le signal n\'est pas encore validé sur ce firmware</string>
+    <string name="reason_signal_absent">le véhicule ne publie pas ce signal actuellement</string>
+    <string name="reason_insufficient_samples">pas encore assez d\'échantillons</string>
+    <string name="reason_model_not_trained">le modèle n\'a aucun ajustement pour prédire</string>
+    <string name="diagnostics_provenance">Ce que vaut chaque valeur, et pourquoi elle manque</string>
+    <string name="label_soc">État de charge</string>
 </resources>