tajniak81andClaude Opus 5
340a81b0d6
The HabuDen has no cloud API to connect to. It is commissioned over Bluetooth in
the Greencell GC app, pointed at an MQTT broker the owner runs, and from then on
publishes there — so the connector is an MQTT client rather than an HTTP one,
and nothing in it reaches Greencell. The wire contract is Home Assistant's own
greencell component and the greencell_client 1.0.3 library beneath it, which is
the only published description of the topics: a BROADCAST on /greencell/broadcast
draws device announcements, and /greencell/evse/{sn}/ carries current in
milliamps, voltage, power under "momentary", the EVSE state, and the access level
chosen in the app.
That meant an MQTT client, and the server takes no dependencies, so internal/mqtt
is hand-rolled the way internal/ocpp's RFC 6455 layer is. It is scoped to what
this connector needs and says so: QoS 0 for everything we send, clean session,
no reconnect — a connection lives for one plugin call, which is exactly how the
manager builds and tears down an instance. Inbound PUBLISH is accepted at QoS 0,
1 and 2 with the acknowledgements each requires, because the QoS of a delivery is
the broker's choice and not ours; an unacknowledged QoS 1 is redelivered forever.
Read-only, and the reason is worth writing down rather than rediscovering. A
device in EXECUTE mode accepts START, STOP, SET_CURRENT and QUERY — but the topic
those go to appears in no source: not Greencell's integration page, not
greencell_client, and Home Assistant ships sensor-only for that same reason.
Publishing to a guessed topic would be a control feature whose failure mode is a
driver believing they stopped a charge. So the access level is reported, and
commandTopic is the seam: an operator who has watched their own broker and found
theirs sets it, and a state read then sends QUERY — the one command a READ-mode
device also honours — instead of waiting out the charger's publish cadence. The
day the topic is public, control is a payload away from the same field.
What the cascade resolves here is a broker, not an account, so host, port, TLS and
credentials resolve together from the highest layer that names a host: an
organization's address paired with a user's password would address a broker with
credentials never meant for it. The serial, the QUERY topic and the listen window
each describe the charger rather than the endpoint, so each resolves on its own.
Two reading rules the tests pin. A phase the device did not report stays nil
rather than zero, because zero amps on a charger is a real measurement — a JSON
null decoding to 0.0 was a live bug until a test caught it — and a partial read
returns with received/complete flags instead of failing, since a device that
publishes some topics on a slower cadence is still worth reading. And a reachable
broker with no charger on it is degraded, not down: the half we configure works
and the missing half is the device. The plugin's end-to-end tests run against an
in-process broker written to the raw wire format, so a bug in the client cannot
hide behind a matching bug in the fixture.
The apps get the third connector card. The panel needed nothing — it renders a
plugin's ConfigFields itself — but the per-user panes are still hand-written per
integration, which is now three near-copies and the argument for the generic
version already noted in the plugins README. The web form splits the broker from
the charger because the server resolves them differently. The phone card is a
declarative config against the shared widget, which gained a number field type, a
degraded state that reads amber rather than red, and a fix for a locked field
that was covering its own displayed value with dots. Twenty keys in three
languages across both apps; Greencell, HabuDen and the literal QUERY join the
proper nouns that stay in English.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
140 lines
7.6 KiB
Markdown
140 lines
7.6 KiB
Markdown
# DriverVault
|
|
|
|
A car control & service-tracking system (originally "Car Control Project").
|
|
Built incrementally — starting with a **car maintenance tracker** (modeled on
|
|
`Car Service.xlsx`) and growing toward live integration with the car via a
|
|
cellular ESP32 device and third-party services (Toyota Connected, EV chargers).
|
|
|
|
## Architecture
|
|
|
|
All clients communicate with the database **only through the API Server** —
|
|
nothing talks to PocketBase directly.
|
|
|
|
```
|
|
┌──────────────────┐
|
|
Web App (Vue) ─────▶│ │
|
|
Phone App (Flutter)▶│ API Server │────▶ PocketBase
|
|
Home Assistant ────▶│ (Go, stdlib) │ (10.2.1.10:8027)
|
|
Car Agent (ESP32) ─▶│ │
|
|
└──────────────────┘
|
|
```
|
|
|
|
| Component | Stack | Status | Docs |
|
|
|---|---|---|---|
|
|
| **API Server** | Go (stdlib) | ✅ built, running, verified | [API Server/README.md](API%20Server/README.md) |
|
|
| **Database** | PocketBase | ✅ running, schema + seed done | — |
|
|
| **Web App** | Vue 3 + Vite + Tailwind v4 | ✅ full feature set (below) | [Web App/README.md](Web%20App/README.md) |
|
|
| **Phone App** | Flutter (Android) | ✅ web parity + biometric login | [Phone App/README.md](Phone%20App/README.md) |
|
|
| **Docker** | Compose (multi-container / all-in-one) | ✅ deployment configs | [Docker/README.md](Docker/README.md) · [Docker-AIO/README.md](Docker-AIO/README.md) |
|
|
| **Car Agent Device** | ESP32 + SIM7600 (LILYGO TTGO) | 🚧 firmware in progress | [Car Agent Device](Car%20Agent%20Device) |
|
|
| **Home Assistant Plugin** | — | ⬜ later | — |
|
|
|
|
The Web and Phone apps are at feature parity.
|
|
|
|
## Features
|
|
|
|
- **Maintenance tracking** — cars, service history (date/odometer + which parts
|
|
were changed), and a per-car parts catalog, with next-due date/km status from
|
|
the spreadsheet formulas.
|
|
- **Technical checks** — the mandatory roadworthiness inspections (przegląd
|
|
techniczny / MOT / TÜV): result, cost, station and the certificate's
|
|
valid-until, which overrides the car's interval and drives the next-due date.
|
|
- **Maintenance log** — workshop visits and repairs outside the routine schedule:
|
|
type/status, workshop, parts used, labour + parts cost, invoice, warranty-until.
|
|
- **Fuel tracking** — refills with derived efficiency (average / best / worst
|
|
consumption, cost per km, price per litre). Consumption is measured between
|
|
full tanks, so partial fills roll into the next full one.
|
|
- **Documents** — insurance, registration, road tax and the rest, each with a
|
|
server-computed renewal/expiry state.
|
|
- **Reminders** — date- and/or odometer-triggered, one-off or recurring, plus
|
|
read-only reminders the server derives from documents and service records.
|
|
- **Attachments** — one optional file (PDF or image) per service record,
|
|
technical check, maintenance entry, refill, document and part; fetched back
|
|
through the API Server, never a public URL.
|
|
- **Accounts** — PocketBase-token login, profile + appearance preferences
|
|
(theme/locale/date format/currency/font), avatar, email verification, data
|
|
export/import, and an account-deletion state machine.
|
|
- **Organizations & roles** — multi-tenant `user` / `admin` / `superadmin`
|
|
roles; admins manage users within their own organization, superadmins span all.
|
|
Any user without an organization can create one and becomes its admin.
|
|
- **Per-user ownership & sharing** — each car has an owner and can be shared with
|
|
other users as read or write; the UI mirrors the server's access checks.
|
|
- **Integrations** — per-user connectors under a superadmin → org-admin → user
|
|
cascade. Built-in today: **Toyota Connected** (read-only vehicle data), the
|
|
**Anker Solix** V1 EV charger and the **Greencell** HabuDen wallbox (read over
|
|
the owner's own MQTT broker — no Greencell cloud is involved).
|
|
- **Cars from the manufacturer's own service** — import a car straight off a
|
|
connected account (MyToyota today), choosing what to pull in, and read everything
|
|
that service knows about it from a dedicated first tab on the car. Generic over
|
|
providers: the next manufacturer is one adapter in the API Server.
|
|
- **EV charging control** — for Anker Solix chargers the API Server runs an
|
|
**OCPP 1.6J Central System**; in own/proxy mode the charger dials back in and
|
|
the owner can start/stop and set limits from the Charging screen.
|
|
- **Translated UI** — the interface reads its text from per-language files
|
|
(English, Polish, Danish today), with English as the fallback for any
|
|
untranslated string. See [TRANSLATIONS.md](TRANSLATIONS.md).
|
|
- **Phone biometric login & app lock** — fingerprint / face sign-in with an
|
|
app-lock that requires an unlock on relaunch. See the Phone App README.
|
|
|
|
## Auth model
|
|
|
|
All apps share one auth model: **authentication is PocketBase's own.**
|
|
`POST /api/auth/login` is proxied to the PocketBase users collection and the
|
|
client keeps the token PocketBase minted — the API Server does **not** issue its
|
|
own JWT. Every protected request carries `Authorization: <token>` (both
|
|
`Bearer <token>` and a raw token are accepted) and the server re-resolves it
|
|
against PocketBase on each call, so a role change or a deletion takes effect
|
|
immediately. Tokens are stateless, so there is no per-device session list;
|
|
changing an account's password rotates its token key and invalidates every token
|
|
already issued. Access to cars/records is gated by per-user ownership and shares;
|
|
user management requires the admin or superadmin role. Creating an organization
|
|
is the one management action open to a plain user — it promotes them to admin of
|
|
the organization they just created.
|
|
|
|
## Domain (from `Car Service.xlsx`)
|
|
|
|
- **Cars** — one per vehicle (was: one spreadsheet sheet), with spec fields
|
|
(engine / transmission / differential oil, brake fluid, coolant, VIN, fuel
|
|
type, build / first-registration dates, …) and configurable service intervals.
|
|
- **Service records** — date + odometer per service, plus which parts were
|
|
changed (oil & oil filter, engine air filter, cabin air filter).
|
|
- **Parts** — per-car catalog of part numbers.
|
|
|
|
Key spreadsheet formulas, reproduced by the API Server on read:
|
|
|
|
```
|
|
Next Service Date = service date + serviceIntervalDays (default 365; Excel: =A+365)
|
|
Next Service Km = service km + serviceIntervalKm (default 15 000; Excel: =B+15000)
|
|
```
|
|
|
|
Intervals are configurable per car.
|
|
|
|
## Getting started
|
|
|
|
Bring up the stack in this order — each app's README has the details:
|
|
|
|
1. **[API Server](API%20Server/README.md)** — configure `.env`, run
|
|
`setup-pocketbase.mjs`, start the server. This must be running for either app.
|
|
2. **[Web App](Web%20App/README.md)** — `npm install && npm run dev`
|
|
(proxies `/api` to the server).
|
|
3. **[Phone App](Phone%20App/README.md)** — `flutter build apk` /
|
|
`flutter run` with `--dart-define=API_BASE=http://<server-ip>:8080/api`.
|
|
|
|
Or skip all of that and bring the whole stack up with **Docker**, which runs the
|
|
schema setup itself — see [Docker](Docker/README.md) (PocketBase + API Server +
|
|
Web App as three containers) or [Docker-AIO](Docker-AIO/README.md) (all three
|
|
in a single image).
|
|
|
|
## Layout
|
|
|
|
```
|
|
DriverVault/
|
|
├── API Server/ # Go gateway to PocketBase (the only DB client)
|
|
├── Web App/ # Vue 3 + Vite + Tailwind v4 SPA + Go BFF
|
|
├── Phone App/ # Flutter (Android)
|
|
├── Car Agent Device/ # ESP32 + SIM7600 firmware (LILYGO TTGO T-SIM7600)
|
|
├── Home Assistant Plugin/ # later phase
|
|
├── Docker/ # Compose deployment (API Server + Web App)
|
|
└── Docker-AIO/ # single all-in-one image
|
|
```
|