fix(hev): read the energy counters as fuel, not kilowatt-hours

[joszz]

What was wrong

On a plain hybrid the dashboard reported 394.0 kWh used today over 59 km, and an efficiency of 6678 Wh/km. Both are physically impossible: 394 kWh is four times a large EV pack.

The gateway publishes drivetrain/powerUsageOfDay on the same topic for every drivetrain, but a plain hybrid has no traction battery worth metering. The trip computer puts its fuel total there instead, in hundredths of a litre. The real reading was 3.94 L over 59 km, or 6.7 L/100 km.

The same car's soc_kwh and totalBatteryCapacity are the BMS percentage scaled by an EV-sized 72.5 kWh default, roughly forty times the real 1.83 kWh pack. The percentage behind them is genuine; only the kWh are invented.

Verifying the scale

The hundredths-of-a-litre scale is measured, not assumed. Regressing the counter against the fuel gauge within each tank over 90 days of production data from an MG HS Hybrid+ gives 20 tanks with r2 between 0.94 and 0.997, implying a 54.7 L tank against the 55 L the car actually has.

Supporting evidence: the counter over distance lands between 5.5 and 8.0 on normal days and 8.9 to 12.3 on short-distance days, exactly how a hybrid behaves on cold short trips. Independently, integrating HvPower across SoC changes puts the pack at 1 to 2 kWh, and the largest observed SoC swing (27.9 points in 38 s) needs 2607 kW at 72.5 kWh but a plausible 65 kW at 1.83 kWh.

What changes

Card	Before	After
Energy today	394.0 kWh	Fuel today 3.9 L
Efficiency	6678 Wh/km	Consumption 6.7 L/100km
HV Battery (expanded)	56.8 kWh / 72.5 kWh	1.4 kWh / 1.8 kWh
Daily chart (Statistics)	Daily Electric Usage (kWh)	Daily Fuel Use (L)

The 78% summary is unchanged, because it was already correct.

BEV and PHEV behaviour is untouched, since their counters really do hold kWh.

How

• Interpretation lives in one place, frontend/src/utils/energy.ts. energyUnit() decides litres vs kWh from the drivetrain; hvBatteryReading() resolves charge, stored energy and capacity together.
• dailyEnergyKwh becomes dailyCounterTotal: the reset detection was always unit-agnostic, only its name claimed otherwise.
• The HV card now takes charge and capacity as separate props instead of deriving a percentage from two numbers it could not trust, keeping the presentation free of that judgement.
• Capacity is deployment configuration (HV_BATTERY_CAPACITY_KWH / HvBattery__CapacityKwh), served on the vehicle list DTO beside the detected drivetrain. Left unset, a plug-in car keeps the gateway's figure and a hybrid shows percentages only, rather than a confident wrong number. Wired into compose, .env.example, the all-in-one entrypoint and the Unraid template.

Deliberately left alone

The widget API still exposes the raw counter as powerUsageOfDayKwh. Renaming it would break existing Homepage widget configs, so the hybrid caveat is documented in the README table instead.

Testing

• 338 frontend tests pass, including new coverage for the unit split, the L/100 km conversion, capacity rescaling and the hybrid-without-capacity case.
• 474 backend tests pass, including new coverage for the capacity config (unset, blank, unparseable, zero and negative all stay unknown).
• Prettier, ESLint, oxlint, stylelint and vue-tsc all clean.

🤖 Generated with Claude Code