ha-vledger

Beta. Everything the design describes is built — capture, trips, refuellings, charging sessions, receipts, metrics, entities, statistics, exports — and runs on the author's vehicle, against whose drives every derivation has been checked; against nobody else's yet. The options may still change between releases, a release may rebuild the derivation from the raw log, and there is no support. The log format is decided and will be read by every later version, so what is captured now is kept. Install it through HACS as a custom repository if you want to try it; this notice goes when the register's checklist for leaving it is met (TASK-0032).

A vehicle ledger for Home Assistant. It keeps a raw log of the handful of vehicle states that matter to a ledger — odometer, position, fuel level, state of charge, charging state — and derives from it what the vehicle's own app never tells you reliably: trips, charging sessions, refuellings, consumption and cost. Passively, from whatever integration already exposes the vehicle, without a line of manufacturer-specific code, and without touching anything else the vehicle reports: it is a ledger, not a monitor.

Status: everything described here is built, in the library and in the integration, and the notice above says what that is worth. Every behaviour is the design, held as requirements in the project's register (ha-vledger-pm).

What it does

• Captures, losslessly. Every change of a source entity you assign to a role becomes one record in a raw log (L0): JSON Lines, append-only, one stream per vehicle and per charge point, rotated monthly, kept outside the Home Assistant recorder and its retention. Start, stop and heartbeat markers make any capture gap visible; nothing is interpolated across one.
• Derives, deterministically. Trips (between standstills), charging sessions (from the charging state), refuellings (a fuel rise at unchanged odometer) and metrics are computed from L0, receipts and configuration (L1) — the same logic live in Home Assistant and in batch from the command line, recomputable from scratch at any time. Every derived value carries a quality flag: measured, receipt, estimated or incomplete.
• Takes receipts. Price and exact quantity come from you: a refuelling or charging receipt, entered from a dashboard, the Vehicle Ledger card beside its trip list, or an action — a notification of the new candidate opens the form — matched to the detected event by time. Receipt values beat sensor values; a detected event without a receipt stays visible as unconfirmed.
• Knows your charge points. Home, work, anywhere fixed: position, radius, tariff, optionally a meter. A charge point with a tariff but no meter still yields cost, estimated through a charging loss factor; a tariff of 0 is cost 0. Anything else is a foreign charge and asks for a receipt.
• Reports. Per month, year and rolling period: distance, litres and kWh, fuel and electricity cost, the cost per 100 km per energy carrier, the electric share two ways (energy by heating value, and an estimated distance share), charge cycles and tank-fill equivalents. Fuel consumption is tank-to-tank between any two receipts, corrected by the fuel level sensor, so a tank that is never filled up still gets a figure. A single trip's fuel and battery energy are its own figures beside that, in litres and kWh and per 100 km, from the trip computer or the sensor deltas, shown when they exceed their possible error or are right to the step they are shown in — an electric trip read from the trip computer is 0 L. A trip's cost is that consumption at the last prices known when it started.

What it is built of

One repository, two packages, one version number (ADR-0002):

src/vledger/               the library and the vledger CLI: all derivation
                           logic, no Home Assistant, no dependencies;
                           published to PyPI as `vledger`
custom_components/vledger/ the Home Assistant integration, a shell over the
                           library: capture, config and options flows,
                           entities, actions, diagnostics, and the Lovelace
                           card as plain JavaScript under frontend/; pins
                           the library by the same version in manifest.json
tests/                     pytest: library tests on L0 fixtures, integration
                           tests with pytest-homeassistant-custom-component;
                           the card's model with Node's own test runner
docs/                      design documents, operating manuals, the user guide

A vehicle is a config entry; its source entities are assigned to roles (odometer, position, fuel_level, soc, charging_state, …), and what the vehicle can do follows from the roles it has. Everything is configured in the UI; no YAML.

Documentation

Decisions, requirements and the work queue are records in the project's register, ha-vledger-pm, not prose here.

Installing

Through HACS, as a custom repository while the notice above stands: Integrations → ⋮ → Custom repositories, add https://github.com/michael-lenz/ha-vledger as an Integration, install it and restart; or copy custom_components/vledger into the configuration directory by hand. Either way Home Assistant installs the library from PyPI (vledger==<version>, pinned in the manifest). Then Settings → Devices & services → Add integration → Vehicle Ledger: the user guide walks the four steps. The library on its own: pip install vledger, which brings the vledger command. A development checkout runs differently — docs/developing.md.

Developing

docs/developing.md is the manual; the short form:

python3 -m venv .venv && .venv/bin/pip install -e ".[dev,ha]"
.venv/bin/python -m pytest -q
.venv/bin/ruff check src tests custom_components
node --test tests/frontend/model.test.mjs

The library's tests run in any Python with .[dev]; the integration's need the ha extra and a venv; the card's need Node and nothing else. CLAUDE.md says how a Claude session works here and with the register.

Privacy

The position history is personal data. It stays on your instance — nothing is transmitted anywhere — and is redacted from logs and diagnostics, but the default storage path lies under the Home Assistant configuration directory and is therefore part of your backups.

License

BSD-3-Clause — see LICENSE.