yaris-obd/BUGS.md

yaris-obd Bug Tracker

Standalone bug/issue tracker for the yaris-obd project, kept separate from PLAN.md. Use this file to record, track status, and hand off bugs to another agent/session. PLAN.md still summarizes bug-fix progress in its phase sections (and Phase 26 is the dedicated road-test bug-fix phase), but the authoritative, issue-by-issue record lives here.

How to use this tracker

• File format: one ## BUG-XX section per issue. Keep the numbering sequential.
• Status field: OPEN → IN PROGRESS → FIXED (commit ref) → CLOSED (deployed + verified) or WONTFIX/DUP as appropriate.
• Relate to phases: each entry's Phase field links a bug to the relevant PLAN.md phase so an agent can find the surrounding context and acceptance criteria.
• When fixed: keep the original symptom/impact recorded (don't delete history), set status to FIXED, add the commit SHA in the Fix field, then move to CLOSED after deploy/verify. Also drop a one-line mention in the corresponding PLAN.md phase.
• For future bugs: add new ## BUG-XX entries here rather than only burying them in chat history. Keep them SMALL and one-issue-per-entry so they are easy to pick up and verify.

---

Open bugs

BUG-01 — WiFi/hotspot unreachable from phone while cell data is on (and wrong documented gateway)

• Status: OPEN
• Severity: Medium (usability of the in-car hotspot from a phone)
• Area: Networking / Pi hotspot (yaris-uplink, NetworkManager shared AP, docs)
• Phase: Phase 26
• Symptom: While a phone is connected to the Pi's no-internet hotspot and cell data is on, the phone cannot load yaris.local, 10.42.0.1, or the Pi's DHCP address at all. With cell data disabled, http://<dhcp-ip>/ loads, but yaris.local and 10.42.0.1 still do not. The working address seen was 10.112.<...>.
• Root cause (confirmed): Phone-OS "smart network switching" — with a no-internet WiFi network associated and cellular available, the OS keeps cellular as the whole-device default route, so no traffic (even a plain page navigation or fetch()) reaches the Pi hotspot. Disabling cell data forces the hotspot WiFi to become the default network. This is the same OS-level ceiling documented in Phase 11/22. Separately, the actual NetworkManager shared-AP subnet is 10.112.0.x, not the documented 10.42.0.1, and yaris.local mDNS isn't resolved from the phone on the Pi AP.
• Fix scope / actions:
  • Make the documented/reachable address correct (surface the Pi's real DHCP-assigned address in the UI / status page rather than hardcoding 10.42.0.1).
  • Extend the yaris.local unicast (shared-dnsmasq) fallback to the AP subnet so it resolves from a phone on the Pi hotspot.
  • Clearly document the cell-data limitation and the workaround (disable cell data / "smart network switching").
• Acceptance: phone on the Pi hotspot can load the web UI via a documented, correct address (optionally yaris.local), and the cell-data caveat is documented.

---

BUG-02 — Micro-USB power port on the Pi is physically damaged

• Status: OPEN
• Severity: Hardware (reliability/power)
• Area: Hardware / power
• Phase: Phase 26
• Symptom: The Pi's micro-USB 5V power connector is worn/damaged and no longer makes a reliable connection. Power is likely to drop under vibration in the car.
• Root cause: Physical wear on the connector.
• Fix scope / actions: No code. Owner hard-wires 5V and GND directly to the Pi's GPIO header (pins 2/4 for 5V, 6/9/14/20/25/30/34/39 for GND) with a suitable PSU, bypassing the micro-USB port. Confirm vcgencmd get_throttled shows no current undervoltage after rewiring (the Phase 19/20 alerts monitor this).
• Acceptance: Stable power with no undervoltage/throttling under load.

---

BUG-03 — DTC/MIL codes are never persisted; lost on OBD disconnect or reboot

• Status: CLOSED (commit e2f2314; deployed + verified 2026-08-11)
• Fix: Persist MIL + codes to SQLite on each poll (save_dtc_state), /api/dtc falls back to the persisted snapshot when OBD is offline, get_overview_stats counts the real dtc table, and a schema migration rebuilds the unused NAME/STATUS/DTC_ID table. Cleared codes are tracked via IS_SET + FIRST_SEEN_AT/LAST_SEEN_AT. Tests: tests/test_dtc_persistence.py.
• Severity: Medium (lost diagnostic data; also a stats bug)
• Area: modules/app_obd.py, modules/app_sql.py, get_overview_stats
• Phase: Phase 26
• Symptom: Stored DTC trouble codes and MIL state live only in the in-memory dtc_codes global in app_obd.py. They vanish as soon as OBD disconnects or the Pi reboots. Separately, get_overview_stats queries a table named dtc_codes that does not exist (the created table is dtc), so the post-road-test state may be wrong/broken.
• Root cause: The SQLite dtc table is created in schema but is never written to or read from by any code path. No DTC persistence exists at all.
• Fix scope / actions:
  • Persist MIL + DTC codes to the dtc SQLite table on each successful poll.
  • Read back from SQLite when OBD is disconnected so last-known codes stay visible.
  • Fix get_overview_stats to query the real dtc table (and use current MIL/DTC state).
  • Add a "cleared/since" concept so a code that was cleared is distinguishable from one still set.
• Acceptance: Codes set during a drive survive a power cycle / OBD disconnect and appear on the DTC page and overview stats.

---

BUG-04 — Server merges two separate trips into one (motion boundary mismatch)

• Status: CLOSED (commit 96fb897; deployed + verified 2026-08-11)
• Fix: Replaced pure time-gap splitting with Pi's motion-aware logic: OBD speed > 1 km/h primary, GPS displacement >= 8 m (3 consecutive) fallback, 5-min inactivity gap. Server trips cleared and recomputed: 17 trips on both Pi and server.

---

BUG-05 — Server route replay reports speed_source: "gps" even when OBD speed is present

• Status: CLOSED (commit e2f2314; deployed + verified 2026-08-11)
• Fix: get_trip_route now mirrors the Pi's logic: "obd" when speed > 0, otherwise "gps". Server docker container rebuilt and health-checked.

---

BUG-06 — Server timestamps are shifted (Postgres stores naive local time as UTC)

• Status: OPEN
• Severity: High-ish (all server trip times / boundaries off by the EDT offset)
• Area: Pi upload (modules/app_upload.py / SQL), server/sql, server/modules/db.py, portal display
• Phase: Phase 26
• Symptom: Server shows trip times (and effectively trip boundaries/comparisons against the Pi) shifted by the Montreal-timezone-to-UTC offset (~4-5 hours depending on DST).
• Root cause: tracking_points.recorded_at is TIMESTAMPTZ, but the Pi sends naive local (Montreal) time (datetime.now()) with no offset. Postgres (UTC container timezone) interprets that naive string as UTC.
• Fix scope / actions (delicate — touches sending, storage, and display):
  • Pi should send timezone-aware timestamps in local Eastern time (or explicit UTC).
  • Server should store/read as America/Toronto (or consistent UTC) and display in Eastern.
  • Optional one-time migration to correct already-stored rows (depends on offset at insert time — needs a decision: re-map by DST window or accept a best-effort correction). Rebuilding the server trips table may be needed. Get owner sign-off on migrating existing data.
• Acceptance: New data displays at the correct local time on the portal; existing shifted rows are corrected (or explicitly accepted as-is if the owner opts out of migration).

---

BUG-07 — Trip replay on the portal sometimes does nothing

• Status: OPEN (needs reproduction/diagnostics)
• Severity: Low/Medium (intermittent UI)
• Area: static/js/history.js (shared Pi+server), server /api/v1/portal/trip/<id>
• Phase: Phase 26
• Symptom: Clicking a trip to replay on the /history page intermittently does nothing — no route renders, no error shown.
• Root cause: Not yet isolated. Plausible contributors: an API/DB race (recompute_trips running concurrently with a route read), DB lock, or clicking before the map is ready. Note history.js uses shared parsing that expects space-separated Pi timestamps and "T"-separated server ones — verify both.
• Fix scope / actions: Add targeted diagnostics (log/reproduce) before fixing. Check map readiness, error handling on the trip-fetch, and the shared timestamp parsing. Add an explicit "failed to load route" state instead of silent inaction.
• Acceptance: Replay is reliable; any failure surfaces a visible error rather than doing nothing.

---

BUG-08 — No trip deletion on the local Pi (only on the remote portal)

• Status: CLOSED (commit c5c478b; deployed + verified 2026-08-11)
• Fix: Added deletable param to data_table macro, window.confirmDelete helper in base.html, DELETE /api/trip/<id> route + app_sql.delete_trip(), and configurable data-delete-url in history.js (shared Pi+server). Trip 1967 deleted, 18→17 trips, 2028 tracking rows preserved.

---

BUG-09 — Server trip scrubber geocoding is slow on each step

• Status: OPEN
• Severity: Medium (UX)
• Area: static/js/history.js showReplayPoint() / scheduleGeocode()
• Phase: Phase 26
• Symptom: Scrubbing through the trip timeline on the server portal is sluggish — the location name takes a long time to appear because each scrub step fires a fresh /api/geocode HTTP request (debounced 600ms). On the Pi this is fast (offline reverse_geocoder), but the server calls Nominatim which adds latency.
• Root cause: Every showReplayPoint() call triggers scheduleGeocode() → debounced fetch(/api/geocode...). No pre-caching or batch loading.
• Fix scope / actions: Pre-fetch geocode results for ALL trip points when the route is first loaded. Store in a local JS map keyed by rounded coordinate. Show cached label instantly during scrubbing. Only fall back to live fetch for uncached points. Optionally batch-geocode at the server API level too (accept multiple lat/lon pairs).
• Acceptance: Scrubbing through trip replay shows location names near-instantly.

BUG-10 — GPS-only false trips generated when car is not connected

• Status: OPEN
• Severity: Medium (data quality)
• Area: modules/app_trip.py build_trip_summaries(), modules/app_sql.py refresh_trips()
• Phase: Phase 26
• Symptom: The Pi generates trips from GPS data alone (GPS jitter/drift) even when the car isn't connected. Since the Pi bench-tests with no OBD, GPS displacement fallback creates phantom "trips" from stationary GPS noise.
• Root cause: The GPS motion fallback (3+ consecutive 8m displacements) can be satisfied by GPS jitter over time, especially indoors or in weak-signal areas. The system doesn't gate trip detection on whether OBD was ever present.
• Fix scope / actions:
  • Option A (strict): Only start trips when OBD wheel speed has been detected at least once since the app started (a car_was_connected flag). No OBD ever = no trips, even with GPS.
  • Option B (lenient): Increase GPS motion requirements when OBD has never been seen (e.g. require 10+ consecutive displacements of 20m+ instead of 3×8m).
  • Recommend Option A — it matches the real-world use case: the Pi is powered by the car's ignition, so OBD should always be reachable when the car is running. No OBD = bench test, don't generate trips.
• Acceptance: Bench-testing the Pi (no car connected) produces zero trips. Real driving with OBD connected still produces correct trips.

---

Resolved bugs

BUG-03 — DTC/MIL codes are never persisted; lost on OBD disconnect or reboot

• Status: CLOSED 2026-08-11
• Commit: e2f2314
• Verification: Deployed to Pi, service restarted clean, /api/dtc returns persisted snapshot when OBD offline, /api/stats shows active_dtc: 0, save_dtc_state/get_persisted_dtc_state confirmed present in running code.

BUG-05 — Server route replay speed_source always "gps"

• Status: CLOSED 2026-08-11
• Commit: e2f2314
• Verification: Server git reset to origin, Docker rebuild, /health OK on LAN and Cloudflare Tunnel. get_trip_route now uses "obd" if speed > 0 else "gps" matching Pi logic.