nilsandClaude Opus 5.5
ca2f899403
ABRP keeps getting live data while the car server is down: with an ABRP API key and user token set in the app (Live data tab, or abrp_api_key / abrp_token in the config file), the car sends the newest sample to ABRP itself at every upload. It tells the server the newest sample ABRP took (abrpSentUtc), and the server forwards only newer ones, so ABRP gets each sample once. Without credentials in the app the server forwards everything, as before. The credentials sit in encrypted storage, go in the request body, and neither they nor ABRP's answer are logged. Settings are grouped by what they are for: - Live data (was Upload): on/off, ABRP credentials, upload frequency. - Settings (replaces the Wi-Fi tab): full screen and voice key, usable capacity and manual SoH (were on Consumption), charging price (was on Charging), Wi-Fi. Charging and Live data get icons of their own. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QLJfZQZeAKAwSqViTmLzki
111 lines
5.2 KiB
Markdown
111 lines
5.2 KiB
Markdown
# Nils' MG4 — car server
|
|
|
|
A small Go service at car.k8s.stinnesbeck.com: the API the car writes to, and the ABRP
|
|
forwarder. Data lives in InfluxDB 2; Grafana reads it from there for the dashboards
|
|
(`../k8s/grafana/`).
|
|
|
|
```
|
|
car ──live telemetry───▶ server ──▶ ABRP api.iternio.com/1/tlm/send
|
|
──daily chunks─────▶ │
|
|
──charging sessions▶ ▼
|
|
InfluxDB 2 ◀── Grafana
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Environment only; the server refuses to start when a required value is missing.
|
|
|
|
| Name | Notes |
|
|
|---|---|
|
|
| `INFLUX_URL`, `INFLUX_TOKEN`, `INFLUX_ORG` | required; the token needs read/write on the bucket |
|
|
| `INFLUX_BUCKET` | default `mg4` |
|
|
| `INGEST_TOKEN` | required, at least 24 characters: `openssl rand -hex 32` |
|
|
| `ABRP_API_KEY`, `ABRP_USER_TOKEN` | optional; both needed to forward |
|
|
| `ABRP_MIN_INTERVAL_SECONDS` | default 5 |
|
|
| `APPROVAL_PASSWORD` | optional, at least 12 characters; switches pairing on (see below) |
|
|
| `PUBLIC_URL` | the address a phone uses, for the pairing QR code; derived from the request if empty |
|
|
| `LISTEN_ADDR` | default `:8080` |
|
|
|
|
The ABRP credentials never reach the car.
|
|
|
|
## Endpoints
|
|
|
|
The ingest endpoints accept `Authorization: Bearer <token>` with either the shared `INGEST_TOKEN`
|
|
or a paired car's own token. A paired token only works for the installation id it was paired
|
|
with (403 otherwise); the shared token works for any.
|
|
|
|
- `POST /v1/telemetry` — `{ installationId, samples: [...] }`, up to 500 samples in ABRP's `tlm`
|
|
field names and units (`utc` in epoch seconds; flags as 0/1 or booleans). Unknown fields are
|
|
dropped, known ones bounded: a value out of range is dropped on its own, and a sample without
|
|
a plausible time (before 2001, or more than an hour ahead) is dropped whole. The rest is stored
|
|
and the answer is `200 {stored, droppedCount, dropped}`, even when nothing was usable, since
|
|
the car would only send it again. The newest sample is forwarded to ABRP if it is under
|
|
5 minutes old and not ahead of the server's clock. A car that sends to ABRP itself adds
|
|
`abrpSentUtc`, the newest sample ABRP took from it; only samples newer than that are
|
|
forwarded, so ABRP gets each one once.
|
|
- `PUT /v1/consumption/daily` — one delta chunk of a day's consumption.
|
|
- `PUT /v1/charging-sessions/{sessionId}` — a finished DC session with its curve.
|
|
- `GET /v1/consumption/history/{installationId}` — the car reads its own totals back.
|
|
- `GET /v1/health` — `{"status":"ok"}`.
|
|
|
|
A malformed request is a 400 naming the field; a database failure is a 500 without detail.
|
|
|
|
## Pairing a car by QR code
|
|
|
|
So nobody types a token in the car. Modelled on the OAuth device authorization grant (RFC 8628);
|
|
on only when `APPROVAL_PASSWORD` is set.
|
|
|
|
1. The car calls `POST /v1/pair/start` `{installationId}` and shows the returned
|
|
`verificationUriComplete` as a QR code, plus the short `userCode` (e.g. `K7F-3QX`).
|
|
2. The phone opens `/pair?code=…`, the owner checks the code and approves with the approval
|
|
password. Five wrong passwords from one address lock that address out for a minute; other
|
|
addresses are unaffected (the address is the last `X-Forwarded-For` entry, which Traefik sets).
|
|
An address may hold three open requests; a car starting again replaces its own.
|
|
3. The car polls `POST /v1/pair/poll` `{deviceCode}`: 202 pending, 200 with its own token
|
|
(handed out once), 403 denied, 410 expired (after 10 minutes) or unknown.
|
|
|
|
Each car gets its own 43-character token; only its SHA-256 is stored (measurement `device` in
|
|
the same bucket), and the token is only handed out, and only accepted, once the device is
|
|
persisted, so a restart never loses a paired car. Manage cars with the approval password:
|
|
|
|
```sh
|
|
curl -H "Authorization: Bearer $APPROVAL_PASSWORD" https://car.k8s.stinnesbeck.com/v1/devices
|
|
curl -X POST -H "Authorization: Bearer $APPROVAL_PASSWORD" https://car.k8s.stinnesbeck.com/v1/devices/<id>/revoke
|
|
```
|
|
|
|
## Storage
|
|
|
|
One bucket, `installationId` tag on every point:
|
|
|
|
| Measurement | Timestamp | Tags | Fields |
|
|
|---|---|---|---|
|
|
| `telemetry` | sample `utc` | — | the ABRP fields that were sent |
|
|
| `consumption_chunk` | `recordedAt` | `date` | km, kwh, hours, socDrop, sohPercent |
|
|
| `charging_session` | `startedAt` | `sessionId` | endedAtMs, duration, energy, cost, start/end SOC |
|
|
| `charging_curve` | point time | `sessionId` | powerKw, socPercent |
|
|
| `device` | paired at | `deviceId` | tokenHash, installationId, revoked |
|
|
|
|
A point with the same measurement, tags and timestamp replaces the earlier one, so the car's
|
|
retries are idempotent: a cached chunk is re-sent with its original `recordedAt`. Days and the
|
|
lifetime total are summed from the chunks when read. Numbers are always written as floats,
|
|
because InfluxDB fixes a field's type on first write.
|
|
|
|
## Development
|
|
|
|
```sh
|
|
nix develop # from the repository root: Go, govulncheck, InfluxDB 2
|
|
cd server
|
|
go test ./...
|
|
govulncheck ./...
|
|
```
|
|
|
|
## Container image
|
|
|
|
```sh
|
|
podman build -t git.stinnesbeck.com/nils/mg4-server:<version> .
|
|
podman push git.stinnesbeck.com/nils/mg4-server:<version>
|
|
```
|
|
|
|
The build runs `go vet` and the tests. The image is a static binary on distroless (about
|
|
11 MB), running as UID 65532 on port 8080.
|