yaris-obd/PLAN.md

# yaris-obd Revival Plan

This document tracks the plan to revive and finish this project: a Raspberry Pi 3-based
OBD-II + GPS car tracker for a 2013 Toyota Yaris, hosting a local web UI over a self-broadcast
WiFi hotspot, with dashcam file retrieval and remote upload of itinerary/dashcam data.

Keep this file up to date as phases complete or plans change, so any future session/agent can
pick up the project without needing prior chat history.

## Hardware

- **Board**: Raspberry Pi 3 Model B Rev 1.2, 906MB RAM. Confirmed too weak to run an AI coding
  agent — all agent-assisted dev work happens on a separate local machine; the Pi is only used
  for hardware bring-up/testing/deployment via SSH (`yaris@<pi-ip>`).
- **GPS/GSM**: Waveshare **SIM868 GSM/GPRS/GNSS/Bluetooth HAT**. Also has unused cellular
  (GSM/GPRS) data capability, earmarked as a fallback internet uplink (see Remote Server phase).
- **OBD-II adapter**: a cheap unbranded USB adapter using a **PL2303** USB-to-serial chip,
  presumed ELM327-compatible (works with the `python-obd` library). Originally the project used
  a Bluetooth OBD adapter; this has been switched to USB.
- **Car**: 2013 Toyota Yaris.

### SIM868 HAT bring-up notes (important gotchas)
- UART routing is a 3-position jumper: **A** = USB↔SIM868 (via onboard CP2102), **B** = Pi
  GPIO↔SIM868, **C** = USB↔Pi console. Must be on **B** for the Pi to talk to the module over
  its own GPIO UART.
- Pi-side UART setup required: `enable_uart=1` and `dtoverlay=disable-bt` in
  `/boot/firmware/config.txt` (frees the full PL011 UART — `/dev/ttyAMA0`/`/dev/serial0` — from
  the onboard Bluetooth controller), `raspi-config nonint do_serial_cons 1` (stops a login shell
  from claiming the serial port), and disable the `hciuart` systemd service.
- **The SIM868 module chip itself needs its PWRKEY button pressed and held (~1-2s) to power on**
  — this is separate from the board's 5V/PWR LED, which can be lit while the module chip is
  fully off. AT commands get zero response if the module chip isn't powered, even with perfect
  UART wiring/config. **Update 2026-08-09: this HAT revision DOES have the "P4" GPIO-power-on
  mod wire installed** (per the Waveshare FAQ/`GSM_PWRKEY.rar` script) — confirmed by pulsing
  physical header pin 7 (BCM GPIO4) LOW for 4s then HIGH while the module was unresponsive, after
  which it immediately answered `AT`. This is now automated in `modules/app_gps.py`
  (`_ensure_module_powered()`), which checks `AT` first and only pulses PWRKEY if the module
  isn't already responding (PWRKEY is a toggle — pulsing an already-on module would turn it back
  off, so this check-first behavior is required). No more manual button-pressing needed after a
  Pi power cycle.
- Confirmed AT command baud rate: **115200**.
- GNSS workflow: `AT+CGNSPWR?` to check GNSS power state, `AT+CGNSPWR=1` to power on,
  `AT+CGNSINF` to poll for a fix. Response format:
  `+CGNSINF: run,fix,utc_time,lat,lon,alt,speed,course,fixmode,reserved1,hdop,pdop,vdop,reserved2,gps_sat_view,gnss_sat_used,gnss_sat_view,cn0,hpa,vpa`
  — field 1 (`fix`) must be `'1'` for a valid fix.
- **The GPS/GNSS antenna is separate from the GSM antenna** — both need to be physically
  connected to their respective u.FL connectors on the HAT. A real fix was obtained only after
  discovering the GPS antenna wasn't plugged in (only GSM was).
- Confirmed real fix obtained near a window: ~80s cold-start TTFF, 5-7 satellites, HDOP ~1.2-1.6.

## Software Architecture Decisions

1. **Offline maps**: Pre-cache/download offline map tiles for the car's usual driving area so
   the live map works fully in the car with no internet (not just numeric GPS readout).
   Tooling: MapTiler Cloud free tier (raster XYZ tiles, `streets-v2` style) — one-time download
   on the dev machine via `scripts/download_map_tiles.py`, output shipped to the Pi as static
   PNGs. Bulk-downloading directly from `tile.openstreetmap.org` was ruled out — it violates the
   OSM tile usage policy. Bounding box is a required CLI arg (the user's own driving area, not
   committed here), zoom 8-15 by default (~14k tiles for a city-plus-suburbs-sized area, well
   under MapTiler's 100k/month free quota).
2. **WiFi hotspot mode**: Auto-switch — the Pi joins home WiFi when in range (for
   syncing/updates), and falls back to broadcasting its own AP otherwise. **Important scope
   clarification**: the hotspot is *only* for local web-UI viewing on a phone/laptop while
   driving — it is not part of the upload path. Remote-server uploads happen independently via
   home WiFi (when in range) or the SIM868 cellular fallback (decision #5) — the phone connecting
   to the hotspot never relays/carries upload traffic.
3. **Local/remote persistence**: Keep SQLite locally (reliable local write path per trip). The
   original plan paired this with MongoDB Atlas for remote sync (`modules/app_db.py`, fixed in
   Phase 7) — **superseded by decision #4/Phase 9**: the actual remote store is the self-hosted
   Postgres server, uploaded via `modules/app_upload.py`. `app_db.py`'s Mongo path is not wired
   into `app.py` and is effectively dead code at this point, kept only for reference.
4. **Remote server**: Self-hosted — a custom server/API (e.g. on a home server or VPS) receives
   itinerary and dashcam uploads, rather than 3rd-party managed cloud services.
5. **Remote upload uplink**: Use the SIM868's GSM/GPRS cellular connection as a fallback uplink
   for uploads when no WiFi is available (e.g. while driving), not just "sync when on home WiFi."

## Phases

### Phase 1: Real GPS integration — ✅ DONE
`modules/app_gps.py` rewritten to read real SIM868 GNSS data via serial AT commands
(`/dev/serial0` @ 115200 baud) instead of hardcoded fake coordinates. Background daemon thread
polls `AT+CGNSINF` every 2s, parses fix data, emits `gps_location` via socketio only on an actual
fix. Verified against real hardware (see bring-up notes above).

### Phase 2: OBD fixes for USB adapter — ✅ DONE
`modules/app_obd.py` fixed (commit "Fix app_obd.py bugs and adapt for USB OBD-II adapter",
pushed to `origin/shameless-aislop`):
- `connection` is never left undefined on failed connect (was a `NameError` crash).
- Added `_find_obd_port()`/`connect_obd()`: auto-detects `/dev/ttyUSB*` (the PL2303 adapter),
  honors an `OBD_PORT` env override, falls back to python-obd's own port auto-scan (still covers
  the old `/dev/rfcomm*` Bluetooth path).
- Fixed stale-response bug: `obd_speed()`/`obd_rpm()` now re-query every loop iteration instead
  of reusing one response forever.
- Fixed `obd_rpm()` using the wrong lock, never updating the global `rpm`, and emitting to the
  wrong socketio event (`obd_speed` instead of `obd_rpm`).
- Fixed `kill_obd()` being a no-op — now uses `threading.Event` flags actually checked in the
  polling loops.
- Fixed inverted thread-start logic (threads were starting on failed connection, not success).
- Fixed `obm_error` → `obd_error` typo (frontend listens for `obd_error`).
- Added `obd` (python-obd) to `requirements.txt`.
- **Still untested**: a real connection to the actual car (adapter has only been tested
  standalone on the Pi so far — correctly reports "no connection to car" with nothing attached).

### Phase 3: Web UI must work fully offline — ✅ DONE
The whole point of the project is a Pi hotspot with **no internet in the car**, but the current
UI silently depended on the internet for core functionality:
- `templates/index.html`/`dash.html`/`dtc.html` loaded Google Fonts, FontAwesome, Leaflet JS/CSS,
  and the Socket.IO client from public CDNs — none of this loads offline, breaking layout, the
  websocket connection itself, and the map entirely.
- `static/js/yaris.js` loaded live map tiles from `tile.openstreetmap.org` (also needs internet).
- A local `static/js/chart.min.js` existed but was unused — `index.html` loaded Chart.js from
  `cdn.jsdelivr.net` instead (turned out the local copy was a stale Chart.js **v2.8.0** while
  `yaris.js`'s config uses v3/v4-style `scales: {x:{...}, y:{...}}` syntax — that mismatch is
  exactly why the CDN was used instead. Replaced the local file with a current v4.5.0 UMD build).

**What was done**:
- Vendored Socket.IO client (4.8.1, matches Flask-SocketIO 5.6.1's Engine.IO v4 protocol) under
  `static/vendor/socketio/`, and Leaflet (1.9.4 JS/CSS + marker/layers images) under
  `static/vendor/leaflet/`.
- FontAwesome 5.12.0 was already vendored locally at `static/fonts/` (self-consistent, just never
  referenced) — repointed all three templates to it instead of the CDN.
- Dropped the Google Fonts (Nunito) `<link>` entirely rather than self-hosting 12 font-weight
  files — Bootstrap's `--bs-font-sans-serif` variable already falls back cleanly to system fonts
  (`-apple-system, Segoe UI, Roboto, ...`) after Nunito, so this is a clean no-cost simplification.
- Replaced `static/js/chart.min.js` with a current Chart.js v4.5.0 UMD build (auto-registering,
  same drop-in behavior as the old CDN `<script src="https://cdn.jsdelivr.net/npm/chart.js">`).
- Offline map tiles: added `scripts/download_map_tiles.py`, a dev-machine-only one-time tile
  downloader using the MapTiler Cloud free tier (raster XYZ, `streets-v2` style, 256px tiles).
  Reads `MAPTILER_KEY` from an env var/CLI arg only — the key itself is never committed or
  deployed, only the resulting static PNG tiles are. Bounding box is a required CLI arg (your own
  driving area's coordinates - not committed/hardcoded) at zoom 8-15 (~14k tiles for a
  city-plus-suburbs-sized area, well under MapTiler's 100k tiles/month free quota). Output goes to
  `static/vendor/tiles/{z}/{x}/{y}.png` (gitignored — regenerate locally, rsync to the Pi as part
  of deployment, don't bloat the git repo with binary tile data).
  - **Tiles populated**: user signed up for a free MapTiler key and the full zoom 8-15 download
    ran to completion — 14,241 downloaded, 24 skipped (out-of-bounds), 0 failed (14,265 tiles
    total, ~285MB). Rsynced to the Pi's `static/vendor/tiles/` (tile counts verified identical
    on both sides). Live Pi instance re-confirmed serving HTTP 200 with the complete offline
    tile set.
- Updated `static/js/yaris.js`'s Leaflet init to point at `/static/vendor/tiles/{z}/{x}/{y}.png`
  (`minZoom`/`maxZoom` 8/15 to match). The initial map center is just a generic placeholder (not
  a real location) - it re-centers automatically to the real live GPS fix once one comes in, and
  the marker is exposed as `carMarker` so Phase 4 can move it on live fixes.
- Added a repo-root `.gitignore` (Python caches, venvs, `.vscode/`, `static/vendor/tiles/`,
  `*.env` except the already-tracked `db/creds.env` placeholder) — there wasn't one before, which
  is why stray `__pycache__`/`.pyc` files kept showing up in source control.
- **Verified**: ran the Flask app in a local venv, confirmed all three pages (`/`, `/dtc`, `/dash`)
  render with **zero external URLs** in the served HTML, every local static asset (JS, CSS, fonts,
  Leaflet images) returns HTTP 200, and all vendored JS files pass a Node.js syntax check.

### Phase 4: Map/GPS display bug — ✅ DONE
`yaris.js`'s Leaflet marker (`carMarker`) was never moved on incoming `gps_location` socket
events — only two text spans (`gpsLocationX`/`Y`) got updated. Fixed: `carMarker.setLatLng(...)`
is now called on every `gps_location` event, and the map re-centers (zoom 15) on the first fix
only (`mapCentered` flag), so the user isn't fighting the map re-centering under them while
panning/zooming during a trip.

**Verified**: also used this as an opportunity to test Phase 3 end-to-end — ran
`scripts/download_map_tiles.py` for real with the user's actual MapTiler API key (smoke-tested
zoom 8-10 first, confirmed idempotent re-run skips existing tiles, confirmed a downloaded tile
is a real map image of the target driving area), then started the full zoom 8-15
download. Took a **headless Chromium screenshot** of the running app's `/` page and confirmed:
sidebar/icons/fonts render correctly (FontAwesome working), the Speed Graph (Chart.js v4) renders,
and **the Leaflet map renders real offline map tiles with the marker in place** — full offline
end-to-end proof, not just "no CDN URLs in the HTML".
- Fixed (was noted here as out of scope, now addressed in Phase 8): `/dash` and `/dtc` used to
  render near-identical body content (both showed "DTC Codes") — `dash.html` now has real
  dashcam-specific content.
- **Full tile download completed** (see Phase 3 update above) and rsynced to the Pi — Phase
  3/4's offline map is now 100% functional end-to-end on the actual deployed device, not just
  the dev machine.

### Phase 5: Pi deployment / autostart — ✅ DONE
Set up a proper venv (`/home/yaris/app/yaris-obd/venv`), installed all requirements (all found
as prebuilt ARM wheels via piwheels — no slow source compiles needed, even for gevent).
Added `deploy/yaris-obd.service` (systemd unit: runs as the `yaris` user, `Restart=on-failure`,
5s `ExecStartPre` sleep to let USB/serial devices enumerate after boot, logs to
`yaris-obd.log`) and `deploy/install_service.sh` (idempotent one-time install helper — also
creates the venv if missing). Installed and enabled on the Pi (`systemctl enable` — survives
reboot).

**Also had to fix Pi → GitHub auth for `git pull`**: the repo is private, and the Pi's existing
`~/.ssh/id_ed25519.pub` turned out to be an *inbound* SSH key (its private half lives on the dev
machine, not the Pi) — useless for the Pi to authenticate outbound. Generated a dedicated
ed25519 keypair **on the Pi itself** (`~/.ssh/yaris_deploy_key`), registered it as a **read-only
deploy key** on the GitHub repo (least-privilege — the Pi only ever needs to pull), and added an
`~/.ssh/config` entry so git transparently uses it for `github.com`. Switched the Pi's `origin`
remote to SSH. `git pull` now works standalone on the Pi with no PAT/interactive auth needed.

**Verified end-to-end**: pulled latest code onto the Pi (was 5 commits stale), confirmed all
Python deps import cleanly, ran the app manually first (HTTP 200, all local static assets —
Leaflet/Socket.IO/Chart.js/FontAwesome — served correctly from the Pi itself), then installed +
started the systemd service and confirmed `active (running)` + `enabled`. **Tested crash
recovery**: sent SIGKILL to the running process, confirmed systemd auto-restarted it (through the
5s `ExecStartPre` delay) and the app was serving HTTP 200 again within ~10s, with zero manual
intervention.

### Phase 6: WiFi hotspot mode — ✅ DONE
Used NetworkManager (already the network manager in use, not hostapd/dnsmasq directly — those
were leftover/unused) since it natively supports AP mode via `nmcli`. Created two connection
profiles on the Pi: `home-wifi` (your real home WiFi network, `autoconnect-priority 10`) and
`Hotspot` (AP mode, `ipv4.method shared`, its own dedicated SSID/password set locally on the Pi -
not committed here, WPA2-PSK, `autoconnect-priority -10`). NM's own autoconnect logic handles
"leaving home WiFi range -> fall back to hotspot" automatically since `home-wifi` has higher
priority and NM always tries it first.

For the reverse direction (home WiFi back in range while sitting in AP mode) added
`deploy/yaris-netwatch.sh` + `.service`/`.timer`: since the Pi's onboard BCM43438 radio can't be
an AP and background-scan for client networks simultaneously, a systemd timer runs every 3
minutes, briefly attempts reconnecting to `home-wifi`, and restores the hotspot if home WiFi still
isn't in range. Installed via `deploy/install_netwatch.sh`.

**Root-caused and fixed a real bug during testing**: the hotspot's SSID broadcast worked
immediately, but its DHCP server initially failed (`dnsmasq: failed to create listening socket
for 10.42.0.1: Address already in use`) — a pre-existing **orphaned system-wide `dnsmasq.service`**
(noted as "likely unused" in earlier investigation) was already bound to the address space
NetworkManager's own internal dnsmasq needs for the hotspot. Confirmed the system dnsmasq's
config was genuinely empty/default (nothing in this project depends on it) and disabled it
(`systemctl disable --now dnsmasq`).

Also added easy access without needing to know the Pi's IP:
- **Renamed the Pi's hostname** from `yarisobd` to `yaris` — `avahi-daemon` (already installed
  and running) now publishes it as `yaris.local` via mDNS.
- **Port 80 -> 5000 redirect** via nftables (`deploy/nftables-yaris.conf` +
  `install_port_redirect.sh`, loaded through an `include` in `/etc/nftables.conf`), so the app is
  reachable at plain `http://yaris.local/` (no port number) instead of `:5000`.

**Verified on real hardware, very carefully** since the SSH session used to do all this testing
itself runs over `wlan0`: used a "dead-man's-switch" pattern for every risky test — a detached
background command (`setsid nohup bash -c 'sleep N && nmcli con up home-wifi' & disown`) armed
*before* each hotspot activation, so the Pi automatically reverts to home WiFi (and SSH access
comes back) even if something goes wrong, no physical access needed. Confirmed: hotspot broadcasts
and a real phone gets a genuine DHCP lease from NetworkManager's own DHCP server and can load the
web UI; `yaris-netwatch` correctly detects AP mode and reconnects to home WiFi when in range (and
is a no-op when already on home WiFi); `http://yaris.local/` and `http://<pi-lan-ip>/` both return
HTTP 200 with no port number from another machine on the network. (Real hotspot SSID/password and
the Pi's LAN IP are intentionally not recorded in this file — see local, non-committed notes.)

**Update — real-hardware bug found + fixed (hotspot->home reconnect was flaky)**: while testing
the phone-relay feature live (see Phase 11 update below), `yaris-netwatch` repeatedly logged "home
WiFi not found" 4 times in a row over ~13 minutes while sitting right next to the router — a real
regression from the original design, not a one-off fluke. Root cause: a plain `nmcli con up
home-wifi` straight out of AP mode relies on NM's scan cache for `wlan0`, which is stale/empty
coming out of AP mode (the radio can't scan while acting as an AP - see above). A single
`--wait 20` connect attempt gave up before a fresh scan could land. Fixed `yaris-netwatch.sh` to
explicitly drop the AP connection first (releases the radio), force `nmcli device wifi rescan`,
wait for it to settle, then retry the connect (longer 30s wait) up to 2 times before conceding and
restoring the hotspot. Bumped `yaris-netwatch.service`'s `TimeoutStartSec` to 180s (retry loop can
take up to ~80s, default systemd 90s start timeout was too tight). Verified fixed on real hardware:
both hotspot->home transitions after the fix recovered in ~7 seconds (previously failing outright).
Deployed: `sudo cp deploy/yaris-netwatch.sh /usr/local/bin/... && cp .service ... && daemon-reload`.

### Phase 7: app_db.py / app_sql.py fixes — ✅ DONE
Neither file was called from `app.py` or anywhere else - orphaned from a prior iteration. Fixed:
- `app_db.py`: applied a prior-session stash fix - resolves `.env` path via `__file__` (was
  cwd-relative), fixes `os.getenv()` calls to pass the actual key names (was called with zero
  args, an immediate `TypeError` if ever invoked), added a clear `RuntimeError` guard if
  credentials are still empty placeholders, returns `client[mDB]`.
- `app_sql.py`: rewritten - resolves `db/sql/` via `__file__` + `os.makedirs` (was cwd-relative),
  fixed `create_conn()` closing the connection immediately and returning `None` (so table
  creation never ran and every caller got a dead connection), added `get_conn()` (lazy singleton
  + table creation for both `tracking` and `dtc` tables), `insert_tracking()`, and a background
  `start_logging()`/`_log_loop()` thread (5s interval) that snapshots GPS (`app_gps.LocationX/Y`)
  + OBD speed (`app_obd.speed`) into the local `tracking` table. Used a deferred (function-local)
  import of `app_obd` inside `_log_loop()` to keep the pre-existing `app_obd`<->`app_sql`
  top-level circular import safe/explicit.
- Also fixed a Python 3.12+/3.14 compat bug found during testing: `sqlite3.version` (the
  sqlite3 *module's* version) was removed/deprecated - switched to `sqlite3.sqlite_version`
  (the actual SQLite library version), which is what was intended.
- Wired `app_sql.start_logging()` into `app.py` alongside the other startup calls
  (`app_gps.start_gps()`, `app_obd.OBD()`).
- `db/sql/` added to `.gitignore` (per-device local trip data, not source).
- Verified locally: `get_conn()` creates `db/sql/<account>_<car>.db` with both tables;
  `insert_tracking()` writes a real row; `start_logging()` thread starts and logs
  "SQL tracking-logger thread started, alive: True"; full `app.py` run confirms the thread
  starts cleanly and (with no real GPS/OBD hardware on the dev machine) correctly logs read
  errors instead of crashing; `app_db.get_database()` raises the new clear `RuntimeError` instead
  of crashing, since `db/creds.env` still holds empty placeholder credentials (real Mongo
  credentials are a user-provided follow-up, out of scope here).

### Phase 8: Dashcam retrieval (app_dash.py) — ✅ DONE, verified on real hardware
Rewrote `app_dash.py` to be brand/device-agnostic: detection via `lsblk -J`, matching partitions
whose parent disk reports `TRAN == "usb"` (this is what safely distinguishes a plugged-in
dashcam/USB stick from the Pi's own onboard storage, which is always `mmc` transport - no more
hardcoded `/dev/sda`). Walks the whole mounted filesystem for video file extensions
(`.mp4/.mov/.avi/.ts/.mkv`) instead of assuming a specific brand's folder layout (DCIM, MOVIE,
NORM/EVENT/PARKING, etc. all just work), preserves each file's relative sub-folder path when
copying (avoids filename collisions across dashcam event/date folders), and skips files already
copied (same relative path + size) so re-running an import is cheap. Mounts read-only to avoid
any risk of corrupting the dashcam's SD card. Dropped the unused/uninstalled `tqdm` CLI-progress
dependency (never actually in `requirements.txt`) since this now runs headless inside the always-
on web server, not interactively.

Wired into `app.py`: `GET /api/dash/devices` (list detected USB storage) and
`POST /api/dash/import` (run the mount->copy->unmount pipeline), both JSON. Fixed the pre-existing
`/dash` vs `/dtc` duplicate-template bug — `dash.html` now has real dashcam content (scan/import
buttons + live status) instead of a copy-pasted "DTC Codes" body. Added a dedicated `dash.js`
(not the shared `yaris.js`, which unconditionally initializes the `/index`-only map/chart and
would throw/crash on `/dash` and `/dtc` since those pages don't have those DOM elements - a
pre-existing bug, worked around by not depending on that shared file for this page's new JS).
Added `dash/videos/` to `.gitignore` (imported footage is per-device data, not source).

**Tested thoroughly without the physical dashcam** (user didn't have it on hand this session):
1. Unit-tested the `lsblk`-JSON detection/filtering logic against a realistic synthetic sample
   (Pi's own `mmcblk0` boot+root partitions plus a simulated USB dashcam partition) - confirmed
   it correctly finds only the USB partition and ignores the Pi's own storage.
2. Integration-tested the real mount -> find-videos -> copy (preserving structure) -> dedupe ->
   unmount pipeline on the actual Pi using a loop-device-backed FAT32 image (`mkfs.vfat` +
   `losetup`) populated with fake nested dashcam video files (`DCIM/100EVENT/...`,
   `DCIM/100NORMAL/...`) - confirmed real mount/copy/unmount all work, confirmed a second import
   run correctly skips already-copied files, confirmed non-video files (e.g. `thumbs.db`) are
   ignored. All simulation artifacts (loop device, test image, temp files) cleaned up afterward.
3. Verified the full `/dash` page + both new API routes locally (Flask dev run + headless
   browser check): auto-scan on page load correctly reports "No USB dashcam/storage device
   detected" (accurate, since none is plugged into the dev machine), Import button correctly
   stays disabled until a device is found, no JS console errors, no regression on `/` or `/dtc`.

**Verified against the real physical dashcam** (Jieli-chipset USB ID `1224:2725`, 29.7GB SD card,
`DCIM/1/VID_###.MOV` layout, 87 files, ~28GB total). This first live hardware test found and fixed
three real bugs the loop-device simulation couldn't have caught:
1. **Superfloppy SD card** - the card has no partition table at all (`lsblk` reports the whole
   `/dev/sda` disk directly as `fstype: vfat`, no child partition) - the original detection assumed
   a partition would always exist. Fixed to also match a `TRAN == "usb"` disk with its own
   `fstype` set directly, not just partitions under it.
2. **Mount permission error** - `mount_device()` called `os.makedirs()` directly, but the service
   runs as unprivileged `yaris` and `/mnt` is root-owned. Fixed to `sudo mkdir -p <mount_point>`
   before the existing `sudo mount`, mirroring that pattern.
3. **OOM crash during upload** (see Phase 10 below) - not a copy-path bug, but discovered
   immediately after the first successful real import.

End-to-end result: full 28GB/87-file import from the SD card completed successfully (resumed
cleanly after being interrupted once by the OOM crash below - `copy_files()`'s skip-if-already-
copied logic meant re-running `/api/dash/import` just picked up the remaining files, no data loss
or re-copy of the first 19 files). SD card unmounted cleanly afterward.

### Phase 9: Remote server for itinerary/dashcam upload — ✅ DONE
Per architecture decisions #4 and #5: self-hosted server/API to receive itinerary (from the
SQLite pipeline) and dashcam file uploads.

Decided/built: Flask API + dedicated Postgres, deployed as a docker-compose stack on the user's
unraid server (separate from any existing containers/DBs there), living in `server/` in this
same repo. Auth: simple `X-Device-Name`/`X-Api-Key` header pair per device, key hash stored
server-side, real key never committed (raw key printed once by `server/scripts/create_device.py`,
saved locally on the Pi only, in gitignored `db/upload_creds.env`). External access: exposed at
`https://yaris.ceaf.dev` via the user's existing Cloudflare Tunnel (public-hostname rule added in
the Cloudflare dashboard, pointing at `192.168.10.10:8098`) — router port-forward + the user's
Unifi firewall is the documented fallback if ever needed instead. Large dashcam uploads can
still prefer a local-network path (e.g. an AdGuard DNS override to bypass the tunnel while on
home WiFi) since tunnels typically cap per-request upload size — noted in `server/README.md`,
not yet needed/built.

Built (`server/` folder):
- `server/sql/init.sql` — Postgres schema: `devices` (name + sha256 api-key-hash), `tracking_points`
  (device_id FK, GPS/speed/odometer + `recorded_at`, unique per device+timestamp so retried
  batches can't duplicate rows), `dashcam_files` (device_id FK, relative_path + sha256, unique per
  device+path+hash so re-uploads are no-ops).
- `server/modules/db.py` — psycopg3 connection pool + query helpers (bulk tracking insert with
  `ON CONFLICT DO NOTHING`, dashcam dedupe-check-before-write).
- `server/modules/auth.py` — `require_device_auth` decorator checking the two headers against
  the stored key hash.
- `server/app.py` — Flask app: `GET /health` (unauthenticated), `POST /api/v1/tracking/batch`
  (bulk JSON insert, capped at 5000 points/request as a sanity guard), `POST /api/v1/dashcam/upload`
  (multipart, streamed to disk with sha256 verification + path-traversal guard on `relative_path`).
- `server/Dockerfile` + `server/docker-compose.yml` — `api` (gunicorn, published on host port
  8098 by default) + `db` (Postgres 17, internal-only, not published to the LAN) services, data
  volume defaults to `server/data/` but pointed at `/mnt/user/appdata/yaris-obd-server` on unraid.
- `server/.env.example` — template for `POSTGRES_PASSWORD`/`API_PORT`/`DATA_DIR`/upload size cap.
- `server/scripts/create_device.py` — run once per device inside the `api` container to register
  it and print its one-time API key. Ran once for device `yaris-2013`.
- `server/README.md` — full unraid deployment + Cloudflare Tunnel exposure + device-registration
  instructions.

Pi-side upload client (`modules/app_upload.py`):
- Background thread, uploads unsent `tracking` rows (batches of 500) and not-yet-uploaded
  dashcam files (sha256-verified) via the API above, with exponential retry/backoff on failure.
- Independent dashcam-upload-only pause toggle (persisted `settings` table + a switch on the
  `/dash` web UI) — trip/GPS logs always keep uploading regardless of the toggle, per explicit
  user request (useful on a slow/metered connection).
- **Backlog-drain tuning**: since tracking rows log every 5s locally, an offline/stale device can
  queue up a large backlog. The loop drains back-to-back (short 1s pause between batches) while a
  batch comes back full, only settling into the slow 30s idle cadence once actually caught up —
  a simulated 1250-row backlog now drains in 3 batches (~0.35s) instead of 13 batches over ~6.5
  minutes with the original fixed 100-row/30s-sleep design.
- `modules/app_sql.py` extended: `UPLOADED` column + migration on `tracking`, `settings` table,
  `dashcam_uploads` dedupe table, and helper functions backing all of the above.

Tested end-to-end against the real deployed server (tracking batch + dedupe, dashcam upload +
dedupe + path-traversal rejection, bad-API-key rejection, toggle-off correctly pausing only
dashcam uploads) and on the real Pi (its actual ~1800-row pre-feature backlog drained and
confirmed matching row counts on the server via direct psql query, live upload status visible on
`/dash`). Committed+pushed (`4ff99f0`, `c4db1ab`, `8dc304e`), deployed on both unraid and the Pi.
Exposed externally at `https://yaris.ceaf.dev` via the user's Cloudflare Tunnel (public hostname
added in the Cloudflare dashboard, pointing at `192.168.10.10:8098`).

### Phase 10: Dashcam upload memory/size fixes — ✅ DONE, verified on real hardware
Two real-hardware-only bugs surfaced once actual ~300MB+ video files (not small test fixtures) hit
the upload path for the first time:

1. **OOM crash from in-memory multipart uploads.** `modules/app_upload.py` originally uploaded
   dashcam files via `requests.post(..., files={"file": f})`. The `requests` library builds the
   *entire* multipart/form-data body in memory before sending when using `files=` - a well-known
   gotcha, not specific to this codebase. On the Pi 3's ~900MB RAM, uploading one ~320MB video this
   way spiked the process past 600MB+ RSS, triggering the kernel OOM killer within minutes
   (confirmed via `dmesg`: repeated `Out of memory: Killed process ... anon-rss:823928kB`, and via
   `pmap -x` showing a single ~362MB anonymous mapping matching the file size almost exactly).
   **Fixed**: added `requests-toolbelt` and rewrote the upload body construction to use
   `MultipartEncoder`, which streams the file in chunks as the request is sent instead of
   materializing it up front. Confirmed via an isolated 300MB test (628MB RSS old way -> 29MB new
   way, byte-identical result) and live on the Pi (RSS stayed flat ~55-59MB during real uploads,
   vs. previously crashing every few minutes).
2. **Cloudflare Tunnel's hard ~100MB request-body cap.** Even after the memory fix, real uploads
   still failed once routed through `https://yaris.ceaf.dev` - a bare `413 Payload Too Large` from
   Cloudflare itself (confirmed: the identical file succeeds direct-LAN, 413s only through the
   tunnel). This is a free-tier platform limit, unrelated to `MAX_DASHCAM_UPLOAD_MB` on the Flask
   side. **Fixed** via a chunked/resumable upload redesign (well under the 100MB cap):
   - Client (`modules/app_upload.py`): `DASHCAM_CHUNK_SIZE = 40MB`; new
     `_upload_video_chunked()` checks `/status` first (enables resume across restarts/failures),
     then POSTs missing chunks one at a time via `MultipartEncoder`.
   - Server (`server/app.py`): new `GET /api/v1/dashcam/upload/status` (reports
     `already_uploaded` or `received_chunk_indices`) and `POST /api/v1/dashcam/upload/chunk`
     (stages chunks under `STORAGE_DIR/.upload_tmp/<device>/<sha256>/`, reassembles + verifies
     SHA256 once all chunks arrive, records via the existing `db.insert_dashcam_file`, cleans up
     the staging dir). A `.total_chunks` marker guards against stale/mismatched partial sets if the
     chunk size ever changes between client versions. The original single-shot
     `/api/v1/dashcam/upload` endpoint is untouched, kept for reference/compatibility.

**Verified end-to-end against the real deployed server through the real Cloudflare tunnel**,
first with a synthetic interrupted-then-resumed 250MB test (status transitions
`not_started` -> partial upload -> `in_progress` w/ correct `received_chunk_indices` -> resume ->
`complete` -> `already_uploaded`, SHA256 match confirmed on disk), then with real dashcam footage:
the Pi copied all 87 real files locally and the background upload thread drained the real backlog
one file at a time, each one verified byte-for-byte (SHA256 match Pi vs. server) and correctly
recorded in Postgres, while the Pi's service ran 50+ minutes straight with RSS staying in a bounded
~55-141MB range (no OOM kills) - a stark contrast to the previous crash-every-few-minutes behavior.
Given home-upload-bandwidth constraints, the full 28GB backlog drains at roughly one ~350MB file
per 4-5 minutes and is expected to take several hours total - this runs unattended in the
background with no user action needed once started.

**Not yet built**: parallel/concurrent chunk uploads (currently strictly sequential, one chunk
then one file at a time) - would speed up the multi-hour full-backlog drain but adds complexity;
not requested by the user yet, flagged here as a possible future optimization if the sequential
pace becomes annoying in practice.

**Known manual step (not yet automated)**: this dashcam model boots into a "select mode" menu
(dashcam / mass-storage / webcam) when it senses USB data lines are live, and needs USB data
communication physically absent to boot straight into recording mode, but present when plugging
into the Pi for import. No code in this repo handles that switch - it's a manual physical step by
the user (e.g. a data-blocking USB cable/adapter, or plugging/unplugging appropriately) each time
before recording vs. before importing. Worth revisiting if it becomes tedious in daily use (e.g. a
Pi-controlled USB data-line switch), but out of scope for now.

### SIM868 cellular fallback for tracking uploads — ⚠️ built, UNTESTED (no SIM card available)
`modules/app_cellular.py` gives the tracking-upload path a fallback over the SIM868's cellular
data connection when WiFi/Ethernet is unreachable. Design notes:
- Uses the SIM868's built-in AT-command HTTP(S) client (`AT+HTTPINIT`/`HTTPPARA`/`HTTPACTION`/
  `HTTPREAD`) rather than a real `ppp0` network interface. Reason: the SIM868's GNSS (polled
  continuously by `modules/app_gps.py`) and its GSM/GPRS radio share the *same* physical UART
  (`/dev/serial0`) — a classic `pppd`/`chat` dial-up would put that port into raw PPP framing for
  as long as the link is up, starving the GNSS polling thread. Staying in AT-command mode lets
  cellular HTTP calls interleave safely through the same serial lock
  (`modules.app_gps._serial_lock`) — each exchange just briefly delays the next GPS poll.
- Only carries small JSON tracking batches, **never** dashcam video — cellular data is far too
  slow/limited for multi-MB video files, and the modem's HTTP AT interface has a small internal
  buffer unsuited to them anyway. Dashcam uploads remain WiFi/Ethernet-only, unchanged.
- `modules/app_upload.py`'s tracking-batch upload always tries WiFi/Ethernet (`requests`) first;
  only on a connection-level failure (no route/DNS/timeout — as opposed to an HTTP error status,
  which means the server WAS reached) does it retry the same batch over cellular.
- Feature-flagged off by default: `YARIS_CELLULAR_ENABLED`/`YARIS_CELLULAR_APN`/
  `YARIS_CELLULAR_APN_USER`/`YARIS_CELLULAR_APN_PASS` added to `db/upload_creds.env`, all blank
  by default so this has zero effect on the already-verified WiFi upload path until the user
  fills in an APN once they get a SIM card. Regression-tested (against the real server) that
  normal WiFi uploads are completely unaffected while cellular is unconfigured.
- `/dash` upload-status card now shows which path (`wifi`/`cellular`) the last successful batch
  used, and whether cellular fallback is configured.
- **Needs validation once a SIM card is available** — exact AT command dialect/timing (SIMCOM
  firmware revisions vary slightly), and whether `AT+HTTPSSL` works for the HTTPS
  `yaris.ceaf.dev` endpoint on this specific module's firmware (if not, a documented fallback is
  a plain-HTTP router port-forward path, avoiding the need for the modem's TLS stack to validate
  a cert chain).

### Phase 11: Phone-relay dashcam upload — ⛔ REMOVED (see update below - hit a hard platform limitation)
Root cause investigation into "why is the transfer from the Pi to the server so slow?" (real
dashcam backlog draining at only ~350MB/4-5min) found the bottleneck is the **Pi's own onboard
BCM43438 WiFi chip** (2.4GHz-only, congested/interfered channel) — confirmed via `iperf3`
raw-TCP tests showing only ~14.7Mbit/s with active retransmits even over a same-subnet direct-LAN
hop that never touches the internet/Cloudflare, ruling out ISP/Cloudflare limits. Since the Pi 3 B
has no 5GHz radio and can't be fixed in software, added a way to bypass its weak WiFi for the
internet-bound leg entirely: a phone opens the same `/dash` page (over the Pi's hotspot/home WiFi)
and manually relays pending dashcam files straight to the remote server using the phone's own
network (WiFi or cellular data), instead of routing everything through the Pi.

**Zero new remote-server upload logic** — the phone's browser JS calls the *exact same*
`/api/v1/dashcam/upload/status` + `/api/v1/dashcam/upload/chunk` endpoints the Pi's own Python
client already uses, in the same 40MB-chunk protocol, just orchestrated by `fetch()`/`FormData`
instead of `requests`/`MultipartEncoder`. The server dedupes purely by SHA256 regardless of which
device sends the bytes, so no server-side changes were needed for the upload path itself — only a
CORS `after_request` hook (`server/app.py`) was added, since the phone's browser calls
`yaris.ceaf.dev` from a page served by a *different* origin (the Pi), which browsers block without
`Access-Control-Allow-*` headers on both the real request and its preflight `OPTIONS`. Wildcard
origin is fine here — auth is header-based (`X-Device-Name`/`X-Api-Key`), not cookie/session-based.

**New Pi-side endpoints** (`app.py`):
- `GET /api/dash/pending` — lists not-yet-uploaded dashcam files (`relative_path`, `sha256`,
  `size`) via a new `app_upload.list_pending_dashcam_files()`.
- `GET /api/dash/file/<path:relpath>` — serves a dashcam file's bytes for the phone to download,
  via `send_file(..., conditional=True)` for **Range-request support** (206 Partial Content) so
  the phone downloads (and immediately re-uploads) one 40MB slice at a time instead of ever
  holding a whole 300+MB file in the browser's memory — the exact same memory-safety lesson
  learned the hard way in Phase 10, applied symmetrically to the download side. Path-traversal
  safe via Werkzeug's `safe_join` against `app_dash.DEFAULT_DESTINATION`.
- `GET /api/dash/relay/config` — hands the phone the same `SERVER_URL`/`DEVICE_NAME`/`API_KEY`
  the Pi's own client uses, so its JS can auth directly with the remote server. Same trust
  boundary as the rest of this project's unauthenticated local UI (anyone on the Pi's own
  hotspot/LAN is already implicitly trusted).
- `POST /api/dash/relay/heartbeat` / `POST /api/dash/relay/stop` — a **lease-based pause**
  (`RELAY_LEASE_SECONDS = 45`) for the Pi's own background dashcam uploader, chosen over a plain
  on/off toggle specifically to self-heal if the phone's browser tab closes/loses connection
  uncleanly (a simple toggle could get stuck "paused" forever). The phone page heartbeats every
  15s while relaying; `_upload_dashcam_files()` skips entirely while a lease is active, re-checked
  between files so it stops promptly if a relay starts mid-drain. Also released via
  `navigator.sendBeacon()` on `beforeunload` as a best-effort immediate release.
- `POST /api/dash/relay/mark_uploaded` — lets the phone tell the Pi "I just uploaded this file"
  right after a successful relay, so the local dedupe table (and the pending list / Pi's own
  background loop) reflect it immediately instead of waiting for the next full backlog scan.

**Performance side-fix**: `modules/app_upload.py`'s dashcam loop previously recomputed SHA256 for
*every* candidate file on *every* loop iteration, including files long since uploaded — wasteful
CPU/IO against a growing, possibly 20GB+, local backlog. Added a `dashcam_hash_cache` SQLite table
(`modules/app_sql.py`, keyed by `relative_path`+`size`+`mtime`) so a file's hash is only computed
once; both the existing background uploader and the new pending-files endpoint benefit.

UI (`templates/dash.html` / `static/js/dash.js`): a new "Relay via phone" card on `/dash` lists
pending files with a per-file "Relay" button and a "Relay all pending" button (manual trigger only
— chosen deliberately over an automatic one, per explicit user preference), plus a "Stop relay"
button. Chunk downloads/uploads retry up to 3 times with backoff before surfacing an error, and a
resumed relay re-checks `/status` first so a previously-interrupted file picks up from its first
missing chunk instead of restarting.

**Tested**: a full local end-to-end simulation (no physical phone/network needed) drove the real
Pi `app.py` and real `server/app.py` Flask apps side by side (Postgres mocked at the `db` module
boundary only — all HTTP routing, chunking, auth, and CORS logic is real), reproducing the exact
sequence the phone's browser JS performs: list pending -> check remote `/status` -> download each
chunk from the Pi via `Range` requests (verified real `206 Partial Content` responses) -> upload
each chunk to the mock-backed server -> verify the reassembled file matches the original
byte-for-byte via SHA256 -> mark uploaded on the Pi -> confirm it drops out of the pending list.
Also verified: path-traversal attempts on `/api/dash/file/` correctly 404, the relay
heartbeat/stop lease correctly pauses/resumes `_upload_dashcam_files()`, and the sha256 cache
table is populated and reused across repeated `/api/dash/pending` calls.

**Deploy gotcha found**: the CORS fix in `server/app.py` was initially deployed to the Pi but not
rebuilt on the actual remote server (the server's Docker image bakes `app.py`/`modules/` in at
build time via `COPY`, so a plain `git pull` + container restart isn't enough — needs
`docker compose build api && docker compose up -d api`). Without it, the phone's cross-origin
`fetch()` calls to `yaris.ceaf.dev` were silently blocked by the browser's CORS policy, which
surfaces in JS as a generic, unhelpful `TypeError: Failed to fetch` — worth remembering as the
first thing to check if this error reappears after a future server-side change.

**Tested for real against a real phone and the real deployed server** (first end-to-end proof
beyond the local simulation above): the initial `/api/dash/pending` call took ~25 minutes for a
one-time full-backlog SHA256 hash of all 87 files (~28GB, no cache existed yet) — after that,
repeat calls returned in ~0.13s. The user then successfully relayed a real file from their phone
(home WiFi) partway through (10/~12 chunks) before stopping to check something important: **is
the relay actually faster, given the phone downloads from the Pi over the same congested radio
diagnosed as the bottleneck?** Measured directly from chunk-arrival timestamps on the server:
**~1.11MB/s (~8.9Mbit/s) for the phone-relay path — statistically the same as the ~9-10Mbit/s
measured for the Pi's own direct Cloudflare upload** earlier this session. **Conclusion: when the
phone is on the same home WiFi as the Pi, the relay provides no speed benefit** — the
download-to-phone leg pays the exact same slow-radio cost as a direct Pi upload would, and the
phone's reupload leg then goes out through the same home internet connection anyway, adding an
extra hop for no gain. The relay only has genuine value when the phone's *second* leg differs
meaningfully from the Pi's own path — e.g. cellular data with better upload than the home ISP, or
uploading after physically leaving home with files already grabbed locally. Stopped the test relay
(`POST /api/dash/relay/stop`) and confirmed the Pi's own background uploader resumed the same
file's chunked upload exactly where the phone left off (shared `/status`/`.upload_tmp` state on
the server made this seamless, no wasted re-transfer).

**Next idea (not yet built)**: the user wants a way to browse/preview individual dashcam clips on
the phone and select specific ones to view or upload (as opposed to bulk-relaying the entire
backlog) — useful for "just grab this one important clip" rather than a wholesale speed
optimization. Not scoped/designed yet.

**Update — tested the "away from home" hotspot+cellular scenario for real, found a real phone-OS
limitation (not a code bug)**: the user asked to test the specific scenario the relay feature was
actually designed for — phone connects to the **Pi's own hotspot** (not home WiFi) to download
pending files, then re-uploads using the phone's **cellular data**, bypassing the Pi's own (in
hotspot mode, nonexistent) internet connection entirely. Confirmed via code review this needs zero
changes: `/api/dash/relay/config` already hands the phone the public `https://yaris.ceaf.dev`
`SERVER_URL` (not a LAN-only address), so the re-upload leg was always going to be internet-bound
regardless of which physical network carries it.

Live-tested with a real dummy file (dashcam upload toggle paused first so the Pi's own uploader
couldn't grab it before the phone did): got `TypeError: Failed to fetch` trying to relay. Confirmed
via a direct test (loading `https://yaris.ceaf.dev/health` as a plain page navigation, not a
`fetch()`, ruling out CORS) that **the phone's own OS was declining to route internet-bound traffic
over cellular while still associated with the Pi's no-internet-gateway hotspot WiFi** — it only
succeeded once the phone auto-fell-back to the home WiFi network (which does have internet)
instead. This is a phone/OS-level "smart network switching" behavior (common on both iOS and
Android to avoid using a WiFi network with no internet gateway) that cannot be fixed in this
project's code — the architecture is sound and was already proven correct in the local end-to-end
simulation and the byte-for-byte reassembly tests earlier in this phase.

**Practical implication**: testing this exact scenario **at home is inherently confounded** — the
phone always has a known-good home WiFi it can silently fall back to, defeating the test. A true
validation needs either (a) actually being away from home with no known WiFi in range, forcing the
phone to use cellular for internet traffic, or (b) manually disabling the phone's WiFi (or its
"switch to mobile data automatically" setting) while connected to the Pi's hotspot, to force
cellular use for this one operation.

**Update — retested more rigorously, confirmed this is a fundamental architecture-level dead end,
not just an untested corner case.** Re-ran the same live test multiple times with longer/managed
"dead-man's-switch" windows (`yaris-netwatch.timer` explicitly stopped during each test run so it
wouldn't yank the Pi back to home WiFi mid-test — an earlier run's failure was actually caused by
netwatch reconnecting home WiFi under the phone, see Phase 6 update, not a phone-network issue).
With netwatch correctly disabled and the Pi confirmed to stay in AP mode for the whole test window,
still got `Failed to fetch`. Directly tested a plain page navigation (not `fetch()`) to
`https://yaris.ceaf.dev/health` with WiFi *fully turned off* (pure cellular) — **that also failed**,
while every other website loaded fine over the same cellular connection with WiFi off. This
narrows the cause precisely: **the browser/phone genuinely cannot reach the public internet at all
while `wlan0`/the phone's WiFi radio is associated with the Pi's hotspot, full stop** — this is not
a settings toggle problem (checked Pixel-specific "switch to mobile data automatically" options,
not present on this device/Android version) but a fundamental **OS-level "default network" routing
decision**: a device's default route for *all* IP traffic (including a web page's `fetch()` calls)
is a single, whole-device choice made by the OS's connectivity manager, not something a browser
page's JavaScript can override per-request. Real per-request network binding (e.g. Android's
`ConnectivityManager.bindProcessToNetwork()`) is an API only available to **native
apps**, not exposed to web pages at all, in any browser, on any phone. Given this, the phone-relay
feature as designed (a web page doing simultaneous WiFi-to-Pi + cellular-to-server transfers)
**cannot ever work while the phone is connected to the Pi's no-internet hotspot** — this isn't a
bug to fix, it's a hard platform ceiling.

**Decision: removed the phone-relay feature entirely** (was Phase 11, now reverted - see below).
Two ways to actually deliver on the original "upload from the road without the Pi's slow WiFi"
goal were discussed: (1) restructure as two distinct, non-simultaneous phases (fully download to
the phone's local storage first while on the Pi's hotspot, then have the user manually switch to
cellular, then upload from local storage) - no native app needed but a more awkward two-step user
flow, or (2) a real native Android app, which *can* hold both networks open at once via
`bindProcessToNetwork()` for a true simultaneous relay. Neither has been built - shelved for now
in favor of simplifying the dashcam retrieval UI (see the new phases below). The Pi's own
background uploader (plain WiFi/Ethernet, optionally SIM868 cellular fallback for tracking data
only) remains the only upload path; it's just slower when the Pi's own WiFi is weak, with no
workaround currently in place for that specific case.

**Side-fix from this test session**: found and fixed a real, unrelated bug in `yaris-netwatch.sh`
during this same test — see the Phase 6 update above.

### Phase 12: Remove phone-relay feature — ✅ DONE
Undo Phase 11 cleanly given the Phase 11 update above (fundamental browser platform limitation,
not fixable). Removed:
- `app.py`: `/api/dash/pending`, `/api/dash/file/<path>`, `/api/dash/relay/config`,
  `/api/dash/relay/heartbeat`, `/api/dash/relay/stop`, `/api/dash/relay/mark_uploaded` routes
  (and the now-unused `os`/`send_file`/`abort`/`safe_join` imports they needed).
- `modules/app_upload.py`: `list_pending_dashcam_files()`, `relay_heartbeat()`/`relay_stop()`/
  `is_relay_active()`, `RELAY_LEASE_SECONDS`/`_relay_lease_until`, and the `is_relay_active()`
  check inside `_upload_dashcam_files()`/`get_status()`.
- `templates/dash.html`: the "Relay via phone" card.
- `static/js/dash.js`: all relay JS (`relayOneFile`, `fetchChunkWithRetry`,
  `uploadChunkWithRetry`, heartbeat timers, pending-file list rendering, etc).
- `server/app.py`: the CORS `after_request` hook, added solely for the phone's cross-origin
  browser calls (the Pi's own Python `requests`-based client was never subject to CORS - that's
  a browser-only enforcement mechanism).
- Kept untouched, as planned: the chunked upload protocol itself
  (`/api/v1/dashcam/upload/chunk` + `/status`), `dashcam_hash_cache` table + `_hash_dashcam_file()`
  (still used by the Pi's own background uploader to avoid rehashing its 20GB+ backlog every
  loop), `DASHCAM_CHUNK_SIZE`/Cloudflare 100MB workaround - none of that is relay-specific.

**Verified**: `python3 -m py_compile` on all touched Python files, `node --check` on `dash.js`,
grepped all five touched files for any leftover `relay`/`RELAY` reference (none found). Smoke-
tested by actually importing `app.py` in a scratch venv and hitting it with Flask's test client:
app imports cleanly (GPS/OBD/SQL/upload startup all log their normal "no hardware" messages, no
crash), `app.url_map` confirms every relay route is gone while `/`, `/dash`, `/dtc`, and the
remaining dashcam/upload API routes are still registered, and both `/` and `/dash` render with
HTTP 200 (`/dash`'s HTML contains zero occurrences of "relay"). Deployed to both the Pi
(`git pull --ff-only` + `systemctl restart yaris-obd.service`, confirmed `active` and `/dash`
returns HTTP 200 with no "relay" text over the real network) and the remote server (needed a full
`docker compose build api && docker compose up -d api` on unraid, not just a restart, since the
CORS-hook removal is baked into the image at build time - confirmed `/health` still returns
`{"status":"ok"}` and the response no longer carries any `Access-Control-*` header).

**Update 2026-08-09**: Phase 13 (OBD hardening) was completed next; see its section below.
Phase 15 is the recommended next software phase because Phases 16/17 and the later list-based
features depend on its shared UI foundation. Phase 14 remains independent but requires a careful
hardware/filesystem deployment pass rather than ordinary application deployment.

### Phase 13: OBD real-hardware readiness (code hardening) — ✅ DONE
**Reordered from Phase 17 on 2026-08-09** because it was completed directly after Phase 12;
the phase numbers now follow actual execution order instead of leaving completed work below
several still-planned phases.
**Independent of everything else in this plan — only touches `app_obd.py`/`app_events.py`, no UI
dependency for the backend part, so this can be done anytime/in parallel with the phases above.**
Nothing has been installed or tested in the actual 2013 Yaris yet - `modules/app_obd.py` has
only ever been tested standalone on the Pi with nothing plugged into the OBD-II port (correctly
reports "no connection to car"). Per explicit user decision, this phase is **code hardening
only** - the user will handle the physical install/bring-up testing themselves. Planned fixes,
all in `modules/app_obd.py` / `modules/app_events.py`:
- **Add a genuine background reconnect loop.** Today, `connect_obd()`/`obd_connection()` only
  ever run once per browser tab's socket `connect` event (`app_events.py`'s
  `connect_event()`) - there is no periodic retry. In the real car, this means: if the page
  happens to load before the adapter/ignition is ready, the connection attempt fails once and
  never retries until another browser tab connects. Add a small polling loop (mirroring the
  pattern already proven in `app_gps.py`'s `_poll_loop()`) that periodically calls
  `connect_obd()` while disconnected, independent of any browser being open.
- **Catch exceptions from `connection.query()`.** Currently a communication hiccup
  (adapter timeout, malformed response, USB blip) would raise inside `obd_speed()`/`obd_rpm()`
  uncaught, silently killing that polling thread forever with no recovery - not just returning
  a null response, an actual crash. Wrap query calls, treat exceptions like a lost connection
  (stop polling, let the reconnect loop above pick it back up) instead of dying silently.
- **Add an `OBD_PROTOCOL` env override**, mirroring the existing `OBD_PORT` override pattern -
  in case the 2013 Yaris's ECU doesn't cleanly auto-negotiate via ELM327's `ATSP0` (auto) and
  needs an explicit protocol code forced (Toyotas this age are normally ISO 15765-4 CAN 11-bit
  500kbaud, but this has never been confirmed against this specific car).
- **Improve connection-failure diagnostics.** Distinguish and log clearly: no adapter detected
  at all (USB/port issue) vs adapter detected but ELM327 handshake failed vs handshake OK but no
  response from the car's ECU (car off/ignition not on) - currently all three collapse into the
  same generic "OBD connection failed" message, which will make first-real-car troubleshooting
  much harder than it needs to be.
- **Add a small connect-time diagnostic log** (ELM327 firmware version + negotiated protocol,
  both available from `python-obd`'s connection object) written once per successful connect -
  useful evidence to sanity-check against Toyota's expected protocol on the very first real test.
- **Expand the data pulled from the car beyond speed/RPM** (backend only - the dashboard cards
  displaying this land in Phase 23 once the redesign reaches them): coolant temperature, fuel
  level, throttle position, and DTC/MIL status (check-engine light on/off + stored trouble codes,
  reusing/wiring up the already-scaffolded but currently-empty `/dtc` page and `GET_DTC` command).
  **Odometer/mileage is not guaranteed** - the standard OBD-II mode 1 PID for total odometer
  (0xA6) was only added to the SAE J1979 spec in later revisions and is inconsistently supported
  across manufacturers/years; whether the 2013 Yaris's ECU exposes it at all can only be
  confirmed once tested against the real car (falls under "code hardening only" for now - add
  the query with graceful "unsupported" handling rather than assuming it will work).

**Implemented 2026-08-09**:
- Added an idempotent, browser-independent reconnect daemon started from `app.py`; it retries
  every 10 seconds and restarts any dead polling workers after reconnect.
- Serialized all python-obd queries so speed, RPM, and the expanded sensor worker cannot issue
  overlapping serial exchanges. Query exceptions and silent connection-state changes now close
  and discard the stale handle, emit disconnected state, and hand recovery back to the reconnect
  loop instead of permanently killing a worker.
- Added `OBD_PROTOCOL` support and distinct logs for no serial adapter, failed ELM327 handshake,
  and ELM327 connected but no ECU response. Successful connections log port, ELM327 firmware,
  negotiated protocol ID, and protocol name once.
- Added backend polling/emits for coolant temperature, fuel level, throttle position, MIL/DTC
  status, stored DTCs, and SAE PID `0xA6` odometer. Odometer uses a custom python-obd command with
  a null/unsupported result left as `None`; support is not assumed for the 2013 Yaris.
- Verified against the Pi's installed python-obd 0.7.3 API, plus focused mocked checks covering
  successful connection, forced protocol, ECU-off status, silent disconnect cleanup, query
  exceptions, and odometer decoding. The Pi currently has `/dev/ttyUSB0` present but is not
  connected to the car, so actual PID availability and negotiated Toyota protocol still require
  the user-planned first in-car test.
- Committed as `8d7909d`, pushed, and deployed to the Pi. After restart the service remained
  `active`, `/` returned HTTP 200, and the log showed four autonomous reconnect attempts with the
  correct "ELM327 handshake succeeded, but the car ECU did not respond" diagnosis and no traceback.

### Phase 14: Power-loss resilience & watchdog — 🟡 PARTIAL (watchdog done; filesystem/shutdown deferred)
**New phase, not code-dependent on anything else — OS/hardware-level, can be done anytime,
ideally before the Pi lives in the car full-time.** A car cuts power abruptly at every key-off;
nothing in the project currently protects against that, and repeated unclean power loss is a
classic cause of SD card corruption on embedded Pi projects. Two complementary angles:
- **Filesystem hardening**: convert the Pi's root filesystem to read-only with a writable overlay
  (`overlayroot`/`raspi-config`'s built-in overlay FS option), so an abrupt power cut can no longer
  corrupt the OS itself. App data that must persist (`db/sql/`, `dash/videos/`, logs) needs to
  live on an explicitly writable partition/bind-mount carved out of the overlay, since those
  still need real writes.
- **Clean shutdown before power loss**: either (a) a small delayed-shutdown power module/circuit
  (holds 5V for a few seconds after ignition-off so the Pi can run `shutdown -h now` cleanly), or
  (b) if the SIM868 HAT or another ADC/GPIO source can sense ignition/voltage state, a software
  voltage-drop watcher that triggers a clean shutdown proactively. Exact approach TBD - depends
  on what's easiest to wire into the existing power setup.
- **Hardware watchdog**: enable the Pi's built-in `bcm2835_wdt` watchdog (via `systemd`'s
  `RuntimeWatchdogSec`/`watchdog-device` support) so a fully hung app or kernel gets a hard reboot
  automatically instead of sitting dead in the car until someone notices.

**Implemented 2026-08-09**:
- Added `deploy/yaris-watchdog.conf` with systemd's hardware watchdog set to 10 seconds and
  `deploy/install_watchdog.sh` to install, activate, and verify it. Deployed to the Pi; confirmed
  `/dev/watchdog0` is the Broadcom BCM2835 watchdog and systemd reports
  `RuntimeWatchdogUSec=10s`.
- Rebooted the Pi and verified the watchdog setting persisted, systemd returned to `running`,
  `yaris-obd.service` returned to `active`, and `/` returned HTTP 200 after startup.
- **Explicitly deferred by user decision**: read-only root/filesystem hardening and clean-shutdown
  hardware. The current 59GB root partition fills the SD card and contains 28GB of dashcam data,
  so overlay root needs a separate persistent writable storage decision first; shrinking the live
  mounted root filesystem is not safe. Clean shutdown likewise needs delayed-power or
  ignition-sense hardware before software can implement it.

### Phase 15: UI design-system foundation — ✅ DONE
**New phase, pulled forward from the old "do the whole redesign at the end" plan.** Building the
Phase 16/17 file browsers (and later the trip-history/Pi-health/settings pages) against the
current old admin-template style just means rebuilding the same UI twice once the full redesign
(Phase 23) happens. Instead, do a *small, scoped* slice of the redesign right now: a shared page
layout/shell plus one reusable list/table component (sortable columns, per-row action buttons,
delete-with-confirmation pattern, empty-state messaging) that every subsequent list-based feature
in this plan (dashcam browser, video browser, trip history, settings) can be built on directly,
instead of writing bespoke list/delete UI code from scratch each time. Not a full redesign of
every existing page yet - just establishes the pattern once so nothing built after this point
needs to be redone in Phase 23.

**Implemented 2026-08-09**:
- Added a shared Jinja shell (`templates/base.html`) for navigation, top bar, footer, common
  styles/scripts, page titles, and per-route active navigation. Converted `/`, `/dash`, and
  `/dtc` to extend it, removing their duplicated shell markup while preserving page content and
  page-specific assets.
- Added a reusable data-table macro (`templates/components.html`) and generic
  `static/js/data-list.js` behavior for dynamic empty states, numeric/text sorting, accessible
  sort direction, and capture-phase confirmation that can stop destructive row handlers before
  they execute. `static/yaris.css` supplies the shared list/action styling.
- Used the empty `/dtc` page as the first component consumer without pulling its Phase 23 OBD
  wiring forward. Also stopped loading dashboard-only `yaris.js` there and guarded its optional
  `#obd-error` target after browser testing exposed an existing null dereference.
- Verified Jinja rendering and one active nav item on all three routes, JavaScript syntax, and
  live Pi HTTP 200 responses. Browser-tested all pages at 1280px and 390px with no horizontal
  overflow; injected sample rows confirmed ascending sort, `aria-sort`, empty-state switching,
  and cancellation of a destructive handler.

### Phase 16: Dashcam USB file browser (list + delete) — ✅ DONE
Replace the current all-or-nothing "Import videos" flow's blind spot (no visibility into what's
actually on the camera) with a real file browser for the mounted USB dashcam device, built on the
Phase 15 shared list component:
- New endpoint(s) in `modules/app_dash.py` to list every video file on the mounted dashcam
  (relative path, size, modified time) without copying anything - reuses the existing
  `find_video_files()` walk, pointed at the dashcam's mount point instead of the local
  destination folder.
- Delete support: individual file delete and a "delete all" bulk action, each requiring the
  mount to be briefly remounted read-write (currently always `ro`) - only for the duration of
  the delete call, then back to read-only (or unmounted) afterward, to minimize risk of
  filesystem corruption from an unclean power loss while writable.
- UI: a `/dash` card showing total file count + total size on the dashcam, a scrollable file
  list with a delete button per row, a "Delete all" button behind a confirmation dialog (real
  data loss risk - no undo).
- Explicitly deferred/out of scope: no in-browser preview/playback of files still on the
  dashcam itself (only after import - see Phase 17). No changes to the USB
  select-mode/data-communication toggle behavior - the user replugs power manually to return the
  camera to recording mode, as they already do.

**Implemented 2026-08-09**:
- Added list, single-delete, and delete-all backend operations using the existing USB-only storage
  detection. Each list/import/delete operation shares one lock so mount and file operations cannot
  race; listings include relative path, byte size, modified timestamp, count, and total size.
- Deletes accept only recognized video extensions, resolve and re-check every target beneath the
  selected mount, and reject absolute paths, traversal, missing files, and symlink escapes.
- Delete operations mount or remount the dashcam read-write only for the operation, then unmount
  or restore it read-only. If unmount fails, the cleanup path immediately attempts a read-only
  remount and reports a cleanup failure if neither safety action succeeds.
- Added `/api/dash/files` and `/api/dash/file` routes plus a `/dash` browser built on Phase 15's
  shared component: file/size/time sorting, totals, refresh, per-row confirmed delete, confirmed
  delete-all, empty/no-device states, and error feedback.
- Verified metadata, traversal rejection, one/all deletion, non-video preservation, import
  regression behavior, and cleanup-failure reporting against temporary filesystem fixtures.
  Deployed to the Pi; the live API correctly returned no storage devices while ignoring the
  attached PL2303 OBD adapter, and the responsive browser UI passed no-device and mocked populated
  list/sort/confirmation/delete tests.
- **Real-hardware deletion verification (2026-08-09)**: connected the 29.7GB FAT dashcam and listed
  all 87 original videos (29,615,111,758 bytes) through the live API. The first controlled delete
  exposed that FAT files were root-owned despite the read-write remount, so unprivileged
  `os.remove()` failed; added a privileged `sudo rm -- <validated-path>` fallback only after the
  existing extension, realpath, and mount-boundary checks pass. Created and deleted a tiny
  disposable `YARIS_OBD_DELETE_TEST.MP4` twice through the real API. Both cycles returned exactly
  to the original 87-file count and byte total, left every real video untouched, unmounted
  `/mnt/dashcam`, and kept the service active. Bulk delete uses the same validated per-file removal
  path but was not run against the real card because it would intentionally erase all footage.
- **Selected import enhancement and real-hardware verification (2026-08-09)**: added per-row
  Import buttons, checkboxes, Select all/Clear selection, and Import selected so importing is no
  longer all-or-nothing. The backend validates every selected path with the same mount-boundary
  protections as deletion, de-duplicates selections, preserves relative folders, tolerates a
  stale/missing file while importing the remaining valid selection, and keeps the existing
  same-size skip behavior. Before committing, paused background dashcam uploads, created a
  disposable `YARIS_OBD_IMPORT_TEST.MP4` on the physical card, selected it in the real mobile-width
  UI, and confirmed exactly one file copied with identical contents. A row-level repeat correctly
  skipped the existing copy; Select all selected all 88 visible rows and Clear selection reset the
  action. Removed both disposable copies, restored uploads, and verified the card returned to its
  original 87 files/29,615,111,758 bytes unmounted. The refined UI was then re-tested against a
  real existing video: it reported one skip, cleared the checkbox, and re-enabled all controls.

### Phase 17: Local imported-video browser + player — ✅ DONE
Same file-browser treatment for videos already imported to the Pi's own disk
(`dash/videos/`, populated by `import_dashcam()`), built on the Phase 15 shared list component:
- List endpoint (reuses `find_video_files()` against `app_dash.DEFAULT_DESTINATION`) showing
  relative path, size, modified time, and upload status (cross-check against
  `app_sql.dashcam_file_marked_uploaded()` - so it's visible at a glance which imported clips
  have already reached the remote server and which are still pending the Pi's own background
  uploader).
- Delete support: **local Pi copy only** - remote server copies are intentionally left alone
  as the safe backup/archive (explicit user decision - see 2026-08-09 discussion). No
  "also delete from server" option is being built for now.
- In-browser video player: since the dashcam records **MP4** (confirmed with the user), this
  is a plain HTML5 `<video>` element - no server-side transcoding needed. Reuses the same
  Range-request-capable file-serving pattern already proven in the (now-removed) relay's
  `/api/dash/file/<path>` endpoint (needed for correct seeking/scrubbing, not just playback).
- UI: a `/dash` card (or a dedicated sub-page if the list gets long) with a file list, a
  "Play" action that opens the video inline, and a delete button per row with a confirmation
  prompt.
- **QOL: video thumbnails.** Scrolling a list of `VID_00234.MOV`-style filenames to find a
  specific clip is rough. Grab one low-res frame per file via `ffmpeg` (cheap, done once per file
  and cached, not on every page load) so the browser shows an actual thumbnail per row instead of
  just a filename.
- **QOL: retention/auto-cleanup policy.** Once a file is confirmed uploaded to the remote server,
  it's safe to free local space. Add an optional automatic cleanup (configurable via the Phase 21
  Settings page - e.g. "delete local copies older than N days once uploaded", off by default)
  so the Pi's limited storage doesn't need to be babysat manually as the dashcam backlog grows.

**Implemented and real-hardware verified 2026-08-09**:
- Added local-video list, playback, thumbnail, and local-only delete APIs. Listing reports path,
  size, modified time, and exact upload status without rehashing: one SQLite join matches the
  existing `(relative path, size, mtime) -> SHA256` cache against confirmed uploads.
- Added a second `/dash` browser using the Phase 15 table component, with lazy thumbnails, sortable
  file/size/time/upload columns, Uploaded/Pending badges, inline HTML5 video playback, confirmed
  "Delete local" actions, totals, and retention status. Remote copies are never deleted.
- Playback uses Flask conditional file serving; a real `Range: bytes=0-1023` request returned 206,
  the exact `Content-Range`, and 1,024 bytes. Browser-tested a real H.264 1080p MOV at mobile width:
  the player reached readyState 4 with its duration loaded and no media error.
- Added cached ffmpeg JPEG thumbnails plus `deploy/install_video_tools.sh`; installed ffmpeg 5.1.9
  on the Pi. Real clips exposed and fixed the edge case where ffmpeg exits 0 without output at a
  late seek, so generation now retries frame zero and verifies a non-empty file. A normal 366MB
  clip generated in ~4.1s and its cached request returned in ~81ms. Generation uses a cooperative
  gevent semaphore/poll loop so cold thumbnails do not freeze the web server.
- Added off-by-default `local_video_retention_days` support. The upload loop checks it after sync;
  only files older than N days whose exact current content is confirmed uploaded are eligible.
  The Phase 21 Settings page will expose the control; `0`/unset remains disabled. Temporary
  filesystem tests confirmed disabled retention deletes nothing and enabled retention preserves
  pending files.
- Replaced a long-held upload/delete lock with per-path in-use/deleting state and reference counts:
  delete now returns HTTP 409 while that exact file is uploading or generating a thumbnail instead
  of blocking gevent and freezing every request.
- Deployed uncommitted code before committing and tested against the real 87-file/28GB Pi library:
  all 87 reported uploaded, total bytes matched 29,615,111,758, and retention reported off. Copied
  a tiny real clip to `YARIS_OBD_LOCAL_TEST.MOV`, verified it appeared Pending, played it in the
  browser, and deleted it through the confirmed UI action; the player closed and the library
  returned to exactly 87 uploaded files. Background uploads were paused for the disposable test,
  restored afterward, and the service remained active.

### Phase 18: Trip history & replay — ✅ DONE
Added a derived, idempotently rebuilt `trips` index over the original non-destructive `tracking`
stream, plus `/api/trips`, bounded `/api/trip/<id>` route responses, and a responsive `/history`
page using the Phase 15 sortable list and the existing offline Leaflet bundle. Trip rows and replay
details show distance in kilometres/miles and average/maximum speed in km/h and mph; speed metrics
prefer OBD wheel speed and fall back to plausible GPS-derived segment speed. The map replay includes
a timestamped scrubber and play/pause timeline that moves a vehicle-position marker through every
recorded point while showing its date, time, and recorded speed.

**Motion-boundary decision after auditing the real Pi data:** the logger records every five seconds
for as long as GPS has a fix, including while parked, so timestamp gaps alone are not trip
boundaries. OBD wheel speed above zero is the primary motion signal. When OBD is absent or stuck at
zero, three sustained GPS displacements of at least eight metres at normal logger cadence act as
the fallback; isolated jumps, implausible jumps, malformed coordinates, stationary jitter, clock
rollback, and five-minute motion gaps are handled explicitly. Trip summaries contain start/end
time and coordinates, Haversine distance, duration, and point count. Route responses retain both
endpoints, filter implausible GPS outliers, and downsample only above 2,000 points. OBD samples are
used only while their last successful query is fresh, preventing a disconnected adapter's stale
last-known speed from creating a false trip. Rebuilds process an overlap after the persisted
high-water mark plus the latest trip rather than loading the unbounded full history every time.

**Implemented and verified 2026-08-09:**
- Audited the live database before choosing the heuristic: 5,132 initial rows covering about 25.5
  hours, no null coordinates, all stored speeds zero, only 114 five-decimal coordinate positions,
  and one old NUL-prefixed latitude. Future coordinates are normalized before insertion; invalid
  snapshots are logged and rejected instead of poisoning trip calculations.
- Replaced unconditional five-second database writes with motion-aware persistence. Sensors are
  still checked every five seconds, but rows are written only for the first fix, fresh OBD motion,
  at least eight metres of accumulated GPS displacement, or a one-minute stationary heartbeat.
  The Pi normally runs only while the car has power, so this is not presented as a full-day parked
  storage problem; it reduces needless writes during bench testing and long idling while retaining
  enough stopped points for traffic pauses in the replay timeline.
- Nine focused detector tests cover sustained GPS fallback, parked jitter/malformed coordinates,
  inactivity splitting, OBD wheel-speed detection and slow-distance calculation, clock rollback,
  route outlier filtering, and route downsampling. SQLite incremental-build integration was also
  exercised against a disposable database, and five logger tests cover first-fix, parked,
  wheel-speed, GPS-fallback, and heartbeat decisions. A copy of the real database
  produced zero false trips across 5,179 parked rows.
- Deployed the uncommitted implementation to the Pi and built the schema against the real database
  without modifying any original tracking rows. Inserted an eight-point disposable GPS route while
  the service was stopped; the live API detected one 0.078km/35-second trip and returned all eight
  ordered replay points. Restored the exact pre-test database afterward, confirmed zero synthetic
  rows, `PRAGMA quick_check=ok`, zero derived trips, and an active service.
- Browser-tested `http://yaris.local/history` through the deployed mDNS/port-80 redirect at a
  390x844 mobile viewport. Empty state, populated sortable row, replay action, offline route
  polyline following every route point, start/end markers, metric/imperial distance and speed
  summary, and no-horizontal-overflow behavior passed. Offline tiles
  now attach only after selecting a route, avoiding irrelevant missing-tile requests around the
  generic empty-map center.
- With user approval, removed the accumulated stationary bench backlog after verification:
  5,454 local SQLite rows and 2,907 remotely synced Postgres rows, all with zero/null speed and no
  detected trip. Preserved a dated pre-cleanup SQLite backup under `/home/yaris/backups/`, vacuumed
  and integrity-checked SQLite, vacuum-analyzed Postgres, and left unrelated settings, upload
  markers, DTCs, and video data untouched. The deployed motion-aware logger then proved two
  consecutive stationary heartbeats were 60.02 seconds apart rather than five seconds.

### Phase 19: Pi health monitoring card — ✅ DONE
Added a dependency-free `/api/health` endpoint and responsive dashboard card reporting CPU
temperature, usable disk pressure/free bytes, RAM usage, human-readable uptime, and Raspberry Pi
firmware power/throttling flags. Data comes from thermal sysfs, `/proc`, `shutil.disk_usage`, and
`vcgencmd get_throttled`; individual unavailable sources are reported explicitly without hiding
the remaining readings. The endpoint exposes structured current and historical flags for Phase
20 alerts, plus warning/degraded/ok status. The browser refreshes every 30 seconds.

**Implemented and verified 2026-08-09:**
- Five focused tests cover memory parsing, missing memory fields, current/historical throttling
  bits, malformed firmware output, and ext4 reserved-block-aware disk pressure. Local non-Pi
  validation correctly reports thermal/firmware sources as unavailable while retaining disk,
  memory, and uptime instead of failing the endpoint.
- Removed the old browser-triggered thread that emitted uptime once per second indefinitely; the
  health poll now provides uptime cheaply with the rest of the system snapshot.
- Deployed uncommitted code to the real Pi. The API returned complete data with no source errors:
  about 47-49°C, 19-20% RAM, 59% usable disk pressure with 22.8GB free, and roughly two hours
  uptime during testing. SQLite/app service behavior remained active.
- Real hardware monitoring immediately found an actionable condition: `vcgencmd get_throttled`
  alternated between `0x50005` (current undervoltage and CPU throttling, both previously occurred)
  and `0x50000` (historical occurrences after the current condition cleared). The dashboard
  prominently distinguishes current warnings from prior events. The Pi power source/cable should
  be corrected before sustained in-car use.
- Browser-tested the real dashboard through `http://yaris.local/` at 390x844 and 1280x900:
  all four metrics, warning state, timestamp, responsive columns, and 30-second data path rendered
  without overflow or new console errors. Also fixed disconnected OBD speed showing `undefined`
  and deferred offline map tiles until a real GPS fix, avoiding irrelevant placeholder requests.

### Phase 20: Alerts/notifications — ✅ DONE
Added an offline-first notification system. A shared bell in the top bar on every web page shows
active local alerts with no modem, SIM card, or internet connection. Optional ntfy delivery mirrors
the same conditions only when explicitly enabled and configured; it defaults off until Phase 21
exposes its topic URL, optional access token, and thresholds.

Monitored conditions:
- MIL/check-engine state and DTC codes.
- Pi filesystem pressure and the physical dashcam USB filesystem, checked read-only and cached for
  five minutes to avoid repeated mounts.
- Pending tracking-row or local dashcam-video upload backlog.
- Pi CPU temperature and Raspberry Pi firmware undervoltage/throttling flags.
- GPS fix loss for a configured duration while fresh OBD wheel speed confirms movement.

The alert engine runs independently every minute and persists active state, first-active time,
last attempt/success, delivery errors, recovery state, and last value in SQLite. It sends once on a
transition, repeats only after the configured cooldown, retries failed deliveries after five
minutes, and sends a recovery notification after a delivered condition clears. GPS cold starts
must remain lost for the full duration before alerting, and stale MIL/DTC values are suppressed
after OBD communication stops. Firmware current flags alert immediately; new historical bits
remain visible for five minutes, and cleared bits are reconciled so the same fault can alert again
after reboot. Failed transient deliveries retry every minute during that window. The bell
explicitly reports a dead/stale monitor instead of silently showing old conditions.
`/api/alerts/status` exposes sanitized diagnostics without the ntfy URL, token, or request errors
that could contain a private topic URL.

**Implemented and verified 2026-08-09:**
- Thirteen focused alert tests cover ntfy request shape/authentication/error redaction, transition
  deduplication, cooldown repeats, recovery, failed-delivery retry, disabled delivery, GPS
  duration/reset, firmware-event recurrence, diagnostic freshness, and dashcam-usage caching. The
  combined targeted suite is 33 tests.
- Deployed uncommitted code and verified the alert thread, state table, status API, and service on
  the Pi. `enabled=false` and `configured=false` produced no external attempt while local alerts
  continued working.
- Tested the ntfy transport against a temporary HTTP receiver bound only to `127.0.0.1` on the Pi:
  path, UTF-8 body, title, priority, tags, and bearer Authorization header all arrived correctly;
  no third-party request or real token was used.
- The real read-only physical-dashcam check found 96.1% usage/1.23GB free, unmounted afterward, and
  the original library remained exactly 87 files/29,615,111,758 bytes. The live bell correctly
  showed that storage alert alongside the real Pi undervoltage/throttling alert.
- Browser-tested the real local bell/dropdown at 390x844 on the dashboard and trip-history page:
  badge counts, alert titles/details, no-alert state, synthetic monitor-failure state, shared-shell
  availability, and no-horizontal-overflow behavior passed with no new console errors.

### Phase 21: Settings page — ✅ DONE
**New phase - depends on Phase 15's shared components, and benefits from Phases 17/20 existing**
so there's real configuration to consolidate. Several settings currently only exist as
SSH-edited files or scattered individual toggles (dashcam upload pause switch on `/dash`,
cellular APN in `db/upload_creds.env`, hotspot SSID/password via `nmcli` directly) or don't exist
yet (retention days from Phase 17, alert webhook/thresholds from Phase 20). Add one dedicated
Settings page consolidating anything reasonably safe to expose over the local-only web UI:
upload toggle, cellular APN, local video retention policy, alert webhook URL + thresholds. WiFi
SSID/password changes likely stay out of scope (higher-risk to expose over a UI that could lock
the Pi out of its own network if fat-fingered) unless it turns out to be easy/safe to add later.

**Implemented and hardware-tested 2026-08-09.** Added a dedicated local `/settings` page and
validated `/api/settings` endpoint backed by the existing SQLite settings table. It consolidates
the dashcam-upload toggle, uploaded-video retention days, SIM868 cellular enable/APN, optional
ntfy enable/URL/token, and alert temperature/disk/backlog/GPS-loss/repeat thresholds. Updates are
validated as a complete group and committed atomically; invalid requests leave the prior
configuration untouched. Cellular enable/APN reads persisted settings live, so those changes do
not need an app restart. Sensitive ntfy URL/token values are write-only through the API: the page
only reports whether each is configured and supports explicit removal, so saved secrets are never
sent back to browser JavaScript. Local Web UI alerts remain active independently of ntfy.

When cellular is configured, ntfy delivery now uses the SIM868's small-body HTTP client as the
primary transport with the notification title, priority, tags, and optional bearer token.
WiFi/Ethernet is the fallback if the modem path fails. The generalized modem POST path rejects
quotes/newlines in AT-command parameters before touching hardware. This is mock/Pi-code tested but
remains explicitly unverified over a real carrier until a SIM is available; Phase 25 must prove
authenticated HTTPS, fallback, retry, and recovery behavior or remove ntfy entirely if the SIM868
cannot deliver it reliably.

Moved the dashcam-upload control from `/dash` into Settings rather than keeping duplicate controls,
while retaining pending-row, last-success/path, and last-error upload health in the new page.
WiFi credentials, remote-server device/API credentials, cellular username/password, and other
lockout/high-risk configuration remain file/SSH managed by design. Focused settings/alert tests
pass locally and on the Pi; the real Pi rejected an invalid update with HTTP 400 while preserving
its exact configuration. The live page loaded through `yaris.local` with the Pi's existing
defaults and shared alert/navigation shell. Browser testing at 390x844 found and fixed an initial
top-bar overlap by adding a dedicated bottom mobile save action; the real save then completed with
no horizontal overflow or console errors.

### Phase 22: Phone-hotspot internet uplink — ✅ DONE
Add a no-SIM internet path where the Pi joins a user's phone hotspot as a WiFi client and uses the
phone's cellular data for outbound synchronization. This must work with an ordinary iPhone or
Android hotspot and support tracking rows, alert events/state, software/server checks, and large
dashcam-video uploads without requiring a modem SIM.

The Pi currently creates its own hotspot for the local Web UI, so this phase must explicitly solve
the single-radio networking tradeoff rather than assuming it can be an access point and hotspot
client simultaneously:
- Add a Settings workflow to save/replace/remove a phone-hotspot SSID and password without exposing
  the saved password back to browser JavaScript. Validate before applying and provide a recovery
  path so a bad credential cannot permanently lock the user out of `yaris.local`.
- Prefer a deterministic NetworkManager design: when the configured phone hotspot is available,
  connect as a client for internet access; when it is unavailable or association fails, restore the
  Pi-hosted hotspot automatically within a bounded timeout. Preserve the existing boot/network
  watchdog behavior and document the exact priority/retry rules.
- Because a Pi 3 single WiFi interface cannot reliably host and join separate networks at once,
  test and document how the user reaches the local Web UI while connected to the phone hotspot.
  Prefer `http://yaris.local/` on the shared phone LAN when the phone permits peer traffic. If
  iOS/Android client isolation or mDNS behavior prevents that, keep the automatic Pi-hotspot
  fallback and present clear current-mode/status guidance rather than promising simultaneous access.
- Surface current uplink mode, connected SSID without password, IP address, internet reachability,
  last transition/error, and whether large video upload is permitted. Never mistake association
  with the phone for proven internet reachability.
- Keep dashcam video off SIM868 cellular, but allow it through the phone hotspot's WiFi path.
  Tracking, server alert synchronization, and other queued data must resume idempotently after the
  phone hotspot appears. Existing cellular-first ntfy behavior remains separate.
- Hardware-test with at least one real phone: cold boot with hotspot present/absent, hotspot
  enable/disable while running, wrong credentials, phone leaving/re-entering range, internet loss
  while still associated, automatic Pi-hotspot recovery, local `yaris.local` access, tracking
  catch-up, and a disposable chunked video upload. Record phone/OS limitations before committing.

**Implemented and hardware-tested 2026-08-09 with a real Pixel hotspot.**
- Added a root-owned `yaris-uplink` NetworkManager helper, systemd timer/wait service, dispatcher
  transition recorder, restricted sudoers entries, and Settings APIs/UI. Priority is
  `phone-hotspot` (20), `home-wifi` (10), then the Pi `Hotspot` (-10). A non-disruptive scan checks
  that the phone SSID is actually visible before replacing a working home connection.
- The intended single-phone workflow is **save credentials first → select Wait for hotspot → enable
  the phone hotspot**. The wait service gives the user ten seconds before dropping the Pi AP, scans
  for up to two minutes, and always restarts the periodic watcher. If the phone never appears or
  later disappears, NetworkManager/helper recovery selects home WiFi when available and otherwise
  restores the Pi hotspot. Multiple dead-man tests independently forced home WiFi recovery.
- Phone credentials go from browser to the privileged helper over stdin and into an atomic
  root-only (`0600`) NetworkManager keyfile. Passwords never enter SQLite, command arguments,
  status files, HTML/JavaScript responses, or read APIs. The UI exposes only configured state and
  SSID, supports replace/remove, and preserves in-progress edits during status polling.
- Status reports actual connection/mode/IP, NetworkManager-proven internet connectivity, whether
  large uploads are currently possible, last transition/error, and the last phone-assigned direct
  address. The non-secret transition record persists across reboot under `/var/lib/yaris-obd`.
- Pi-hosted hotspot testing initially found that the real phone could open `10.42.0.1` but not
  `yaris.local` even though Avahi correctly joined/published on `wlan0`. Added a NetworkManager
  shared-dnsmasq unicast fallback for `yaris.local`; the repeated dead-man test then passed.
- Pixel tethering has a different limitation: the hotspot-host phone can reach the Pi by its DHCP
  address, but relays neither mDNS (`yaris.local`) nor the DHCP hostname (`yaris`). Settings
  therefore retains and links the last direct phone-network address with a DHCP-change warning.
  The tested Pixel repeatedly assigned the same address, but the implementation does not assume it
  is permanent.
- Proved cold boot both with Pixel absent (selected home WiFi) and present (selected Pixel directly,
  Web UI/service started, and the server received a fresh heartbeat). Turning Pixel off repeatedly
  restored home WiFi in about 16 seconds. The same fallback code is covered for restoring the Pi
  hotspot when home WiFi is unavailable.
- Proved real tracking uploads through Pixel data against remote Postgres. The first disposable
  1 MiB video exposed repeated TLS EOF failures over tethering despite small requests working;
  setting only the phone profile MTU to 1400 fixed the path, after which a second 1 MiB disposable
  video reached the real server over Pixel data. Both named local/server files and exact database
  upload/hash rows were removed afterward, and dashcam uploads were restored enabled.
- The future Phase 24 alert-event synchronization queue will automatically use this normal IP
  uplink; Phase 22 does not prematurely implement that server schema/API.

### Phase 23: Finish web UI redesign — ✅ DONE
**Completed 2026-08-10 (final commit c685ef2).** Full responsive redesign of the Pi web UI,
including two UX polish passes and multiple bug-fix rounds.

**What was done:**
- Replaced the SB Admin 2-style fixed left sidebar with a purpose-built layout:
  - **Desktop (≥768 px):** dark fixed sidebar (`var(--sidebar-width) = 14 rem`) with collapsible
    icon-only mode (`4 rem`). State persisted via `localStorage`. Logo is a functional home link.
  - **Mobile (<768 px):** no sidebar. Full-width content with a sticky **bottom tab bar** (5 items:
    Dashboard, Dashcam, History, DTC, Settings). Logo shown in the topbar.
- Removed every placeholder element, inline style hacks, and stub dropdowns.
- Dashboard shows **6 OBD stat cards** wired to live socket events; RPM shows `—` (not `- rpm`)
  when disconnected.
- GPS map and coordinates merged into one card (lat/lon in card footer).
- **Speed history chart** (Chart.js): gradient fill, 60-point rolling window, session max/avg/count,
  NOW+MAX badges in header, auto-expands on desktop, collapsed by default on mobile.
- **Overview stats card** (new `/api/stats` endpoint): trips, total km, drive time, all-time max
  speed, videos on Pi, active DTC count (green/red) — displayed in a 3-column bottom row alongside
  GPS and speed history.
- DTC page fully wired to `/api/dtc` (MIL indicator + table, live refresh).
- `yaris.css` completely rewritten: CSS custom properties, sidebar, bottom nav, OBD cards,
  `border-start-*` utilities, mobile padding fix (removed Bootstrap `py-4 !important` conflict).
- `theme.js` rewritten: localStorage-backed collapse toggle.
- **Dashcam mobile**: thumbnail/size/date/upload columns hidden on mobile; action buttons icon-only
  (`<i>` only, no text); `data_table` macro supports optional column `class`; action buttons wrapped
  in `<div class="data-list-actions">` inside `<td>` (fixes desktop row layout).
- **Trip history mobile**: date shortened to `"9 Aug 18:00"` on <768 px; imperial units wrapped in
  `d-none d-sm-inline` spans; Replay button icon-only (`▶`).
- **Notification badge**: repositioned with `top/right` CSS offset (was clipped by `translate-middle`).
- Footer updated to `© vroom vroom yaris de course 2023`.
- Synthetic test trip in DB: 50 points, Old Port → Plateau Montreal, 3 km, 8 min, 43.5 km/h max.
- All 63 tests pass. Verified on Pi at 390×844 (mobile) and 1280×800 (desktop).

### Phase 23.5: UI polish, dashcam improvements, odometer, WiFi upgrade — ✅ DONE
**Completed 2026-08-10.** A focused multi-session polish and hardware upgrade pass on top of Phase 23.

**Dashcam & video:**
- Async dashcam import — import now fires in a background thread, returns `{status:"started"}` immediately, and the UI polls `/api/dash/import/status` every 3 s. Eliminates mobile timeout and `_device_lock` blocking all routes during copy.
- Per-file Convert button on MOV/non-MP4 files. `/api/local-video/convert` POST with `force=True` bypasses the auto-convert toggle.
- Real ffmpeg progress via `-progress pipe:1` — reads `out_time_ms` lines in a thread, computes `pct = out_time_s / duration_s * 100`. Old `elapsed/duration` estimate was wrong for RPi3 (encodes slower than realtime).
- Bitrate set to `-b:v 4M -b:a 128k` (~100 MB per 3-min clip); previous default was unusably small.
- `.converting.mp4` temp files excluded from file list and upload queue.
- Thumbnail patching during conversion — `refreshConvertingOnly()` updates badge text in-place without a full re-render; full render only when file count changes. Fixes thumbnail-reload flicker every 10 s.
- Mobile converting badge: spinner + % shown under thumbnail on mobile (`dash-thumb-meta`, `dash-thumb-converting`).
- Mobile checkbox column now visible in dashcam file list.
- Download button on Pi video files (`/api/local-video/file?download=1`, `as_attachment=True`).

**Odometer & trips:**
- `_log_loop` passes `app_obd.odometer` to `insert_tracking()` — OBD odometer now stored in every tracking row.
- `START_ODOMETER` / `END_ODOMETER` columns added to trips table (auto-migrated).
- `build_trip_summaries()` reads odometer from first/last tracking row of each trip; `list_trips()` falls back to cumulative distance sum for legacy trips with NULL odometer.
- Overview dashboard: `odometer_km` (MAX from tracking) and `video_count` now included in `/api/stats`.
- Trip history table: new "Odometer" column showing `start → end km`.

**Settings:**
- Separate upload toggles: "Upload trips & GPS logs" and "Upload dashcam videos (WiFi only)" are now independent switches. `TRIPS_UPLOAD_SETTING_KEY` added to `app_upload.py`.

**Map & location:**
- Recenter (⊕) button on dashboard GPS card and history route map.
- Offline reverse geocoding via `reverse_geocoder` Python library (~20 MB KD-tree, no internet needed). Exposed as `/api/geocode?lat=&lon=` — browser never calls any external service.
- When internet is available (phone hotspot), `/api/geocode` tries Nominatim first for street-level accuracy, falls back to `reverse_geocoder` for city/region. Results cached with `functools.lru_cache(512)` keyed at 4-decimal precision (~11 m).
- Dashboard GPS card footer: location name shown below lat/lon, updated on first fix and after moving >50 m.
- Trip history scrubber: location name shown in timeline panel, debounced 600 ms while scrubbing.
- GPS coords parsed as `float` before `toFixed()` — was crashing silently on string input from socket.

**Trip history UX:**
- Imperial units removed from `formatDistance` and `formatSpeed` (km / km/h only).
- Replay button hidden on mobile (`d-none d-sm-table-cell`); tapping anywhere on the trip row triggers replay instead (`data-trip-id` on `<tr>`, `cursor: pointer`).
- `data_table` macro supports optional `class` on column headers.

**WiFi upgrade — TP-Link Archer T3U (RTL8812BU):**
- RTL8812BU DKMS driver built and installed on Pi (`morrownr/88x2bu-20210702`, kernel 6.12.96+rpt-rpi-v8).
- `INTERFACE = "wlan1"` in `yaris_uplink.py`; `install_netwatch.sh` rebinds home-wifi, Hotspot, phone-hotspot to wlan1.
- `resolve_interface()` checks `/sys/class/net/wlan1` at startup — falls back to `wlan0` automatically if dongle is absent or driver fails. `INTERFACE` is module-level so all functions use the correct iface.
- `restore_fallback()` extended: if wlan1 primary fails, also tries `home-wifi-fb` and Hotspot on wlan0.
- `install_netwatch.sh` creates `home-wifi-fb` profile on wlan0 with `autoconnect=no` and lower priority — NM uses it only when explicitly activated by `restore_fallback()`.
- `dhcp-client-id=yaris-obd` in phone-hotspot keyfile — phone DHCP assigns a consistent lease by client-id, giving the Pi a stable IP on the phone hotspot network.
- Status JSON now includes `interface` field for diagnostics.
- SSH alias updated to new wlan1 IP (192.168.50.213).

### Phase 24: Remote trip + dashcam portal with shared web UI — ✅ DONE
**Completed 2026-08-10.** Extended the existing `server/` Flask deployment from an upload-only API into a full read-only browser portal backed by Postgres tracking data and the uploaded dashcam archive.

#### What was built

**Database (server/sql/)**
- `migrate_phase24.sql`: adds `users` (bcrypt browser auth) and `trips` (server-side computed trip index) tables
- `init.sql` updated to include both tables so fresh deployments don't need a separate migration step
- `trips` table: `(device_id, start_time)` unique key, full summary stats, start/end coordinates

**DB layer (server/modules/db.py)**
- `get_user_by_id()`, `get_user_by_username()`, `create_user()` — browser auth helpers
- `compute_trips_for_device()` — splits raw `tracking_points` into trip segments (gap > 5 min = new trip), filters out <50m blips, computes distance (haversine), duration, avg/max speed, upserts into `trips` table
- `list_trips()`, `get_trip_route()` — portal trip API helpers returning same JSON shape as Pi `/api/trips`/`/api/trip/<id>`
- `list_dashcam_files()`, `get_dashcam_file()` — dashcam browse/stream helpers
- `get_overview_stats()` — aggregated counts/totals for the Overview page

**Auth (server/modules/user_auth.py)**
- Flask-Login based browser session auth, completely separate from device `X-Api-Key` auth
- `User` class, `load_user()` loader, `check_password()`, `hash_password()`, `require_login` decorator
- `login_manager.login_view = "login_page"` — unauthenticated requests redirected to `/login`

**Application (server/app.py)**
- Added Flask-Login init, `SECRET_KEY` from env
- `_geocode_cached()` — same Nominatim→reverse_geocoder offline fallback as Pi, LRU cached
- `/login` GET/POST with CSRF token (stored in session, validated on POST)
- `/logout`
- Portal pages: `GET /` → Overview, `GET /history` → Trip history (reuses Pi `history.js`), `GET /dashcam` → Dashcam archive
- Portal JSON API: `/api/v1/portal/stats`, `/api/v1/portal/trips`, `/api/v1/portal/trip/<id>`, `/api/v1/portal/dashcam`, `/api/v1/portal/dashcam/stream/<id>` (Range-request streaming), `/api/v1/portal/recompute-trips`
- Pi history.js compatibility aliases: `/api/trips`, `/api/trip/<id>`, `/api/geocode`
- Auto-recompute trips in background thread after each tracking batch upload
- Path traversal guard on dashcam stream: rejects any storage path that escapes `STORAGE_DIR`

**Templates (server/templates/)**
- `base.html` — shared shell matching Pi visual style; "Remote server" badge in sidebar and mobile topbar; navigation has Overview / Trip history / Dashcam archive only (no Pi-hardware nav items)
- `login.html` — standalone login page with CSRF token, flash messages
- `index.html` — Overview page: 6 stat cards (trips, distance, drive time, top speed, videos, odometer), recent trips table, recent dashcam clips table
- `history.html` — identical layout to Pi history page; reuses `history.js` + `data-list.js` unchanged
- `dashcam.html` — file list table (name, size, uploaded date, download button) + inline video player with seek/Range support
- `components.html` — same `data_table` macro as Pi (needed by history.html)

**Scripts (server/scripts/)**
- `create_user.py` — create or update browser portal user: `docker compose exec server python scripts/create_user.py admin yourpassword`
- `recompute_trips.py` — recompute trips for all devices: `docker compose exec server python scripts/recompute_trips.py`

**Infrastructure**
- `server/requirements.txt`: added `Flask-Login`, `bcrypt`, `reverse_geocoder`
- `server/Dockerfile`: added `ffmpeg`, updated COPY paths to use repo-root build context (`context: ..`), copies shared `static/` assets
- `server/docker-compose.yml`: build `context: ..`, `dockerfile: server/Dockerfile`; added `SECRET_KEY` and `DEVICE_NAME` env vars; added `migrate_phase24.sql` mount (for existing deployments)
- `server/.env.example`: added `SECRET_KEY`, `DEVICE_NAME` entries with generation instructions

#### Bug fixes and UI polish (post-deploy)
- `/api/trips` was returning a bare array; `history.js` expected `{trips:[...]}` wrapper → fixed
- `formatSpeed(null)`, `formatDistance(null)`, `trip.odo_start_km.toFixed(0)` crashed on null data → null guards added in `static/js/history.js`
- Map tiles loaded grey: server has no offline tile cache → `history.js` now reads `data-tile-url` attribute from `#history-map` div; Pi template uses `/static/vendor/tiles/{z}/{x}/{y}.png`, server template uses OSM `https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png`
- Geocode returned `name` key; `history.js` expected `label` → server geocode now returns `label`
- Delete buttons: Bootstrap Modal `.getOrCreate()` was silently failing (async timing) → replaced with synchronous `window.confirm()` defined in `base.html` as `window.confirmDelete`
- Trip row delete button was wrapping to a new line → added `text-nowrap` to cell, removed whitespace between buttons in template
- Sidebar flash on page navigation: `theme.js` was restoring collapsed state with CSS transitions active → added transition suppression (set `transition: none` on sidebar + contentWrapper + toggleBtn before applying state, re-enable after two `requestAnimationFrame` calls)
- Sidebar toggle arrow direction wrong when collapsed: CSS already applies `transform: rotate(180deg)` to `.app-sidebar.collapsed .sidebar-collapse-btn`; the JS was also swapping the icon class (`fa-chevron-left` ↔ `fa-chevron-right`), causing a double-flip → removed JS icon class swap entirely, CSS handles it
- Added `.app-sidebar.collapsed .sidebar-env-badge { display: none }` and `.sidebar-user-text { opacity: 0; width: 0 }` CSS in `base.html` so badge and username hide correctly when sidebar is collapsed

#### Deployment steps (existing unraid stack)
1. `git pull` on unraid (or however you deploy the server)
2. Run migration: `docker compose exec db psql -U yarisobd -d yarisobd -f /docker-entrypoint-initdb.d/migrate_phase24.sql`
3. Add `SECRET_KEY` and `DEVICE_NAME` to `.env`
4. Rebuild: `docker compose up -d --build`
5. Create portal user: `docker compose exec api python scripts/create_user.py admin yourpassword`
6. Run initial trip computation: `docker compose exec api python scripts/recompute_trips.py`
7. Browse to `https://your-cloudflare-tunnel-url/` → login page


### Phase 24.5: Pre-car-test code audit & bug fixes — ✅ DONE
**Completed 2026-08-10.** Full read-only audit of all Pi modules, JS files, and server code. 63 tests pass.

#### Bugs found and fixed

| File | Severity | Bug | Fix |
|---|---|---|---|
| `modules/app_alerts.py` | MEDIUM | `videos["files"]` crashed if `list_local_videos()` returned `None` or missing key | `.get("files", [])` with `or {}` fallback |
| `modules/app_cellular.py` | MEDIUM | `read_resp.encode(errors="replace")` called `.encode()` on an already-str return value, changing return type to bytes | Removed `.encode()` — `body = read_resp` directly |
| `modules/app_settings.py` | MEDIUM | `apn` was uninitialized when `isinstance(apn, str)` check failed, causing `NameError`/wrong value stored | Initialize `apn = ""` in the else branch |
| `modules/app_upload.py` | LOW | `import json as _json` was inside a `ConnectionError` except handler — runs on every fallback attempt | Moved `import json` to top of file |
| `server/app.py` | HIGH | `int(request.args.get("limit"))` had no try/except — non-numeric query param crashed the trips and dashcam list endpoints with `ValueError` | Wrapped in `try/except (ValueError, TypeError)` |
| `server/app.py` | MEDIUM | `os.path.commonpath()` for path traversal safety raised `ValueError` on cross-root paths (Windows paths in DB), crashing the video stream endpoint | Wrapped in `try/except ValueError` |
| `tests/test_app_settings.py` | — | `valid_payload()` was missing `trips_upload_enabled` and `video_convert_enabled` (added in Phase 23.5 but test not updated), causing a pre-existing test failure | Added missing fields to `valid_payload()` |

#### Bugs confirmed NOT present (audit false positives)
- `app_obd.py` speed/rpm lock: `obd_speed_lock` already wraps the entire `while` loop including the write — no actual race
- `server/modules/db.py` DSN: Audit saw masked credential (view tool hides `password=`) — actual f-string is correct
- `app_sql.py` `state[0]` null crash: Code already has `if state is not None` check before indexing
- `app_cellular.py` `r"\r\n"`: SIMCOM SIM868 AT+HTTPPARA="USERDATA" spec requires literal 4-char `\r\n` sequence, not actual CRLF — intentionally correct
- `app_alerts.py` Authorization header: View tool masked `Bearer {token}` as `******` — actual code is correct

### Phase 24.6: Yaris 2013 OBD compatibility analysis & hardening — ✅ DONE
**Completed 2026-08-10.** Full compatibility analysis of every OBD PID against the 2013 Toyota Yaris (1.5L 1NZ-FE). Two real bugs fixed, deployed to Pi.

#### PID compatibility verdict

| PID | Command | OBD-II mandatory? | 2013 Yaris | Null-safe in code? |
|-----|---------|------------------|-----------|-------------------|
| 0x0D | SPEED | ✅ Yes | ✅ Yes | ✅ Yes |
| 0x0C | RPM | ✅ Yes | ✅ Yes | ✅ Yes |
| 0x05 | COOLANT_TEMP | ✅ Yes | ✅ Yes | ✅ Yes |
| 0x11 | THROTTLE_POS | ✅ Yes | ✅ Yes | ✅ Yes |
| 0x2F | FUEL_LEVEL | ⚠️ Optional | ✅ Likely | ✅ Yes |
| 0x01 | STATUS/MIL | ✅ Yes | ✅ Yes | ✅ Yes |
| Mode 3 | GET_DTC | ✅ Yes | ✅ Yes | ✅ Yes |
| 0xA6 | ODOMETER | ❌ Non-standard | ⚠️ Likely unsupported | ✅ Fixed (was broken) |

**Odometer note:** PID 0xA6 is a Mode 01 extended PID added in SAE J1979 DA (2014). The 2013 Yaris predates this spec; Toyota's ECU exposure of 0xA6 is inconsistent even on newer models. Expect `odometer = None` permanently — the UI handles this gracefully. The risk was in the decoder raising an exception that killed the whole OBD session; now fixed.

#### Protocol & connection
- **Protocol:** `OBD_PROTOCOL` env var defaults to `None` → python-obd sends `ATSP0` (auto-detect) → ELM327 will settle on ISO 15765-4 CAN 11-bit 500kbps, which is what the 2013 Yaris uses. ✅
- **OBD_PROTOCOL=6 hint:** After first confirmed working connection on the real car, uncomment `#Environment=OBD_PROTOCOL=6` in `deploy/yaris-obd.service` to skip the 3–5s auto-probe on every ignition-on.
- **Port:** auto-detects `/dev/ttyUSB0` (first USB serial device). ELM327 USB adapters enumerate there. Can override with `OBD_PORT` env var. ✅
- **Reconnect cycle:** ~10s (poll interval) + ~3–5s (ELM327 auto-probe) + ~2s (first poll) = up to ~17s from ignition-on to first live data. Acceptable.

#### Motion detection & trip logic
- **Primary:** OBD speed (PID 0x0D, polled every 2s) via `get_fresh_speed(max_age=5)`.
- **Fallback:** GPS haversine displacement when OBD speed is stale/unavailable.
- **During OBD warmup:** `speed_updated_at is None` → `get_fresh_speed()` returns `None` → GPS fallback activates. No false trip start — idle GPS drift rows spaced 60s apart are filtered by `MIN_GPS_MOTION_SAMPLES=3`.
- **Trips are post-computed** from raw `tracking` rows — no real-time open/close state machine. Power cut mid-trip is safe; all committed rows are recovered on restart. ✅

#### Bugs fixed

| File | Severity | Bug | Fix |
|---|---|---|---|
| `modules/app_obd.py` `_decode_odometer` | HIGH | Raised `ValueError` on unexpected byte count from unsupported/garbage 0xA6 response. Exception propagated through `_query()` and triggered `_mark_connection_lost()`, killing the entire OBD session on 2013 Yaris | Wrapped in `try/except Exception`, return `None` on any error |
| `modules/app_obd.py` `connect_obd` | MEDIUM | All sensor globals retained stale values from the previous ignition cycle — dashboard briefly shows wrong readings on reconnect | Reset all sensor globals to `None`/`[]` at start of each new connection |
| `deploy/yaris-obd.service` | INFO | No hint for pinning OBD protocol after initial test | Added commented `#Environment=OBD_PROTOCOL=6` with instructions |

### Phase 24.7: Final pre-car-test polish & map fixes — ✅ DONE
**Completed 2026-08-10.** Final round of fixes before car test.

#### Changes
- **`scripts/diagnose.sh`** — new diagnostic & recovery script. Run on Pi over SSH: `bash scripts/diagnose.sh` (read-only) or `bash scripts/diagnose.sh --fix` (auto-fix). Checks: service state, OBD USB adapter, SIM868 UART, disk/DB health, SQLite integrity, upload backlog, recent log errors, Python env, Pi throttling/temp/memory. Prints a cheatsheet of recovery commands. Exit code = number of critical issues.
- **`app.py`** — removed duplicate `app_gps` import; removed debug `print("hello ...")` that spammed the log on every index page load.
- **Server portal map tiles** — switched from `tile.openstreetmap.org` (rate-limited/blocked the Cloudflare tunnel egress IP) to **CARTO Voyager** (`basemaps.cartocdn.com`) which is free, CDN-backed, and reliable. Map now loads correctly on `yaris.ceaf.dev`.
- **Map zoom limits** — `history.js` now reads `data-min-zoom`/`data-max-zoom`/`data-tile-subdomains` from the `#history-map` div. Pi template caps to zoom 8–15 (matches offline cached tile range). Server template allows full 3–19. Prevents grey tiles when zooming outside cached range.
- **`tiles.addTo(map)` at init** — tiles were previously only added lazily on first trip click; now added immediately so the map background shows on page load.

### Phase 24.8: Deploy onboarding docs + uplink interface consistency — ✅ DONE
**Completed 2026-08-10.** Tightened the fresh-install path and aligned network-status plumbing with the Phase 23 wlan1-first architecture.

#### Changes
- **`deploy/readme.md`** — added a complete fresh-Pi install guide with:
  - required packages (`network-manager`, `nftables`, `avahi-daemon`, `dnsmasq-base`, Python tooling),
  - required NetworkManager profiles (`home-wifi`, `Hotspot`) with concrete `nmcli` examples,
  - deploy script run order (`install_service`, `install_port_redirect`, `install_netwatch`, `install_video_tools`, optional watchdog),
  - post-install verification and update/recovery commands.
- **Quick copy/paste bootstrap** — added a "Quick install" block at the top of `deploy/readme.md` for faster onboarding when provisioning a fresh Pi.
- **Root README deploy link** — `readme.md` now explicitly points to `deploy/readme.md` for clean Pi setup, instead of requiring PLAN deep-reading for first-time install.
- **Network status interface fix (`modules/app_network.py`)** — status endpoint previously hardcoded `wlan0`, which could misreport real uplink state after the T3U migration. It now resolves interface at runtime (`wlan1` primary, `wlan0` fallback) and reports the active interface in the response.
- **Dispatcher hook fix (`deploy/90-yaris-uplink`)** — previously ignored wlan1 events; now listens for both `wlan0` and `wlan1` so uplink transition recording remains accurate on current hardware.
- **README hardware photo** — added a current hardware build image (`pics/yaris-obd-hardware.jpg`) at the bottom of `readme.md`; saved without EXIF metadata and resized for lighter page load.

### Phase 25: Pre-install Yaris 2013 compatibility test — 🚧 PLANNED (core-system gate)
**Added 2026-08-09; intentionally immediately before the Android app.** Bench tests, synthetic
routes, attached-hardware tests, and stationary Pi runs cannot prove the complete system works
when temporarily connected to and powered by the actual 2013 Toyota Yaris. This phase is the
pre-installation acceptance gate for the complete core Pi/web/server system after Phase 24. It is
verification and targeted correction—not permanent installation or another redesign—and the
system is not considered ready to install until the results are recorded here. Permanent mounting,
cable routing, trim work, and final installation are explicitly outside the roadmap and will be
handled by the owner after this phase passes.

Prepare a temporary, removable test setup before driving:
- Connect the Pi, SIM868 HAT/antennas, USB OBD adapter, dashcam, and representative intended power
  source without permanently mounting or routing anything. Secure every temporary component and
  cable so it cannot interfere with pedals, steering, airbags, visibility, occupants, or loose-item
  safety during the controlled drive; remove the setup after testing.
- Resolve the Phase 19/20 undervoltage/throttling warning before the test; confirm
  `vcgencmd get_throttled` shows no current power fault at idle and under load with the temporary
  representative power setup. This validates electrical compatibility, not final cable routing.
- Back up the Pi SQLite database and record baseline row/trip/video/upload counts on the Pi and
  remote server. Use a uniquely timestamped test window so generated records can be reconciled
  without deleting unrelated history.
- Verify the service, watchdog, storage mounts, hotspot, `http://yaris.local/`, alert engine, GPS
  antenna view, dashcam recording mode, free space, and remote server health before moving.
- Use a second person for UI/log observations while the vehicle is moving, or record diagnostics
  for review afterward. The driver must not operate or troubleshoot the UI while driving.

Run a controlled route containing ignition-off/on, stationary idle, low-speed streets, normal road
speed, several complete stops, turns, a short GPS-obstructed segment if safely available, and a
clean trip end:
- **OBD/ECU:** confirm the ELM327 reaches `CAR_CONNECTED`, record negotiated Toyota protocol and
  adapter firmware, and verify real speed/RPM/coolant/fuel/throttle/MIL/DTC values. Compare wheel
  speed against the instrument cluster at several safe speeds. Record unsupported PIDs (especially
  odometer PID A6) as capabilities, not failures, and verify reconnect after ignition cycling and a
  deliberate USB disconnect/reconnect.
- **GPS and motion logging:** confirm fixes while stationary and moving, route coordinates on the
  offline map, OBD-speed-first motion detection, GPS displacement fallback when OBD is deliberately
  unavailable, one-minute idle heartbeat behavior, and no false trip from stationary GPS drift.
- **Trip boundary/replay:** after the inactivity timeout, verify exactly one trip (or the expected
  number for deliberate ignition gaps), correct start/end time and coordinates, plausible
  distance/average/max speed, km/mi and km/h/mph values, route polyline, start/end markers, timeline
  scrubber, play/pause marker position, and stopped portions of the route.
- **Local web UI:** test the final Phase 23 interface on the actual phone over the Pi/phone network at
  `http://yaris.local/`; verify the explicit **In-car / Local Pi** identity, dashboard telemetry,
  DTC page, trip history, dashcam library, settings, alerts, responsive layout, reconnect behavior,
  and no new browser console/API errors.
- **Dashcam workflow:** create a known short real clip, switch the camera safely into USB storage
  mode, detect/list it without confusing the OBD adapter, import only that selected file, verify
  thumbnail/playback/Range seeking, preserve the source until checks finish, and confirm the camera
  returns to recording afterward. Test deletion only with the disposable clip.
- **Alerts:** safely exercise conditions that can be simulated without damaging hardware (upload
  backlog, temporary GPS loss while OBD reports motion, and disposable threshold overrides).
  Confirm local bell transition/recovery/cooldown behavior and offline alert-state reconciliation
  with the Phase 24 server after connectivity returns. Do not intentionally overheat, undervolt,
  fill storage, or trigger a real MIL. With a real SIM, explicitly determine whether the SIM868
  transport can reliably deliver ntfy notifications while WiFi/Ethernet is unavailable, including
  authentication, timeout, retry, and recovery. If that cannot be made reliable on the actual
  modem/network, remove the ntfy feature and its settings rather than retain a transport that fails
  in the only situation where it is useful.
- **Power/reliability:** perform multiple normal ignition/power cycles, confirm automatic boot,
  service/watchdog startup, SIM868 power-on, OBD/GPS recovery, no SQLite corruption, and no current
  undervoltage/throttling. The deferred Phase 14 clean-shutdown limitation must be explicitly
  accepted or resolved with representative delayed-power/ignition-sense hardware before declaring
  the design ready for permanent installation.

Verify the complete remote path after connectivity returns:
- Confirm every test-window tracking row uploads exactly once and the selected dashcam clip resumes
  or completes without corruption; compare counts, timestamps, hashes, and byte sizes locally and
  remotely.
- On the Phase 24 portal, verify the explicit **Remote server** identity, authenticated
  vehicle-scoped trip summary/replay, route and timeline agreement with the local Pi, archived clip
  thumbnail/playback/Range seeking/download, synchronized alert history/current state without
  duplicate transitions after an offline interval, and absence of local-only OBD/cellular/Pi
  controls.
- The Android companion is intentionally outside this core acceptance gate and remains the final,
  low-priority Phase 26. Its own hotspot/cellular binding, trip display, and disposable clip relay
  require separate real-phone/in-car acceptance when that phase is implemented.

Acceptance requires a written result for every item, captured negotiated protocol/PID support,
measured trip/count/hash comparisons, relevant logs/screenshots, no unexplained tracebacks or data
loss, and cleanup of every disposable record/file while preserving the real drive. Any defect found
must be fixed, redeployed uncommitted, and the affected in-car test repeated before the final commit
and **ready-to-install** sign-off. Afterward, the owner handles permanent installation outside the
phase roadmap.

### Phase 25.5a: Device configuration sync backend — ✅ COMPLETE (connection-driven server sync)
**Server API and Pi sync thread implemented.** Server stores device config; Pi fetches when internet available and applies changes without restart.

#### Implemented (Phase 25.5a)
- **Database migrations** (`server/sql/migrate_phase25_5a.sql`):
  - Add `owner_name`, `car_model`, `device_name`, `avatar_path` to Postgres `devices` table
  - Add `config_version` and `config_updated_at` for change detection
  
- **Server API endpoints** (`server/modules/device_config.py`):
  - `GET /api/device-config` (device auth): Pi fetches config from server
  - `POST /api/device-config` (user auth): Portal/admin updates device config
  - Validation: 1-100 chars for names, 1-255 for paths
  - Config version incremented on any change (cache invalidation signal)
  
- **Server database helper** (`server/modules/db.py`):
  - `get_device_by_id()`: retrieve device with all config fields
  
- **Pi sync thread** (`modules/app_device_sync.py`):
  - Connectivity-driven: syncs every 5min when online, backoff to 60sec when offline
  - Fetches config from `/api/device-config` endpoint (device_key auth)
  - Detects changes via config_version
  - Stores synced config in SQLite
  - Reuses the existing upload credentials from `db/upload_creds.env`
    (`YARIS_SERVER_URL` + `YARIS_DEVICE_NAME` + `YARIS_API_KEY`;
    `YARIS_DEVICE_KEY` also accepted as an override for the key)
  - Ready for hot-reload on config change (future: signal handler)
  
- **Pi startup** (`app.py`):
  - `app_device_sync.start_sync()` starts background thread at boot

#### How it works
1. **At Pi startup**: loads device config from `config/device.json` (no network needed)
2. **When internet available**: sync thread wakes up every 5min and fetches from server
3. **If config changed** (new config_version): SQLite updated, next request reads new values
4. **If internet lost**: Pi continues with last-synced config from database
5. **User can still edit locally**: Settings page updates database; if sync enabled, server values override on next sync

#### Trade-offs
- Eventual consistency: changes on server may take 5min to reach Pi
- No hot-reload yet (requires app restart or signal handler to apply avatar/name changes immediately)
- Config version only increments on change; no periodic re-sync (efficient for offline car)

#### Testing
- Server endpoints accessible via `/api/device-config`
- Pi thread starts on boot (check logs for connectivity attempts)
- Sync disabled if `YARIS_SERVER_URL`, `YARIS_DEVICE_NAME`, or an API key
  (`YARIS_API_KEY` / `YARIS_DEVICE_KEY`) is not set
- **2026-08-10 access verification**: SSH access confirmed to Pi at `[email protected]`
  (new WiFi card/subnet) and to unraid via `ssh unraid` (`[email protected]`).
  Follow-up deployment succeeded the same day: Pi fast-forwarded from `d7b9bb6` to `cd004fb`,
  service restarted cleanly, and unraid rebuilt the API stack after manually applying
  `migrate_phase25_5a.sql`.

### Phase 25.5b: Remote portal device settings + hot-reload — ✅ COMPLETE
**The remote editor and Pi-side hot-reload are now wired.** The server portal can
edit the device identity that the Pi sync thread consumes, and the running Pi UI
updates its display-facing values without a manual restart once sync lands.

#### Implemented (Phase 25.5b so far)
- **Remote portal page**: `/settings/device` renders a login-protected editor for
  `owner_name`, `car_model`, `device_name`, and `avatar_path`
- **Portal JSON endpoint**: `GET /api/v1/portal/device-config` returns the current
  config for the configured single-device deployment
- **Navigation**: desktop sidebar + mobile bottom nav now expose **Device settings**
- **Portal UX**: live avatar preview, config-version display, dirty-state save
  button, and inline sync/explanation text
- **Pi hot-reload**:
  - `Account.reload_runtime_config()` and `Car.reload_runtime_config()` refresh
    display fields from the live SQLite-backed device config
  - local `/api/device-config` saves now reload the in-process `account`/`car`
    objects immediately
  - server sync now invokes a registered reload callback after writing new config
    locally, so next-page renders reflect synced values without restarting Flask

#### Validation
- Added runtime reload tests for `Account`, `Car`, and the sync callback path
- Existing suite still passes (`67 passed`)
- **Live 2026-08-10 verification**:
  - deployed the portal page to unraid and confirmed `/settings/device` routes to login (`302`)
  - fixed two real sync blockers on the Pi: reuse `db/upload_creds.env` and send
    the server's required `X-Device-Name` / `X-Api-Key` headers
  - enabled **Sync with server** on the Pi, changed `owner_name` on the server,
    waited through the sync thread's 60-second offline/backoff window, and
    observed both `GET /api/device-config` and the rendered topbar username on
    the Pi update to `quoije-sync-test`, then revert cleanly to `quoije`

---

  ### Phase 25.5c: Multi-device provisioning + force-sync UX — ✅ COMPLETE
  Extend the current single-device portal page into a real multi-device management
  surface: register devices from the server, mint/rotate API keys, help the Pi
  consume those credentials without SSH-heavy manual steps, and expose an honest
  **force sync** action that works with the system's pull-based/offline-first
  architecture.

  #### Goals
  - **Multi-device server view**: stop assuming one `DEVICE_NAME` in the portal;
    show all registered devices and let the user select which one is being edited
  - **Device registration from the portal**: create a new device row and return a
    one-time raw API key directly in the browser UI (same behavior as
    `server/scripts/create_device.py`, but web-managed)
  - **Credential handoff to the Pi**: make it possible to put `YARIS_SERVER_URL`,
    `YARIS_DEVICE_NAME`, and `YARIS_API_KEY` onto the Pi from the app UI rather
    than editing `db/upload_creds.env` manually over SSH
  - **Force sync button**: let the user request an immediate config pull without
    pretending the cloud server can magically push into an offline car

  #### Proposed implementation
  1. **Server: device management model + portal**
     - Add a device list page/card in the remote portal, with:
       - registered devices table
       - "Add device" action
       - "Rotate API key" action
       - per-device "Edit settings" action
     - Replace the single-device lookup helper with:
       - list devices
       - fetch one device by id
       - update one device's identity/config
     - Keep raw API keys **write-only/one-time reveal**:
       - show only immediately after create/rotate
       - never store raw keys server-side
       - only store hash as today

  2. **Server: browser APIs**
     - Add login-protected endpoints for:
       - list devices
       - create device + return one-time API key
       - rotate device API key + return one-time API key
       - get/update selected device config
       - request force sync for a selected device
     - Device settings UI should populate from the selected device row, not from a
       single hardcoded portal `DEVICE_NAME`

  3. **Pi: credential management UI**
     - Add a local Settings section for remote server credentials:
       - server URL
       - device name
       - API key
       - connection test button
     - Persist those values in the existing gitignored
       `db/upload_creds.env` (or an equivalent sqlite-backed secret store if we
       later choose to migrate away from env files)
     - After saving:
       - reload upload client / sync client config
       - allow enabling **Sync with server** only when creds test cleanly

  4. **Force sync semantics**
     - **Constraint**: the server cannot directly reach a Pi behind hotspot/NAT,
       and the car is often offline. So a server-side force sync button cannot be
       a true push.
     - Proposed behavior:
       - server sets a per-device `force_sync_requested_at` flag/version bump
       - Pi checks that flag during normal online polling
       - local Pi UI also gets a **Sync now** button that triggers an immediate
         fetch against the server using the saved credentials
     - Result:
       - from server: "sync on next online contact"
       - from Pi: "sync immediately if internet is currently available"

  #### Data model changes
  - Add server columns such as:
    - `last_config_sync_at`
    - `last_config_sync_version`
    - `force_sync_requested_at`
    - `api_key_rotated_at`
  - Optionally add a lightweight pairing/claim model later if copying raw API keys
    manually into the Pi UI feels too clunky

  #### UI/UX shape
  - **Remote portal**
    - left: device list / selector
    - right: settings form for selected device
    - actions: Add device, Rotate key, Copy creds, Request sync
    - status badges: last seen, last config version, last sync requested, maybe
      last successful contact
  - **Pi local app**
    - server credentials card in Settings
    - Test connection button
    - Sync now button
    - clear warning when local edits are locked because server sync is enabled

  #### Security / operational notes
  - Never display a stored API key after the creation/rotation response is gone
  - Keep key rotation explicit; rotating a key should warn that the old Pi config
    will stop authenticating until updated
  - Avoid logging raw keys in Flask logs, JS errors, or shell output captured in
    committed docs
  - Because the Pi is usually offline, all flows must degrade gracefully when the
    remote portal requests work the Pi cannot act on yet

  #### Suggested execution order
  1. Server multi-device DB/API refactor
  2. Remote portal device list + register/rotate key UI
  3. Pi local server-credentials UI + connection test
  4. Pi/local immediate **Sync now** button
  5. Server "request sync" flag + per-device status indicators
  6. End-to-end validation:
     - create device on server
     - copy/paste creds into Pi UI
     - test connection
     - enable sync
     - change device identity on server
     - verify Pi receives it
     - rotate key and verify old key stops working until Pi updated

  #### Open constraint to keep in mind
  - If you want **zero manual copy/paste** for API key provisioning, that becomes
    a pairing problem (claim code / QR / short-lived token). That is doable, but
    it is a bigger scope than simply exposing key create/copy fields in the two
    existing UIs. My recommendation is to ship copy/paste provisioning first, then
    add a pairing flow only if it still feels too annoying.

  #### Implementation progress (2026-08-10)
  - **Server-side multi-device API/UI**
    - Added device listing, create-device, rotate-key, per-device config, and
      request-sync endpoints in the remote portal
    - Reworked `/settings/device` into a multi-device management page with a
      registered-device list, selected-device editor, one-time API-key reveal, and
      copy-credentials helper
  - **Server schema**
    - Added Phase 25.5c migration for `last_config_sync_at`,
      `last_config_sync_version`, `force_sync_requested_at`, and
      `api_key_rotated_at`
    - Added device sync acknowledgement endpoint so the Pi can report when a
      config version was actually applied
  - **Pi-side provisioning**
    - Added local Settings UI/API for `YARIS_SERVER_URL`, `YARIS_DEVICE_NAME`, and
      `YARIS_API_KEY`
    - Added **Test connection** and **Sync now** actions in the Pi app
    - Reused the existing gitignored `db/upload_creds.env` store instead of
      inventing a second credential location
  - **Runtime behavior fixes**
    - Upload client now reads credentials dynamically instead of only at import
    - Device sync thread can restart after credentials are added later
    - Enabling **Sync with server** now validates that remote credentials exist

  #### Validation
  - Local tests expanded to `72 passed`
  - Deployed Phase 25.5c to unraid and applied `migrate_phase25_5c.sql`
  - Deployed Phase 25.5c to the Pi at `192.168.50.213`; `yaris-obd.service`
    restarted cleanly
  - Pi local API checks:
    - `GET /api/remote-config` shows the saved remote server credentials state
    - `POST /api/remote-config/test` succeeds with authenticated device creds
    - `POST /api/remote-config/sync-now` succeeds (`no_change` when already current)
  - Server sync-ack metadata verified live: `last_config_sync_version` matched the
    current `config_version` for `yaris-2013`, and `last_config_sync_at` populated
  - Temporary create/delete validation of the new device-provisioning helper
    succeeded on the live server (`phase25c-validate-temp`)

  #### Remaining polish ideas (not blockers)
  - Exercise the authenticated browser flow for create/rotate/request-sync in the
    live portal UI itself, not just the backing APIs/helpers
  - If copy/paste provisioning feels too clunky in practice, add a later QR /
    claim-code pairing flow
  - Main portal overview/history/dashcam pages are **not** multi-device yet:
    the data model already separates rows by `device_id`, but those pages still
    read from the single configured `DEVICE_NAME`. Today that means the new
    multi-device management page can manage several devices, but the normal trip
    history view still shows one configured car/device at a time until a later
    portal-wide device selector/filter is implemented.

  ---

  ### Phase 26: Native Android companion app — 🚧 PLANNED (low priority, always last)
  Revives the phone-relay goal (Phase 11/12) properly this time, using a real native app instead of
  a web page - the only way to actually hold a WiFi connection to the Pi's hotspot and a cellular
  connection to the internet open simultaneously (`ConnectivityManager.bindProcessToNetwork()`,
unavailable to browser JS - see the Phase 11 update). Explicitly **not urgent** and intentionally
kept at the end of the roadmap, after all web/server work and the Phase 25 core in-car acceptance
test are done. Permanent vehicle installation remains owner-handled and is not an implementation
phase. Scope, at a high level (not yet designed in detail):
- **Dashcam file transfer**: browse/select/delete dashcam clips already imported to the Pi (same
  data as the Phase 17 local video browser, just a native client instead of/alongside the web UI),
  download them to the phone, and upload to the remote server over cellular while the phone stays
  on the Pi's hotspot for the download leg - the true simultaneous dual-network relay the web
  version could never deliver.
- **Trip/location info**: surface live GPS position, speed, and trip history (Phase 18) pulled
  from the Pi while connected to its hotspot (reusing the existing `/api/gps`-style data feeds),
  so the app is useful as a real "check on the car" companion, not just a file-transfer tool.
- Not yet scoped: distribution (sideload vs Play Store), whether it talks to the Pi directly over
  the hotspot only or also to the remote server directly for trip history when away from the car,
  and how much of the existing REST API surface can be reused as-is vs needs new
  mobile-friendly endpoints. To be designed once Phases 12-24 (web-side cleanup + hardening,
  redesign, remote portal, and core in-car acceptance) are done.

## Working Notes / Environment Gotchas

- **Pi credentials/SSH**: `ssh yaris@<pi-ip>`. Confirm current IP before connecting (varies by
  network — check locally, not recorded here) — usually reachable via `yaris.local` too (mDNS,
  see Phase 6). **Current verified LAN IP (2026-08-10): `192.168.50.213`** after the TP-Link
  Archer T3U WiFi change.
- **Local dev repo**: work happens on a separate dev machine, not on the Pi. Push to
  `origin/shameless-aislop`, the repo's current default branch (repo is public).
- **unraid server SSH**: `ssh [email protected]` (alias `unraid`). Real git checkout lives at
  `/mnt/user/app/git/yaris-obd` (not `/mnt/user/appdata/...`, which is only the docker-managed data
  volume for the `db`/`dashcam` containers). **Re-verified 2026-08-10**: alias works and lands in
  `/root`. Deploy with
  `cd /mnt/user/app/git/yaris-obd && git pull --ff-only && cd server && docker compose up -d --build`.
  Container names: `yaris-obd-db` (Postgres 17), `yaris-obd-api`. For existing databases, also run
  the mounted migration scripts manually, e.g.
  `docker compose exec db psql -U yarisobd -d yarisobd -f /docker-entrypoint-initdb.d/migrate_phase25_5a.sql`.
  **Important 2026-08-10**: this checkout had a long-diverged local `shameless-aislop`
  (`ahead 136, behind 146`), so `git pull --ff-only` failed. To avoid destroying local history, the
  Phase 25.5a deploy was performed from a fresh temporary clone while reusing the same `.env` and
  Docker data. Reconcile or replace the old checkout before relying on it for future ff-only deploys.
- **Pi deploy loop**: `ssh yaris@<pi-ip>` (alias `yarisobd`) ->
  `cd ~/app/yaris-obd && git pull --ff-only` -> `sudo systemctl restart yaris-obd.service`
  (passwordless sudo confirmed via `yaris ALL=(ALL) NOPASSWD: ALL`). App stdout/stderr goes to
  `~/app/yaris-obd/yaris-obd.log` (not journald - the systemd unit redirects both streams there),
  so use `tail`/`grep` on that file, not `journalctl`, to see application-level prints (upload
  progress, OBD/GNSS errors, etc.) - `journalctl -u yaris-obd.service` only shows service
  start/stop/crash lifecycle events. **Update 2026-08-09**: plain `print()` calls were silently
  invisible in that log for months because Python fully-buffers stdout when it's not a TTY (a
  file, in this case) — `logging`-based lines (e.g. the `obd` library's own logger, which uses
  stderr) showed up fine, but bare `print()` diagnostics from `app_gps.py` never did. Fixed by
  adding `Environment=PYTHONUNBUFFERED=1` to the systemd unit
  (`deploy/yaris-obd.service`) — **remember to also copy the updated unit file to
  `/etc/systemd/system/yaris-obd.service` and run `sudo systemctl daemon-reload`** on the Pi, a
  plain `git pull` + restart does NOT pick up systemd unit file changes (the live
  `/etc/systemd/system/` copy is independent of the repo's `deploy/` copy).
- **Pi deploy loop, requirements.txt changes**: after any `requirements.txt` change (e.g. adding
  `RPi.GPIO`), also run `~/app/yaris-obd/venv/bin/pip install -r requirements.txt` on the Pi — a
  `git pull` alone doesn't install new dependencies into the venv.
- **Pi memory budget**: ~900MB usable RAM, no swap. Any code path that might buffer a whole
  dashcam-sized file (hundreds of MB) in memory is unsafe on this hardware - stream, don't buffer
  (see Phase 10).
- **Git push auth**: if `git push` fails with a credential/auth error, run `gh auth login`
  (device-code browser flow) then `gh auth setup-git` to wire git to use the `gh` CLI's stored
  credentials — this fixed push auth issues in this environment without needing SSH keys or PATs.
- **Pi environment gap**: Debian Bookworm blocks system-wide `pip install` (PEP 668,
  "externally-managed-environment"). Use a venv for the real app dependency install (Phase 5)
  rather than `--break-system-packages` everywhere. (Resolved in Phase 5 — venv at
  `/home/yaris/app/yaris-obd/venv`.)
- **Pi → GitHub auth for `git pull` (private repo)**: the Pi's pre-existing
  `~/.ssh/id_ed25519.pub` is an *inbound* key only (private half is on the dev machine) — can't
  be reused for the Pi's own outbound git auth. Generated a dedicated keypair on the Pi
  (`~/.ssh/yaris_deploy_key`), added it as a GitHub **read-only deploy key** on this repo, and
  added an `~/.ssh/config` entry pinning `github.com` to that key. `[email protected]:...` (SSH
  remote) then works standalone on the Pi, no PAT/interactive login needed.
- **piwheels**: pip on the Pi automatically uses `piwheels.org` as an extra index (Raspberry Pi
  OS default `pip.conf`) — this is why `gevent` (which normally needs a C compile) installed in
  seconds from a prebuilt ARM wheel instead of taking many minutes to build from source.
- **python-obd note**: `obd.OBD()` (or with `portstr=`) performs the ELM327 handshake at
  connection time; if there's no car on the other end, it raises rather than silently returning
  a dead handle — `app_obd.py`'s `connect_obd()` already catches this and sets `connection = None`.