# yaris-obd 🚗📡

A Raspberry Pi 3-based OBD-II, GPS, and dashcam system for my 2013 Toyota Yaris. It reads live
vehicle data over USB, tracks position with a SIM868 GNSS/GSM HAT, logs everything locally, and
serves a web UI over the car's own WiFi hotspot. The dashboard and pre-cached map work fully
offline, while trip data and dashcam footage sync to a self-hosted remote server whenever an
internet uplink is available.

<table>
<tr>
<td width="120">
<a href="https://open.spotify.com/playlist/5u9vSw39FrIz7KghBkmgH4">
<img src="https://image-cdn-fa.spotifycdn.com/image/ab67706c0000d72c979ac180a23a70139d1ebd81" width="100" />
</a>
</td>
<td>

**rené lévesque bangers**
i have a dream

[![Listen on Spotify](https://img.shields.io/badge/Listen_on-Spotify-1DB954?style=for-the-badge&logo=spotify&logoColor=white)](https://open.spotify.com/playlist/5u9vSw39FrIz7KghBkmgH4)

</td>
</tr>
</table>

## Screenshot

![UI](pics/ui.png)

## Features

- 📊 **Live OBD-II data** over a cheap USB ELM327-compatible adapter: speed, RPM, coolant
  temperature, fuel level, throttle position, MIL status, stored DTCs, and odometer when the ECU
  supports it. Includes automatic background reconnects, serialized queries, and clear
  adapter/ELM327/ECU diagnostics
- 🛰️ **Real GPS tracking** via a Waveshare SIM868 GNSS/GSM/Bluetooth HAT, plotted live on an
  offline Leaflet map (pre-cached map tiles — no internet needed in the car). The module powers
  itself on through the HAT's GPIO PWRKEY wiring after a Pi power cycle
- 📶 **Self-hosted WiFi hotspot** so you can load the web UI on your phone from inside the car,
  with automatic switching back to home WiFi when it is available (`http://yaris.local` — no
  port number)
- 🎥 **Dashcam file retrieval** — detects a USB dashcam automatically (any brand/folder layout,
  no hardcoded device path), mounts it read-only, and safely copies footage locally. Verified
  against a real 28GB/87-file import. The web UI can also browse, sort, and delete individual or
  all videos directly from the connected dashcam with confirmed, temporary read-write operations
- ☁️ **Remote upload** — a self-hosted server (Flask + Postgres, `server/`) receives trip/GPS
  logs and dashcam footage over the internet (via Cloudflare Tunnel or a plain port-forward).
  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
- 📡 **Optional cellular fallback** through the SIM868 for small trip-log uploads when normal
  WiFi/Ethernet is unavailable (dashcam video stays off cellular)
- 🗄️ **Local-first SQLite logging** with retry-safe remote sync and automatic backoff
- 🖥️ **Offline web UI** built with Flask, Jinja, Bootstrap 5, Socket.IO, Chart.js, and Leaflet,
  all served locally with a shared responsive page shell
- 🔌 **Headless Pi deployment** as a self-restarting `systemd` service with a 10-second BCM2835
  hardware watchdog, verified across a real reboot

## Hardware

| Part | Notes |
| --- | --- |
| Raspberry Pi 3 Model B Rev 1.2 | Web UI host, logger, uploader, and WiFi hotspot |
| Waveshare SIM868 HAT | GNSS (GPS) + optional GSM/GPRS uplink, unused Bluetooth |
| USB OBD-II adapter | PL2303-based, ELM327-compatible (originally Bluetooth, switched to USB) |
| USB dashcam | Any brand — detected as generic USB mass storage |
| 2013 Toyota Yaris | The patient |

See [PLAN.md](./PLAN.md) for full hardware bring-up notes (SIM868 jumper/UART setup, antenna
gotchas, etc.) and the detailed project history.

## Getting started

```bash
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python3 app.py
```

The app serves on `http://<host>:5000`. On the Pi it runs as a `systemd` service and is reachable
with no port number at `http://yaris.local` after installing the mDNS and port-redirect setup.
Deployment helpers for the app service, hotspot watcher, port redirect, and hardware watchdog are
in [deploy/](./deploy); see [PLAN.md](./PLAN.md) for the complete Pi setup and hardware notes.

For the remote server (receives trip logs + dashcam uploads), see [server/README.md](./server/README.md).

## Project status

This project was revived after a couple of years on the shelf. Phases 1-13 and 15-16 are complete:
real GNSS, hardened OBD support, offline maps/UI, automatic WiFi hotspot switching, local logging,
dashcam import, resumable remote upload, deployment, and the shared UI foundation are implemented.
The pipeline has been exercised on the real Pi and dashcam, including a complete 28GB import and
remote upload. Actual OBD PID availability still needs the first in-car test.

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
partition, and clean shutdown still needs delayed-power or ignition-sense hardware.

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. The next roadmap work is the local imported-video browser/player, followed by trip history, Pi
health, alerts, settings, and a final UI polish pass. Full phase history, verification notes, and
current scope live in [PLAN.md](./PLAN.md).