From a7ab088cf593d38c0927e453b9b28e1c0c495f12 Mon Sep 17 00:00:00 2001 From: Mathieu Moran Date: Mon, 10 Aug 2026 05:55:37 -0400 Subject: [PATCH] docs: update PLAN.md and readme for phases 24.5-24.7 - PLAN.md: add Phase 24.7 section (diagnose.sh, map tile fixes, app.py cleanup) - readme.md: update project status to reflect phases 24-24.7 complete, add remote portal to features list, add diagnostics/recovery section Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- PLAN.md | 10 ++++++++++ readme.md | 45 +++++++++++++++++++++++++++------------------ 2 files changed, 37 insertions(+), 18 deletions(-) diff --git a/PLAN.md b/PLAN.md index 29af2a4..7086526 100644 --- a/PLAN.md +++ b/PLAN.md @@ -1373,6 +1373,16 @@ including two UX polish passes and multiple bug-fix rounds. | `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 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 diff --git a/readme.md b/readme.md index 1e7a666..4371243 100644 --- a/readme.md +++ b/readme.md @@ -55,6 +55,12 @@ Dashboard — mobile (390 px) and desktop (1280 px): Dashcam videos upload in resumable 40MB chunks (works around tunnel body-size limits and keeps the Pi's memory footprint flat regardless of file size); a UI toggle can pause dashcam uploads independently while trip logs keep syncing +- 🌐 **Remote web portal** — a full read-only browser portal at the same server URL (Phase 24): + login-protected (Flask-Login + bcrypt), trip history with OSM/CARTO live map and route replay, + dashcam archive browsing with inline video player and Range-request seeking, overview stats + dashboard, and delete buttons for trips and clips. Shared `history.js` code runs on both the + Pi and the server — tile source and zoom limits are configured per-deployment via HTML data + attributes. Accessible at `https://your-cloudflare-tunnel-url/` - 📡 **Optional cellular fallback** through the SIM868 for small trip-log uploads when normal WiFi/Ethernet is unavailable (dashcam video stays off cellular) - 🗄️ **Motion-aware local-first SQLite logging** — five-second motion checks without five-second @@ -109,24 +115,15 @@ For the remote server (receives trip logs + dashcam uploads), see [server/README ## Project status -Phases 1–13, 15–23, and 23.5 are complete. The full responsive web UI redesign (Phase 23) is done, -followed by a major polish and hardware upgrade pass (Phase 23.5): +Phases 1–24.7 are complete. The system is fully built and audited, ready for the Phase 25 real-vehicle test: -- **Async dashcam import** with progress polling — no more mobile timeouts -- **Per-file Convert button** with real ffmpeg progress (reads `out_time_ms` via `-progress pipe:1`) -- **Odometer tracking** from OBD in every trip row and the overview dashboard -- **Separate upload toggles** for trips/logs vs dashcam videos -- **Download button** on Pi video files -- **Offline reverse geocoding** — `/api/geocode` route on the Pi uses `reverse_geocoder` (20 MB, - no internet needed); falls back to Nominatim for street-level accuracy when online. Browser never - calls any external service -- **Live location name** on dashboard GPS card (updates every ~50 m) and trip scrubber timeline -- **Recenter button** on dashboard and history maps -- **Imperial units removed** — metric only (km / km/h) -- **Mobile trip replay** — tap any trip row to load the route; Replay button kept on desktop only -- **TP-Link Archer T3U WiFi dongle** — RTL8812BU DKMS driver installed; all WiFi traffic moved to - `wlan1` (AC1300, dual-band). `wlan0` onboard stays silent as automatic fallback if dongle is - absent. Consistent phone-hotspot IP via `dhcp-client-id` +- **Phases 1–23.5**: core Pi system — GPS, OBD, dashcam, trip history, web UI redesign, WiFi upgrade, cellular fallback, alerts, settings, upload +- **Phase 24**: remote web portal at `https://yaris.ceaf.dev/` — login-protected, trip history with CARTO live map, dashcam archive, delete, overview stats +- **Phase 24.5**: full code audit — 6 bugs fixed across Pi modules and server, 63 tests passing +- **Phase 24.6**: Yaris 2013 OBD compatibility hardening — `_decode_odometer` no longer kills the OBD session on unsupported PIDs, sensor globals reset on reconnect, `OBD_SKIP_VOLTAGE_CHECK` escape hatch for clone ELM327 adapters +- **Phase 24.7**: diagnostic script (`scripts/diagnose.sh`), map tile switch to CARTO, zoom limit fix + +**Next**: Phase 25 — temporary real-vehicle test in the 2013 Yaris (see PLAN.md for the full acceptance checklist). Phase 26 (Android companion app) follows after that. Phase 14 is partially complete: the Pi's hardware watchdog is deployed and reboot-verified. Read-only-root storage hardening is deferred until persistent storage is moved off the SD root @@ -134,7 +131,7 @@ partition, and clean shutdown still needs delayed-power or ignition-sense hardwa The browser-based phone relay was removed after real-world testing confirmed that mobile browsers cannot reliably use the Pi's WiFi and cellular data simultaneously. A native Android companion is -planned later instead. +planned later instead (Phase 26). The local Web UI includes a Settings page for safe runtime configuration: dashcam uploads, uploaded-video retention, cellular APN fallback, optional ntfy delivery, and alert thresholds. @@ -151,3 +148,15 @@ A temporary, removable real-vehicle compatibility test in the 2013 Yaris (Phase final low-priority Android phase (Phase 26). Permanent installation is owner-handled and is not a roadmap phase. Full phase history, verification notes, and current scope live in [PLAN.md](./PLAN.md). + +## Diagnostics & recovery + +If something goes wrong in the car, SSH in and run: + +```bash +bash ~/app/yaris-obd/scripts/diagnose.sh # read-only health check +bash ~/app/yaris-obd/scripts/diagnose.sh --fix # attempt auto-fix +``` + +Checks service state, OBD/UART hardware, disk/DB health, upload backlog, Pi throttling, and +prints a cheatsheet of recovery commands. Exit code = number of critical issues found.