Vehicle Consumption

Features

• One entry per vehicle, set up from its device: the odometer and the fuel and battery sensors are detected automatically, or you pick them yourself
• Fuel, electric and plug-in hybrid: fuel used (L) and energy used (kWh) worked out from the level changes; miles, US gallons and Wh converted
• Refuels and charges detected when the level jumps up (3 L / 1 kWh by default), small sensor jitters ignored
• Trips: a trip starts when the odometer moves and ends after a gap without driving (30 minutes by default), with its distance, consumption and cost
• Consumption in L/100 km and kWh/100 km for the last trip, the current month and on average
• Cost: fuel and electricity prices from a sensor (such as ha-carburants-france) or fixed; cost of the month and cost per km
• CO₂: the CO₂ of the fuel burnt (by fuel type: petrol, diesel, LPG, E85) and of the energy charged (grid factor in g/kWh, French grid by default), per trip, per month and per km
• History kept across restarts: the last 24 months, and every trip, refuel and charge of the last 365 days, rebuilt from the recorder for the days the tracking does not cover yet
• Actions to log a refuel or a charge by hand (add_refuel, add_charge) to start over (reset_statistics) or to rebuild everything from the recorded history (import_history)
• Service reminder: log a service with its interval (log_service), and the Next service sensor counts the distance left, negative once overdue
• CSV export of every trip, refuel and charge kept (export), for a spreadsheet
• Lovelace card bundled with the integration, added automatically to the dashboard resources (nothing to add by hand): fuel and battery gauges, trip / month / average / cost per km tiles, monthly chart (consumption, distance, cost or CO₂), CO₂ per km under the cost per km, recent trips and refuels or charges, a pulsing dot while driving, a popup to log a refuel or a charge; visual editor
• UI setup, no YAML; English, French, German, Spanish, Italian, Dutch, Portuguese, Polish, Romanian, Danish, Swedish, Bulgarian, Russian, Ukrainian, Hungarian, Slovak, Czech, Slovenian, Latvian, Greek and Serbian (Cyrillic and Latin)

Supported integrations

The odometer and the fuel and battery sensors of these integrations are detected from their own sensor keys, read from each integration's source code. The setup form comes prefilled; check it and change what you want.

¹ Disabled by default in Tesla Fleet and Teslemetry: enable the Odometer entity first. ² Teslemetry and Tessie. ³ On an electric Ford, FordPass reports the battery level there. ⁴ The Leaf integration has no odometer: pick one from another source. ⁵ WiCAN, depending on the vehicle profile.

Any other vehicle integration works too, as long as its device has an odometer plus fuel sensors (litres or gallons, or a level in %) and/or battery sensors (kWh, or a level in %): they are recognised from their names, units and device classes, or picked by hand. Units are converted (miles and metres to km, US gallons to litres, Wh, kJ and MJ to kWh). A level in % needs the tank or battery capacity to be turned into litres or kWh. The setup starts from the vehicle's device, so sensors without one (Torque) cannot be used.

Home chargers#

For an electric or plug-in hybrid car, the energy counter of your home charger is found automatically (it is another device) and measures home charges at the charger, losses included:

• evcc (Marketplace, evcc_intg): Charged (Total) of the loadpoint, else Session energy / Charge energy
• Easee (Marketplace): Lifetime energy, else Session energy
• Zaptec (Marketplace): Energy meter, else Session total charge
• Wallbox (official integration): Added energy
• Ohme (official integration): Energy (Home Assistant before 2026.7)

Any other energy sensor (kWh or Wh) that counts what the charger delivers works too, picked by hand: a total counter or a session counter that goes back to 0.

Prerequisites

• Home Assistant 2024.12 or newer
• A vehicle integration with an odometer and at least one fuel or battery sensor

Configuration

Settings → Devices & services → Add integration → Vehicle Consumption, once per vehicle:

1. Pick the vehicle (its device from the car integration) and give it a name
2. Check the sensors: the odometer and the fuel and battery sensors found on the device are filled in; change or complete them if needed
3. Set the prices (a price sensor, such as a station of ha-carburants-france, or a fixed price)

Everything can be changed later with Configure, which also holds the trip and refuel/charge thresholds.

At least one fuel or battery sensor is needed. A vehicle with only fuel sensors is tracked as fuel, with only battery sensors as electric, with both as plug-in hybrid.

Entities#

One device per vehicle; the entities only exist when they make sense for it (fuel_* with fuel sensors, energy_* with battery sensors). For a vehicle named My car:

Actions#

vehicle_consumption.add_refuel#

Logs a refuel by hand: it shows up in the card's refuels with source manual. Consumption still comes from the sensors, so a manual refuel does not change it. Fields: config_entry_id (the vehicle, required), liters (required), cost (total), price (per litre), odometer (in the unit of the odometer sensor: miles for a car that reports miles; the last reading when left out).

action: vehicle_consumption.add_refuel
data:
  config_entry_id: 01JC0EXAMPLE0000000000000
  liters: 42.5
  cost: 74.80

For example from an automation, when a fuel card notification or a script tells you what you paid:

triggers:
  - trigger: event
    event_type: fuel_receipt
actions:
  - action: vehicle_consumption.add_refuel
    data:
      config_entry_id: 01JC0EXAMPLE0000000000000
      liters: "{{ trigger.event.data.liters }}"
      price: "{{ trigger.event.data.price }}"
      odometer: "{{ states('sensor.my_car_mileage') | float(0) }}"

vehicle_consumption.add_charge#

Same for a charge: config_entry_id, energy (kWh, required), cost, price (per kWh), odometer.

action: vehicle_consumption.add_charge
data:
  config_entry_id: 01JC0EXAMPLE0000000000000
  energy: 31.2
  price: 0.2516

vehicle_consumption.log_service#

Logs a service done on the vehicle, at odometer (the odometer sensor's unit; the current reading when left out), with interval, the distance to the next one (the odometer sensor's unit; the one logged before when left out, 0 turns the reminder off). The Next service sensor (sensor.<vehicle>_next_service) then gives the distance left, negative once overdue, with last_service, last_service_odometer, interval and overdue as attributes. Kept across restarts and through reset_statistics. Open to every user, like a refuel.

action: vehicle_consumption.log_service
data:
  config_entry_id: 01JC0EXAMPLE0000000000000
  interval: 15000

A reminder 500 km before:

triggers:
  - trigger: numeric_state
    entity_id: sensor.my_car_next_service
    below: 500
actions:
  - action: notify.mobile_app_phone
    data:
      message: "Service due in {{ states('sensor.my_car_next_service') | int }} km"

vehicle_consumption.export#

Writes every trip, refuel and charge kept (the last 365 days) to a CSV file, newest first, in the units chosen: one row each with type (trip, refuel, charge), start, end, distance, fuel, energy, liters, cost, price, odometer, the consumptions, co2, source and estimated. path is optional: vehicle_consumption_<vehicle>.csv in the configuration folder by default; a relative path is inside the configuration folder, an absolute one must be in the configuration folder or in allowlist_external_dirs; it must end in .csv, and hidden folders such as .storage are refused. Returns the path and the number of rows. Administrators only.

action: vehicle_consumption.export
data:
  config_entry_id: 01JC0EXAMPLE0000000000000
  path: exports/car.csv
response_variable: result  # {"path": "/config/exports/car.csv", "rows": 412}

vehicle_consumption.reset_statistics#

Clears the trips, months, refuels, charges and totals of a vehicle and starts over. Administrators only.

action: vehicle_consumption.reset_statistics
data:
  config_entry_id: 01JC0EXAMPLE0000000000000

vehicle_consumption.import_history#

Administrators only. Rebuilds the trips, months, refuels and charges of a vehicle from what Home Assistant recorded of its sensors over the last days (365 by default, up to 730). The recorder's states are used where it still has them (10 days by default); before them, the hourly long-term statistics of the sensors stand in (kept for good for sensors with a state class: the hourly state of a mileage or a fuel quantity, the hourly mean of a level in % or a price), so older trips are found to the hour (each hour counts in its own month: the hour before midnight on the last day of a month stays in that month; with a half-hour or quarter-hour offset, as in India, Iran, Nepal, Newfoundland or South Australia, the hour across that midnight is shared between the two months in proportion, and so is the hour across midnight for a level whose statistics are hourly means). The total is always exact. When a counting sensor was only recorded after the tracking started, the import keeps the months before it as tracked, those in the hourly statistics included; when every counting sensor was recorded from before the tracking, the import rebuilds every month from the history, and a month start that falls inside such a shared hour may then move up to what was driven or used in that hour from one month to the next. Those hours are only used once the odometer and every fuel or battery sensor that does the counting have statistics: a level without a state class has none, and the import then starts with the recorded states. Refuels and charges logged by hand are kept. It runs on its own once, over 365 days, when the vehicle is added, so the card is filled from the first day.

At every start of Home Assistant and every reload of the vehicle, the days of the last 365 that are not counted yet (before the tracking started, an import over fewer days included) are read from the history and added before the tracked figures, which stay exactly as they are; each period is read once.

An import never replaces what was tracked with less:

• A source missing from the history: when the odometer or a fuel or battery sensor that does the counting has no usable recorded reading (excluded from the recorder, only unavailable or unknown, new or just changed), the import changes nothing.
• A source no longer recorded: when a source's current reading is not its last recorded one (excluded from the recorder since), the import changes nothing, as long as something is already tracked.
• Partly covered months: the replay only stands in from the month after the one where every counting source has its first recorded reading; the months before keep their trips, figures, refuels and charges as tracked, even when one source was recorded from before the tracking started (a source first recorded within 5 minutes of the tracking start, the same poll, covers it). When every source was recorded from before the tracking started, the replay stands in for all of it.
• Less than tracked: if the replay still ends with less distance (by more than 1 km), fuel or energy (by more than 1 L / kWh and 5 %) than tracked, in total, in any month, in the trips or in the trip being driven (a sensor recorded only from the middle of it), the recorder has a gap: everything stays as tracked and a warning is logged. The same goes for the cost: a tracked cost is never replaced by none (a price sensor excluded from the recorder and not available yet when the import runs) nor by less (by more than 1 and 5 %).

The charger counter is optional and is not required for an import.

action: vehicle_consumption.import_history
data:
  config_entry_id: 01JC0EXAMPLE0000000000000
  days: 60

Events#

vehicle_consumption_trip_ended#

Fired once per trip, when it is final: the trip gap after the odometer last moved, or 65 minutes if the trip gap is shorter. A trip shows up in the trips list after the trip gap, but an odometer polled hourly (Renault, MyPeugeot…) can still report the rest of the same drive within the hour and reopen it; the event waits until that can no longer happen, so it carries the figures of the whole drive, and a trip announced is never reopened (a later reading starts a new trip). A new trip starting makes the previous one final at once. Only for trips closed while Home Assistant runs (not for a trip closed at startup, which ended while it was stopped, nor for trips found in the history), and only when the odometer moved. The figures are in the units of the Units option.

triggers:
  - trigger: event
    event_type: vehicle_consumption_trip_ended
    event_data:
      vehicle: My car
conditions:
  - condition: template
    value_template: "{{ trigger.event.data.distance >= 5 }}"
actions:
  - action: notify.mobile_app_phone
    data:
      title: Trip ended
      message: >-
        {{ trigger.event.data.distance }} km in {{ trigger.event.data.duration }} min,
        {{ trigger.event.data.fuel_consumption }} L/100 km, {{ trigger.event.data.cost }} €

Diagnostics#

Settings → Devices & services → Vehicle Consumption → ⋮ → Download diagnostics gives the entry, the tracked figures and the current state of each source sensor. VINs, plates, GPS positions, addresses and account data (user names, e-mails, tokens) are replaced by **REDACTED**.

Card#

The card is added to the dashboard resources by the integration. Add it from the dashboard (Add card → Vehicle Consumption Card) or in YAML:

type: custom:vehicle-consumption-card
entity: sensor.my_car_consumption

In the visual editor, Vehicle lists every vehicle set up in Vehicle Consumption, by name: nothing to look up, and a vehicle added later shows up in the list. The card picker previews the card with your first vehicle.

The badge in the header is a gauge whose colour gives the state of the vehicle: the primary colour when all is well, green while driving, orange when the fuel or battery is low, grey when the vehicle is not available.

The + button opens a popup at the top of the card to log a refuel (litres) or a charge (kWh), its total cost and, optionally, the odometer. The popup is modal: Tab stays inside it, Escape closes it and the focus goes back to the + button. The sections fold and unfold with a tap, and fold back on their own when you tap elsewhere.

Mini card#

A compact view of the vehicle (Add card → Vehicle Consumption Mini Card): the header with the average consumption, the fuel and battery gauges, the last trip and the average. Its detail button at the top right opens the full card in place; a tap outside the card brings the compact view back. It takes the options of the full card (used by the full view), plus:

type: custom:vehicle-consumption-mini-card
entity: sensor.my_car_consumption

The card picker shows both cards with their name and description in Home Assistant's language.

How it works

Vehicle Consumption follows the levels reported by the car rather than asking you to log every refuel.

When a vehicle is added, the last 365 days of its sensors are replayed once, in order, as if the integration had been there: the past trips, refuels and charges are found the same way, at the prices of then when a price sensor is used (its value when the period starts, else the first one recorded). The recorded states give every reading (as long as the recorder keeps them, purge_keep_days: 10 days by default); before them, the hourly statistics give one reading an hour, so a trip there only ends after an hour parked.

• Reference level: for fuel (L) and energy (kWh), it keeps a reference level. When a reading goes down, the difference is counted as used and the reference follows. When it goes up by at least the threshold (3 L / 1 kWh by default), it is a refuel or a charge: the amount added is recorded, with its cost at the current price. A smaller rise is sensor noise (a tank sloshing, a battery warming up) and is ignored. unknown and unavailable readings are skipped. A level in % is turned into litres or kWh with the capacity you set; when a quantity (L) or energy (kWh) sensor is set too, the level is only shown, the quantity does the counting. A sensor can be used for one source only.
• Home charger: with a charger energy counter, a home charge is the counter going up, until it has not moved for 30 minutes. Its amount is what the counter delivered (losses included; a session counter going back to 0 starts a new session) and its cost that amount × the electricity price; it is listed as Home charger. A battery rise while the counter moves is that session, never counted twice; a battery rise while the charger is idle is a charge away from home, recorded as before. The energy used still comes from the battery going down.
• Distance: every rise of the odometer is added up (a jump over 2000 km is ignored as a glitch).
• Trips: a trip starts when the odometer moves and ends after the trip gap (30 minutes by default) without moving. Its distance, fuel, energy and cost are what was counted between its start and its end.
• Estimated trips: a coarse sensor (Renault reports whole litres) cannot measure a short trip: 11 km shows no drop (0 L, 0 €) and the next 2 km trip gets the whole litre. The step of the sensor is learnt from its readings (1 L for whole litres, 1 % of the capacity for a level); when a trip's expected use is under 5 steps, its fuel or energy is the distance × the average consumption of the months up to the trip covering at least 300 km (else of the whole period), its cost follows at the current price, and it is marked estimated: true (≈ Estimated in the card's trip list, also in the trip sensors and the vehicle_consumption_trip_ended event). Only what is shown is estimated: the stored trips, the months and the total stay measured, so their sums stay true; the estimate applies to stored trips too, once the sensor's step has been seen after an update. A fine-grained sensor (hundredths of a litre) keeps its trips measured.
• Prices: the fuel price per litre and the electricity price per kWh come from a sensor (such as the station prices of ha-carburants-france, or your electricity tariff) or a fixed value; a sensor wins over the fixed price. While the sensor is unknown or unavailable (a best-price sensor with no station for a while, a restart), its last price is used, and kept across restarts. Without any price, cost stays empty.
• CO₂ is the fuel used × the factor of its type (tailpipe CO₂ per litre: petrol 2.31 kg, diesel 2.68 kg, LPG 1.66 kg, E85 1.61 kg) plus the energy used × the grid factor (g/kWh, set in the options). It is worked out from the counted totals, so changing a factor applies to the whole history. Per km it is shown from 5 km, like the consumption.
• Consumption is the amount used divided by the distance, × 100. Under 5 km it is not shown: too short to mean anything.
• History: months are kept for 24 months (local time), trips, refuels and charges for 365 days (the card lists the newest, with the count of the year). The days of the last 365 that are not counted yet are added from the recorder's history at every start and reload. Everything is stored in .storage/vehicle_consumption.<entry_id> and survives restarts.

Support

If you find this project useful, you can support its development:

Features

• show_title option (also in the visual editor) hides the header's title, for a card placed under a section heading of its own (asked in juju35/ha-vehicle-card#72).

Maintenance

• No code change: released again to check the installation from the Marketplace.

Features

• Service reminder: vehicle_consumption.log_service logs a service (at the current or a given odometer) and the distance to the next one; the new Next service sensor gives the distance left, negative once overdue, with the last service and the interval as attributes. Kept across restarts and through reset_statistics; interval: 0 turns it off.
• CSV export: vehicle_consumption.export writes every trip, refuel and charge kept to a CSV file (in the configuration folder or allowlist_external_dirs, never a hidden folder), one row each with the same columns. Administrators only; returns the path and the number of rows.

Performance

• Translations load on demand: in the release zip, the frontend files keep English only (vehicle-consumption-card.js 118 KB → 70 KB) and each other language is its own <file>.i18n.<lang>.js file next to them, fetched the first time a card or the panel needs it. Home Assistant loads the card on every dashboard, so each page used to download and parse all 22 languages to use one. The cards and panel are defined once the page's language has arrived (a few milliseconds), so they render translated from the start.

Maintenance

• The Marketplace now installs the release zip (zip_release), like the other ha-* integrations: the split files are only in it.
• The repository keeps every language in the sources: the release runs scripts/split-frontend.mjs before building the zip, and the Validate workflow checks the split on a copy (every table is rebuilt from the split files and compared).

What's new

• New mini card (custom:vehicle-consumption-mini-card): gauges, last trip and average, with a detail button that opens the full card.
• The card picker names and describes both cards in Home Assistant's language.
• The refuel popup is modal for assistive technology: Tab stays inside it and the focus goes back to the add button when it closes.

Fixes

• In imperial units, the tank capacity, fixed fuel price and refuel threshold are typed in US gallons and per gallon (stored in litres), and a new vehicle defaults to imperial when Home Assistant uses US customary units.
• Switching the units option no longer changes the sensors' native units, which broke their long-term statistics: consumption, cost and CO₂ per distance stay metric with the imperial figure in attributes, and distances and volumes are shown in miles and gallons by Home Assistant.
• Short trips from a sensor in whole litres (Renault) no longer show 0 L and 0 € or a whole litre for 2 km: under 5 steps of the sensor, a trip's fuel or energy is estimated from its distance and the recent average consumption, marked estimated (≈ in the card); months and totals stay measured.

What's new

• New option Units: imperial shows miles, US gallons, mpg, mi/kWh and the cost and CO₂ per mile on the card, in the main sensor's attributes, in the trip ended event and in the consumption sensors (metric stays the default).
• The odometer given to add_refuel / add_charge is read in the unit of the vehicle's odometer sensor (miles for a car reporting miles), and the card's refuel popup takes gallons in imperial units.

Fixes

• vehicle_consumption_trip_ended is fired once per trip with its final figures: it waits until an hourly odometer can no longer reopen the trip (65 minutes, or the trip gap if longer), instead of firing for each part of a drive.
• The main sensor no longer records its card data (trip, month, total, levels, prices, odometer, counts) in the history at every change.